Return to popen.3 CVS log

Up to [cvs.NetBSD.org] / src / lib / libc / gen

Annotation of src/lib/libc/gen/popen.3, Revision 1.15

1.15    ! wiz         1: .\"    $NetBSD: popen.3,v 1.14 2004/07/14 19:12:26 kleink Exp $
1.5       cgd         2: .\"
1.3       jtc         3: .\" Copyright (c) 1991, 1993
                      4: .\"    The Regents of the University of California.  All rights reserved.
1.1       cgd         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.
1.13      agc        14: .\" 3. Neither the name of the University nor the names of its contributors
1.1       cgd        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: .\"
1.6       perry      30: .\"     @(#)popen.3    8.2 (Berkeley) 5/3/95
1.1       cgd        31: .\"
1.15    ! wiz        32: .Dd July 14, 2004
1.1       cgd        33: .Dt POPEN 3
                     34: .Os
                     35: .Sh NAME
                     36: .Nm popen ,
                     37: .Nm pclose
                     38: .Nd process
                     39: .Tn I/O
1.7       perry      40: .Sh LIBRARY
                     41: .Lb libc
1.1       cgd        42: .Sh SYNOPSIS
1.12      wiz        43: .In stdio.h
1.1       cgd        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
1.6       perry      53: a process by creating an IPC connection,
1.1       cgd        54: forking,
                     55: and invoking the shell.
1.6       perry      56: Historically,
                     57: .Nm popen
                     58: was implemented with a unidirectional pipe;
                     59: hence many implementations of
                     60: .Nm popen
                     61: only allow the
1.1       cgd        62: .Fa type
1.6       perry      63: argument to specify reading or writing, not both.
                     64: Since
                     65: .Nm popen
                     66: is now implemented using sockets, the
                     67: .Fa type
                     68: may request a bidirectional data flow.
                     69: The
                     70: .Fa type
                     71: argument is a pointer to a null-terminated string
                     72: which must be
                     73: .Ql r
                     74: for reading,
                     75: .Ql w
                     76: for writing, or
                     77: .Ql r+
                     78: for reading and writing.
1.1       cgd        79: .Pp
                     80: The
                     81: .Fa command
                     82: argument is a pointer to a null-terminated string
                     83: containing a shell command line.
                     84: This command is passed to
                     85: .Pa /bin/sh
                     86: using the
                     87: .Fl c
                     88: flag; interpretation, if any, is performed by the shell.
                     89: .Pp
                     90: The return value from
                     91: .Fn popen
                     92: is a normal standard
                     93: .Tn I/O
                     94: stream in all respects
                     95: save that it must be closed with
                     96: .Fn pclose
                     97: rather than
                     98: .Fn fclose .
                     99: Writing to such a stream
                    100: writes to the standard input of the command;
                    101: the command's standard output is the same as that of the process that called
                    102: .Fn popen ,
                    103: unless this is altered by the command itself.
                    104: Conversely, reading from a
                    105: .Dq popened
                    106: stream reads the command's standard output, and
                    107: the command's standard input is the same as that of the process that called
                    108: .Fn popen .
                    109: .Pp
                    110: Note that output
                    111: .Fn popen
                    112: streams are fully buffered by default.
                    113: .Pp
                    114: The
                    115: .Fn pclose
                    116: function waits for the associated process to terminate
                    117: and returns the exit status of the command
                    118: as returned by
                    119: .Fn wait4 .
1.9       wiz       120: .Sh RETURN VALUES
1.1       cgd       121: The
                    122: .Fn popen
                    123: function returns
                    124: .Dv NULL
                    125: if the
1.6       perry     126: .Xr fork 2 ,
                    127: .Xr pipe 2 ,
1.1       cgd       128: or
1.6       perry     129: .Xr socketpair 2
1.1       cgd       130: calls fail,
                    131: or if it cannot allocate memory.
                    132: .Pp
                    133: The
                    134: .Fn pclose
                    135: function
                    136: returns \-1 if
                    137: .Fa stream
                    138: is not associated with a
                    139: .Dq popened
                    140: command, if
                    141: .Fa stream
1.11      jmmv      142: has already been
1.1       cgd       143: .Dq pclosed ,
                    144: or if
1.8       fair      145: .Xr wait4 2
1.1       cgd       146: returns an error.
                    147: .Sh ERRORS
                    148: The
                    149: .Fn popen
                    150: function does not reliably set
                    151: .Va errno .
                    152: .Sh SEE ALSO
1.9       wiz       153: .Xr sh 1 ,
1.1       cgd       154: .Xr fork 2 ,
                    155: .Xr pipe 2 ,
1.6       perry     156: .Xr socketpair 2 ,
1.1       cgd       157: .Xr wait4 2 ,
1.9       wiz       158: .Xr fclose 3 ,
1.1       cgd       159: .Xr fflush 3 ,
                    160: .Xr fopen 3 ,
                    161: .Xr stdio 3 ,
                    162: .Xr system 3
1.14      kleink    163: .Sh STANDARDS
                    164: The
                    165: .Fn popen
                    166: and
                    167: .Fn pclose
                    168: functions conform to
                    169: .St -p1003.2-92 .
1.9       wiz       170: .Sh HISTORY
                    171: A
                    172: .Fn popen
                    173: and a
                    174: .Fn pclose
                    175: function appeared in
                    176: .At v7 .
1.1       cgd       177: .Sh BUGS
                    178: Since the standard input of a command opened for reading
                    179: shares its seek offset with the process that called
                    180: .Fn popen ,
                    181: if the original process has done a buffered read,
                    182: the command's input position may not be as expected.
                    183: Similarly, the output from a command opened for writing
                    184: may become intermingled with that of the original process.
                    185: The latter can be avoided by calling
                    186: .Xr fflush 3
                    187: before
                    188: .Fn popen .
                    189: .Pp
                    190: Failure to execute the shell
                    191: is indistinguishable from the shell's failure to execute command,
                    192: or an immediate exit of the command.
                    193: The only hint is an exit status of 127.
                    194: .Pp
                    195: The
                    196: .Fn popen
                    197: argument
                    198: always calls
1.8       fair      199: .Xr sh 1 ,
1.1       cgd       200: never calls
1.8       fair      201: .Xr csh 1 .