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  2013-04-19 "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 The
  84 .I type
  85 argument is a pointer to a null-terminated string which must contain
  86 either the letter \(aqr\(aq for reading or the letter \(aqw\(aq for writing.
  87 Since glibc 2.9,
  88 this argument can additionally include the letter \(aqe\(aq,
  89 which causes the close-on-exec flag
  90 .RB ( FD_CLOEXEC )
  91 to be set on the underlying file descriptor;
  92 see the description of the
  93 .B O_CLOEXEC
  94 flag in
  95 .BR open (2)
  96 for reasons why this may be useful.
  97 .PP
  98 The return value from
  99 .BR popen ()
 100 is a normal standard I/O stream in all respects save that it must be closed
 101 with
 102 .BR pclose ()
 103 rather than
 104 .BR fclose (3).
 105 Writing to such a stream writes to the standard input of the command; the
 106 command's standard output is the same as that of the process that called
 107 .BR popen (),
 108 unless this is altered by the command itself.
 109 Conversely, reading from
 110 the stream reads the command's standard output, and the command's
 111 standard input is the same as that of the process that called
 112 .BR popen ().
 113 .PP
 114 Note that output
 115 .BR popen ()
 116 streams are fully buffered by default.
 117 .PP
 118 The
 119 .BR pclose ()
 120 function waits for the associated process to terminate and returns the exit
 121 status of the command as returned by
 122 .BR wait4 (2).
 123 .SH RETURN VALUE
 124 The
 125 .BR popen ()
 126 function returns NULL if the
 127 .BR fork (2)
 128 or
 129 .BR pipe (2)
 130 calls fail, or if it cannot allocate memory.
 131 .PP
 132 The
 133 .BR pclose ()
 134 function returns \-1 if
 135 .\" These conditions actually give undefined results, so I commented
 136 .\" them out.
 137 .\" .I stream
 138 .\" is not associated with a "popen()ed" command, if
 139 .\".I stream
 140 .\" already "pclose()d", or if
 141 .BR wait4 (2)
 142 returns an error, or some other error is detected.
 143 In the event of an error, these functions set
 144 .I errno
 145 to indicate the cause of the error.
 146 .SH ERRORS
 147 The
 148 .BR popen ()
 149 function does not set
 150 .I errno
 151 if memory allocation fails.
 152 If the underlying
 153 .BR fork (2)
 154 or
 155 .BR pipe (2)
 156 fails,
 157 .I errno
 158 is set appropriately.
 159 If the
 160 .I type
 161 argument is invalid, and this condition is detected,
 162 .I errno
 163 is set to
 164 .BR EINVAL .
 165 .PP
 166 If
 167 .BR pclose ()
 168 cannot obtain the child status,
 169 .I errno
 170 is set to
 171 .BR ECHILD .
 172 .SH CONFORMING TO
 173 POSIX.1-2001.
 174
 175 The \(aqe\(aq value for
 176 .I type
 177 is a Linux extension.
 178 .SH BUGS
 179 Since the standard input of a command opened for reading shares its seek
 180 offset with the process that called
 181 .BR popen (),
 182 if the original process has done a buffered read, the command's input
 183 position may not be as expected.
 184 Similarly, the output from a command
 185 opened for writing may become intermingled with that of the original
 186 process.
 187 The latter can be avoided by calling
 188 .BR fflush (3)
 189 before
 190 .BR popen ().
 191 .PP
 192 Failure to execute the shell is indistinguishable from the shell's failure
 193 to execute command, or an immediate exit of the command.
 194 The only hint is an exit status of 127.
 195 .\" .SH HISTORY
 196 .\" A
 197 .\" .BR popen ()
 198 .\" and a
 199 .\" .BR pclose ()
 200 .\" function appeared in Version 7 AT&T UNIX.
 201 .SH SEE ALSO
 202 .BR sh (1),
 203 .BR fork (2),
 204 .BR pipe (2),
 205 .BR wait4 (2),
 206 .BR fclose (3),
 207 .BR fflush (3),
 208 .BR fopen (3),
 209 .BR stdio (3),
 210 .BR system (3)