Commit | Line | Data |
---|---|---|
af359dea C |
1 | .\" Copyright 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
fa528602 | 3 | .\" |
af359dea C |
4 | .\" Redistribution and use in source and binary forms, with or without |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)popen.3 6.4 (Berkeley) 4/30/91 | |
33 | .\" | |
34 | .Dd April 30, 1991 | |
35 | .Dt POPEN 3 | |
36 | .Os | |
37 | .Sh NAME | |
38 | .Nm popen , | |
39 | .Nm pclose | |
40 | .Nd process | |
41 | .Tn I/O | |
42 | .Sh SYNOPSIS | |
43 | .Fd #include <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 a pipe, | |
54 | forking, | |
55 | and invoking the shell. | |
56 | Since a pipe is by definition unidirectional, the | |
57 | .Fa type | |
58 | argument may specify only reading or writing, not both; | |
59 | the resulting stream is correspondingly read-only or write-only. | |
60 | .Pp | |
61 | The | |
62 | .Fa command | |
63 | argument is a pointer to a null-terminated string | |
64 | containing a shell command line. | |
65 | This command is passed to | |
66 | .Pa /bin/sh | |
67 | using the | |
68 | .Fl c | |
69 | flag; interpretation, if any, is performed by the shell. | |
70 | The | |
71 | .Fa mode | |
72 | argument is a pointer to a null-terminated string | |
73 | which must be either | |
74 | .Ql r | |
75 | for reading | |
76 | or | |
77 | .Ql w | |
78 | for writing. | |
79 | .Pp | |
80 | The return value from | |
81 | .Fn popen | |
82 | is a normal standard | |
83 | .Tn I/O | |
84 | stream in all respects | |
85 | save that it must be closed with | |
86 | .Fn pclose | |
87 | rather than | |
88 | .Fn fclose . | |
89 | Writing to such a stream | |
90 | writes to the standard input of the command; | |
91 | the command's standard output is the same as that of the process that called | |
92 | .Fn popen , | |
93 | unless this is altered by the command itself. | |
94 | Conversely, reading from a | |
95 | .Dq popened | |
96 | stream reads the command's standard output, and | |
97 | the command's standard input is the same as that of the process that called | |
98 | .Fn popen . | |
99 | .Pp | |
100 | Note that output | |
101 | .Fn popen | |
102 | streams are fully buffered by default. | |
103 | .Pp | |
104 | The | |
105 | .Fn pclose | |
106 | function waits for the associated process to terminate | |
107 | and returns the exit status of the command | |
108 | as returned by | |
109 | .Fn wait4 . | |
110 | .Sh RETURN VALUE | |
111 | The | |
112 | .Fn popen | |
113 | function returns | |
114 | .Dv NULL | |
115 | if the | |
116 | .Xr fork 2 | |
117 | or | |
118 | .Xr pipe 2 | |
119 | calls fail, | |
120 | or if it cannot allocate memory. | |
121 | .Pp | |
122 | The | |
123 | .Fn pclose | |
124 | function | |
fa528602 | 125 | returns \-1 if |
af359dea C |
126 | .Fa stream |
127 | is not associated with a | |
128 | .Dq popened | |
129 | command, if | |
130 | .Fa stream | |
131 | already | |
132 | .Dq pclosed , | |
133 | or if | |
134 | .Xr wait4 | |
4af1c353 | 135 | returns an error. |
af359dea C |
136 | .Sh ERRORS |
137 | The | |
138 | .Fn popen | |
139 | function does not reliably set | |
140 | .Va errno . | |
141 | .Sh SEE ALSO | |
142 | .Xr fork 2 , | |
143 | .Xr sh 1 , | |
144 | .Xr pipe 2 , | |
145 | .Xr wait4 2 , | |
146 | .Xr fflush 3 , | |
147 | .Xr fclose 3 , | |
148 | .Xr fopen 3 , | |
149 | .Xr stdio 3 , | |
150 | .Xr system 3 | |
151 | .Sh BUGS | |
152 | Since the standard input of a command opened for reading | |
153 | shares its seek offset with the process that called | |
154 | .Fn popen , | |
155 | if the original process has done a buffered read, | |
156 | the command's input position may not be as expected. | |
157 | Similarly, the output from a command opened for writing | |
158 | may become intermingled with that of the original process. | |
159 | The latter can be avoided by calling | |
160 | .Xr fflush 3 | |
161 | before | |
162 | .Fn popen . | |
163 | .Pp | |
164 | Failure to execute the shell | |
165 | is indistinguishable from the shell's failure to execute command, | |
166 | or an immediate exit of the command. | |
167 | The only hint is an exit status of 127. | |
168 | .Pp | |
169 | The | |
170 | .Fn popen | |
171 | argument | |
fd07beb4 | 172 | always calls |
af359dea | 173 | .Xr sh , |
fd07beb4 | 174 | never calls |
af359dea C |
175 | .Xr csh . |
176 | .Sh HISTORY | |
177 | A | |
178 | .Fn popen | |
179 | and a | |
180 | .Fn pclose | |
181 | function appeared in | |
182 | .At v7 . |