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 .\" FIXME . According to http://udrepper.livejournal.com/20407.html,
  39 .\" popen() will add support for an 'e' mode to open the pipe ends
  40 .\" with close-on-exec set; probably this will be in glibc 2.9,
  41 .\" and needs to be documented.
  42 .\"
  43 .TH POPEN 3  2008-08-29 "GNU" "Linux Programmer's Manual"
  44 .SH NAME
  45 popen, pclose \- process I/O
  46 .SH SYNOPSIS
  47 .nf
  48 .B #include <stdio.h>
  49 .sp
  50 .BI "FILE *popen(const char *" command ", const char *" type );
  51 .sp
  52 .BI "int pclose(FILE *" stream );
  53 .fi
  54 .sp
  55 .in -4n
  56 Feature Test Macro Requirements for glibc (see
  57 .BR feature_test_macros (7)):
  58 .ad l
  59 .in
  60 .sp
  61 .BR popen (),
  62 .BR pclose ():
  63 _POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE || _POSIX_SOURCE
  64 _BSD_SOURCE || _SVID_SOURCE
  65 .ad b
  66 .SH DESCRIPTION
  67 The
  68 .BR popen ()
  69 function opens a process by creating a pipe, forking, and invoking the
  70 shell.
  71 Since a pipe is by definition unidirectional, the
  72 .I type
  73 argument may specify only reading or writing, not both; the resulting
  74 stream is correspondingly read-only or write-only.
  75 .PP
  76 The
  77 .I command
  78 argument is a pointer to a null-terminated string containing a shell
  79 command line.
  80 This command is passed to
  81 .I /bin/sh
  82 using the
  83 .B \-c
  84 flag; interpretation, if any, is performed by the shell.
  85 The
  86 .I type
  87 argument is a pointer to a null-terminated string which must be either "r"
  88 for reading or "w" for writing.
  89 .PP
  90 The return value from
  91 .BR popen ()
  92 is a normal standard I/O stream in all respects save that it must be closed
  93 with
  94 .BR pclose ()
  95 rather than
  96 .BR fclose (3).
  97 Writing to such a stream writes to the standard input of the command; the
  98 command's standard output is the same as that of the process that called
  99 .BR popen (),
 100 unless this is altered by the command itself.
 101 Conversely, reading from a
 102 "popened" stream reads the command's standard output, and the command's
 103 standard input is the same as that of the process that called
 104 .BR popen ().
 105 .PP
 106 Note that output
 107 .BR popen ()
 108 streams are fully buffered by default.
 109 .PP
 110 The
 111 .BR pclose ()
 112 function waits for the associated process to terminate and returns the exit
 113 status of the command as returned by
 114 .BR wait4 (2).
 115 .SH "RETURN VALUE"
 116 The
 117 .BR popen ()
 118 function returns NULL if the
 119 .BR fork (2)
 120 or
 121 .BR pipe (2)
 122 calls fail, or if it cannot allocate memory.
 123 .PP
 124 The
 125 .BR pclose ()
 126 function returns \-1 if
 127 .\" These conditions actually give undefined results, so I commented
 128 .\" them out.
 129 .\" .I stream
 130 .\" is not associated with a "popen()ed" command, if
 131 .\".I stream
 132 .\" already "pclose()d", or if
 133 .BR wait4 (2)
 134 returns an error, or some other error is detected.
 135 .SH ERRORS
 136 The
 137 .BR popen ()
 138 function does not set
 139 .I errno
 140 if memory allocation fails.
 141 If the underlying
 142 .BR fork (2)
 143 or
 144 .BR pipe (2)
 145 fails,
 146 .I errno
 147 is set appropriately.
 148 If the
 149 .I type
 150 argument is invalid, and this condition is detected,
 151 .I errno
 152 is set to
 153 .BR EINVAL .
 154 .PP
 155 If
 156 .BR pclose ()
 157 cannot obtain the child status,
 158 .I errno
 159 is set to
 160 .BR ECHILD .
 161 .SH "CONFORMING TO"
 162 POSIX.1-2001.
 163 .SH BUGS
 164 Since the standard input of a command opened for reading shares its seek
 165 offset with the process that called
 166 .BR popen (),
 167 if the original process has done a buffered read, the command's input
 168 position may not be as expected.
 169 Similarly, the output from a command
 170 opened for writing may become intermingled with that of the original
 171 process.
 172 The latter can be avoided by calling
 173 .BR fflush (3)
 174 before
 175 .BR popen ().
 176 .PP
 177 Failure to execute the shell is indistinguishable from the shell's failure
 178 to execute command, or an immediate exit of the command.
 179 The only hint is an exit status of 127.
 180 .\" .SH HISTORY
 181 .\" A
 182 .\" .BR popen ()
 183 .\" and a
 184 .\" .BR pclose ()
 185 .\" function appeared in Version 7 AT&T UNIX.
 186 .SH "SEE ALSO"
 187 .BR sh (1),
 188 .BR fork (2),
 189 .BR pipe (2),
 190 .BR wait4 (2),
 191 .BR fclose (3),
 192 .BR fflush (3),
 193 .BR fopen (3),
 194 .BR stdio (3),
 195 .BR system (3)