diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/pclose.3p')
| -rw-r--r-- | man-pages-posix-2017/man3p/pclose.3p | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/pclose.3p b/man-pages-posix-2017/man3p/pclose.3p new file mode 100644 index 0000000..b9c8174 --- /dev/null +++ b/man-pages-posix-2017/man3p/pclose.3p @@ -0,0 +1,227 @@ +'\" et +.TH PCLOSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH 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. +.\" +.SH NAME +pclose +\(em close a pipe stream to or from a process +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +.P +int pclose(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The +\fIpclose\fR() +function shall close a stream that was opened by +\fIpopen\fR(), +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 +\fIpclose\fR(), +then +\fIpclose\fR() +shall return \-1 with +.IR errno +set to +.BR [ECHILD] +to report this situation. This can happen if the application calls one +of the following functions: +.IP " *" 4 +\fIwait\fR() +.IP " *" 4 +\fIwaitpid\fR() +with a +.IR pid +argument less than or equal to 0 or equal to the process ID of the +command line interpreter +.IP " *" 4 +Any other function not defined in this volume of POSIX.1\(hy2017 that could do one of the above +.P +In any case, +\fIpclose\fR() +shall not return before the child process created by +\fIpopen\fR() +has terminated. +.P +If the command language interpreter cannot be executed, the child +termination status returned by +\fIpclose\fR() +shall be as if the command language interpreter terminated using +.IR exit (127) +or +.IR _exit (127). +.P +The +\fIpclose\fR() +function shall not affect the termination status of any child of the +calling process other than the one created by +\fIpopen\fR() +for the associated stream. +.P +If the argument +.IR stream +to +\fIpclose\fR() +is not a pointer to a stream created by +\fIpopen\fR(), +the result of +\fIpclose\fR() +is undefined. +.P +If a thread is canceled during execution of +\fIpclose\fR(), +the behavior is undefined. +.SH "RETURN VALUE" +Upon successful return, +\fIpclose\fR() +shall return the termination status of the command language +interpreter. Otherwise, +\fIpclose\fR() +shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIpclose\fR() +function shall fail if: +.TP +.BR ECHILD +The status of the child process could not be obtained, as described +above. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +There is a requirement that +\fIpclose\fR() +not return before the child process terminates. This is intended to +disallow implementations that return +.BR [EINTR] +if a signal is received while waiting. If +\fIpclose\fR() +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. +.P +If the stream pointed to by +.IR stream +was not created by +\fIpopen\fR(), +historical implementations of +\fIpclose\fR() +return \-1 without setting +.IR errno . +To avoid requiring +\fIpclose\fR() +to set +.IR errno +in this case, POSIX.1\(hy2008 makes the behavior unspecified. An application +should not use +\fIpclose\fR() +to close any stream that was not created by +\fIpopen\fR(). +.P +Some historical implementations of +\fIpclose\fR() +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 +\fIpclose\fR() +function in POSIX.1\(hy2008, such implementations are not conforming. Also, some +historical implementations return +.BR [EINTR] +if a signal is received, even though the child process has not +terminated. Such implementations are also considered non-conforming. +.P +Consider, for example, an application that uses: +.sp +.RS 4 +.nf + +popen("command", "r") +.fi +.P +.RE +.P +to start +.IR 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 +\fIpopen\fR()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. +.P +To conform to POSIX.1\(hy2008, +\fIpclose\fR() +must use +\fIwaitpid\fR(), +or some similar function, instead of +\fIwait\fR(). +.P +The code sample below illustrates how the +\fIpclose\fR() +function might be implemented on a system conforming to POSIX.1\(hy2008. +.sp +.RS 4 +.nf + +int pclose(FILE *stream) +{ + int stat; + pid_t pid; +.P + 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); +} +.fi +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfork\fR\^(\|)", +.IR "\fIpopen\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<stdio.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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.opengroup.org/unix/online.html . +.PP +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 . |