popen() — Initiate a pipe stream to or from a process

Standards

Standards / Extensions	C or C++	Dependencies
XPG4 XPG4.2 Single UNIX Specification, Version 3	both	POSIX(ON)

Format

#define  _XOPEN_SOURCE
#include <stdio.h>

FILE *popen(const char *command, const char *mode);

General description

The popen() function executes the command specified by the string command. It creates a pipe between the calling program and the executed command, and returns a pointer to a stream that can be used to either read from or write to the pipe.

The environment of the executed command will be as if a child process were created within the popen() call using fork(), and the child invoked the sh utility using the call:

execl("/bin/sh", "sh", "-c", command, (char *)0);

The popen() function ensures that any streams from previous popen() calls that remain open in the parent process are closed in the child process.

The mode argument to popen() is a string that specifies I/O mode:

If mode is r, file descriptor STDOUT_FILENO will be the writable end of the pipe when the child process is started. The file descriptor fileno(stream) in the calling process, where stream is the stream pointer returned by popen(), will be the readable end of the pipe.
If mode is w, file descriptor STDIN_FILENO will be the readable end of the pipe when the child process is started. The file descriptor fileno(stream) in the calling process, where stream is the stream pointer returned by popen(), will be the writable end of the pipe.
If mode is any other value, a NULL pointer is returned and errno is set to EINVAL.

After popen(), both the parent and the child process will be capable of executing independently before either terminates.

Because open files are shared, a mode r command can be used as an input filter and a mode w command as an output filter.

Buffered reading before opening an input filter (that is, before popen()) may leave the standard input of that filter mispositioned. Similar problems with an output filter may be prevented by buffer flushing with fflush().

A stream opened with popen() should be closed by pclose().

The behavior of popen() is specified for values of mode of r and w. mode values of rb and wb are supported but are not portable.

If the shell command cannot be executed, the child termination status returned by pclose() will be as if the shell command terminated using exit(127) or _exit(127).

If the application calls waitpid() with a pid argument greater than 0, and it still has a stream that was created with popen() open, it must ensure that pid does not refer to the process started by popen()

The stream returned by popen() will be designated as byte-oriented.

Special behavior for file tagging and conversion: When the FILETAG(,AUTOTAG) runtime option is specified, the pipe opened for communication between the parent and child process by popen() will be tagged with the writer''s program CCSID upon first I/O. For example, if popen(some_command, "r") were specified, then the stream returned by the popen() would be tagged in the child process'' program CCSID.

Returned value

If successful, popen() returns a pointer to an open stream that can be used to read or write to a pipe.

If unsuccessful, popen() returns a NULL pointer and sets errno to one of the following values:

Error Code: Description
EINVAL: The mode argument is invalid.

popen() may also set errno values as described by spawn(), fork(), or pipe().