Movatterモバイル変換

NAME

popen - initiate pipe streams to or from a process

SYNOPSIS

[CX] #include <stdio.h>

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

DESCRIPTION

Thepopen() function shall execute the command specified by the stringcommand. It shall create a pipe between thecalling program and the executed command, and shall return a pointer to a stream that can be used to either read from or write tothe pipe.

The environment of the executed command shall be as if a child process were created within thepopen() call using thefork() function, and the child invoked theshutility using the call:

execl(shell path, "sh", "-c",command, (char *)0);

whereshell path is an unspecified pathname for thesh utility.

Thepopen() function shall ensure that any streams from previouspopen() calls that remain open in the parentprocess are closed in the new child process.

Themode argument topopen() is a string that specifies I/O mode:

1. Ifmode isr, when the child process is started, its file descriptor STDOUT_FILENO shall be the writable end ofthe pipe, and the file descriptorfileno(stream) in the calling process, wherestream is the stream pointerreturned bypopen(), shall be the readable end of the pipe.

2. Ifmode isw, when the child process is started its file descriptor STDIN_FILENO shall be the readable end of thepipe, and the file descriptorfileno(stream) in the calling process, wherestream is the stream pointerreturned bypopen(), shall be the writable end of the pipe.

3. Ifmode is any other value, the result is unspecified.

Afterpopen(), both the parent and the child process shall be capable of executing independently before eitherterminates.

Pipe streams are byte-oriented.

RETURN VALUE

Upon successful completion,popen() shall return a pointer to an open stream that can be used to read or write to thepipe. Otherwise, it shall return a null pointer and may seterrno to indicate the error.

ERRORS

Thepopen() function shall fail if:

[EMFILE]

{STREAM_MAX} streams are currently open in the calling process.

Thepopen() function may fail if:

[EMFILE]

{FOPEN_MAX} streams are currently open in the calling process.

[EINVAL]

Themode argument is invalid.

Thepopen() function may also seterrno values as described byforkorpipe.

EXAMPLES

Using popen() to Obtain a List of Files from the ls Utility

The following example demonstrates the use ofpopen() andpclose() toexecute the commandls* in order to obtain a list of files in the current directory:

#include <stdio.h>...
FILE *fp;int status;char path[PATH_MAX];
fp = popen("ls *", "r");if (fp == NULL)    /* Handle error */;
while (fgets(path, PATH_MAX, fp) != NULL)    printf("%s", path);
status = pclose(fp);if (status == -1) {    /* Error reported by pclose() */    ...} else {    /* Use macros described under wait() to inspect `status' in order       to determine success/failure of command executed by popen() */    ...}

APPLICATION USAGE

Since open files are shared, a moder command can be used as an input filter and a modew command as an outputfilter.

Buffered reading before opening an input filter may leave the standard input of that filter mispositioned. Similar problems withan output filter may be prevented by careful buffer flushing; for example, withfflush.

A stream opened bypopen() should be closed bypclose().

The behavior ofpopen() is specified for values ofmode ofr andw. Other modes such asrbandwb might be supported by specific implementations, but these would not be portable features. Note that historicalimplementations ofpopen() only check to see if the first character ofmode isr. Thus, amode ofrobert the robot would be treated asmoder, and amode ofanything else would be treated asmodew.

If the application callswaitpid() orwaitid() with apid argument greater than 0, and it still has a stream that was calledwithpopen() open, it must ensure thatpid does not refer to the process started bypopen().

To determine whether or not the environment specified in the Shell and Utilities volume of POSIX.1-2017 is present, use thefunction call:

sysconf(_SC_2_VERSION)

(Seesysconf).

RATIONALE

Thepopen() function should not be used by programs that have set user (or group) ID privileges. Thefork() andexec family of functions (exceptexeclp() andexecvp()), should be usedinstead. This prevents any unforeseen manipulation of the environment of the user that could cause execution of commands notanticipated by the calling program.

If the original andpopen()ed processes both intend to read or write or read and write a common file, and either will beusing FILE-type C functions (fread(),fwrite(), and so on), the rules for sharing file handles must be observed (seeInteraction of File Descriptors and Standard I/O Streams).

FUTURE DIRECTIONS

None.

SEE ALSO

Standard I/O Streams,fork,pclose,pipe,sysconf,system,wait,waitid

XBD<stdio.h>

XCUsh

CHANGE HISTORY

First released in Issue 1. Derived from Issue 1 of the SVID.

Issue 5

A statement is added to the DESCRIPTION indicating that pipe streams are byte-oriented.

Issue 6

The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:

• The optional [EMFILE] error condition is added.

IEEE Std 1003.1-2001/Cor 2-2004, item XSH/TC2/D6/67 is applied, adding the example to the EXAMPLES section.

Issue 7

Austin Group Interpretation 1003.1-2001 #029 is applied, clarifying the values formode in the DESCRIPTION.

SD5-XSH-ERN-149 is applied, changing the {STREAM_MAX} [EMFILE] error condition from a ``may fail'' to a ``shall fail''.

POSIX.1-2008, Technical Corrigendum 1, XSH/TC1-2008/0432 [14] is applied.