lib/libc/gen/popen.3

   1 .\" Copyright (c) 1991, 1993
   2 .\"     The Regents of the University of California.  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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd May 3, 1995
  29 .Dt POPEN 3
  30 .Os
  31 .Sh NAME
  32 .Nm popen ,
  33 .Nm pclose
  34 .Nd process
  35 .Tn I/O
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In stdio.h
  40 .Ft FILE *
  41 .Fn popen "const char *command" "const char *type"
  42 .Ft int
  43 .Fn pclose "FILE *stream"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn popen
  47 function
  48 .Dq opens
  49 a process by creating a bidirectional pipe
  50 forking,
  51 and invoking the shell.
  52 Any streams opened by previous
  53 .Fn popen
  54 calls in the parent process are closed in the new child process.
  55 Historically,
  56 .Fn popen
  57 was implemented with a unidirectional pipe;
  58 hence many implementations of
  59 .Fn popen
  60 only allow the
  61 .Fa type
  62 argument to specify reading or writing, not both.
  63 Since
  64 .Fn popen
  65 is now implemented using a bidirectional pipe, the
  66 .Fa type
  67 argument may request a bidirectional data flow.
  68 The
  69 .Fa type
  70 argument is a pointer to a null-terminated string
  71 which must be
  72 .Ql r
  73 for reading,
  74 .Ql w
  75 for writing, or
  76 .Ql r+
  77 for reading and writing.
  78 .Pp
  79 The
  80 .Fa type
  81 argument may be augmented by appending an
  82 .Ql e
  83 to set the descriptor's close-on-exec flag.
  84 For example,
  85 .Ql re
  86 for reading,
  87 .Ql we
  88 for writing, or
  89 .Ql r+e
  90 for reading and writing.
  91 Use of this flag is important when operating in threaded environments.
  92 .Pp
  93 The
  94 .Fa command
  95 argument is a pointer to a null-terminated string
  96 containing a shell command line.
  97 This command is passed to
  98 .Pa /bin/sh
  99 using the
 100 .Fl c
 101 flag; interpretation, if any, is performed by the shell.
 102 .Pp
 103 The return value from
 104 .Fn popen
 105 is a normal standard
 106 .Tn I/O
 107 stream in all respects
 108 save that it must be closed with
 109 .Fn pclose
 110 rather than
 111 .Fn fclose .
 112 Writing to such a stream
 113 writes to the standard input of the command;
 114 the command's standard output is the same as that of the process that called
 115 .Fn popen ,
 116 unless this is altered by the command itself.
 117 Conversely, reading from a
 118 .Dq popened
 119 stream reads the command's standard output, and
 120 the command's standard input is the same as that of the process that called
 121 .Fn popen .
 122 .Pp
 123 Note that output
 124 .Fn popen
 125 streams are fully buffered by default.
 126 .Pp
 127 .Fn popen
 128 automatically interlocks and closes descriptors associated with other
 129 active
 130 .Fn popen
 131 files in any sub-process it creates, preventing file descriptor leakage
 132 between
 133 .Fn popen
 134 calls in a thread-safe manner.
 135 However,
 136 .Fn popen
 137 has no control over fork or fork/exec sequences run by other threads which
 138 do not use the popen mechanism and in this situation it is likely that
 139 popen descriptors will leak into those sub-processes.
 140 It is recommended that the
 141 .Ql e
 142 flag be used to prevent descriptor leakages into miscellanious fork/exec
 143 sequences that might be executed by other threads in a multi-threaded
 144 program.
 145 .Pp
 146 The
 147 .Fn pclose
 148 function waits for the associated process to terminate
 149 and returns the exit status of the command
 150 as returned by
 151 .Fn wait4 .
 152 .Sh RETURN VALUES
 153 The
 154 .Fn popen
 155 function returns
 156 .Dv NULL
 157 if the
 158 .Xr fork 2
 159 or
 160 .Xr pipe 2
 161 calls fail,
 162 or if it cannot allocate memory.
 163 .Pp
 164 The
 165 .Fn pclose
 166 function
 167 returns \-1 if
 168 .Fa stream
 169 is not associated with a
 170 .Dq popened
 171 command, if
 172 .Fa stream
 173 already
 174 .Dq pclosed ,
 175 or if
 176 .Xr wait4 2
 177 returns an error.
 178 .Sh ERRORS
 179 The
 180 .Fn popen
 181 function does not reliably set
 182 .Va errno .
 183 .Sh SEE ALSO
 184 .Xr sh 1 ,
 185 .Xr fork 2 ,
 186 .Xr pipe 2 ,
 187 .Xr wait4 2 ,
 188 .Xr fclose 3 ,
 189 .Xr fflush 3 ,
 190 .Xr fopen 3 ,
 191 .Xr stdio 3 ,
 192 .Xr system 3
 193 .Sh HISTORY
 194 A
 195 .Fn popen
 196 and a
 197 .Fn pclose
 198 function appeared in
 199 .At v7 .
 200 .Pp
 201 Bidirectional functionality was added in
 202 .Fx 2.2.6 .
 203 .Sh BUGS
 204 Since the standard input of a command opened for reading
 205 shares its seek offset with the process that called
 206 .Fn popen ,
 207 if the original process has done a buffered read,
 208 the command's input position may not be as expected.
 209 Similarly, the output from a command opened for writing
 210 may become intermingled with that of the original process.
 211 The latter can be avoided by calling
 212 .Xr fflush 3
 213 before
 214 .Fn popen .
 215 .Pp
 216 Failure to execute the shell
 217 is indistinguishable from the shell's failure to execute command,
 218 or an immediate exit of the command.
 219 The only hint is an exit status of 127.
 220 .Pp
 221 The
 222 .Fn popen
 223 function
 224 always calls
 225 .Xr sh 1 ,
 226 never calls
 227 .Xr csh 1 .