NAME

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

C SYNOPSIS

       #include "pmapi.h"
       #include "libpcp.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

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