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

NAME

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

SYNOPSIS

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

DESCRIPTION

20       The popen() function shall execute the command specified by the  string
21       command.   It  shall  create a pipe between the calling program and the
22       executed command, and shall return a pointer to a stream  that  can  be
23       used to either read from or write to the pipe.
24
25       The  environment of the executed command shall be as if a child process
26       were created within the popen() call using the fork() function, and the
27       child invoked the sh utility using the call:
28
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
87           #include <stdio.h>
88           ...
89
90           FILE *fp;
91           int status;
92           char path[PATH_MAX];
93
94           fp = popen("ls *", "r");
95           if (fp == NULL)
96               /* Handle error */;
97
98           while (fgets(path, PATH_MAX, fp) != NULL)
99               printf("%s", path);
100
101           status = pclose(fp);
102           if (status == -1) {
103               /* Error reported by pclose() */
104               ...
105           } else {
106               /* Use macros described under wait() to inspect `status' in order
107                  to determine success/failure of command executed by popen() */
108               ...
109           }
110

APPLICATION USAGE

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

RATIONALE

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

FUTURE DIRECTIONS

156       None.
157

COPYRIGHT

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