xref: /dragonfly/lib/libc/gen/popen.3 (revision f2c43266) 
1.\" Copyright (c) 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
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. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     @(#)popen.3	8.2 (Berkeley) 5/3/95
29.\" $FreeBSD: src/lib/libc/gen/popen.3,v 1.10.2.4 2003/03/15 15:11:05 trhodes Exp $
30.\" $DragonFly: src/lib/libc/gen/popen.3,v 1.4 2006/04/08 08:17:06 swildner Exp $
31.\"
32.Dd May 3, 1995
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
49The
50.Fn popen
51function
52.Dq opens
53a process by creating a bidirectional pipe
54forking,
55and invoking the shell.
56Any streams opened by previous
57.Fn popen
58calls in the parent process are closed in the new child process.
59Historically,
60.Fn popen
61was implemented with a unidirectional pipe;
62hence many implementations of
63.Fn popen
64only allow the
65.Fa type
66argument to specify reading or writing, not both.
67Since
68.Fn popen
69is now implemented using a bidirectional pipe, the
70.Fa type
71argument may request a bidirectional data flow.
72The
73.Fa type
74argument is a pointer to a null-terminated string
75which must be
76.Ql r
77for reading,
78.Ql w
79for writing, or
80.Ql r+
81for reading and writing.
82.Pp
83The
84.Fa command
85argument is a pointer to a null-terminated string
86containing a shell command line.
87This command is passed to
88.Pa /bin/sh
89using the
90.Fl c
91flag; interpretation, if any, is performed by the shell.
92.Pp
93The return value from
94.Fn popen
95is a normal standard
96.Tn I/O
97stream in all respects
98save that it must be closed with
99.Fn pclose
100rather than
101.Fn fclose .
102Writing to such a stream
103writes to the standard input of the command;
104the command's standard output is the same as that of the process that called
105.Fn popen ,
106unless this is altered by the command itself.
107Conversely, reading from a
108.Dq popened
109stream reads the command's standard output, and
110the command's standard input is the same as that of the process that called
111.Fn popen .
112.Pp
113Note that output
114.Fn popen
115streams are fully buffered by default.
116.Pp
117The
118.Fn pclose
119function waits for the associated process to terminate
120and returns the exit status of the command
121as returned by
122.Fn wait4 .
123.Sh RETURN VALUES
124The
125.Fn popen
126function returns
127.Dv NULL
128if the
129.Xr fork 2
130or
131.Xr pipe 2
132calls fail,
133or if it cannot allocate memory.
134.Pp
135The
136.Fn pclose
137function
138returns \-1 if
139.Fa stream
140is not associated with a
141.Dq popened
142command, if
143.Fa stream
144already
145.Dq pclosed ,
146or if
147.Xr wait4 2
148returns an error.
149.Sh ERRORS
150The
151.Fn popen
152function does not reliably set
153.Va errno .
154.Sh SEE ALSO
155.Xr sh 1 ,
156.Xr fork 2 ,
157.Xr pipe 2 ,
158.Xr wait4 2 ,
159.Xr fclose 3 ,
160.Xr fflush 3 ,
161.Xr fopen 3 ,
162.Xr stdio 3 ,
163.Xr system 3
164.Sh HISTORY
165A
166.Fn popen
167and a
168.Fn pclose
169function appeared in
170.At v7 .
171.Pp
172Bidirectional functionality was added in
173.Fx 2.2.6 .
174.Sh BUGS
175Since the standard input of a command opened for reading
176shares its seek offset with the process that called
177.Fn popen ,
178if the original process has done a buffered read,
179the command's input position may not be as expected.
180Similarly, the output from a command opened for writing
181may become intermingled with that of the original process.
182The latter can be avoided by calling
183.Xr fflush 3
184before
185.Fn popen .
186.Pp
187Failure to execute the shell
188is indistinguishable from the shell's failure to execute command,
189or an immediate exit of the command.
190The only hint is an exit status of 127.
191.Pp
192The
193.Fn popen
194function
195always calls
196.Xr sh 1 ,
197never calls
198.Xr csh 1 .
199