lib/libc/gen/popen.3

   1 .\"     $NetBSD: popen.3,v 1.20 2015/01/21 08:35:31 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)popen.3     8.2 (Berkeley) 5/3/95
  31 .\"
  32 .Dd January 19, 2015
  33 .Dt POPEN 3
  34 .Os
  35 .Sh NAME
  36 .Nm popen ,
  37 .Nm popenve ,
  38 .Nm pclose
  39 .Nd process
  40 .Tn I/O
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In stdio.h
  45 .Ft FILE *
  46 .Fn popen "const char *command" "const char *type"
  47 .Ft FILE *
  48 .Fn popenve "const char *path" "char * const *argv" "char * const *envp" "const char *type"
  49 .Ft int
  50 .Fn pclose "FILE *stream"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn popen
  54 function
  55 .Dq opens
  56 a process by creating an IPC connection,
  57 forking,
  58 and invoking the shell.
  59 Historically,
  60 .Nm popen
  61 was implemented with a unidirectional pipe;
  62 hence many implementations of
  63 .Nm popen
  64 only allow the
  65 .Fa type
  66 argument to specify reading or writing, not both.
  67 Since
  68 .Nm popen
  69 is now implemented using sockets, the
  70 .Fa type
  71 may request a bidirectional data flow.
  72 The
  73 .Fa type
  74 argument is a pointer to a null-terminated string
  75 which must be
  76 .Ql r
  77 for reading,
  78 .Ql w
  79 for writing, or
  80 .Ql r+
  81 for reading and writing.
  82 In addition if the character
  83 .Ql e
  84 is present in the
  85 .Fa type
  86 string, the file descriptor used internally is set to be closed on
  87 .Xr exec 3 .
  88 .Pp
  89 The
  90 .Fa command
  91 argument is a pointer to a null-terminated string
  92 containing a shell command line.
  93 This command is passed to
  94 .Pa /bin/sh
  95 using the
  96 .Fl c
  97 flag; interpretation, if any, is performed by the shell.
  98 .Pp
  99 The
 100 .Fn popenve
 101 function is similar to
 102 .Fn popen
 103 but the first three arguments are passed
 104 to
 105 .Xr execve 2
 106 and there is no shell involved in the command invocation.
 107 .Pp
 108 The return value from
 109 .Fn popen
 110 and
 111 .Fn popenve
 112 is a normal standard
 113 .Tn I/O
 114 stream in all respects
 115 save that it must be closed with
 116 .Fn pclose
 117 rather than
 118 .Fn fclose .
 119 Writing to such a stream
 120 writes to the standard input of the command;
 121 the command's standard output is the same as that of the process that called
 122 .Fn popen ,
 123 unless this is altered by the command itself.
 124 Conversely, reading from a
 125 .Dq popened
 126 stream reads the command's standard output, and
 127 the command's standard input is the same as that of the process that called
 128 .Fn popen .
 129 .Pp
 130 Note that output
 131 .Fn popen
 132 streams are fully buffered by default.
 133 .Pp
 134 The
 135 .Fn pclose
 136 function waits for the associated process to terminate
 137 and returns the exit status of the command
 138 as returned by
 139 .Fn wait4 .
 140 .Sh RETURN VALUES
 141 The
 142 .Fn popen
 143 function returns
 144 .Dv NULL
 145 if the
 146 .Xr vfork 2 ,
 147 .Xr pipe 2 ,
 148 or
 149 .Xr socketpair 2
 150 calls fail,
 151 or if it cannot allocate memory, preserving
 152 the errno from those functions.
 153 .Pp
 154 The
 155 .Fn pclose
 156 function
 157 returns \-1 if
 158 .Fa stream
 159 is not associated with a
 160 .Dq popened
 161 command, if
 162 .Fa stream
 163 has already been
 164 .Dq pclosed ,
 165 setting errno to
 166 .Dv ESRCH
 167 or if
 168 .Xr wait4 2
 169 returns an error, preserving the errno returned by
 170 .Xr wait4 2 .
 171 .Sh SEE ALSO
 172 .Xr sh 1 ,
 173 .Xr execve 2 ,
 174 .Xr fork 2 ,
 175 .Xr pipe 2 ,
 176 .Xr socketpair 2 ,
 177 .Xr wait4 2 ,
 178 .Xr fclose 3 ,
 179 .Xr fflush 3 ,
 180 .Xr fopen 3 ,
 181 .Xr shquote 3 ,
 182 .Xr stdio 3 ,
 183 .Xr system 3
 184 .Sh STANDARDS
 185 The
 186 .Fn popen
 187 and
 188 .Fn pclose
 189 functions conform to
 190 .St -p1003.2-92 .
 191 .Sh HISTORY
 192 A
 193 .Fn popen
 194 and a
 195 .Fn pclose
 196 function appeared in
 197 .At v7 .
 198 .Sh BUGS
 199 Since the standard input of a command opened for reading
 200 shares its seek offset with the process that called
 201 .Fn popen ,
 202 if the original process has done a buffered read,
 203 the command's input position may not be as expected.
 204 Similarly, the output from a command opened for writing
 205 may become intermingled with that of the original process.
 206 The latter can be avoided by calling
 207 .Xr fflush 3
 208 before
 209 .Fn popen .
 210 .Pp
 211 Failure to execute the shell
 212 is indistinguishable from the shell's failure to execute command,
 213 or an immediate exit of the command.
 214 The only hint is an exit status of 127.
 215 .Pp
 216 The
 217 .Fn popen
 218 argument
 219 always calls
 220 .Xr sh 1 ,
 221 never calls
 222 .Xr csh 1 .
 223 .Pp
 224 The
 225 .Fn popenve
 226 function first appeared in
 227 .Nx 8 .