int __pmProcessAddArg(__pmExecCtl_t **
, const char *
int __pmProcessPipe(__pmExecCtl_t ** handle , const char * type , int toss , FILE ** fp );
int __pmProcessPipeClose(FILE * fp );
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.
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 .
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.