---
name: "__pmProcessPipe"
section: "3"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/__pmProcessPipe"
---

# \_\_pmProcessPipe(3)

support for process execution at the end of a pipe

## NAME

**\_\_pmProcessPipe**, **\_\_pmProcessPipeClose** - support for process execution at the end of a pipe

## C SYNOPSIS

**#include "pmapi.h"**\
 **#include "libpcp.h"**

**int \_\_pmProcessPipe(\_\_pmExecCtl\_t \*\****handle***,** **const char \****type***,** **int** *toss***,** **FILE \*\****fp***);**\
 **int \_\_pmProcessPipeClose(FILE \****fp***);**

**cc ... -lpcp**

## CAVEAT

This documentation is intended for internal Performance Co-Pilot (PCP) developer use.

These interfaces are not part of the PCP APIs that are guaranteed to remain fixed across releases, and they may not work, or may provide different semantics at some point in the future.

## DESCRIPTION

Within the libraries and applications of the Performance Co-Pilot (PCP) these routines are provide a convenient and safe alternative to [**popen**(3)](/popen/3.md) and [**pclose**(3)](/pclose/3.md) for executing commands in a separate process that is connected to the caller by a pipe.

Setting up the command and arguments is fully documented in [**\_\_pmProcessAddArg**(3)](/__pmProcessAddArg/3.md) and is identical to the procedure used to setup [**\_\_pmProcessExec**(3)](/__pmProcessExec/3.md).

Once all the command name and arguments have been registered calling **\_\_pmProcessPipe** uses a [**pipe**(2)](/pipe/2.md), [**fork**(2)](/fork/2.md) and **execvp**(2) sequence to execute the command.

The *type* argument needs to be **\`\`r''** to read from the pipe, else **\`\`w''** to write to the pipe.

The argument *toss* may be used to assign some or all of the standard I/O streams for the command to */dev/null* - specifically *toss* is either **PM\_EXEC\_TOSS\_NONE** to keep all I/O streams the same as the parent process, else the bit-wise or of **PM\_EXEC\_TOSS\_STDIN** and/or **PM\_EXEC\_TOSS\_STDOUT** and/or **PM\_EXEC\_TOSS\_STDERR** to reassign **stdin**, **stdout** and **stderr** respectively. **PM\_EXEC\_TOSS\_ALL** is a convenience macro equivalent to **PM\_EXEC\_TOSS\_STDIN \| PM\_EXEC\_TOSS\_STDOUT \| PM\_EXEC\_TOSS\_STDERR**.

Obviously some combinations of argument values make no sense, e.g. *type* equal to **\`\`r''** and **PM\_EXEC\_TOSS\_STDOUT** set in *toss* or *type* equal to **\`\`w''** and **PM\_EXEC\_TOSS\_STDIN** set in *type*.

**\_\_pmProcessPipe** returns a standard I/O stream for the pipe via the *fp* argument.

Once the caller determines all the work has been done, **\_\_pmProcessPipeClose** should be called.

Nested calling of [**\_\_pmProcessExec**(3)](/__pmProcessExec/3.md) and/or **\_\_pmProcessPipe** is not allowed.  Once [**\_\_pmProcessAddArg**(3)](/__pmProcessAddArg/3.md) is called with *handle* set to **NULL** to start the registration and execution sequence any attempt to start a second registration sequence will be blocked until the first one is completed by calling [**\_\_pmProcessExec**(3)](/__pmProcessExec/3.md) or **\_\_pmProcessPipe**.

**\_\_pmProcessPipe** will release any storage allocations prior to return, so there is no need for the caller to worry about memory leaks.

## DIAGNOSTICS

If successful **\_\_pmProcessPipe** returns 0.  Other conditions are rare (e.g. memory allocation failure) and are indicated by a return value that can be decoded using [**pmErrStr**(3)](/pmErrStr/3.md).

The return status from **\_\_pmProcessPipeClose** is a little more complicated. If the command completes with an exit status of 0, the return value is 0. Return values less than 0 indicate a more serious error and the value can be decoded using [**pmErrStr**(3)](/pmErrStr/3.md). If the command was executed, but did not exit with status of 0 then the return value is an encoding of the [**waitpid**(2)](/waitpid/2.md) status as follows: 2000 if something unknown went wrong, else if 1000 + signal number of the command was killed or stopped by a signal, else the exit status of the command.

## SEE ALSO

**execvp**(2), [**fork**(2)](/fork/2.md), **pclose**(2), [**pipe**(2)](/pipe/2.md), **popen**(2), [**\_\_pmProcessAddArg**(3)](/__pmProcessAddArg/3.md), [**\_\_pmProcessExec**(3)](/__pmProcessExec/3.md) and **waitpid**(3).