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



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult 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 call-
       ing 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 undefined.

       After  popen(),  both  the  parent and the child process shall be capable of executing independently before either termi-
       nates.

       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 may fail if:

       EMFILE {FOPEN_MAX} or {STREAM_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() or pipe().

       The following sections are informative.

EXAMPLES
       None.

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 prob-
       lems with an output filter may be prevented by careful buffer flushing; for example, with fflush().

       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  IEEE Std 1003.1-2001  is
       present, use the function call:


              sysconf(_SC_2_VERSION)

       (See sysconf()).

RATIONALE
       The popen() function should not be used by programs that have set user (or group) ID privileges. The fork() and exec fam-
       ily 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
       Interaction of File Descriptors and Standard I/O Streams ).

FUTURE DIRECTIONS
       None.

SEE ALSO
       pclose(),  pipe(),  sysconf(),  system(),  the  Base Definitions volume of IEEE Std 1003.1-2001, <stdio.h>, the Shell and
       Utilities volume of IEEE Std 1003.1-2001, sh

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003  Edition,  Standard  for
       Information  Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copy-
       right (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. 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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                     POPEN(3P)