-.TH POPEN 3 ""
-.AT 3
-.SH NAME
-popen, pclose \- initiate I/O to/from a process
-.SH SYNOPSIS
-.B #include <stdio.h>
-.PP
-.SM
-.B FILE
-.B *popen(command, type)
-.br
-.B char *command, *type;
-.PP
-.B pclose(stream)
-.br
-.SM
-.B FILE
-.B *stream;
-.SH DESCRIPTION
-The arguments to
-.I popen
-are pointers to null-terminated strings containing respectively a
-shell command line and an I/O mode, either "r" for reading or "w" for
-writing. It creates a pipe between the calling process and
-the command to be executed. The value returned is a stream pointer that
-can be used (as appropriate) to write to the standard input
-of the command or read from its standard output.
-.PP
-A stream opened by
-.I popen
-should be closed by
-.IR pclose ,
-which waits for the associated process to terminate
-and returns the exit status of the command.
-.PP
-Because open files are shared, a type "r" command may be used as an input
-filter, and a type "w" as an output filter.
-.SH "SEE ALSO"
-sh(1), pipe(2), wait4(2), fclose(3), fopen(3), system(3)
-.SH DIAGNOSTICS
-.I Popen
-returns a null pointer if files or processes cannot be created, or the shell
-cannot be accessed.
-.PP
-.I Pclose
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\" must display the following acknowledgement:
+.\" This product includes software developed by the University of
+.\" California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\" may be used to endorse or promote products derived from this software
+.\" without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" @(#)popen.3 8.2 (Berkeley) 5/3/95
+.\"
+.Dd May 3, 1995
+.Dt POPEN 3
+.Os
+.Sh NAME
+.Nm popen ,
+.Nm pclose
+.Nd process
+.Tn I/O
+.Sh SYNOPSIS
+.Fd #include <stdio.h>
+.Ft FILE *
+.Fn popen "const char *command" "const char *type"
+.Ft int
+.Fn pclose "FILE *stream"
+.Sh DESCRIPTION
+The
+.Fn popen
+function
+.Dq opens
+a process by creating an IPC connection,
+forking,
+and invoking the shell.
+Historically,
+.Nm popen
+was implemented with a unidirectional pipe;
+hence many implementations of
+.Nm popen
+only allow the
+.Fa type
+argument to specify reading or writing, not both.
+Since
+.Nm popen
+is now implemented using sockets, the
+.Fa type
+may request a bidirectional data flow.
+The
+.Fa type
+argument is a pointer to a null-terminated string
+which must be
+.Ql r
+for reading,
+.Ql w
+for writing, or
+.Ql r+
+for reading and writing.
+.Pp
+The
+.Fa command
+argument is a pointer to a null-terminated string
+containing a shell command line.
+This command is passed to
+.Pa /bin/sh
+using the
+.Fl c
+flag; interpretation, if any, is performed by the shell.
+.Pp
+The return value from
+.Fn popen
+is a normal standard
+.Tn I/O
+stream in all respects
+save that it must be closed with
+.Fn pclose
+rather than
+.Fn fclose .
+Writing to such a stream
+writes to the standard input of the command;
+the command's standard output is the same as that of the process that called
+.Fn popen ,
+unless this is altered by the command itself.
+Conversely, reading from a
+.Dq popened
+stream reads the command's standard output, and
+the command's standard input is the same as that of the process that called
+.Fn popen .
+.Pp
+Note that output
+.Fn popen
+streams are fully buffered by default.
+.Pp
+The
+.Fn pclose
+function waits for the associated process to terminate
+and returns the exit status of the command
+as returned by
+.Fn wait4 .
+.Sh RETURN VALUE
+The
+.Fn popen
+function returns
+.Dv NULL
+if the
+.Xr fork 2 ,
+.Xr pipe 2 ,
+or
+.Xr socketpair 2
+calls fail,
+or if it cannot allocate memory.
+.Pp
+The
+.Fn pclose
+function
projects / unix-history / blobdiff