popen(3p)

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

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       popen — initiate pipe streams to or from a process
14

SYNOPSIS

16       #include <stdio.h>
17
18       FILE *popen(const char *command, const char *mode);
19

DESCRIPTION

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

RETURN VALUE

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

ERRORS

65       The popen() function shall fail if:
66
67       EMFILE {STREAM_MAX} streams are currently open in the calling process.
68
69       The popen() function may fail if:
70
71       EMFILE {FOPEN_MAX} streams are currently open in the calling process.
72
73       EINVAL The mode argument is invalid.
74
75       The popen() function may also set errno values as described  by  fork()
76       or pipe().
77
78       The following sections are informative.
79

EXAMPLES

81   Using popen() to Obtain a List of Files from the ls Utility
82       The  following  example demonstrates the use of popen() and pclose() to
83       execute the command ls* in order to obtain a list of files in the  cur‐
84       rent directory:
85
86           #include <stdio.h>
87           ...
88
89           FILE *fp;
90           int status;
91           char path[PATH_MAX];
92
93           fp = popen("ls *", "r");
94           if (fp == NULL)
95               /* Handle error */;
96
97           while (fgets(path, PATH_MAX, fp) != NULL)
98               printf("%s", path);
99
100           status = pclose(fp);
101           if (status == −1) {
102               /* Error reported by pclose() */
103               ...
104           } else {
105               /* Use macros described under wait() to inspect `status' in order
106                  to determine success/failure of command executed by popen() */
107               ...
108           }
109

APPLICATION USAGE

111       Since  open  files are shared, a mode r command can be used as an input
112       filter and a mode w command as an output filter.
113
114       Buffered reading before opening an input filter may leave the  standard
115       input  of  that  filter  mispositioned. Similar problems with an output
116       filter may be prevented by careful buffer flushing; for  example,  with
117       fflush().
118
119       A stream opened by popen() should be closed by pclose().
120
121       The  behavior  of  popen()  is specified for values of mode of r and w.
122       Other modes such as rb and wb might be supported by specific  implemen‐
123       tations, but these would not be portable features. Note that historical
124       implementations of popen() only check to see if the first character  of
125       mode  is  r.  Thus, a mode of robert the robot would be treated as mode
126       r, and a mode of anything else would be treated as mode w.
127
128       If the application calls waitpid() or  waitid()  with  a  pid  argument
129       greater  than 0, and it still has a stream that was called with popen()
130       open, it must ensure that pid does not refer to the process started  by
131       popen().
132
133       To  determine whether or not the environment specified in the Shell and
134       Utilities volume of POSIX.1‐2008 is present, use the function call:
135
136           sysconf(_SC_2_VERSION)
137
138       (See sysconf()).
139

RATIONALE

141       The popen() function should not be used by programs that have set  user
142       (or  group)  ID  privileges.  The  fork()  and exec family of functions
143       (except execlp() and execvp()), should be used instead.  This  prevents
144       any  unforeseen  manipulation of the environment of the user that could
145       cause execution of commands not anticipated by the calling program.
146
147       If the original and popen()ed processes both intend to read or write or
148       read  and  write  a  common  file, and either will be using FILE-type C
149       functions (fread(), fwrite(), and so on), the rules  for  sharing  file
150       handles  must  be  observed  (see  Section  2.5.1,  Interaction of File
151       Descriptors and Standard I/O Streams).
152

FUTURE DIRECTIONS

154       None.
155

COPYRIGHT

165       Portions  of  this text are reprinted and reproduced in electronic form
166       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
167       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
168       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
169       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
170       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
171       event of any discrepancy between this version and the original IEEE and
172       The Open Group Standard, the original IEEE and The Open Group  Standard
173       is  the  referee document. The original Standard can be obtained online
174       at http://www.unix.org/online.html .
175
176       Any typographical or formatting errors that appear  in  this  page  are
177       most likely to have been introduced during the conversion of the source
178       files to man page format. To report such errors,  see  https://www.ker‐
179       nel.org/doc/man-pages/reporting_bugs.html .
180
181
182
183IEEE/The Open Group                  2013                            POPEN(3P)