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 command 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 forestalled by careful buffer flushing, e.g., with fflush(); see fclose(3S).

STANDARDS CONFORMANCE

popen(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2

pclose(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2

popen(3S)

Technical documentation

» Table of Contents

» Index