original/man3/popen.3

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