POPEN(3)                   POSIX Programmer's Manual                  POPEN(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       popen -- initiate pipe streams to or from a process

SSYYNNOOPPSSIISS
       #include <stdio.h>

       FILE *popen(const char *_c_o_m_m_a_n_d, const char *_m_o_d_e);

DDEESSCCRRIIPPTTIIOONN
       The _p_o_p_e_n() function shall execute the command specified by the string
       _c_o_m_m_a_n_d.  It shall create a pipe between the calling program and the
       executed command, and shall return a pointer to a stream that can be
       used to either read from or write to the pipe.

       The environment of the executed command shall be as if a child process
       were created within the _p_o_p_e_n() call using the _f_o_r_k() function, and the
       child invoked the _s_h utility using the call:

           eexxeeccll((_s_h_e_l_l _p_a_t_h,, ""sshh"",, ""--cc"",, _c_o_m_m_a_n_d,, ((cchhaarr **))00));;

       where _s_h_e_l_l _p_a_t_h is an unspecified pathname for the _s_h utility.

       The _p_o_p_e_n() function shall ensure that any streams from previous
       _p_o_p_e_n() calls that remain open in the parent process are closed in the
       new child process.

       The _m_o_d_e argument to _p_o_p_e_n() is a string that specifies I/O mode:

        1. If _m_o_d_e is _r, when the child process is started, its file
           descriptor STDOUT_FILENO shall be the writable end of the pipe, and
           the file descriptor _f_i_l_e_n_o(_s_t_r_e_a_m) in the calling process, where
           _s_t_r_e_a_m is the stream pointer returned by _p_o_p_e_n(), shall be the
           readable end of the pipe.

        2. If _m_o_d_e is _w, when the child process is started its file descriptor
           STDIN_FILENO shall be the readable end of the pipe, and the file
           descriptor _f_i_l_e_n_o(_s_t_r_e_a_m) in the calling process, where _s_t_r_e_a_m is
           the stream pointer returned by _p_o_p_e_n(), shall be the writable end
           of the pipe.

        3. If _m_o_d_e is any other value, the result is unspecified.

       After _p_o_p_e_n(), both the parent and the child process shall be capable
       of executing independently before either terminates.

       Pipe streams are byte-oriented.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, _p_o_p_e_n() shall return a pointer to an open
       stream that can be used to read or write to the pipe. Otherwise, it
       shall return a null pointer and may set _e_r_r_n_o to indicate the error.

EERRRROORRSS
       The _p_o_p_e_n() function shall fail if:

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

       The _p_o_p_e_n() function may fail if:

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

       EEIINNVVAALL The _m_o_d_e argument is invalid.

       The _p_o_p_e_n() function may also set _e_r_r_n_o values as described by _f_o_r_k()
       or _p_i_p_e().

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
   UUssiinngg ppooppeenn(()) ttoo OObbttaaiinn aa LLiisstt ooff FFiilleess ffrroomm tthhee llss UUttiilliittyy
       The following example demonstrates the use of _p_o_p_e_n() and _p_c_l_o_s_e() to
       execute the command _l_s* in order to obtain a list of files in the
       current directory:

           ##iinncclluuddee <<ssttddiioo..hh>>
           ......

           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() */
               ...
           }

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Since open files are shared, a mode _r command can be used as an input
       filter and a mode _w command as an output filter.

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

       A stream opened by _p_o_p_e_n() should be closed by _p_c_l_o_s_e().

       The behavior of _p_o_p_e_n() is specified for values of _m_o_d_e of _r and _w.
       Other modes such as _r_b and _w_b might be supported by specific
       implementations, but these would not be portable features. Note that
       historical implementations of _p_o_p_e_n() only check to see if the first
       character of _m_o_d_e is _r.  Thus, a _m_o_d_e of _r_o_b_e_r_t _t_h_e _r_o_b_o_t would be
       treated as _m_o_d_e _r, and a _m_o_d_e of _a_n_y_t_h_i_n_g _e_l_s_e would be treated as _m_o_d_e
       _w.

       If the application calls _w_a_i_t_p_i_d() or _w_a_i_t_i_d() with a _p_i_d argument
       greater than 0, and it still has a stream that was called with _p_o_p_e_n()
       open, it must ensure that _p_i_d does not refer to the process started by
       _p_o_p_e_n().

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

           ssyyssccoonnff((__SSCC__22__VVEERRSSIIOONN))

       (See _s_y_s_c_o_n_f()).

RRAATTIIOONNAALLEE
       The _p_o_p_e_n() function should not be used by programs that have set user
       (or group) ID privileges. The _f_o_r_k() and _e_x_e_c family of functions
       (except _e_x_e_c_l_p() and _e_x_e_c_v_p()), should be used instead. This prevents
       any unforeseen manipulation of the environment of the user that could
       cause execution of commands not anticipated by the calling program.

       If the original and _p_o_p_e_n()ed processes both intend to read or write or
       read and write a common file, and either will be using FILE-type C
       functions (_f_r_e_a_d(), _f_w_r_i_t_e(), and so on), the rules for sharing file
       handles must be observed (see _S_e_c_t_i_o_n _2_._5_._1, _I_n_t_e_r_a_c_t_i_o_n _o_f _F_i_l_e
       _D_e_s_c_r_i_p_t_o_r_s _a_n_d _S_t_a_n_d_a_r_d _I_/_O _S_t_r_e_a_m_s).

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _S_e_c_t_i_o_n _2_._5, _S_t_a_n_d_a_r_d _I_/_O _S_t_r_e_a_m_s, _f_o_r_k(), _p_c_l_o_s_e(), _p_i_p_e(), _s_y_s_c_o_n_f(),
       _s_y_s_t_e_m(), _w_a_i_t(), _w_a_i_t_i_d()

       The Base Definitions volume of POSIX.1-2008, <<ssttddiioo..hh>>

       The Shell and Utilities volume of POSIX.1-2008, _s_h

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be obtained online
       at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                             POPEN(3)
