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  2015-03-29 "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 .sp
  47 .BI "FILE *popen(const char *" command ", const char *" type );
  48 .sp
  49 .BI "int pclose(FILE *" stream );
  50 .fi
  51 .sp
  52 .in -4n
  53 Feature Test Macro Requirements for glibc (see
  54 .BR feature_test_macros (7)):
  55 .ad l
  56 .in
  57 .sp
  58 .BR popen (),
  59 .BR pclose ():
  60 .RS 4
  61 _POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE
  62 .RE
  63 .ad b
  64 .SH DESCRIPTION
  65 The
  66 .BR popen ()
  67 function opens a process by creating a pipe, forking, and invoking the
  68 shell.
  69 Since a pipe is by definition unidirectional, the
  70 .I type
  71 argument may specify only reading or writing, not both; the resulting
  72 stream is correspondingly read-only or write-only.
  73 .PP
  74 The
  75 .I command
  76 argument is a pointer to a null-terminated string containing a shell
  77 command line.
  78 This command is passed to
  79 .I /bin/sh
  80 using the
  81 .B \-c
  82 flag; interpretation, if any, is performed by the shell.
  83
  84 The
  85 .I type
  86 argument is a pointer to a null-terminated string which must contain
  87 either the letter \(aqr\(aq for reading or the letter \(aqw\(aq for writing.
  88 Since glibc 2.9,
  89 this argument can additionally include the letter \(aqe\(aq,
  90 which causes the close-on-exec flag
  91 .RB ( FD_CLOEXEC )
  92 to be set on the underlying file descriptor;
  93 see the description of the
  94 .B O_CLOEXEC
  95 flag in
  96 .BR open (2)
  97 for reasons why this may be useful.
  98 .PP
  99 The return value from
 100 .BR popen ()
 101 is a normal standard I/O stream in all respects save that it must be closed
 102 with
 103 .BR pclose ()
 104 rather than
 105 .BR fclose (3).
 106 Writing to such a stream writes to the standard input of the command; the
 107 command's standard output is the same as that of the process that called
 108 .BR popen (),
 109 unless this is altered by the command itself.
 110 Conversely, reading from
 111 the stream reads the command's standard output, and the command's
 112 standard input is the same as that of the process that called
 113 .BR popen ().
 114 .PP
 115 Note that output
 116 .BR popen ()
 117 streams are block buffered by default.
 118 .PP
 119 The
 120 .BR pclose ()
 121 function waits for the associated process to terminate and returns the exit
 122 status of the command as returned by
 123 .BR wait4 (2).
 124 .SH RETURN VALUE
 125 The
 126 .BR popen ()
 127 function returns NULL if the
 128 .BR fork (2)
 129 or
 130 .BR pipe (2)
 131 calls fail, or if it cannot allocate memory.
 132 .PP
 133 The
 134 .BR pclose ()
 135 function returns \-1 if
 136 .\" These conditions actually give undefined results, so I commented
 137 .\" them out.
 138 .\" .I stream
 139 .\" is not associated with a "popen()ed" command, if
 140 .\".I stream
 141 .\" already "pclose()d", or if
 142 .BR wait4 (2)
 143 returns an error, or some other error is detected.
 144 In the event of an error, these functions set
 145 .I errno
 146 to indicate the cause of the error.
 147 .SH ERRORS
 148 The
 149 .BR popen ()
 150 function does not set
 151 .I errno
 152 if memory allocation fails.
 153 If the underlying
 154 .BR fork (2)
 155 or
 156 .BR pipe (2)
 157 fails,
 158 .I errno
 159 is set appropriately.
 160 If the
 161 .I type
 162 argument is invalid, and this condition is detected,
 163 .I errno
 164 is set to
 165 .BR EINVAL .
 166 .PP
 167 If
 168 .BR pclose ()
 169 cannot obtain the child status,
 170 .I errno
 171 is set to
 172 .BR ECHILD .
 173 .SH ATTRIBUTES
 174 For an explanation of the terms used in this section, see
 175 .BR attributes (7).
 176 .TS
 177 allbox;
 178 lbw17 lb lb
 179 l l l.
 180 Interface       Attribute       Value
 181 T{
 182 .BR popen (),
 183 .BR pclose ()
 184 T}      Thread safety   MT-Safe
 185 .TE
 186
 187 .SH CONFORMING TO
 188 POSIX.1-2001, POSIX.1-2008.
 189
 190 The \(aqe\(aq value for
 191 .I type
 192 is a Linux extension.
 193 .SH BUGS
 194 Since the standard input of a command opened for reading shares its seek
 195 offset with the process that called
 196 .BR popen (),
 197 if the original process has done a buffered read, the command's input
 198 position may not be as expected.
 199 Similarly, the output from a command
 200 opened for writing may become intermingled with that of the original
 201 process.
 202 The latter can be avoided by calling
 203 .BR fflush (3)
 204 before
 205 .BR popen ().
 206 .PP
 207 Failure to execute the shell is indistinguishable from the shell's failure
 208 to execute command, or an immediate exit of the command.
 209 The only hint is an exit status of 127.
 210 .\" .SH HISTORY
 211 .\" A
 212 .\" .BR popen ()
 213 .\" and a
 214 .\" .BR pclose ()
 215 .\" function appeared in Version 7 AT&T UNIX.
 216 .SH SEE ALSO
 217 .BR sh (1),
 218 .BR fork (2),
 219 .BR pipe (2),
 220 .BR wait4 (2),
 221 .BR fclose (3),
 222 .BR fflush (3),
 223 .BR fopen (3),
 224 .BR stdio (3),
 225 .BR system (3)