Annotation of src/lib/libc/gen/popen.3, Revision 1.20.2.1
1.20.2.1! pgoyette 1: .\" $NetBSD: popen.3,v 1.21 2017/02/21 19:53:20 abhinav Exp $
1.5 cgd 2: .\"
1.3 jtc 3: .\" Copyright (c) 1991, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
1.13 agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 15: .\" may be used to endorse or promote products derived from this software
16: .\" without specific prior written permission.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28: .\" SUCH DAMAGE.
29: .\"
1.6 perry 30: .\" @(#)popen.3 8.2 (Berkeley) 5/3/95
1.1 cgd 31: .\"
1.19 christos 32: .Dd January 19, 2015
1.1 cgd 33: .Dt POPEN 3
34: .Os
35: .Sh NAME
36: .Nm popen ,
1.19 christos 37: .Nm popenve ,
1.1 cgd 38: .Nm pclose
39: .Nd process
40: .Tn I/O
1.7 perry 41: .Sh LIBRARY
42: .Lb libc
1.1 cgd 43: .Sh SYNOPSIS
1.12 wiz 44: .In stdio.h
1.1 cgd 45: .Ft FILE *
46: .Fn popen "const char *command" "const char *type"
1.19 christos 47: .Ft FILE *
48: .Fn popenve "const char *path" "char * const *argv" "char * const *envp" "const char *type"
1.1 cgd 49: .Ft int
50: .Fn pclose "FILE *stream"
51: .Sh DESCRIPTION
52: The
53: .Fn popen
54: function
55: .Dq opens
1.6 perry 56: a process by creating an IPC connection,
1.1 cgd 57: forking,
58: and invoking the shell.
1.6 perry 59: Historically,
1.20.2.1! pgoyette 60: .Fn popen
1.6 perry 61: was implemented with a unidirectional pipe;
62: hence many implementations of
1.20.2.1! pgoyette 63: .Fn popen
1.6 perry 64: only allow the
1.1 cgd 65: .Fa type
1.6 perry 66: argument to specify reading or writing, not both.
67: Since
1.20.2.1! pgoyette 68: .Fn popen
1.6 perry 69: is now implemented using sockets, the
70: .Fa type
71: may request a bidirectional data flow.
72: The
73: .Fa type
74: argument is a pointer to a null-terminated string
75: which must be
76: .Ql r
77: for reading,
78: .Ql w
79: for writing, or
80: .Ql r+
81: for reading and writing.
1.17 christos 82: In addition if the character
83: .Ql e
84: is present in the
85: .Fa type
86: string, the file descriptor used internally is set to be closed on
1.18 wiz 87: .Xr exec 3 .
1.1 cgd 88: .Pp
89: The
90: .Fa command
91: argument is a pointer to a null-terminated string
92: containing a shell command line.
93: This command is passed to
94: .Pa /bin/sh
95: using the
96: .Fl c
97: flag; interpretation, if any, is performed by the shell.
98: .Pp
1.20 wiz 99: The
1.19 christos 100: .Fn popenve
101: function is similar to
102: .Fn popen
103: but the first three arguments are passed
104: to
105: .Xr execve 2
106: and there is no shell involved in the command invocation.
107: .Pp
1.1 cgd 108: The return value from
109: .Fn popen
1.19 christos 110: and
111: .Fn popenve
1.1 cgd 112: is a normal standard
113: .Tn I/O
114: stream in all respects
115: save that it must be closed with
116: .Fn pclose
117: rather than
118: .Fn fclose .
119: Writing to such a stream
120: writes to the standard input of the command;
121: the command's standard output is the same as that of the process that called
122: .Fn popen ,
123: unless this is altered by the command itself.
124: Conversely, reading from a
125: .Dq popened
126: stream reads the command's standard output, and
127: the command's standard input is the same as that of the process that called
128: .Fn popen .
129: .Pp
130: Note that output
131: .Fn popen
132: streams are fully buffered by default.
133: .Pp
134: The
135: .Fn pclose
136: function waits for the associated process to terminate
137: and returns the exit status of the command
138: as returned by
139: .Fn wait4 .
1.9 wiz 140: .Sh RETURN VALUES
1.1 cgd 141: The
142: .Fn popen
143: function returns
144: .Dv NULL
145: if the
1.19 christos 146: .Xr vfork 2 ,
1.6 perry 147: .Xr pipe 2 ,
1.1 cgd 148: or
1.6 perry 149: .Xr socketpair 2
1.1 cgd 150: calls fail,
1.19 christos 151: or if it cannot allocate memory, preserving
152: the errno from those functions.
1.1 cgd 153: .Pp
154: The
155: .Fn pclose
156: function
157: returns \-1 if
158: .Fa stream
159: is not associated with a
160: .Dq popened
161: command, if
162: .Fa stream
1.11 jmmv 163: has already been
1.1 cgd 164: .Dq pclosed ,
1.20 wiz 165: setting errno to
166: .Dv ESRCH
1.1 cgd 167: or if
1.8 fair 168: .Xr wait4 2
1.19 christos 169: returns an error, preserving the errno returned by
1.20 wiz 170: .Xr wait4 2 .
1.1 cgd 171: .Sh SEE ALSO
1.9 wiz 172: .Xr sh 1 ,
1.19 christos 173: .Xr execve 2 ,
1.1 cgd 174: .Xr fork 2 ,
175: .Xr pipe 2 ,
1.6 perry 176: .Xr socketpair 2 ,
1.1 cgd 177: .Xr wait4 2 ,
1.9 wiz 178: .Xr fclose 3 ,
1.1 cgd 179: .Xr fflush 3 ,
180: .Xr fopen 3 ,
1.16 wiz 181: .Xr shquote 3 ,
1.1 cgd 182: .Xr stdio 3 ,
183: .Xr system 3
1.14 kleink 184: .Sh STANDARDS
185: The
186: .Fn popen
187: and
188: .Fn pclose
189: functions conform to
190: .St -p1003.2-92 .
1.9 wiz 191: .Sh HISTORY
192: A
193: .Fn popen
194: and a
195: .Fn pclose
196: function appeared in
197: .At v7 .
1.1 cgd 198: .Sh BUGS
199: Since the standard input of a command opened for reading
200: shares its seek offset with the process that called
201: .Fn popen ,
202: if the original process has done a buffered read,
203: the command's input position may not be as expected.
204: Similarly, the output from a command opened for writing
205: may become intermingled with that of the original process.
206: The latter can be avoided by calling
207: .Xr fflush 3
208: before
209: .Fn popen .
210: .Pp
211: Failure to execute the shell
212: is indistinguishable from the shell's failure to execute command,
213: or an immediate exit of the command.
214: The only hint is an exit status of 127.
215: .Pp
216: The
217: .Fn popen
218: argument
219: always calls
1.8 fair 220: .Xr sh 1 ,
1.1 cgd 221: never calls
1.8 fair 222: .Xr csh 1 .
1.19 christos 223: .Pp
224: The
225: .Fn popenve
226: function first appeared in
227: .Nx 8 .
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to popen.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / gen