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

NNAAMMEE
     ppooppeenn, ppcclloossee - process I/O

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ssttddiioo..hh>>

     _F_I_L_E _*
     ppooppeenn(_c_o_n_s_t _c_h_a_r _*_c_o_m_m_a_n_d, _c_o_n_s_t _c_h_a_r _*_t_y_p_e)

     _i_n_t
     ppcclloossee(_F_I_L_E _*_s_t_r_e_a_m)

DDEESSCCRRIIPPTTIIOONN
     The ppooppeenn() function ``opens'' a process by creating a pipe, forking, and
     invoking the shell.  Since a pipe is by definition unidirectional, the
     _t_y_p_e argument may specify only reading or writing, not both; the result-
     ing stream is correspondingly read-only or write-only.

     The _c_o_m_m_a_n_d argument is a pointer to a null-terminated string containing
     a shell command line.  This command is passed to _/_b_i_n_/_s_h using the --cc
     flag; interpretation, if any, is performed by the shell.  The _m_o_d_e argu-
     ment is a pointer to a null-terminated string which must be either `r'
     for reading or `w' for writing.

     The return value from ppooppeenn() is a normal standard I/O stream in all re-
     spects save that it must be closed with ppcclloossee() rather than ffcclloossee().
     Writing to such a stream writes to the standard input of the command; the
     command's standard output is the same as that of the process that called
     ppooppeenn(), unless this is altered by the command itself.  Conversely, read-
     ing from a ``popened'' stream reads the command's standard output, and
     the command's standard input is the same as that of the process that
     called ppooppeenn().

     Note that output ppooppeenn() streams are fully buffered by default.

     The ppcclloossee() function waits for the associated process to terminate and
     returns the exit status of the command as returned by wwaaiitt44().

RREETTUURRNN VVAALLUUEE
     The ppooppeenn() function returns NULL if the fork(2) or pipe(2) calls fail,
     or if it cannot allocate memory.

     The ppcclloossee() function returns -1 if _s_t_r_e_a_m is not associated with a
     ``popened'' command, if _s_t_r_e_a_m already ``pclosed'', or if wait4 returns
     an error.

EERRRROORRSS
     The ppooppeenn() function does not reliably set _e_r_r_n_o.

SSEEEE AALLSSOO
     fork(2),  sh(1),  pipe(2),  wait4(2),  fflush(3),  fclose(3),  fopen(3),
     stdio(3),  system(3)

BBUUGGSS
     Since the standard input of a command opened for reading shares its seek
     offset with the process that called ppooppeenn(), if the original process has
     done a buffered read, the command's input position may not be as expect-
     ed.  Similarly, the output from a command opened for writing may become
     intermingled with that of the original process.  The latter can be avoid-
     ed by calling fflush(3) before ppooppeenn().


     Failure to execute the shell is indistinguishable from the shell's fail-
     ure to execute command, or an immediate exit of the command.  The only
     hint is an exit status of 127.

     The ppooppeenn() argument always calls sh,  never calls csh.

HHIISSTTOORRYY
     A ppooppeenn() and a ppcclloossee() function appeared in Version 7 AT&T UNIX.

BSD Experimental                April 30, 1991                               2

























































