[apple/libc.git] / gen / FreeBSD / popen.3

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