1PMPROCESSPIPE(3)           Library Functions Manual           PMPROCESSPIPE(3)
2
3
4

NAME

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

C SYNOPSIS

10       #include "pmapi.h"
11       #include "libpcp.h"
12
13       int __pmProcessAddArg(__pmExecCtl_t **handle, const char *arg);
14       int __pmProcessPipe(__pmExecCtl_t **handle, const char *type, int toss,
15       FILE **fp);
16       int __pmProcessPipeClose(FILE *fp);
17
18       cc ... -lpcp
19

CAVEAT

21       This  documentation is intended for internal Performance Co-Pilot (PCP)
22       developer use.
23
24       These interfaces are not part of the PCP APIs that  are  guaranteed  to
25       remain  fixed  across  releases,  and they may not work, or may provide
26       different semantics at some point in the future.
27

DESCRIPTION

29       Within the libraries and applications of the Performance Co-Pilot (PCP)
30       these  routines  are  provide  a  convenient  and  safe  alternative to
31       popen(3) and pclose(3) for executing commands  in  a  separate  process
32       that is connected to the caller by a pipe.
33
34       Setting up the command and arguments is fully documented in __pmProces‐
35       sAddArg(3) and is identical to the procedure used to setup  __pmProces‐
36       sExec(3).
37
38       Once  all  the  command name and arguments have been registered calling
39       __pmProcessPipe uses a pipe (2), fork (2) and execvp  (2)  sequence  to
40       execute the command.
41
42       The  type  argument needs to be ``r'' to read from the pipe, else ``w''
43       to write to the pipe.
44
45       The argument toss may be used to assign some or all of the standard I/O
46       streams  for  the  command  to  /dev/null - specifically toss is either
47       PM_EXEC_TOSS_NONE to keep all  I/O  streams  the  same  as  the  parent
48       process,   else   the   bit-wise   or   of   PM_EXEC_TOSS_STDIN  and/or
49       PM_EXEC_TOSS_STDOUT and/or PM_EXEC_TOSS_STDERR to reassign stdin,  std‐
50       out  and  stderr respectively.  PM_EXEC_TOSS_ALL is a convenience macro
51       equivalent    to    PM_EXEC_TOSS_STDIN    |    PM_EXEC_TOSS_STDOUT    |
52       PM_EXEC_TOSS_STDERR.
53
54       Obviously some combinations of argument values make no sense, e.g. type
55       equal to ``r'' and PM_EXEC_TOSS_STDOUT set in toss  or  type  equal  to
56       ``w'' and PM_EXEC_TOSS_STDIN set in type.
57
58       __pmProcessPipe  returns  a standard I/O stream for the pipe via the fp
59       argument.
60
61       Once the caller  determines  all  the  work  has  been  done,  __pmPro‐
62       cessPipeClose should be called.
63
64       Nested  calling  of  __pmProcessExec(3)  and/or  __pmProcessPipe is not
65       allowed.  Once __pmProcessAddArg(3) is called with handle set  to  NULL
66       to start the registration and execution sequence any attempt to start a
67       second registration sequence will be blocked until  the  first  one  is
68       completed by calling __pmProcessExec(3) or __pmProcessPipe.
69

SEE ALSO

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

DIAGNOSTICS

75       If successful __pmProcessPipe returns 0.   Other  conditions  are  rare
76       (e.g.  alloc  failure)  and are indicated by a return value that can be
77       decoded using pmErrStr(3).
78
79       The return status from __pmProcessPipeClose is a  little  more  compli‐
80       cated.   If  the command completes with an exit status of 0, the return
81       value is 0.  Return values less than 0 indicate a  more  serious  error
82       and  the  value  can  be decoded using pmErrStr(3).  If the command was
83       executed, but did not exit with status of 0 then the return value is an
84       encoding of the waitpid(2) status as follows: 2000 if something unknown
85       went wrong, else if 1000 + signal number of the command was  killed  or
86       stopped by a signal, else the exit status of the command.
87
88
89
90Performance Co-Pilot                  PCP                     PMPROCESSPIPE(3)
Impressum