__pmprocessexec(3) — Linux manual page

NAME | C SYNOPSIS | CAVEAT | DESCRIPTION | DIAGNOSTICS | SEE ALSO | COLOPHON

PMPROCESSEXEC(3)        Library Functions Manual        PMPROCESSEXEC(3)

NAME         top

       __pmProcessAddArg, __pmProcessUnpickArgs, __pmProcessExec -
       process execution support

C SYNOPSIS         top

       #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         top

       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         top

       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 __pmProcessAddArg.  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 argument 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         top

       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         top

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

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨http://www.pcp.io/⟩.  If you have a bug report for this manual
       page, send it to [email protected].  This page was obtained from the
       project's upstream Git repository
       ⟨https://github.com/performancecopilot/pcp.git⟩ on 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

Performance Co-Pilot               PCP                  PMPROCESSEXEC(3)

Pages that refer to this page: __pmprocesspipe(3)