Open System Services Library Calls Reference Manual (G06.29+, H06.08+, J06.03+)

pclose(3) OSS Library Calls Reference Manual
NAME
pclose - Closes a pipe to a process
LIBRARY
G-series native OSS processes: /G/system/sysnn/zossesrl
32-bit H-series and J-series OSS processes: /G/system/zdllnnn/zossedll |
64-bit H-series and J-series OSS processes: /G/system/zdllnnn/yossedll |
SYNOPSIS
#include <stdio.h>
int pclose(
FILE *stream);
PARAMETERS
stream Points to a FILE structure for an open pipe returned by a previous call to the
popen( ) function.
DESCRIPTION
The pclose( ) function closes a pipe between the calling program and a shell command to be exe-
cuted. Use the pclose( ) function to close any stream you have opened with the popen( ) function.
The pclose( ) function affects only the termination status of the child process associated with the
popen( ) function’s stream.
The pclose( ) function closes the stream, waits for the associated process to end, and then returns
the exit status from the shell. Note, however, that if the application has called one of the follow-
ing functions, and one of these functions prevents the pclose( ) function from obtaining the exit
status, the pclose( ) function returns an error.
• The wait( ) function
• The waitpid( ) function with a pid parameter that is less than or equal to 0 (zero), or
equal to the command line interpreter’s OSS process ID
• Any function not in the POSIX standards that can simulate these functions
CAUTIONS
If the original processes and the process started with the popen( ) function concurrently read or
write a common file, neither should use buffered I/O. If they do, the results are unpredictable.
RETURN VALUES
The pclose( ) function does not return until the popen( ) function’s child process terminates.
Upon successful completion, the pclose( ) function returns the exit status of the shell.
If the stream parameter is not associated with a previous popen( ) call, the value -1 is returned
and errno is set to [EBADF]. If the status of the child could not be obtained, the pclose( ) func-
tion returns the value -1 and errno is set to [ECHILD].
If the command could not be executed, the pclose( ) function returns an exit status of 127 to indi-
cate the error.
ERRORS
If any of the following conditions occurs, the pclose( ) function returns the value -1 and sets
errno to the corresponding value:
[EBADF] The stream parameter is not associated with a valid file descriptor.
[ECHILD] The status of the child process could not be obtained.
5−52 Hewlett-Packard Company 527187-017