PMPROCESSPIPE

Section: C Library Functions (3)
Index Return to Main Contents

NAME

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

C SYNOPSIS

#include < pcp/pmapi.h >
#include < pcp/impl.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

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.


Index

NAME
C SYNOPSIS
DESCRIPTION
SEE ALSO
DIAGNOSTICS