1PMPROCESSPIPE(3) Library Functions Manual PMPROCESSPIPE(3)
2
6 __pmProcessPipe, __pmProcessClosePipe - support for process execution
7 at the end of a pipe
8
10 #include "pmapi.h"
11 #include "libpcp.h"
12 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 cc ... -lpcp
19
21 This documentation is intended for internal Performance Co-Pilot (PCP)
22 developer use.
23 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
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 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 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 The type argument needs to be ``r'' to read from the pipe, else ``w''
43 to write to the pipe.
44 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 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 __pmProcessPipe returns a standard I/O stream for the pipe via the fp
59 argument.
60 Once the caller determines all the work has been done, __pmPro‐
62 cessPipeClose should be called.
63 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
71 execvp(2), fork(2), pclose(2), pipe(2), popen(2), __pmProcessAddArg(3),
72 __pmProcessExec(3) and waitpid(3).
73
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 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.
87Performance Co-Pilot PCP PMPROCESSPIPE(3)