[unix-history] / usr / src / lib / libc / gen / popen.3

.\"	@(#)popen.3	4.1 (Berkeley) %G%
.\"
.TH POPEN 3S
.AT 3
.SH NAME
popen, pclose \- initiate I/O to/from a process
.SH SYNOPSIS
.B #include <stdio.h>
.PP
.SM
.B FILE
.B *popen(command, type)
.br
.B char *command, *type;
.PP
.B pclose(stream)
.br
.SM
.B FILE
.B *stream;
.SH DESCRIPTION
The arguments to 
.I popen
are pointers to null-terminated strings
containing respectively a shell command line and an I/O
mode, either "r" for reading or "w" for
writing.
It creates a pipe between
the calling process and
the command to be executed.
The value returned 
is a stream pointer that
can be used (as appropriate) to write to the standard input
of the command or read from its standard output.
.PP
A stream opened by
.I popen
should be closed by
.I pclose,
which waits for the associated process to terminate
and returns the exit status of the command.
.PP
Because open files are shared, a type "r" command
may be used as an input filter,
and a type "w" as an output filter.
.SH "SEE ALSO"
pipe(2),
fopen(3),
fclose(3),
system(3),
wait(2)
.SH DIAGNOSTICS
.I Popen
returns a null pointer
if files or processes cannot be created, or the Shell 
cannot be accessed.
.PP
.I Pclose
returns \-1 if
.I stream
is not associated with a `popened' command.
.SH BUGS
Buffered reading before opening an input filter
may leave the standard input of that filter mispositioned.
Similar problems with an output filter may be
forestalled by careful buffer flushing, e.g. with
.I fflush,
see
.IR fclose (3).
Commit	Line	Data
fa528602 KM	1	.\" @(#)popen.3 4.1 (Berkeley) %G%
	2	.\"
	3	.TH POPEN 3S
	4	.AT 3
	5	.SH NAME
	6	popen, pclose \- initiate I/O to/from a process
	7	.SH SYNOPSIS
	8	.B #include <stdio.h>
	9	.PP
	10	.SM
	11	.B FILE
	12	.B *popen(command, type)
	13	.br
	14	.B char command, type;
	15	.PP
	16	.B pclose(stream)
	17	.br
	18	.SM
	19	.B FILE
	20	.B *stream;
	21	.SH DESCRIPTION
	22	The arguments to
	23	.I popen
	24	are pointers to null-terminated strings
	25	containing respectively a shell command line and an I/O
	26	mode, either "r" for reading or "w" for
	27	writing.
	28	It creates a pipe between
	29	the calling process and
	30	the command to be executed.
	31	The value returned
	32	is a stream pointer that
	33	can be used (as appropriate) to write to the standard input
	34	of the command or read from its standard output.
	35	.PP
	36	A stream opened by
	37	.I popen
	38	should be closed by
	39	.I pclose,
	40	which waits for the associated process to terminate
	41	and returns the exit status of the command.
	42	.PP
	43	Because open files are shared, a type "r" command
	44	may be used as an input filter,
	45	and a type "w" as an output filter.
	46	.SH "SEE ALSO"
	47	pipe(2),
	48	fopen(3),
	49	fclose(3),
	50	system(3),
	51	wait(2)
	52	.SH DIAGNOSTICS
	53	.I Popen
	54	returns a null pointer
	55	if files or processes cannot be created, or the Shell
	56	cannot be accessed.
	57	.PP
	58	.I Pclose
	59	returns \-1 if
	60	.I stream
	61	is not associated with a `popened' command.
	62	.SH BUGS
	63	Buffered reading before opening an input filter
	64	may leave the standard input of that filter mispositioned.
65	Similar problems with an output filter may be
66	forestalled by careful buffer flushing, e.g. with
67	.I fflush,
68	see
69	.IR fclose (3).