| .\" Copyright 1991 The Regents of the University of California. |
| .\" All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" 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. |
| .\" %%%LICENSE_END |
| .\" |
| .\" @(#)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 2021-03-22 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| popen, pclose \- pipe stream to or from a process |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdio.h> |
| .PP |
| .BI "FILE *popen(const char *" command ", const char *" type ); |
| .BI "int pclose(FILE *" stream ); |
| .fi |
| .PP |
| .RS -4 |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .RE |
| .PP |
| .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. |
| .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. |
| .PP |
| The |
| .I type |
| argument is a pointer to a null-terminated string which must contain |
| either the letter \(aqr\(aq for reading or the letter \(aqw\(aq for writing. |
| Since glibc 2.9, |
| this argument can additionally include the letter \(aqe\(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. |
| .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 (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 (). |
| .PP |
| Note that output |
| .BR popen () |
| streams are block 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 (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. |
| .PP |
| .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. |
| .PP |
| 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 . |
| .PP |
| 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). |
| .ad l |
| .nh |
| .TS |
| allbox; |
| lbx lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR popen (), |
| .BR pclose () |
| T} Thread safety MT-Safe |
| .TE |
| .hy |
| .ad |
| .sp 1 |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008. |
| .PP |
| The \(aqe\(aq value for |
| .I type |
| is a Linux extension. |
| .SH NOTES |
| .BR Note : |
| 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 (). |
| .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) |
