1PMPROCESSEXEC(3) Library Functions Manual PMPROCESSEXEC(3)
2
6 __pmProcessAddArg, __pmProcessUnpickArgs, __pmProcessExec - process ex‐
7 ecution support
8
10 #include "pmapi.h"
11 #include "libpcp.h"
12 int __pmProcessAddArg(__pmExecCtl_t **handle, const char *arg);
14 int __pmProcessUnpickArgs(__pmExecCtl_t **handle, const char *command);
15 int __pmProcessExec(__pmExecCtl_t **handle, int toss, int wait);
16 cc ... -lpcp
18
20 This documentation is intended for internal Performance Co-Pilot (PCP)
21 developer use.
22 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
28 Within the libraries and applications of the Performance Co-Pilot (PCP)
29 these routines are provide a convenient and safe alternative to sys‐
30 tem(3) for executing commands in a separate process.
31 Use __pmProcessAddArg to register the executable and command arguments
33 in order. handle should be set to NULL before the first call to __pm‐
34 ProcessAddArg for a particular command execution and it will be set to
35 an opaque pointer to data structures that are manipulated in __pmPro‐
36 cessAddArg, __pmProcessExec and the related __pmProcessPipe(3) rou‐
37 tines.
38 When called with handle set to NULL arg is treated as the name of the
40 command to be executed and subsequent calls (if any) are for the argu‐
41 ments to that command. The name of the command can be a full pathname,
42 or the name of an executable that can be found on the current $PATH as
43 per the rules of execvp(2) that is used by __pmProcessExec.
44 __pmProcessUnpickArgs is a convenience wrapper to assist conversion of
46 code that assumes the command is a shell command that has been prepared
47 for use with system(3) or popen(3) in existing code. The arguments in
48 command are picked off one-by-one and used to call __pmProcessAddArgs.
49 The parser is simple, as the routine is designed for simple shell com‐
50 mand syntax, where arguments are separated by one or more spaces but
51 embedded spaces within an argument are allowed if the arguement is en‐
52 closed in single or double quotes. More advanced shell syntax like es‐
53 cape characters and input-output redirection are not recognized.
54 Once all the command name and arguments have been registered calling
56 __pmProcessExec uses a fork(2) and execvp(2) sequence to execute the
57 command.
58 The argument toss may be used to assign some or all of the standard I/O
60 streams for the command to /dev/null - specifically toss is either
61 PM_EXEC_TOSS_NONE to keep all I/O streams the same as the parent
62 process, else the bit-wise or of PM_EXEC_TOSS_STDIN and/or
63 PM_EXEC_TOSS_STDOUT and/or PM_EXEC_TOSS_STDERR to reassign stdin, std‐
64 out and stderr respectively. PM_EXEC_TOSS_ALL is a convenience macro
65 equivalent to PM_EXEC_TOSS_STDIN | PM_EXEC_TOSS_STDOUT |
66 PM_EXEC_TOSS_STDERR.
67 The wait argument should be PM_EXEC_WAIT if __pmProcessExec should wait
69 for completion of the command and harvest the exit status, else
70 PM_EXEC_NOWAIT in which case __pmProcessExec returns immediately (ef‐
71 fectively running the command in the background).
72 Nested calling of __pmProcessExec and/or __pmProcessPipe(3) is not al‐
74 lowed. Once __pmProcessAddArg is called with handle set to NULL to
75 start the registration and execution sequence any attempt to start a
76 second registration sequence will be blocked until the first one is
77 completed by calling __pmProcessExec or __pmProcessPipe(3).
78
80 If successful __pmProcessAddArg returns 0. Other conditions are rare
81 (e.g. memory allocation failure) and are indicated by a return value
82 that can be decoded using pmErrStr(3). When an error does occur __pm‐
83 ProcessAddArg cleans up any allocations made in the current call and
84 uses handle to clean up any allocations made by previous calls so there
85 is no need for the caller to worry about memory leaks, and then
86 (re)sets handle to NULL before returning.
87 __pmProcessUnpickArgs returns 0 on success. In the case of an untermi‐
89 nated string, a message is generated and PM_ERR_GENERIC is returned.
90 Other return values less than 0 indicate a more serious error and the
91 value can be decoded using pmErrStr(3). When an error does occur the
92 clean up is similar to __pmProcessAddArg so there is no need for the
93 caller to worry about memory leaks.
94 The return status from __pmProcessExec is more complicated. If either
96 PM_EXEC_NOWAIT is specified, or the command completes with an exit sta‐
97 tus of 0, the return value is 0. Return values less than 0 indicate a
98 more serious error and the value can be decoded using pmErrStr(3). If
99 the command was executed, but did not exit with status of 0 then the
100 return value is an encoding of the waitpid(2) status as follows: 2000
101 if something unknown went wrong, else if 1000 + signal number of the
102 command was killed or stopped by a signal, else the exit status of the
103 command.
104
106 execvp(2), fork(2), __pmProcessPipe(3), popen(3), system(3) and wait‐
107 pid(3).
108Performance Co-Pilot PCP PMPROCESSEXEC(3)