pdp11v/usr/man/u_man/man3/popen.3s

.TH POPEN 3S
.SH NAME
popen, pclose \- initiate pipe 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 int 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
.B "r"
for reading or
.B "w"
for writing.
.I Popen\^
creates a pipe between the calling program and the command to be executed.
The value returned 
is a stream pointer such that
one can write to the standard input
of the command,
if the I/O mode is
.BR "w" ,
by writing to the file
.IR stream ;
and one can read from the standard output of the command,
if the I/O mode is
.BR  "r" ,
by reading from the file
.IR stream .
.PP
A stream opened by
.I popen\^
should be closed by
.IR 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
.B "r"
command
may be used as an input filter
and a type
.B "w"
as an output filter.
.SH "SEE ALSO"
pipe(2),
wait(2),
fclose(3S),
fopen(3S),
system(3S).
.SH DIAGNOSTICS
.I Popen\^
returns a
.SM NULL
pointer
if files or processes cannot be created, or if the shell 
cannot be accessed.
.PP
.I Pclose\^
returns \-1 if
.I stream\^
is not associated with a
.RI `` popen\^ ed''
command.
.SH BUGS
If the original and
.RI `` popen\^ ed''
processes concurrently read or write a common file,
neither should use buffered I/O, because the buffering
gets all mixed up.
Problems with an output filter may be
forestalled by careful buffer flushing, e.g. with
.IR fflush ;
see
.IR fclose (3S).
.\"	@(#)popen.3s	5.2 of 5/18/82