tools/llvm: Do not build with symbols
[minix3.git] / lib / libc / gen / popen.3
blob84009044c98098c81deec5ac920f3d0dfadaad20
1 .\"     $NetBSD: popen.3,v 1.18 2011/06/27 08:21:07 wiz Exp $
2 .\"
3 .\" Copyright (c) 1991, 1993
4 .\"     The Regents of the University of California.  All rights reserved.
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.
14 .\" 3. Neither the name of the University nor the names of its contributors
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 .\"
30 .\"     @(#)popen.3     8.2 (Berkeley) 5/3/95
31 .\"
32 .Dd June 24, 2011
33 .Dt POPEN 3
34 .Os
35 .Sh NAME
36 .Nm popen ,
37 .Nm pclose
38 .Nd process
39 .Tn I/O
40 .Sh LIBRARY
41 .Lb libc
42 .Sh SYNOPSIS
43 .In stdio.h
44 .Ft FILE *
45 .Fn popen "const char *command" "const char *type"
46 .Ft int
47 .Fn pclose "FILE *stream"
48 .Sh DESCRIPTION
49 The
50 .Fn popen
51 function
52 .Dq opens
53 a process by creating an IPC connection,
54 forking,
55 and invoking the shell.
56 Historically,
57 .Nm popen
58 was implemented with a unidirectional pipe;
59 hence many implementations of
60 .Nm popen
61 only allow the
62 .Fa type
63 argument to specify reading or writing, not both.
64 Since
65 .Nm popen
66 is now implemented using sockets, the
67 .Fa type
68 may request a bidirectional data flow.
69 The
70 .Fa type
71 argument is a pointer to a null-terminated string
72 which must be
73 .Ql r
74 for reading,
75 .Ql w
76 for writing, or
77 .Ql r+
78 for reading and writing.
79 In addition if the character
80 .Ql e
81 is present in the
82 .Fa type
83 string, the file descriptor used internally is set to be closed on
84 .Xr exec 3 .
85 .Pp
86 The
87 .Fa command
88 argument is a pointer to a null-terminated string
89 containing a shell command line.
90 This command is passed to
91 .Pa /bin/sh
92 using the
93 .Fl c
94 flag; interpretation, if any, is performed by the shell.
95 .Pp
96 The return value from
97 .Fn popen
98 is a normal standard
99 .Tn I/O
100 stream in all respects
101 save that it must be closed with
102 .Fn pclose
103 rather than
104 .Fn fclose .
105 Writing to such a stream
106 writes to the standard input of the command;
107 the command's standard output is the same as that of the process that called
108 .Fn popen ,
109 unless this is altered by the command itself.
110 Conversely, reading from a
111 .Dq popened
112 stream reads the command's standard output, and
113 the command's standard input is the same as that of the process that called
114 .Fn popen .
116 Note that output
117 .Fn popen
118 streams are fully buffered by default.
121 .Fn pclose
122 function waits for the associated process to terminate
123 and returns the exit status of the command
124 as returned by
125 .Fn wait4 .
126 .Sh RETURN VALUES
128 .Fn popen
129 function returns
130 .Dv NULL
131 if the
132 .Xr fork 2 ,
133 .Xr pipe 2 ,
135 .Xr socketpair 2
136 calls fail,
137 or if it cannot allocate memory.
140 .Fn pclose
141 function
142 returns \-1 if
143 .Fa stream
144 is not associated with a
145 .Dq popened
146 command, if
147 .Fa stream
148 has already been
149 .Dq pclosed ,
150 or if
151 .Xr wait4 2
152 returns an error.
153 .Sh ERRORS
155 .Fn popen
156 function does not reliably set
157 .Va errno .
158 .Sh SEE ALSO
159 .Xr sh 1 ,
160 .Xr fork 2 ,
161 .Xr pipe 2 ,
162 .Xr socketpair 2 ,
163 .Xr wait4 2 ,
164 .Xr fclose 3 ,
165 .Xr fflush 3 ,
166 .Xr fopen 3 ,
167 .Xr shquote 3 ,
168 .Xr stdio 3 ,
169 .Xr system 3
170 .Sh STANDARDS
172 .Fn popen
174 .Fn pclose
175 functions conform to
176 .St -p1003.2-92 .
177 .Sh HISTORY
179 .Fn popen
180 and a
181 .Fn pclose
182 function appeared in
183 .At v7 .
184 .Sh BUGS
185 Since the standard input of a command opened for reading
186 shares its seek offset with the process that called
187 .Fn popen ,
188 if the original process has done a buffered read,
189 the command's input position may not be as expected.
190 Similarly, the output from a command opened for writing
191 may become intermingled with that of the original process.
192 The latter can be avoided by calling
193 .Xr fflush 3
194 before
195 .Fn popen .
197 Failure to execute the shell
198 is indistinguishable from the shell's failure to execute command,
199 or an immediate exit of the command.
200 The only hint is an exit status of 127.
203 .Fn popen
204 argument
205 always calls
206 .Xr sh 1 ,
207 never calls
208 .Xr csh 1 .