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


6       __pmProcessAddArg,  __pmProcessUnpickArgs,  __pmProcessExec  -  process
7       execution 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
34       __pmProcessAddArg for a particular command execution and it will be set
35       to an opaque  pointer  to  data  structures  that  are  manipulated  in
36       __pmProcessAddArg,  __pmProcessExec  and the related __pmProcessPipe(3)
37       routines.
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
52       enclosed  in  single or double quotes.  More advanced shell syntax like
53       escape 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
71       (effectively running the command in the background).
73       Nested calling of  __pmProcessExec  and/or  __pmProcessPipe(3)  is  not
74       allowed.   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       execvp(2), fork(2), __pmProcessPipe(3), popen(3), system(3)  and  wait‐
81       pid(3).


84       If  successful  __pmProcessAddArg returns 0.  Other conditions are rare
85       (e.g. alloc failure) and are indicated by a return value  that  can  be
86       decoded using pmErrStr(3).
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).
93       The return status from __pmProcessExec is more complicated.  If  either
94       PM_EXEC_NOWAIT is specified, or the command completes with an exit sta‐
95       tus of 0, the return value is 0.  Return values less than 0 indicate  a
96       more  serious error and the value can be decoded using pmErrStr(3).  If
97       the command was executed, but did not exit with status of  0  then  the
98       return  value  is an encoding of the waitpid(2) status as follows: 2000
99       if something unknown went wrong, else if 1000 + signal  number  of  the
100       command  was killed or stopped by a signal, else the exit status of the
101       command.
105Performance Co-Pilot                  PCP                     PMPROCESSEXEC(3)