| .\" Copyright 1991 The Regents of the University of California. |
| .\" All rights reserved. |
| .\" |
| .\" 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 6.4 (Berkeley) 4/30/91 |
| .\" |
| .\" Converted for Linux, Mon Nov 29 14:45:38 1993, faith@cs.unc.edu |
| .\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de) |
| .\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) |
| .\" |
| .TH POPEN 3 1998-05-07 "BSD MANPAGE" "Linux Programmer's Manual" |
| .SH NAME |
| popen, pclose \- process I/O |
| .SH SYNOPSIS |
| .B #include <stdio.h> |
| .sp |
| .BI "FILE *popen(const char *" command ", const char *" type ); |
| .sp |
| .BI "int pclose(FILE *" stream ); |
| .SH DESCRIPTION |
| The |
| .BR popen () |
| function opens a process by creating a pipe, forking, and invoking the |
| shell. Since a pipe is by definition unidirectional, the |
| .I type |
| argument may specify only reading or writing, not both; the resulting |
| stream is correspondingly read-only or write-only. |
| .PP |
| The |
| .I command |
| argument is a pointer to a null-terminated string containing a shell |
| command line. This command is passed to |
| .I /bin/sh |
| using the |
| .B \-c |
| flag; interpretation, if any, is performed by the shell. The |
| .I type |
| argument is a pointer to a null-terminated string which must be either `r' |
| for reading or `w' for writing. |
| .PP |
| The return value from |
| .BR popen () |
| is a normal standard I/O stream in all respects save that it must be closed |
| with |
| .BR pclose () |
| rather than |
| .BR 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 |
| .BR popen (), |
| unless this is altered by the command itself. Conversely, reading from a |
| ``popened'' stream reads the command's standard output, and the command's |
| standard input is the same as that of the process that called |
| .BR popen (). |
| .PP |
| Note that output |
| .BR popen () |
| streams are fully buffered by default. |
| .PP |
| The |
| .BR pclose () |
| function waits for the associated process to terminate and returns the exit |
| status of the command as returned by |
| .BR wait4 (). |
| .SH "RETURN VALUE" |
| The |
| .BR popen () |
| function returns NULL if the |
| .BR fork (2) |
| or |
| .BR pipe (2) |
| calls fail, or if it cannot allocate memory. |
| .PP |
| The |
| .BR pclose () |
| function returns \-1 if |
| .\" These conditions actually give undefined results, so I commented |
| .\" them out. |
| .\" .I stream |
| .\" is not associated with a ``popened'' command, if |
| .\".I stream |
| .\" already ``pclosed'', or if |
| .BR wait4 () |
| returns an error, or some other error is detected. |
| .SH ERRORS |
| The |
| .BR popen () |
| function does not set |
| .I errno |
| if memory allocation fails. If the underlying |
| .BR fork () |
| or |
| .BR pipe () |
| fails, |
| .I errno |
| is set appropriately. If the |
| .I type |
| argument is invalid, and this condition is detected, |
| .I errno |
| is set to |
| .BR EINVAL . |
| .PP |
| If |
| .BR pclose () |
| cannot obtain the child status, |
| .I errno |
| is set to |
| .BR ECHILD . |
| .SH "CONFORMING TO" |
| POSIX.2 |
| .SH BUGS |
| Since the standard input of a command opened for reading shares its seek |
| offset with the process that called |
| .BR popen (), |
| if the original process has done a buffered read, the command's input |
| position may not be as expected. Similarly, the output from a command |
| opened for writing may become intermingled with that of the original |
| process. The latter can be avoided by calling |
| .BR fflush (3) |
| before |
| .BR popen (). |
| .PP |
| Failure to execute the shell is indistinguishable from the shell's failure |
| to execute command, or an immediate exit of the command. The only hint is |
| an exit status of 127. |
| .SH HISTORY |
| A |
| .BR popen () |
| and a |
| .BR pclose () |
| function appeared in Version 7 AT&T UNIX. |
| .SH "SEE ALSO" |
| .BR sh (1), |
| .BR fork (2), |
| .BR pipe (2), |
| .BR wait4 (2), |
| .BR fclose (3), |
| .BR fflush (3), |
| .BR fopen (3), |
| .BR stdio (3), |
| .BR system (3) |