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

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,
• The waitpid subroutine with a process ID less than or equal to zero or equal to the process ID of the command line interpreter, or
• Any other function that could perform one of the two 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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The fclose or fflush subroutine, fopen, freopen, or fdopen subroutine, pipe subroutine, popen subroutine, wait, waitpid, or wait3 subroutine.

Files, Directories, and File Systems for Programmers in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

Input and Output Handling Programmer's Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.