Commit | Line | Data |
---|---|---|
11c62c4c CL |
1 | .\" Copyright 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
fa528602 | 3 | .\" |
11c62c4c CL |
4 | .\" %sccs.include.redist.roff% |
5 | .\" | |
6 | .\" @(#)popen.3 6.4 (Berkeley) %G% | |
7 | .\" | |
8 | .Dd | |
9 | .Dt POPEN 3 | |
10 | .Os | |
11 | .Sh NAME | |
12 | .Nm popen , | |
13 | .Nm pclose | |
14 | .Nd process | |
15 | .Tn I/O | |
16 | .Sh SYNOPSIS | |
17 | .Fd #include <stdio.h> | |
18 | .Ft FILE * | |
19 | .Fn popen "const char *command" "const char *type" | |
20 | .Ft int | |
21 | .Fn pclose "FILE *stream" | |
22 | .Sh DESCRIPTION | |
23 | The | |
24 | .Fn popen | |
25 | function | |
26 | .Dq opens | |
27 | a process by creating a pipe, | |
28 | forking, | |
29 | and invoking the shell. | |
30 | Since a pipe is by definition unidirectional, the | |
31 | .Fa type | |
32 | argument may specify only reading or writing, not both; | |
33 | the resulting stream is correspondingly read-only or write-only. | |
34 | .Pp | |
35 | The | |
36 | .Fa command | |
37 | argument is a pointer to a null-terminated string | |
38 | containing a shell command line. | |
39 | This command is passed to | |
40 | .Pa /bin/sh | |
41 | using the | |
42 | .Fl c | |
43 | flag; interpretation, if any, is performed by the shell. | |
44 | The | |
45 | .Fa mode | |
46 | argument is a pointer to a null-terminated string | |
47 | which must be either | |
48 | .Ql r | |
49 | for reading | |
50 | or | |
51 | .Ql w | |
52 | for writing. | |
53 | .Pp | |
54 | The return value from | |
55 | .Fn popen | |
56 | is a normal standard | |
57 | .Tn I/O | |
58 | stream in all respects | |
59 | save that it must be closed with | |
60 | .Fn pclose | |
61 | rather than | |
62 | .Fn fclose . | |
63 | Writing to such a stream | |
64 | writes to the standard input of the command; | |
65 | the command's standard output is the same as that of the process that called | |
66 | .Fn popen , | |
67 | unless this is altered by the command itself. | |
68 | Conversely, reading from a | |
69 | .Dq popened | |
70 | stream reads the command's standard output, and | |
71 | the command's standard input is the same as that of the process that called | |
72 | .Fn popen . | |
73 | .Pp | |
74 | Note that output | |
75 | .Fn popen | |
76 | streams are fully buffered by default. | |
77 | .Pp | |
78 | The | |
79 | .Fn pclose | |
80 | function waits for the associated process to terminate | |
81 | and returns the exit status of the command | |
82 | as returned by | |
83 | .Fn wait4 . | |
84 | .Sh RETURN VALUE | |
85 | The | |
86 | .Fn popen | |
87 | function returns | |
88 | .Dv NULL | |
89 | if the | |
90 | .Xr fork 2 | |
91 | or | |
92 | .Xr pipe 2 | |
93 | calls fail, | |
94 | or if it cannot allocate memory. | |
95 | .Pp | |
96 | The | |
97 | .Fn pclose | |
98 | function | |
fa528602 | 99 | returns \-1 if |
11c62c4c CL |
100 | .Fa stream |
101 | is not associated with a | |
102 | .Dq popened | |
103 | command, if | |
104 | .Fa stream | |
105 | already | |
106 | .Dq pclosed , | |
107 | or if | |
108 | .Xr wait4 | |
4af1c353 | 109 | returns an error. |
11c62c4c CL |
110 | .Sh ERRORS |
111 | The | |
112 | .Fn popen | |
113 | function does not reliably set | |
114 | .Va errno . | |
115 | .Sh SEE ALSO | |
116 | .Xr fork 2 , | |
117 | .Xr sh 1 , | |
118 | .Xr pipe 2 , | |
119 | .Xr wait4 2 , | |
120 | .Xr fflush 3 , | |
121 | .Xr fclose 3 , | |
122 | .Xr fopen 3 , | |
123 | .Xr stdio 3 , | |
124 | .Xr system 3 | |
125 | .Sh BUGS | |
126 | Since the standard input of a command opened for reading | |
127 | shares its seek offset with the process that called | |
128 | .Fn popen , | |
129 | if the original process has done a buffered read, | |
130 | the command's input position may not be as expected. | |
131 | Similarly, the output from a command opened for writing | |
132 | may become intermingled with that of the original process. | |
133 | The latter can be avoided by calling | |
134 | .Xr fflush 3 | |
135 | before | |
136 | .Fn popen . | |
137 | .Pp | |
138 | Failure to execute the shell | |
139 | is indistinguishable from the shell's failure to execute command, | |
140 | or an immediate exit of the command. | |
141 | The only hint is an exit status of 127. | |
142 | .Pp | |
143 | The | |
144 | .Fn popen | |
145 | argument | |
fd07beb4 | 146 | always calls |
11c62c4c | 147 | .Xr sh , |
fd07beb4 | 148 | never calls |
11c62c4c CL |
149 | .Xr csh . |
150 | .Sh HISTORY | |
151 | A | |
152 | .Fn popen | |
153 | and a | |
154 | .Fn pclose | |
155 | function appeared in | |
156 | .At v7 . |