diff options
Diffstat (limited to 'man/man3/popen.3')
| -rw-r--r-- | man/man3/popen.3 | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/man/man3/popen.3 b/man/man3/popen.3 new file mode 100644 index 000000000..c56d938e4 --- /dev/null +++ b/man/man3/popen.3 @@ -0,0 +1,208 @@ +'\" t +.\" Copyright 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)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 (date) "Linux man-pages (unreleased)" +.SH NAME +popen, pclose \- pipe stream to or from a process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "FILE *popen(const char *" command ", const char *" type ); +.BI "int pclose(FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR popen (), +.BR pclose (): +.nf + _POSIX_C_SOURCE >= 2 + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.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. +.P +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. +.P +The +.I type +argument is a pointer to a null-terminated string which must contain +either the letter \[aq]r\[aq] for reading or the letter \[aq]w\[aq] for writing. +Since glibc 2.9, +this argument can additionally include the letter \[aq]e\[aq], +which causes the close-on-exec flag +.RB ( FD_CLOEXEC ) +to be set on the underlying file descriptor; +see the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.P +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 (3). +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 +the 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 (). +.P +Note that output +.BR popen () +streams are block buffered by default. +.P +The +.BR pclose () +function waits for the associated process to terminate and returns the exit +status of the command as returned by +.BR wait4 (2). +.SH RETURN VALUE +.BR popen (): +on success, returns a pointer to an open stream that +can be used to read or write to the pipe; +if the +.BR fork (2) +or +.BR pipe (2) +calls fail, or if the function cannot allocate memory, +NULL is returned. +.P +.BR pclose (): +on success, returns the exit status of the command; if +.\" These conditions actually give undefined results, so I commented +.\" them out. +.\" .I stream +.\" is not associated with a "popen()ed" command, if +.\".I stream +.\" already "pclose()d", or if +.BR wait4 (2) +returns an error, or some other error is detected, +\-1 is returned. +.P +On failure, both functions set +.I errno +to indicate the error. +.SH ERRORS +The +.BR popen () +function does not set +.I errno +if memory allocation fails. +If the underlying +.BR fork (2) +or +.BR pipe (2) +fails, +.I errno +is set to indicate the error. +If the +.I type +argument is invalid, and this condition is detected, +.I errno +is set to +.BR EINVAL . +.P +If +.BR pclose () +cannot obtain the child status, +.I errno +is set to +.BR ECHILD . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR popen (), +.BR pclose () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The \[aq]e\[aq] value for +.I type +is a Linux extension. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH CAVEATS +Carefully read Caveats in +.BR system (3). +.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 (). +.P +Failure to execute the shell is indistinguishable from the shell's failure +to execute the 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) |