pclose()

The PHP pclose() Function

The PHP pclose() function closes a process file pointer — the special stream returned by popen() when you launch an external command. Where fclose() just shuts a normal file handle, pclose() does something extra: it waits for the underlying process to finish and hands you back its exit status.

This page covers the syntax, the return value (and a subtle gotcha around it), a complete read-and-close example, and when you should reach for proc_open() instead.

Why pclose() exists

popen() runs a shell command and gives you a pipe to either feed input into it ('w' mode) or read its output ('r' mode). That pipe is backed by a real OS process. If you simply abandon the handle — or close it with the wrong function — the process can be left as a zombie and its exit code is lost. pclose() is the correct counterpart: it flushes the pipe, blocks until the child process exits, reaps it, and returns the exit code so your script can react to success or failure.

Always pair every popen() with a pclose(). Using fclose() on a popen() handle is undefined behavior.

Syntax

pclose(resource $handle): int

Parameters

The function takes a single parameter:

• $handle — the process file pointer that was returned by popen(). It is invalid to pass any other kind of resource.

Return Value

pclose() returns the termination status of the process as an integer (this is the raw value from the C pclose call — on most systems the actual exit code is in the high byte). It returns -1 if the process could not be reaped. On older PHP versions, passing an invalid handle emits a warning and returns FALSE.

To get the plain exit code on a Unix-like system, shift the value right by 8 bits:

$status   = pclose($handle);
$exitCode = $status >> 8;   // 0 means the command succeeded

Example

Open a command, read its output, then close the pipe and inspect the result:

<?php

// Run an external command and read its output.
$handle = popen('ls -la', 'r');

if ($handle === false) {
    die("Failed to start the command.\n");
}

$output = '';
while (!feof($handle)) {
    $output .= fread($handle, 1024);
}

echo $output;

// Close the pipe and capture the process exit status.
$status   = pclose($handle);
$exitCode = $status >> 8;

echo "Command exited with code: $exitCode\n";

We open a process file pointer with popen(), read the full output in a loop with fread() (a single fread may not capture everything for larger output), then close the pipe with pclose() and decode the exit code. An exit code of 0 conventionally means success.

Common pitfalls

• Don't mix fclose() and pclose(). A handle from popen() must be closed with pclose(), and a handle from fopen() with fclose().
• pclose() blocks. It waits for the child process to finish. If the command never terminates, your script hangs there.
• Read before you close. pclose() may discard any unread buffered output, so finish reading the pipe first.
• One direction per pipe. A popen() pipe is either readable or writable, not both — for two-way communication you need proc_open().

When to use proc_open() instead

popen()/pclose() are perfect for a quick one-shot command where you only need its output or need to feed it input. When you need both at once, separate stdout and stderr, environment control, or a working directory, use proc_open() — it gives you full bidirectional control over the spawned process.

Conclusion

pclose() is the required companion to popen(): it closes the process pipe, waits for the command to finish, and returns its exit status so you can verify the command succeeded. Always pair the two, read the pipe before closing it, and remember to shift the status right by 8 bits to read the real exit code on Unix systems. For anything beyond a single-direction pipe, reach for proc_open().

Practice