popen(3p)

1POPEN(P)                   POSIX Programmer's Manual                  POPEN(P)
2
3
4

NAME

6       popen - initiate pipe streams to or from a process
7

SYNOPSIS

9       #include <stdio.h>
10
11       FILE *popen(const char *command, const char *mode);
12
13

DESCRIPTION

15       The  popen() function shall execute the command specified by the string
16       command. It shall create a pipe between the  calling  program  and  the
17       executed  command,  and  shall return a pointer to a stream that can be
18       used to either read from or write to the pipe.
19
20       The environment of the executed command shall be as if a child  process
21       were created within the popen() call using the fork() function, and the
22       child invoked the sh utility using the call:
23
24
25              execl(shell path, "sh", "-c", command, (char *)0);
26
27       where shell path is an unspecified pathname for the sh utility.
28
29       The popen() function  shall  ensure  that  any  streams  from  previous
30       popen()  calls that remain open in the parent process are closed in the
31       new child process.
32
33       The mode argument to popen() is a string that specifies I/O mode:
34
35        1. If mode is r, when the child process is started, its file  descrip‐
36           tor  STDOUT_FILENO  shall  be the writable end of the pipe, and the
37           file descriptor fileno(stream) in the calling process, where stream
38           is  the  stream  pointer returned by popen(), shall be the readable
39           end of the pipe.
40
41        2. If mode is w, when the child process is started its file descriptor
42           STDIN_FILENO  shall  be  the readable end of the pipe, and the file
43           descriptor fileno(stream) in the calling process, where  stream  is
44           the  stream  pointer returned by popen(), shall be the writable end
45           of the pipe.
46
47        3. If mode is any other value, the result is undefined.
48
49       After popen(), both the parent and the child process shall  be  capable
50       of executing independently before either terminates.
51
52       Pipe streams are byte-oriented.
53

RETURN VALUE

55       Upon  successful  completion, popen() shall return a pointer to an open
56       stream that can be used to read or write to  the  pipe.  Otherwise,  it
57       shall return a null pointer and may set errno to indicate the error.
58

ERRORS

60       The popen() function may fail if:
61
62       EMFILE {FOPEN_MAX}  or  {STREAM_MAX}  streams are currently open in the
63              calling process.
64
65       EINVAL The mode argument is invalid.
66
67
68       The popen() function may also set errno values as described  by  fork()
69       or pipe() .
70
71       The following sections are informative.
72

EXAMPLES

74       None.
75

APPLICATION USAGE

77       Since  open  files are shared, a mode r command can be used as an input
78       filter and a mode w command as an output filter.
79
80       Buffered reading before opening an input filter may leave the  standard
81       input  of  that  filter  mispositioned. Similar problems with an output
82       filter may be prevented by careful buffer flushing; for  example,  with
83       fflush() .
84
85       A stream opened by popen() should be closed by pclose().
86
87       The  behavior  of  popen()  is specified for values of mode of r and w.
88       Other modes such as rb and wb might be supported by specific  implemen‐
89       tations, but these would not be portable features. Note that historical
90       implementations of popen() only check to see if the first character  of
91       mode is r. Thus, a mode of robert the robot would be treated as mode r,
92       and a mode of anything else would be treated as mode w.
93
94       If the application calls waitpid() or  waitid()  with  a  pid  argument
95       greater  than 0, and it still has a stream that was called with popen()
96       open, it must ensure that pid does not refer to the process started  by
97       popen().
98
99       To  determine whether or not the environment specified in the Shell and
100       Utilities volume of IEEE Std 1003.1-2001 is present, use  the  function
101       call:
102
103
104              sysconf(_SC_2_VERSION)
105
106       (See sysconf() ).
107

RATIONALE

109       The  popen() function should not be used by programs that have set user
110       (or group) ID privileges. The  fork()  and  exec  family  of  functions
111       (except  execlp()  and execvp()), should be used instead. This prevents
112       any unforeseen manipulation of the environment of the user  that  could
113       cause execution of commands not anticipated by the calling program.
114
115       If the original and popen()ed processes both intend to read or write or
116       read and write a common file, and either  will  be  using  FILE-type  C
117       functions  (  fread(), fwrite(), and so on), the rules for sharing file
118       handles must be observed (see Interaction of File Descriptors and Stan‐
119       dard I/O Streams ).
120

FUTURE DIRECTIONS

122       None.
123

COPYRIGHT

130       Portions  of  this text are reprinted and reproduced in electronic form
131       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
132       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
133       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
134       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
135       event of any discrepancy between this version and the original IEEE and
136       The  Open Group Standard, the original IEEE and The Open Group Standard
137       is the referee document. The original Standard can be  obtained  online
138       at http://www.opengroup.org/unix/online.html .
139
140
141
142IEEE/The Open Group                  2003                             POPEN(P)