pclose() — Close a pipe stream to or from a process

Standards

Standards / Extensions C or C++ Dependencies

XPG4
XPG4.2
Single UNIX Specification, Version 3

 both

POSIX(ON)

Format

#define  _XOPEN_SOURCE
#include <stdio.h>

int pclose(FILE *stream);

General description

The pclose() function closes a stream that was opened by popen(), waits for the command specified as an argument in popen() to terminate, and returns the status of the process that was running the shell command. However, if a call caused the termination status to be unavailable to pclose(), then pclose() returns -1 with errno set to ECHILD to report this situation; this can happen if the application calls one of the following functions:
  • wait()
  • waitid()
  • waitpid() with a pid argument less than or equal to the process ID of the shell command
  • any other function that could do one of the above

In any case, pclose() will not return before the child process created by popen() has terminated.

If the shell command cannot be executed, the child termination status returned by pclose() will be as if the shell command terminated using exit(127) or _exit(127).

The pclose() function will not affect the termination status of any child of the calling process other than the one created by popen() for the associated stream.

If the argument stream to pclose() is not a pointer to a stream created by popen(), the termination status returned will be -1.

Threading Behavior: The pclose() function can be executed from any thread within the parent process.

Returned value

If successful, pclose() returns the termination status of the shell command.

If unsuccessful, pclose() returns -1 and sets errno to one of the following values:
Error Code
Description
ECHILD
The status of the child process could not be obtained.

Related information

Parent topic: Library functions