# __pmprocesspipe

## 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)  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  **__pm‐**
           **ProcessAddArg**(3)  and  is identical to the procedure used to setup
           __pmProcessExec(3).
    
           Once all the command name and arguments have been registered call‐
           ing **__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 stan‐
           dard 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 con‐
           venience  macro  equivalent   to   **PM_EXEC_TOSS_STDIN   |   PM_EX‐**
           **EC_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,  **__pm‐**
           **ProcessPipeClose** 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  **__pm‐**
           **ProcessPipe**.
    


## DIAGNOSTICS



           If  successful  **__pmProcessPipe** returns  0.  Other conditions are
           rare (e.g. memory allocation failure) and are indicated by  a  re‐
           turn value that can be decoded using pmErrStr(3).
    
           The  return status from **__pmProcessPipeClose** is a little more com‐
           plicated.  If the command completes with an exit status of 0,  the
           return  value is 0.  Return values less than 0 indicate a more se‐
           rious 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  fol‐
           lows:  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.
    


* * *