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.