# popen

## PROLOG



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


## NAME



           popen — initiate pipe streams to or from a process
    


## SYNOPSIS



           #include <stdio.h>
    
           FILE *popen(const char *_command_ , const char *_mode_);
    


## DESCRIPTION



           The _popen_() function shall execute the command specified by the
           string _command_.  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 _popen_() call using the _fork_()
           function, and the child invoked the _sh_ utility using the call:
    
               execl(_shell path_ , "sh", "-c", _command_ , (char *)0);
    
           where _shell path_ is an unspecified pathname for the _sh_ utility.
    
           The _popen_() function shall ensure that any streams from previous
           _popen_() calls that remain open in the parent process are closed in
           the new child process.
    
           The _mode_ argument to _popen_() is a string that specifies I/O mode:
    
            1. If _mode_ 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 _fileno_(_stream_) in the calling
               process, where _stream_ is the stream pointer returned by
               _popen_(), shall be the readable end of the pipe.
    
            2. If _mode_ 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 _fileno_(_stream_) in the calling process,
               where _stream_ is the stream pointer returned by _popen_(), shall
               be the writable end of the pipe.
    
            3. If _mode_ is any other value, the result is unspecified.
    
           After _popen_(), both the parent and the child process shall be
           capable of executing independently before either terminates.
    
           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 the pipe.
           Otherwise, it shall return a null pointer and may set _errno_ to
           indicate the error.
    


## ERRORS



           The _popen_() function shall fail if:
    
           **EMFILE**{STREAM_MAX} streams are currently open in the calling
                  process.
    
           The _popen_() function may fail if:
    
           **EMFILE**{FOPEN_MAX} streams are currently open in the calling
                  process.
    
           **EINVAL** The _mode_ argument is invalid.
    
           The _popen_() function may also set _errno_ values as described by
           fork(3p) or pipe(3p).
    
           _The following sections are informative._
    


## EXAMPLES



       **Using popen() to Obtain a List of Files from the ls Utility**
           The following example demonstrates the use of _popen_() and _pclose_()
           to execute the command _ls_ * 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 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 fflush(3p).
    
           A stream opened by _popen_() should be closed by _pclose_().
    
           The behavior of _popen_() is specified for values of _mode_ of _r_ and
           _w_.  Other modes such as _rb_ and _wb_ might be supported by specific
           implementations, but these would not be portable features. Note
           that historical implementations of _popen_() only check to see if
           the first character of _mode_ is _r_.  Thus, a _mode_ of _robert the_
           _robot_ would be treated as _mode r_ , and a _mode_ of _anything else_
           would be treated as _mode w_.
    
           If the application calls _waitpid_() or _waitid_() with a _pid_ argument
           greater than 0, and it still has a stream that was called with
           _popen_() open, it must ensure that _pid_ does not refer to the
           process started by _popen_().
    
           To determine whether or not the environment specified in the Shell
           and Utilities volume of POSIX.1‐2017 is present, use the function
           call:
    
               sysconf(_SC_2_VERSION)
    
           (See sysconf(3p)).
    


## RATIONALE



           The _popen_() function should not be used by programs that have set
           user (or group) ID privileges. The _fork_() and _exec_ family of
           functions (except _execlp_() and _execvp_()), 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 _popen_()ed processes both intend to read or
           write or read and write a common file, and either will be using
           FILE-type C functions (_fread_(), _fwrite_(), and so on), the rules
           for sharing file handles must be observed (see _Section 2.5.1_ ,
           _Interaction of File Descriptors and Standard I/O Streams_).
    


## FUTURE DIRECTIONS



           None.
    


* * *