2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright 1991 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 6.4 (Berkeley) 4/30/91
|
|
|
|
.\"
|
|
|
|
.\" Converted for Linux, Mon Nov 29 14:45:38 1993, faith@cs.unc.edu
|
|
|
|
.\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de)
|
|
|
|
.\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
|
|
|
|
.\"
|
|
|
|
.TH POPEN 3 1998-05-07 "BSD MANPAGE" "Linux Programmer's Manual"
|
|
|
|
.SH NAME
|
|
|
|
popen, pclose \- process I/O
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.B #include <stdio.h>
|
|
|
|
.sp
|
|
|
|
.BI "FILE *popen(const char *" command ", const char *" type );
|
|
|
|
.sp
|
|
|
|
.BI "int pclose(FILE *" stream );
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR popen ()
|
2004-11-03 13:51:07 +00:00
|
|
|
function opens a process by creating a pipe, forking, and invoking the
|
|
|
|
shell. Since a pipe is by definition unidirectional, the
|
|
|
|
.I type
|
|
|
|
argument may specify only reading or writing, not both; the resulting
|
|
|
|
stream is correspondingly read-only or write-only.
|
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.I command
|
|
|
|
argument is a pointer to a null-terminated string containing a shell
|
|
|
|
command line. This command is passed to
|
|
|
|
.I /bin/sh
|
|
|
|
using the
|
|
|
|
.B \-c
|
|
|
|
flag; interpretation, if any, is performed by the shell. The
|
|
|
|
.I type
|
|
|
|
argument is a pointer to a null-terminated string which must be either `r'
|
|
|
|
for reading or `w' for writing.
|
|
|
|
.PP
|
|
|
|
The return value from
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR popen ()
|
2004-11-03 13:51:07 +00:00
|
|
|
is a normal standard I/O stream in all respects save that it must be closed
|
|
|
|
with
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR pclose ()
|
2004-11-03 13:51:07 +00:00
|
|
|
rather than
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR fclose ().
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR popen (),
|
2004-11-03 13:51:07 +00:00
|
|
|
unless this is altered by the command itself. Conversely, reading from a
|
|
|
|
``popened'' stream reads the command's standard output, and the command's
|
|
|
|
standard input is the same as that of the process that called
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR popen ().
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
Note that output
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR popen ()
|
2004-11-03 13:51:07 +00:00
|
|
|
streams are fully buffered by default.
|
|
|
|
.PP
|
|
|
|
The
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR pclose ()
|
2004-11-03 13:51:07 +00:00
|
|
|
function waits for the associated process to terminate and returns the exit
|
|
|
|
status of the command as returned by
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR wait4 ().
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "RETURN VALUE"
|
|
|
|
The
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR popen ()
|
2005-11-02 13:55:25 +00:00
|
|
|
function returns NULL if the
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR fork (2)
|
|
|
|
or
|
|
|
|
.BR pipe (2)
|
|
|
|
calls fail, or if it cannot allocate memory.
|
|
|
|
.PP
|
|
|
|
The
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR pclose ()
|
2004-11-03 13:51:07 +00:00
|
|
|
function returns \-1 if
|
|
|
|
.\" These conditions actually give undefined results, so I commented
|
|
|
|
.\" them out.
|
|
|
|
.\" .I stream
|
2006-06-03 01:26:30 +00:00
|
|
|
.\" is not associated with a ``popen()ed'' command, if
|
2004-11-03 13:51:07 +00:00
|
|
|
.\".I stream
|
2006-06-03 01:26:30 +00:00
|
|
|
.\" already ``pclose()d'', or if
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR wait4 ()
|
2004-11-03 13:51:07 +00:00
|
|
|
returns an error, or some other error is detected.
|
|
|
|
.SH ERRORS
|
|
|
|
The
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR popen ()
|
2004-11-03 13:51:07 +00:00
|
|
|
function does not set
|
|
|
|
.I errno
|
|
|
|
if memory allocation fails. If the underlying
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR fork ()
|
|
|
|
or
|
|
|
|
.BR pipe ()
|
2004-11-03 13:51:07 +00:00
|
|
|
fails,
|
|
|
|
.I errno
|
|
|
|
is set appropriately. If the
|
|
|
|
.I type
|
|
|
|
argument is invalid, and this condition is detected,
|
|
|
|
.I errno
|
|
|
|
is set to
|
|
|
|
.BR EINVAL .
|
|
|
|
.PP
|
|
|
|
If
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR pclose ()
|
2004-11-03 13:51:07 +00:00
|
|
|
cannot obtain the child status,
|
|
|
|
.I errno
|
|
|
|
is set to
|
|
|
|
.BR ECHILD .
|
|
|
|
.SH "CONFORMING TO"
|
2006-08-03 13:57:30 +00:00
|
|
|
POSIX.1-2001.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH BUGS
|
|
|
|
Since the standard input of a command opened for reading shares its seek
|
|
|
|
offset with the process that called
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR popen (),
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
|
|
|
.BR fflush (3)
|
|
|
|
before
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR popen ().
|
2004-11-03 13:51:07 +00:00
|
|
|
.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.
|
|
|
|
.SH HISTORY
|
|
|
|
A
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR popen ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and a
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR pclose ()
|
2004-11-03 13:51:07 +00:00
|
|
|
function appeared in Version 7 AT&T UNIX.
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR sh (1),
|
|
|
|
.BR fork (2),
|
|
|
|
.BR pipe (2),
|
|
|
|
.BR wait4 (2),
|
|
|
|
.BR fclose (3),
|
|
|
|
.BR fflush (3),
|
|
|
|
.BR fopen (3),
|
|
|
|
.BR stdio (3),
|
|
|
|
.BR system (3)
|