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 20, 2013
  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 A letter
  80 .Ql e
  81 may be appended to that to request that the underlying file descriptor
  82 be set close-on-exec.
  83 .Pp
  84 The
  85 .Fa command
  86 argument is a pointer to a null-terminated string
  87 containing a shell command line.
  88 This command is passed to
  89 .Pa /bin/sh
  90 using the
  91 .Fl c
  92 flag; interpretation, if any, is performed by the shell.
  93 .Pp
  94 The return value from
  95 .Fn popen
  96 is a normal standard
  97 .Tn I/O
  98 stream in all respects
  99 save that it must be closed with
 100 .Fn pclose
 101 rather than
 102 .Fn fclose .
 103 Writing to such a stream
 104 writes to the standard input of the command;
 105 the command's standard output is the same as that of the process that called
 106 .Fn popen ,
 107 unless this is altered by the command itself.
 108 Conversely, reading from a
 109 .Dq popened
 110 stream reads the command's standard output, and
 111 the command's standard input is the same as that of the process that called
 112 .Fn popen .
 113 .Pp
 114 Note that output
 115 .Fn popen
 116 streams are fully buffered by default.
 117 .Pp
 118 The
 119 .Fn pclose
 120 function waits for the associated process to terminate
 121 and returns the exit status of the command
 122 as returned by
 123 .Xr wait4 2 .
 124 .Sh RETURN VALUES
 125 The
 126 .Fn popen
 127 function returns
 128 .Dv NULL
 129 if the
 130 .Xr fork 2
 131 or
 132 .Xr pipe 2
 133 calls fail,
 134 or if it cannot allocate memory.
 135 .Pp
 136 The
 137 .Fn pclose
 138 function
 139 returns \-1 if
 140 .Fa stream
 141 is not associated with a
 142 .Dq popened
 143 command, if
 144 .Fa stream
 145 already
 146 .Dq pclosed ,
 147 or if
 148 .Xr wait4 2
 149 returns an error.
 150 .Sh ERRORS
 151 The
 152 .Fn popen
 153 function does not reliably set
 154 .Va errno .
 155 .Sh SEE ALSO
 156 .Xr sh 1 ,
 157 .Xr fork 2 ,
 158 .Xr pipe 2 ,
 159 .Xr wait4 2 ,
 160 .Xr fclose 3 ,
 161 .Xr fflush 3 ,
 162 .Xr fopen 3 ,
 163 .Xr stdio 3 ,
 164 .Xr system 3
 165 .Sh HISTORY
 166 A
 167 .Fn popen
 168 and a
 169 .Fn pclose
 170 function appeared in
 171 .At v7 .
 172 .Pp
 173 Bidirectional functionality was added in
 174 .Fx 2.2.6 .
 175 .Sh BUGS
 176 Since the standard input of a command opened for reading
 177 shares its seek offset with the process that called
 178 .Fn popen ,
 179 if the original process has done a buffered read,
 180 the command's input position may not be as expected.
 181 Similarly, the output from a command opened for writing
 182 may become intermingled with that of the original process.
 183 The latter can be avoided by calling
 184 .Xr fflush 3
 185 before
 186 .Fn popen .
 187 .Pp
 188 Failure to execute the shell
 189 is indistinguishable from the shell's failure to execute command,
 190 or an immediate exit of the command.
 191 The only hint is an exit status of 127.
 192 .Pp
 193 The
 194 .Fn popen
 195 function
 196 always calls
 197 .Xr sh 1 ,
 198 never calls
 199 .Xr csh 1 .