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 con‐
       venient 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_EX‐
       EC_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 __pmProcessEx‐
       ec(3) or __pmProcessPipe.

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).

       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.

SEE ALSO

       execvp(2),  fork(2),  pclose(2),  pipe(2),  popen(2),  __pmProcessAddArg(3), __pmProcessExec(3) and wait‐
       pid(3).

Performance Co-Pilot                                   PCP                                      PMPROCESSPIPE(3)