diff options
Diffstat (limited to 'man3/popen.3')
| -rw-r--r-- | man3/popen.3 | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/man3/popen.3 b/man3/popen.3 new file mode 100644 index 000000000..0f164919a --- /dev/null +++ b/man3/popen.3 @@ -0,0 +1,168 @@ +.\" 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 +.B 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 +.B popen() +is a normal standard I/O stream in all respects save that it must be closed +with +.B 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 +.B popen +streams are fully buffered by default. +.PP +The +.B 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 +.B popen +function returns +.B NULL +if the +.BR fork (2) +or +.BR pipe (2) +calls fail, or if it cannot allocate memory. +.PP +The +.B 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 +.B wait4 +returns an error, or some other error is detected. +.SH ERRORS +The +.B popen +function does not set +.I errno +if memory allocation fails. If the underlying +.BR fork() " or " 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 +.B 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 +.B popen() +and a +.B 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) |