man3/popen.3

   1 .\" Copyright 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   5 .\"
   6 .\"     @(#)popen.3     6.4 (Berkeley) 4/30/91
   7 .\"
   8 .\" Converted for Linux, Mon Nov 29 14:45:38 1993, faith@cs.unc.edu
   9 .\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de)
  10 .\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
  11 .\"
  12 .TH popen 3 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 popen, pclose \- pipe stream to or from a process
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <stdio.h>
  21 .PP
  22 .BI "FILE *popen(const char *" command ", const char *" type );
  23 .BI "int pclose(FILE *" stream );
  24 .fi
  25 .PP
  26 .RS -4
  27 Feature Test Macro Requirements for glibc (see
  28 .BR feature_test_macros (7)):
  29 .RE
  30 .PP
  31 .BR popen (),
  32 .BR pclose ():
  33 .nf
  34     _POSIX_C_SOURCE >= 2
  35         || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  36 .fi
  37 .SH DESCRIPTION
  38 The
  39 .BR popen ()
  40 function opens a process by creating a pipe, forking, and invoking the
  41 shell.
  42 Since a pipe is by definition unidirectional, the
  43 .I type
  44 argument may specify only reading or writing, not both; the resulting
  45 stream is correspondingly read-only or write-only.
  46 .PP
  47 The
  48 .I command
  49 argument is a pointer to a null-terminated string containing a shell
  50 command line.
  51 This command is passed to
  52 .I /bin/sh
  53 using the
  54 .B \-c
  55 flag; interpretation, if any, is performed by the shell.
  56 .PP
  57 The
  58 .I type
  59 argument is a pointer to a null-terminated string which must contain
  60 either the letter \(aqr\(aq for reading or the letter \(aqw\(aq for writing.
  61 Since glibc 2.9,
  62 this argument can additionally include the letter \(aqe\(aq,
  63 which causes the close-on-exec flag
  64 .RB ( FD_CLOEXEC )
  65 to be set on the underlying file descriptor;
  66 see the description of the
  67 .B O_CLOEXEC
  68 flag in
  69 .BR open (2)
  70 for reasons why this may be useful.
  71 .PP
  72 The return value from
  73 .BR popen ()
  74 is a normal standard I/O stream in all respects save that it must be closed
  75 with
  76 .BR pclose ()
  77 rather than
  78 .BR fclose (3).
  79 Writing to such a stream writes to the standard input of the command; the
  80 command's standard output is the same as that of the process that called
  81 .BR popen (),
  82 unless this is altered by the command itself.
  83 Conversely, reading from
  84 the stream reads the command's standard output, and the command's
  85 standard input is the same as that of the process that called
  86 .BR popen ().
  87 .PP
  88 Note that output
  89 .BR popen ()
  90 streams are block buffered by default.
  91 .PP
  92 The
  93 .BR pclose ()
  94 function waits for the associated process to terminate and returns the exit
  95 status of the command as returned by
  96 .BR wait4 (2).
  97 .SH RETURN VALUE
  98 .BR popen ():
  99 on success, returns a pointer to an open stream that
 100 can be used to read or write to the pipe;
 101 if the
 102 .BR fork (2)
 103 or
 104 .BR pipe (2)
 105 calls fail, or if the function cannot allocate memory,
 106 NULL is returned.
 107 .PP
 108 .BR pclose ():
 109 on success, returns the exit status of the command; if
 110 .\" These conditions actually give undefined results, so I commented
 111 .\" them out.
 112 .\" .I stream
 113 .\" is not associated with a "popen()ed" command, if
 114 .\".I stream
 115 .\" already "pclose()d", or if
 116 .BR wait4 (2)
 117 returns an error, or some other error is detected,
 118 \-1 is returned.
 119 .PP
 120 On failure, both functions set
 121 .I errno
 122 to indicate the error.
 123 .SH ERRORS
 124 The
 125 .BR popen ()
 126 function does not set
 127 .I errno
 128 if memory allocation fails.
 129 If the underlying
 130 .BR fork (2)
 131 or
 132 .BR pipe (2)
 133 fails,
 134 .I errno
 135 is set to indicate the error.
 136 If the
 137 .I type
 138 argument is invalid, and this condition is detected,
 139 .I errno
 140 is set to
 141 .BR EINVAL .
 142 .PP
 143 If
 144 .BR pclose ()
 145 cannot obtain the child status,
 146 .I errno
 147 is set to
 148 .BR ECHILD .
 149 .SH ATTRIBUTES
 150 For an explanation of the terms used in this section, see
 151 .BR attributes (7).
 152 .ad l
 153 .nh
 154 .TS
 155 allbox;
 156 lbx lb lb
 157 l l l.
 158 Interface       Attribute       Value
 159 T{
 160 .BR popen (),
 161 .BR pclose ()
 162 T}      Thread safety   MT-Safe
 163 .TE
 164 .hy
 165 .ad
 166 .sp 1
 167 .SH STANDARDS
 168 POSIX.1-2001, POSIX.1-2008.
 169 .PP
 170 The \(aqe\(aq value for
 171 .I type
 172 is a Linux extension.
 173 .SH NOTES
 174 .BR Note :
 175 carefully read Caveats in
 176 .BR system (3).
 177 .SH BUGS
 178 Since the standard input of a command opened for reading shares its seek
 179 offset with the process that called
 180 .BR popen (),
 181 if the original process has done a buffered read, the command's input
 182 position may not be as expected.
 183 Similarly, the output from a command
 184 opened for writing may become intermingled with that of the original
 185 process.
 186 The latter can be avoided by calling
 187 .BR fflush (3)
 188 before
 189 .BR popen ().
 190 .PP
 191 Failure to execute the shell is indistinguishable from the shell's failure
 192 to execute command, or an immediate exit of the command.
 193 The only hint is an exit status of 127.
 194 .\" .SH HISTORY
 195 .\" A
 196 .\" .BR popen ()
 197 .\" and a
 198 .\" .BR pclose ()
 199 .\" function appeared in Version 7 AT&T UNIX.
 200 .SH SEE ALSO
 201 .BR sh (1),
 202 .BR fork (2),
 203 .BR pipe (2),
 204 .BR wait4 (2),
 205 .BR fclose (3),
 206 .BR fflush (3),
 207 .BR fopen (3),
 208 .BR stdio (3),
 209 .BR system (3)