1PMPROCESSEXEC(3)           Library Functions Manual           PMPROCESSEXEC(3)


6       __pmProcessAddArg, __pmProcessUnpickArgs, __pmProcessExec - process ex‐
7       ecution support


10       #include "pmapi.h"
11       #include "libpcp.h"
13       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);
17       cc ... -lpcp


20       This documentation is intended for internal Performance Co-Pilot  (PCP)
21       developer use.
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.


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.
32       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.
39       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.
45       __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.
55       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.
59       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    |
68       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).
73       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).


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.
88       __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.
95       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.


106       execvp(2),  fork(2),  __pmProcessPipe(3), popen(3), system(3) and wait‐
107       pid(3).
111Performance Co-Pilot                  PCP                     PMPROCESSEXEC(3)