popen(3C)
NAME
popen, pclose - initiate a pipe to or from a process
SYNOPSIS
#include <stdio.h>
FILE *popen(const char *command, const char *mode);
int pclose(FILE *stream);
DESCRIPTION
The popen() function creates a pipe between the calling pro-
gram and the command to be executed. The arguments to
popen() are pointers to null-terminated strings. The com-
mand argument consists of a shell command line. The mode
argument is an I/O mode, either r for reading or w for writ-
ing. 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 w, by writing to the file stream (see intro(3)); 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 may be used as an input
filter and a type w as an output filter.
The environment of the executed command will be as if a
child process were created within the popen() call using
fork(2). If the application is standard-conforming (see
standards(5)), the child is invoked with the call:
execl("/usr/xpg4/bin/sh", "sh", "-c", command, (char
*)0);
otherwise, the child is invoked with the call:
execl("/usr/bin/sh", "sh", "-c", command, (char *)0);
The pclose() function closes a stream opened by popen() by
closing the pipe. It waits for the associated process to
terminate and returns the termination status of the process
running the command language interpreter. This is the value
returned by waitpid(2). See wstat(3HEAD) for more informa-
tion on termination status.
RETURN VALUES
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 and may set errno to
indicate the error.
Upon successful completion, pclose() returns the termination
status of the command language interpreter as returned by
waitpid(). Otherwise, it returns -1 and sets errno to indi-
cate the error.
ERRORS
The popen() function may fail if:
EMFILE
There are currently FOPEN_MAX or STREAM_MAX streams
open in the calling process.
EINVAL
The mode argument is invalid.
The pclose() function will fail if:
ECHILD
The status of the child process could not be obtained,
as described above.
The popen() function may also set errno values as described
by fork(2) or pipe(2).
USAGE
If the original and popen() processes concurrently read or
write a common file, neither should use buffered I/O. Prob-
lems with an output filter may be forestalled by careful
buffer flushing, for example, with fflush() (see
fclose(3C)). A security hole exists through the IFS and PATH
environment variables. Full pathnames should be used (or
PATH reset) and IFS should be set to space and tab (" \t").
The signal handler for SIGCHLD should be set to default when
using popen(). If the process has established a signal
handler for SIGCHLD, it will be called when the command ter-
minates. If the signal handler or another thread in the
same process issues a wait(2) call, it will interfere with
the return value of pclose(). If the process's signal
handler for SIGCHLD has been set to ignore the signal,
pclose() will fail and errno will be set to ECHILD.
EXAMPLES
Example 1: popen() example
The following program will print on the standard output (see
stdio(3C)) the names of files in the current directory with
a .c suffix.
#include <stdio.h>
#include <stdlib.h>
main()
{
char *cmd = "/usr/bin/ls *.c";
char buf[BUFSIZ];
FILE *ptr;
if ((ptr = popen(cmd, "r")) != NULL)
while (fgets(buf, BUFSIZ, ptr) != NULL)
(void) printf("%s", buf);
(void) pclose(ptr);
return 0;
}
Example 2: system() replacement
The following code fragment can be used in a multithreaded
process in place of the MT-Unsafe system(3C) function:
pclose(popen(cmd, "w"));
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Standard |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
ksh(1), pipe(2), wait(2), waitpid(2), fclose(3C), fopen(3C),
stdio(3C), system(3C), wstat(3HEAD), attributes(5), stan-
dards(5)
Man(1) output converted with
man2html