pclose Subroutine

Purpose

Closes a pipe to a process.

Library

Standard C Library (libc.a)

Syntax

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

Description

The pclose subroutine closes a pipe between the calling program and a shell command to be executed. Use the pclose subroutine to close any stream you opened with the popen subroutine. The pclose subroutine waits for the associated process to end, and then returns the exit status of the command.

Attention: If the original processes and the popen process are reading or writing a common file, neither the popen subroutine nor the pclose subroutine should use buffered I/O. If they do, the results are unpredictable.

Avoid problems with an output filter by flushing the buffer with the fflush subroutine.

Parameter

Item	Description
Stream	Specifies the FILE pointer of an opened pipe.

Return Values

The pclose subroutine returns a value of -1 if the Stream parameter is not associated with a popen command or if the status of the child process could not be obtained. Otherwise, the value of the termination status of the command language interpreter is returned; this will be 127 if the command language interpreter cannot be executed.

Error Codes

If the application has:

Called the wait subroutine,
Called the waitpid subroutine with a process ID less than or equal to zero or equal to the process ID of the command line interpreter,
Masked the SIGCHILD signal, or
Called any other function that could perform one of the steps above, and

one of these calls caused the termination status to be unavailable to the pclose subroutine, a value of -1 is returned and the errno global variable is set to ECHILD.