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

NAME

6       __pmProcessPipe,  __pmProcessPipeClose  - 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 __pmProcessPipe(__pmExecCtl_t **handle, const char *type, int toss,
14       FILE **fp);
15       int __pmProcessPipeClose(FILE *fp);
16
17       cc ... -lpcp
18

CAVEAT

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

DESCRIPTION

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

DIAGNOSTICS

70       If  successful  __pmProcessPipe  returns  0.  Other conditions are rare
71       (e.g. alloc failure) and are indicated by a return value  that  can  be
72       decoded using pmErrStr(3).
73
74       The  return  status  from __pmProcessPipeClose is a little more compli‐
75       cated.  If the command completes with an exit status of 0,  the  return
76       value  is  0.   Return values less than 0 indicate a more serious error
77       and the value can be decoded using pmErrStr(3).  If the command was ex‐
78       ecuted,  but  did not exit with status of 0 then the return value is an
79       encoding of the waitpid(2) status as follows: 2000 if something unknown
80       went  wrong,  else if 1000 + signal number of the command was killed or
81       stopped by a signal, else the exit status of the command.
82

SEE ALSO

84       execvp(2), fork(2), pclose(2), pipe(2), popen(2), __pmProcessAddArg(3),
85       __pmProcessExec(3) and waitpid(3).
86
87
88
89Performance Co-Pilot                  PCP                     PMPROCESSPIPE(3)
Impressum