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 .
CVSweb <webmaster@jp.NetBSD.org>