popen.3s (2010 09)

p
popen(3S) popen(3S)
NAME
popen( ), pclose( ) - initiate pipe I/O to/from a process
SYNOPSIS
#include <stdio.h>
FILE *popen(const char *command, const char *type);
int pclose(FILE *stream);
DESCRIPTION
popen() creates a pipe between the calling program and a command to be executed by the POSIX shell,
/usr/bin/sh (see sh-posix (1)).
The arguments to
popen() are pointers to null-terminated strings containing, respectively, a shell com-
mand line and an I/O mode, either r
for reading or w for writing.
popen() returns a stream pointer such that one can write to the standard input of the command if the
I/O mode is w by writing to the file stream; and one can read from the standard output of the command if
the I/O mode is
r by reading from the file stream .
Because open files are shared, a type
r command can be used as an input filter and a type w command as
an output filter. If mode is other than
r or w, the result is undefined.
A stream opened by
popen() should be closed by pclose(), which waits for the associated process to
terminate and returns the exit status of the command. However, if a call caused the termination status to
be unavailable to pclose(), then pclose() returns -1 with errno set to [ECHILD]. This can happen
in one of the following conditions:
• If the signal handler for
SIGCHLD is set to SIG_IGN.
• If the signal handler or another thread in the same process issues
wait() or waitpid() call.
APPLICATION USAGE
After a stream is associated with a pipe by
popen(), the stream is byte-oriented (see orientation (5)).
RETURN VALUE
Upon successful completion,
popen() returns a pointer to an open stream that can be used to read or
write to the pipe. Otherwise, it returns a NULL pointer if files or processes cannot be created and set
errno to indicate the error. The success of the command execution can be checked by examining the
return value of pclose().
Upon successful return,
pclose() returns the termination status of the command language interpreter.
Otherwise, pclose() returns -1 if stream is not associated with a popen()’ed command and set errno
to indicate the error.
ERRORS
The
popen() function fails if:
[EMFILE] The maximum number of file descriptors allowed are currently open.
The
pclose() function fails if:
[ECHILD] The status of the child process is not available.
WARNINGS
If the original and popen()’ed processes concurrently read or write a common file, neither should use
buffered I/O because the buffering will not work properly. Problems with an output filter can be fores-
talled by careful buffer flushing, e.g., with fflush(); see fclose (3S).
SEE ALSO
pipe(2), wait(2), fclose(3S), fopen(3S), system(3S), orientation(5), thread_safety(5).
STANDARDS CONFORMANCE
popen(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2
pclose(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1