# pclose

## 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



           pclose — close a pipe stream to or from a process
    


## SYNOPSIS



           #include <stdio.h>
    
           int pclose(FILE *_stream_);
    


## DESCRIPTION



           The _pclose_() function shall close a stream that was opened by
           _popen_(), 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 _pclose_(), then _pclose_() shall return
           -1 with _errno_ set to **[ECHILD]** to report this situation. This can
           happen if the application calls one of the following functions:
    
            *  _wait_()
    
            *  _waitpid_() with a _pid_ 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‐2017
               that could do one of the above
    
           In any case, _pclose_() shall not return before the child process
           created by _popen_() has terminated.
    
           If the command language interpreter cannot be executed, the child
           termination status returned by _pclose_() shall be as if the command
           language interpreter terminated using _exit_(127) or __exit_(127).
    
           The _pclose_() function shall not affect the termination status of
           any child of the calling process other than the one created by
           _popen_() for the associated stream.
    
           If the argument _stream_ to _pclose_() is not a pointer to a stream
           created by _popen_(), the result of _pclose_() is undefined.
    
           If a thread is canceled during execution of _pclose_(), the behavior
           is undefined.
    


## RETURN VALUE



           Upon successful return, _pclose_() shall return the termination
           status of the command language interpreter. Otherwise, _pclose_()
           shall return -1 and set _errno_ to indicate the error.
    


## ERRORS



           The _pclose_() function shall fail if:
    
           **ECHILD** The status of the child process could not be obtained, as
                  described above.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           There is a requirement that _pclose_() not return before the child
           process terminates. This is intended to disallow implementations
           that return **[EINTR]** if a signal is received while waiting. If
           _pclose_() 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 _stream_ was not created by _popen_(),
           historical implementations of _pclose_() return -1 without setting
           _errno_.  To avoid requiring _pclose_() to set _errno_ in this case,
           POSIX.1‐2008 makes the behavior unspecified. An application should
           not use _pclose_() to close any stream that was not created by
           _popen_().
    
           Some historical implementations of _pclose_() 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 _pclose_() function in POSIX.1‐2008, such implementations
           are not conforming. Also, some historical implementations return
           **[EINTR]** 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:
    
               popen("command", "r")
    
           to start _command_ , which is part of the same application. The
           parent writes a prompt to its standard output (presumably the
           terminal) and then reads from the _popen_()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, _pclose_() must use _waitpid_(), or some
           similar function, instead of _wait_().
    
           The code sample below illustrates how the _pclose_() function might
           be implemented on a system conforming to POSIX.1‐2008.
    
               int pclose(FILE *stream)
               {
                   int stat;
                   pid_t pid;
    
                   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);
               }
    


## FUTURE DIRECTIONS



           None.
    


* * *