1.\"	$OpenBSD: popen.3,v 1.20 2016/02/05 18:09:20 espie 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.Dd $Mdocdate: February 5 2016 $
31.Dt POPEN 3
32.Os
33.Sh NAME
34.Nm popen ,
35.Nm pclose
36.Nd process I/O
37.Sh SYNOPSIS
38.In stdio.h
39.Ft FILE *
40.Fn popen "const char *command" "const char *type"
41.Ft int
42.Fn pclose "FILE *stream"
43.Sh DESCRIPTION
44The
45.Fn popen
46function
47.Dq opens
48a process by creating a pipe, forking, and invoking the shell.
49Since a pipe is by definition unidirectional, the
50.Fa type
51argument may specify only reading or writing, not both;
52the resulting stream is correspondingly read-only or write-only.
53.Pp
54The
55.Fa command
56argument is a pointer to a NUL-terminated
57string containing a shell command line.
58This command is passed to
59.Pa /bin/sh
60using the
61.Fl c
62flag; interpretation, if any, is performed by the shell.
63The
64.Fa type
65argument is a pointer to a NUL-terminated
66string which must be either
67.Qq r
68or
69.Qq re
70for reading
71or
72.Qq w
73or
74.Qq we
75for writing.
76If the letter
77.Qq e
78is present in the string then the close-on-exec flag shall be set on the
79file descriptor underlying the
80.Vt FILE
81that is returned.
82.Pp
83The return value from
84.Fn popen
85is a normal standard I/O stream in all respects
86except that it must be closed with
87.Fn pclose
88rather than
89.Xr fclose 3 .
90Writing to such a stream
91writes to the standard input of the command;
92the command's standard output is the same as that of the process that called
93.Fn popen ,
94unless this is altered by the command itself.
95Conversely, reading from a
96.Dq popened
97stream reads the command's standard output, and
98the command's standard input is the same as that of the process that called
99.Fn popen .
100.Pp
101Note that
102.Fn popen
103output streams are fully buffered by default.
104In addition, fork handlers established using
105.Xr pthread_atfork 3
106are not called when a multithreaded program calls
107.Fn popen .
108.Pp
109The
110.Fn pclose
111function waits for the associated process to terminate and returns the
112exit status of the command as returned by
113.Xr wait4 2 .
114.Sh RETURN VALUES
115The
116.Fn popen
117function returns
118.Dv NULL
119if the
120.Xr fork 2
121or
122.Xr pipe 2
123calls fail,
124or if it cannot allocate memory.
125.Pp
126The
127.Fn pclose
128function returns \-1 if
129.Fa stream
130is not associated with a
131.Dq popened
132command, if
133.Fa stream
134already
135.Dq pclosed ,
136or if
137.Xr wait4 2
138returns an error.
139.Sh ERRORS
140The
141.Fn popen
142function does not reliably set
143.Va errno .
144.Sh SEE ALSO
145.Xr sh 1 ,
146.Xr fork 2 ,
147.Xr pipe 2 ,
148.Xr wait4 2 ,
149.Xr fclose 3 ,
150.Xr fflush 3 ,
151.Xr fopen 3 ,
152.Xr stdio 3 ,
153.Xr system 3
154.Sh HISTORY
155A
156.Fn popen
157and a
158.Fn pclose
159function appeared in
160.At v7 .
161.Sh CAVEATS
162Never supply the
163.Fn popen
164function with a command containing any part of an unsanitized user-supplied
165string.
166Shell meta-characters present will be honored by the
167.Xr sh 1
168command interpreter.
169.Pp
170It is often simpler to bypass the shell entirely and use
171.Xr pipe 2 ,
172.Xr fork 2 ,
173.Xr dup2 2 ,
174.Xr execlp 3 ,
175and
176.Xr fdopen 3
177directly instead of having to sanitize a string for shell consumption.
178.Sh BUGS
179Since the standard input of a command opened for reading
180shares its seek offset with the process that called
181.Fn popen ,
182if the original process has done a buffered read,
183the command's input position may not be as expected.
184Similarly, the output from a command opened for writing
185may become intermingled with that of the original process.
186The latter can be avoided by calling
187.Xr fflush 3
188before
189.Fn popen .
190.Pp
191Failure to execute the shell is indistinguishable from the shell's
192failure to execute
193.Fa command ,
194or an immediate exit of the command.
195The only hint is an exit status of 127.
196