User  |  Syst  |  Libr  |  Device  |  Files  |  Other  |  Admin  |  Head  |

---

   __pmprocesspipe    ( 3 )

---

---

Имя (Name)

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

---

Синопсис C (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
       __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.

---

Диагностика (Diagnostic)

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.

---

Смотри также (See also)

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

---