1PCLOSE(3P)                 POSIX Programmer's Manual                PCLOSE(3P)
2
3
4

PROLOG

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

NAME

12       pclose — close a pipe stream to or from a process
13

SYNOPSIS

15       #include <stdio.h>
16
17       int pclose(FILE *stream);
18

DESCRIPTION

20       The pclose() function shall close a stream that was opened by  popen(),
21       wait for the command to terminate, and return the termination status of
22       the process that was running the command  language  interpreter.   How‐
23       ever,  if  a  call  caused  the termination status to be unavailable to
24       pclose(), then pclose() shall return -1 with errno set to  [ECHILD]  to
25       report  this situation. This can happen if the application calls one of
26       the following functions:
27
28        *  wait()
29
30        *  waitpid() with a pid argument less than or equal to 0 or  equal  to
31           the process ID of the command line interpreter
32
33        *  Any  other function not defined in this volume of POSIX.1‐2017 that
34           could do one of the above
35
36       In any case, pclose() shall not return before the child process created
37       by popen() has terminated.
38
39       If  the command language interpreter cannot be executed, the child ter‐
40       mination status returned by pclose() shall be as if  the  command  lan‐
41       guage interpreter terminated using exit(127) or _exit(127).
42
43       The  pclose()  function  shall not affect the termination status of any
44       child of the calling process other than the one created by popen()  for
45       the associated stream.
46
47       If the argument stream to pclose() is not a pointer to a stream created
48       by popen(), the result of pclose() is undefined.
49
50       If a thread is canceled during execution of pclose(), the  behavior  is
51       undefined.
52

RETURN VALUE

54       Upon successful return, pclose() shall return the termination status of
55       the command language interpreter. Otherwise, pclose() shall  return  -1
56       and set errno to indicate the error.
57

ERRORS

59       The pclose() function shall fail if:
60
61       ECHILD The  status  of  the  child  process  could  not be obtained, as
62              described above.
63
64       The following sections are informative.
65

EXAMPLES

67       None.
68

APPLICATION USAGE

70       None.
71

RATIONALE

73       There is a requirement  that  pclose()  not  return  before  the  child
74       process  terminates.  This is intended to disallow implementations that
75       return [EINTR] if a signal  is  received  while  waiting.  If  pclose()
76       returned  before  the  child  terminated, there would be no way for the
77       application to discover which child used  to  be  associated  with  the
78       stream, and it could not do the cleanup itself.
79
80       If the stream pointed to by stream was not created by popen(), histori‐
81       cal implementations of pclose() return -1 without  setting  errno.   To
82       avoid  requiring pclose() to set errno in this case, POSIX.1‐2008 makes
83       the behavior unspecified. An application should  not  use  pclose()  to
84       close any stream that was not created by popen().
85
86       Some  historical implementations of pclose() either block or ignore the
87       signals SIGINT, SIGQUIT, and SIGHUP while waiting for the child process
88       to  terminate.  Since  this  behavior is not described for the pclose()
89       function in POSIX.1‐2008,  such  implementations  are  not  conforming.
90       Also,  some  historical  implementations  return [EINTR] if a signal is
91       received, even though the child process has not terminated. Such imple‐
92       mentations are also considered non-conforming.
93
94       Consider, for example, an application that uses:
95
96
97           popen("command", "r")
98
99       to  start  command,  which  is part of the same application. The parent
100       writes a prompt to its standard output (presumably  the  terminal)  and
101       then reads from the popen()ed stream. The child reads the response from
102       the user, does some transformation on the response (pathname expansion,
103       perhaps)  and  writes  the  result  to  its standard output. The parent
104       process reads the result from the pipe, does  something  with  it,  and
105       prints  another prompt. The cycle repeats. Assuming that both processes
106       do appropriate buffer flushing, this would be expected to work.
107
108       To conform to POSIX.1‐2008, pclose() must use waitpid(), or some  simi‐
109       lar function, instead of wait().
110
111       The  code  sample  below illustrates how the pclose() function might be
112       implemented on a system conforming to POSIX.1‐2008.
113
114
115           int pclose(FILE *stream)
116           {
117               int stat;
118               pid_t pid;
119
120               pid = <pid for process created for stream by popen()>
121               (void) fclose(stream);
122               while (waitpid(pid, &stat, 0) == -1) {
123                   if (errno != EINTR){
124                       stat = -1;
125                       break;
126                   }
127               }
128               return(stat);
129           }
130

FUTURE DIRECTIONS

132       None.
133

SEE ALSO

135       fork(), popen(), wait()
136
137       The Base Definitions volume of POSIX.1‐2017, <stdio.h>
138
140       Portions of this text are reprinted and reproduced in  electronic  form
141       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
142       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
143       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
144       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
145       event of any discrepancy between this version and the original IEEE and
146       The Open Group Standard, the original IEEE and The Open Group  Standard
147       is  the  referee document. The original Standard can be obtained online
148       at http://www.opengroup.org/unix/online.html .
149
150       Any typographical or formatting errors that appear  in  this  page  are
151       most likely to have been introduced during the conversion of the source
152       files to man page format. To report such errors,  see  https://www.ker
153       nel.org/doc/man-pages/reporting_bugs.html .
154
155
156
157IEEE/The Open Group                  2017                           PCLOSE(3P)
Impressum