PMPROCESSPIPE(3)

NAME
__pmProcessPipe, __pmProcessClosePipe - support for process execution at the end of a pipe

C SYNOPSIS
#include <pcp/pmapi.h>
#include <pcp/impl.h>

int __pmProcessAddArg(__pmExecCtl_t **handle, const char *arg);
int __pmProcessPipe(__pmExecCtl_t **handle, const char *type, int toss, FILE **fp);
int __pmProcessPipeClose(FILE *fp);

cc ... -lpcp

DESCRIPTION

Within the libraries and applications of the Performance Co-Pilot (PCP) these routines are provide a convenient and safe alternative to popen(3) and pclose(3) 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) and is identical to the procedure used to setup __pmProcessExec(3).

Once all the command name and arguments have been registered calling __pmProcessPipe uses a pipe (2), fork (2) 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) and/or __pmProcessPipe is not allowed. Once __pmProcessAddArg(3) 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) or __pmProcessPipe.

SEE ALSO
execvp(2), fork(2), pclose(2), pipe(2), popen(2), __pmProcessAddArg(3), __pmProcessExec(3) and waitpid(3).

DIAGNOSTICS
If successful __pmProcessPipe returns 0. Other conditions are rare (e.g. alloc failure) and are indicated by a return value that can be decoded using pmErrStr(3).

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). If the command was executed, but did not exit with status of 0 then the return value is an encoding of the waitpid(2) 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.