NAME | C SYNOPSIS | CAVEAT | DESCRIPTION | SEE ALSO | DIAGNOSTICS | COLOPHON

PMPROCESSPIPE(3)          Library Functions Manual          PMPROCESSPIPE(3)

NAME         top

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

C SYNOPSIS         top

       #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         top

       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         top

       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         top

       execvp(2), fork(2), pclose(2), pipe(2), popen(2),
       __pmProcessAddArg(3), __pmProcessExec(3) and waitpid(3).

DIAGNOSTICS         top

       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.

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@groups.io.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2017-11-25.  (At that time, the date of the most recent commit that
       was found in the repository was 2017-11-24.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Performance Co-Pilot                 PCP                    PMPROCESSPIPE(3)

Pages that refer to this page: __pmprocessexec(3)