PCLOSE(3)                  POSIX Programmer's Manual                 PCLOSE(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
       pclose -- close a pipe stream to or from a process

SSYYNNOOPPSSIISS
       #include <stdio.h>

       int pclose(FILE *_s_t_r_e_a_m);

DDEESSCCRRIIPPTTIIOONN
       The _p_c_l_o_s_e() function shall close a stream that was opened by _p_o_p_e_n(),
       wait for the command to terminate, and return the termination status of
       the process that was running the command language interpreter.
       However, if a call caused the termination status to be unavailable to
       _p_c_l_o_s_e(), then _p_c_l_o_s_e() shall return -1 with _e_r_r_n_o set to [[EECCHHIILLDD]] to
       report this situation. This can happen if the application calls one of
       the following functions:

        *  _w_a_i_t()

        *  _w_a_i_t_p_i_d() with a _p_i_d argument less than or equal to 0 or equal to
           the process ID of the command line interpreter

        *  Any other function not defined in this volume of POSIX.1-2008 that
           could do one of the above

       In any case, _p_c_l_o_s_e() shall not return before the child process created
       by _p_o_p_e_n() has terminated.

       If the command language interpreter cannot be executed, the child
       termination status returned by _p_c_l_o_s_e() shall be as if the command
       language interpreter terminated using _e_x_i_t(127) or ___e_x_i_t(127).

       The _p_c_l_o_s_e() function shall not affect the termination status of any
       child of the calling process other than the one created by _p_o_p_e_n() for
       the associated stream.

       If the argument _s_t_r_e_a_m to _p_c_l_o_s_e() is not a pointer to a stream created
       by _p_o_p_e_n(), the result of _p_c_l_o_s_e() is undefined.

RREETTUURRNN VVAALLUUEE
       Upon successful return, _p_c_l_o_s_e() shall return the termination status of
       the command language interpreter. Otherwise, _p_c_l_o_s_e() shall return -1
       and set _e_r_r_n_o to indicate the error.

EERRRROORRSS
       The _p_c_l_o_s_e() function shall fail if:

       EECCHHIILLDD The status of the child process could not be obtained, as
              described above.

       _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
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       There is a requirement that _p_c_l_o_s_e() not return before the child
       process terminates. This is intended to disallow implementations that
       return [[EEIINNTTRR]] if a signal is received while waiting. If _p_c_l_o_s_e()
       returned before the child terminated, there would be no way for the
       application to discover which child used to be associated with the
       stream, and it could not do the cleanup itself.

       If the stream pointed to by _s_t_r_e_a_m was not created by _p_o_p_e_n(),
       historical implementations of _p_c_l_o_s_e() return -1 without setting _e_r_r_n_o.
       To avoid requiring _p_c_l_o_s_e() to set _e_r_r_n_o in this case, POSIX.1-2008
       makes the behavior unspecified. An application should not use _p_c_l_o_s_e()
       to close any stream that was not created by _p_o_p_e_n().

       Some historical implementations of _p_c_l_o_s_e() either block or ignore the
       signals SIGINT, SIGQUIT, and SIGHUP while waiting for the child process
       to terminate. Since this behavior is not described for the _p_c_l_o_s_e()
       function in POSIX.1-2008, such implementations are not conforming.
       Also, some historical implementations return [[EEIINNTTRR]] if a signal is
       received, even though the child process has not terminated. Such
       implementations are also considered non-conforming.

       Consider, for example, an application that uses:

           ppooppeenn((""ccoommmmaanndd"",, ""rr""))

       to start _c_o_m_m_a_n_d, which is part of the same application. The parent
       writes a prompt to its standard output (presumably the terminal) and
       then reads from the _p_o_p_e_n()ed stream. The child reads the response from
       the user, does some transformation on the response (pathname expansion,
       perhaps) and writes the result to its standard output. The parent
       process reads the result from the pipe, does something with it, and
       prints another prompt. The cycle repeats. Assuming that both processes
       do appropriate buffer flushing, this would be expected to work.

       To conform to POSIX.1-2008, _p_c_l_o_s_e() must use _w_a_i_t_p_i_d(), or some
       similar function, instead of _w_a_i_t().

       The code sample below illustrates how the _p_c_l_o_s_e() function might be
       implemented on a system conforming to POSIX.1-2008.

           iinntt ppcclloossee((FFIILLEE **ssttrreeaamm))
           {{
               iinntt ssttaatt;;
               ppiidd__tt ppiidd;;

               pid = <pid for process created for stream by popen()>
               (void) fclose(stream);
               while (waitpid(pid, &stat, 0) == -1) {
                   if (errno != EINTR){
                       stat = -1;
                       break;
                   }
               }
               return(stat);
           }

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _f_o_r_k(), _p_o_p_e_n(), _w_a_i_t()

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

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                            PCLOSE(3)
