man3/popen.3

   1 .\" Copyright 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by the University of
  16 .\"     California, Berkeley and its contributors.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\" %%%LICENSE_END
  33 .\"
  34 .\"     @(#)popen.3     6.4 (Berkeley) 4/30/91
  35 .\"
  36 .\" Converted for Linux, Mon Nov 29 14:45:38 1993, faith@cs.unc.edu
  37 .\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de)
  38 .\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
  39 .\"
  40 .TH POPEN 3  2017-09-15 "GNU" "Linux Programmer's Manual"
  41 .SH NAME
  42 popen, pclose \- pipe stream to or from a process
  43 .SH SYNOPSIS
  44 .nf
  45 .B #include <stdio.h>
  46 .PP
  47 .BI "FILE *popen(const char *" command ", const char *" type );
  48 .PP
  49 .BI "int pclose(FILE *" stream );
  50 .fi
  51 .PP
  52 .in -4n
  53 Feature Test Macro Requirements for glibc (see
  54 .BR feature_test_macros (7)):
  55 .ad l
  56 .in
  57 .PP
  58 .BR popen (),
  59 .BR pclose ():
  60 .RS 4
  61 _POSIX_C_SOURCE\ >=\ 2
  62     || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  63 .RE
  64 .ad b
  65 .SH DESCRIPTION
  66 The
  67 .BR popen ()
  68 function opens a process by creating a pipe, forking, and invoking the
  69 shell.
  70 Since a pipe is by definition unidirectional, the
  71 .I type
  72 argument may specify only reading or writing, not both; the resulting
  73 stream is correspondingly read-only or write-only.
  74 .PP
  75 The
  76 .I command
  77 argument is a pointer to a null-terminated string containing a shell
  78 command line.
  79 This command is passed to
  80 .I /bin/sh
  81 using the
  82 .B \-c
  83 flag; interpretation, if any, is performed by the shell.
  84 .PP
  85 The
  86 .I type
  87 argument is a pointer to a null-terminated string which must contain
  88 either the letter \(aqr\(aq for reading or the letter \(aqw\(aq for writing.
  89 Since glibc 2.9,
  90 this argument can additionally include the letter \(aqe\(aq,
  91 which causes the close-on-exec flag
  92 .RB ( FD_CLOEXEC )
  93 to be set on the underlying file descriptor;
  94 see the description of the
  95 .B O_CLOEXEC
  96 flag in
  97 .BR open (2)
  98 for reasons why this may be useful.
  99 .PP
 100 The return value from
 101 .BR popen ()
 102 is a normal standard I/O stream in all respects save that it must be closed
 103 with
 104 .BR pclose ()
 105 rather than
 106 .BR fclose (3).
 107 Writing to such a stream writes to the standard input of the command; the
 108 command's standard output is the same as that of the process that called
 109 .BR popen (),
 110 unless this is altered by the command itself.
 111 Conversely, reading from
 112 the stream reads the command's standard output, and the command's
 113 standard input is the same as that of the process that called
 114 .BR popen ().
 115 .PP
 116 Note that output
 117 .BR popen ()
 118 streams are block buffered by default.
 119 .PP
 120 The
 121 .BR pclose ()
 122 function waits for the associated process to terminate and returns the exit
 123 status of the command as returned by
 124 .BR wait4 (2).
 125 .SH RETURN VALUE
 126 .BR popen ():
 127 on success, returns a pointer to an open stream that
 128 can be used to read or write to the pipe;
 129 if the
 130 .BR fork (2)
 131 or
 132 .BR pipe (2)
 133 calls fail, or if the function cannot allocate memory,
 134 NULL is returned.
 135 .PP
 136 .BR pclose ():
 137 on success, returns the exit status of the command; if
 138 .\" These conditions actually give undefined results, so I commented
 139 .\" them out.
 140 .\" .I stream
 141 .\" is not associated with a "popen()ed" command, if
 142 .\".I stream
 143 .\" already "pclose()d", or if
 144 .BR wait4 (2)
 145 returns an error, or some other error is detected,
 146 \-1 is returned.
 147 .PP
 148 Both functions set
 149 .I errno
 150 to an appropriate value in the case of an error.
 151 .SH ERRORS
 152 The
 153 .BR popen ()
 154 function does not set
 155 .I errno
 156 if memory allocation fails.
 157 If the underlying
 158 .BR fork (2)
 159 or
 160 .BR pipe (2)
 161 fails,
 162 .I errno
 163 is set appropriately.
 164 If the
 165 .I type
 166 argument is invalid, and this condition is detected,
 167 .I errno
 168 is set to
 169 .BR EINVAL .
 170 .PP
 171 If
 172 .BR pclose ()
 173 cannot obtain the child status,
 174 .I errno
 175 is set to
 176 .BR ECHILD .
 177 .SH ATTRIBUTES
 178 For an explanation of the terms used in this section, see
 179 .BR attributes (7).
 180 .TS
 181 allbox;
 182 lbw17 lb lb
 183 l l l.
 184 Interface       Attribute       Value
 185 T{
 186 .BR popen (),
 187 .BR pclose ()
 188 T}      Thread safety   MT-Safe
 189 .TE
 190 .sp 1
 191 .SH CONFORMING TO
 192 POSIX.1-2001, POSIX.1-2008.
 193 .PP
 194 The \(aqe\(aq value for
 195 .I type
 196 is a Linux extension.
 197 .SH NOTES
 198 .BR Note :
 199 carefully read Caveats in
 200 .BR system (3).
 201 .SH BUGS
 202 Since the standard input of a command opened for reading shares its seek
 203 offset with the process that called
 204 .BR popen (),
 205 if the original process has done a buffered read, the command's input
 206 position may not be as expected.
 207 Similarly, the output from a command
 208 opened for writing may become intermingled with that of the original
 209 process.
 210 The latter can be avoided by calling
 211 .BR fflush (3)
 212 before
 213 .BR popen ().
 214 .PP
 215 Failure to execute the shell is indistinguishable from the shell's failure
 216 to execute command, or an immediate exit of the command.
 217 The only hint is an exit status of 127.
 218 .\" .SH HISTORY
 219 .\" A
 220 .\" .BR popen ()
 221 .\" and a
 222 .\" .BR pclose ()
 223 .\" function appeared in Version 7 AT&T UNIX.
 224 .SH SEE ALSO
 225 .BR sh (1),
 226 .BR fork (2),
 227 .BR pipe (2),
 228 .BR wait4 (2),
 229 .BR fclose (3),
 230 .BR fflush (3),
 231 .BR fopen (3),
 232 .BR stdio (3),
 233 .BR system (3)