NAME

       __pmProcessAddArg, __pmProcessUnpickArgs, __pmProcessExec - process execution support

C SYNOPSIS

       #include "pmapi.h"
       #include "libpcp.h"

       int __pmProcessAddArg(__pmExecCtl_t **handle, const char *arg);
       int __pmProcessUnpickArgs(__pmExecCtl_t **handle, const char *command);
       int __pmProcessExec(__pmExecCtl_t **handle, int toss, int wait);

       cc ... -lpcp

CAVEAT

       This documentation is intended for internal Performance Co-Pilot (PCP) developer use.

       These  interfaces  are not part of the PCP APIs that are guaranteed to remain fixed across
       releases, and they may not work, or may provide different semantics at some point  in  the
       future.

DESCRIPTION

       Within the libraries and applications of the Performance Co-Pilot (PCP) these routines are
       provide a convenient and safe  alternative  to  system(3)  for  executing  commands  in  a
       separate process.

       Use  __pmProcessAddArg  to register the executable and command arguments in order.  handle
       should be set to NULL before the first call to __pmProcessAddArg for a particular  command
       execution  and it will be set to an opaque pointer to data structures that are manipulated
       in __pmProcessAddArg, __pmProcessExec and the related __pmProcessPipe(3) routines.

       When called with handle set to NULL arg is treated as  the  name  of  the  command  to  be
       executed and subsequent calls (if any) are for the arguments to that command.  The name of
       the command can be a full pathname, or the name of an executable that can be found on  the
       current $PATH as per the rules of execvp(2) that is used by __pmProcessExec.

       __pmProcessUnpickArgs  is  a convenience wrapper to assist conversion of code that assumes
       the command is a shell command that has been prepared for use with system(3)  or  popen(3)
       in  existing  code.   The  arguments in command are picked off one-by-one and used to call
       __pmProcessAddArgs.  The parser is simple, as the routine is  designed  for  simple  shell
       command  syntax,  where  arguments are separated by one or more spaces but embedded spaces
       within an argument are allowed if the arguement is enclosed in single  or  double  quotes.
       More  advanced  shell  syntax  like escape characters and input-output redirection are not
       recognized.

       Once all the command name and arguments have been registered calling __pmProcessExec  uses
       a fork(2) and execvp(2) sequence to execute the command.

       The  argument  toss  may be used to assign some or all of the standard I/O streams for the
       command to /dev/null - specifically toss is  either  PM_EXEC_TOSS_NONE  to  keep  all  I/O
       streams  the same as the parent process, else the bit-wise or of PM_EXEC_TOSS_STDIN and/or
       PM_EXEC_TOSS_STDOUT and/or  PM_EXEC_TOSS_STDERR  to  reassign  stdin,  stdout  and  stderr
       respectively.   PM_EXEC_TOSS_ALL is a convenience macro equivalent to PM_EXEC_TOSS_STDIN |
       PM_EXEC_TOSS_STDOUT | PM_EXEC_TOSS_STDERR.

       The wait argument should be PM_EXEC_WAIT if __pmProcessExec should wait for completion  of
       the command and harvest the exit status, else PM_EXEC_NOWAIT in which case __pmProcessExec
       returns immediately (effectively running the command in the background).

       Nested  calling  of  __pmProcessExec  and/or  __pmProcessPipe(3)  is  not  allowed.   Once
       __pmProcessAddArg  is  called  with  handle  set  to  NULL  to  start the registration and
       execution sequence any attempt to start a second registration  sequence  will  be  blocked
       until the first one is completed by calling __pmProcessExec or __pmProcessPipe(3).

DIAGNOSTICS

       If  successful  __pmProcessAddArg  returns  0.   Other  conditions  are  rare (e.g. memory
       allocation failure) and are indicated  by  a  return  value  that  can  be  decoded  using
       pmErrStr(3).  When an error does occur __pmProcessAddArg cleans up any allocations made in
       the current call and uses handle to clean up any allocations made  by  previous  calls  so
       there  is  no need for the caller to worry about memory leaks, and then (re)sets handle to
       NULL before returning.

       __pmProcessUnpickArgs returns 0 on success.  In the case  of  an  unterminated  string,  a
       message  is  generated  and  PM_ERR_GENERIC  is returned.  Other return values less than 0
       indicate a more serious error and the value can be decoded  using  pmErrStr(3).   When  an
       error  does occur the clean up is similar to __pmProcessAddArg so there is no need for the
       caller to worry about memory leaks.

       The return status from __pmProcessExec is more complicated.  If either  PM_EXEC_NOWAIT  is
       specified,  or  the  command  completes  with  an exit status of 0, the return value is 0.
       Return values less than 0 indicate a more serious error and the value can be decoded using
       pmErrStr(3).   If  the  command  was  executed, but did not exit with status of 0 then the
       return value is an encoding of the waitpid(2) status as follows: 2000 if something unknown
       went wrong, else if 1000 + signal number of the command was killed or stopped by a signal,
       else the exit status of the command.

SEE ALSO

       execvp(2), fork(2), __pmProcessPipe(3), popen(3), system(3) and waitpid(3).