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 .\"     @(#)popen.3     8.2 (Berkeley) 5/3/95
  29 .\" $FreeBSD: src/lib/libc/gen/popen.3,v 1.10.2.4 2003/03/15 15:11:05 trhodes Exp $
  30 .\" $DragonFly: src/lib/libc/gen/popen.3,v 1.4 2006/04/08 08:17:06 swildner Exp $
  31 .\"
  32 .Dd May 3, 1995
  33 .Dt POPEN 3
  34 .Os
  35 .Sh NAME
  36 .Nm popen ,
  37 .Nm pclose
  38 .Nd process
  39 .Tn I/O
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In stdio.h
  44 .Ft FILE *
  45 .Fn popen "const char *command" "const char *type"
  46 .Ft int
  47 .Fn pclose "FILE *stream"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn popen
  51 function
  52 .Dq opens
  53 a process by creating a bidirectional pipe
  54 forking,
  55 and invoking the shell.
  56 Any streams opened by previous
  57 .Fn popen
  58 calls in the parent process are closed in the new child process.
  59 Historically,
  60 .Fn popen
  61 was implemented with a unidirectional pipe;
  62 hence many implementations of
  63 .Fn popen
  64 only allow the
  65 .Fa type
  66 argument to specify reading or writing, not both.
  67 Since
  68 .Fn popen
  69 is now implemented using a bidirectional pipe, the
  70 .Fa type
  71 argument 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 .Pp
  83 The
  84 .Fa command
  85 argument is a pointer to a null-terminated string
  86 containing a shell command line.
  87 This command is passed to
  88 .Pa /bin/sh
  89 using the
  90 .Fl c
  91 flag; interpretation, if any, is performed by the shell.
  92 .Pp
  93 The return value from
  94 .Fn popen
  95 is a normal standard
  96 .Tn I/O
  97 stream in all respects
  98 save that it must be closed with
  99 .Fn pclose
 100 rather than
 101 .Fn fclose .
 102 Writing to such a stream
 103 writes to the standard input of the command;
 104 the command's standard output is the same as that of the process that called
 105 .Fn popen ,
 106 unless this is altered by the command itself.
 107 Conversely, reading from a
 108 .Dq popened
 109 stream reads the command's standard output, and
 110 the command's standard input is the same as that of the process that called
 111 .Fn popen .
 112 .Pp
 113 Note that output
 114 .Fn popen
 115 streams are fully buffered by default.
 116 .Pp
 117 The
 118 .Fn pclose
 119 function waits for the associated process to terminate
 120 and returns the exit status of the command
 121 as returned by
 122 .Fn wait4 .
 123 .Sh RETURN VALUES
 124 The
 125 .Fn popen
 126 function returns
 127 .Dv NULL
 128 if the
 129 .Xr fork 2
 130 or
 131 .Xr pipe 2
 132 calls fail,
 133 or if it cannot allocate memory.
 134 .Pp
 135 The
 136 .Fn pclose
 137 function
 138 returns \-1 if
 139 .Fa stream
 140 is not associated with a
 141 .Dq popened
 142 command, if
 143 .Fa stream
 144 already
 145 .Dq pclosed ,
 146 or if
 147 .Xr wait4 2
 148 returns an error.
 149 .Sh ERRORS
 150 The
 151 .Fn popen
 152 function does not reliably set
 153 .Va errno .
 154 .Sh SEE ALSO
 155 .Xr sh 1 ,
 156 .Xr fork 2 ,
 157 .Xr pipe 2 ,
 158 .Xr wait4 2 ,
 159 .Xr fclose 3 ,
 160 .Xr fflush 3 ,
 161 .Xr fopen 3 ,
 162 .Xr stdio 3 ,
 163 .Xr system 3
 164 .Sh HISTORY
 165 A
 166 .Fn popen
 167 and a
 168 .Fn pclose
 169 function appeared in
 170 .At v7 .
 171 .Pp
 172 Bidirectional functionality was added in
 173 .Fx 2.2.6 .
 174 .Sh BUGS
 175 Since the standard input of a command opened for reading
 176 shares its seek offset with the process that called
 177 .Fn popen ,
 178 if the original process has done a buffered read,
 179 the command's input position may not be as expected.
 180 Similarly, the output from a command opened for writing
 181 may become intermingled with that of the original process.
 182 The latter can be avoided by calling
 183 .Xr fflush 3
 184 before
 185 .Fn popen .
 186 .Pp
 187 Failure to execute the shell
 188 is indistinguishable from the shell's failure to execute command,
 189 or an immediate exit of the command.
 190 The only hint is an exit status of 127.
 191 .Pp
 192 The
 193 .Fn popen
 194 function
 195 always calls
 196 .Xr sh 1 ,
 197 never calls
 198 .Xr csh 1 .