diff options
Diffstat (limited to 'man3/popen.3')
| -rw-r--r-- | man3/popen.3 | 208 |
1 files changed, 0 insertions, 208 deletions
diff --git a/man3/popen.3 b/man3/popen.3 deleted file mode 100644 index 6c2cd00..0000000 --- a/man3/popen.3 +++ /dev/null @@ -1,208 +0,0 @@ -'\" 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 2023-10-31 "Linux man-pages 6.7" -.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) |