Pcreate,
Pxcreate,
Pcreate_callback —
create and control a process
Process Control Library (libproc, -lproc)
#include
<libproc.h>
struct ps_prochandle *
Pcreate(
const char
*file,
char *const *argv,
int *perr,
char
*path,
size_t len);
struct ps_prochandle *
Pxcreate(
const
char *file,
char *const *argv,
char *const *envp,
int *perr,
char
*path,
size_t len);
void
Pcreate_callback(
struct
ps_prochandle *P);
The
Pcreate() function creates a process
controlled by the
libproc library. The
Pxcreate() function does the same while
also allowing the replacement of the environment via
envp.
Both functions cause the caller to
fork(2).
Followed by the child calling
exec(2) to load the
new process image specified by
file. The
PATH is searched for
file if it is not an absolute path, similar
to
execvp(2).
The process image will be invoked with the arguments specified by
argv, which should be a
NULL-terminated array of character strings.
Each entry in the array is an individual argument. The environment of the
process image will be inherited from the running process if the
Pcreate() function is called or if the
Pxcreate() function is called and the value
of
envp is
NULL. Otherwise,
envp should be a
NULL-terminated array of character strings
whose entries are in the form of
key=value. For
more on the process environment, see
environ(5).
The
Pcreate_callback() function allows a way
for callers to inject a callback into the child process before the call to
exec(2). The symbol
Pcreate_callback is a symbol that may be
interposed on by consumers. It allows the chance for the modification of
signal dispositions or any other changes that a caller may wish to make.
If the caller's real user or group ID is not their effective user or group ID,
then the child process's user and group IDs will all be reset to the real user
and group id.
The
perr argument must be a
non-
NULL pointer. If the
Pcreate() or
Pxcreate() functions fail, the value
pointed to will be filled in with a more detailed error code listed in
ERRORS. A human-readable error
message is obtained with
Pcreate_error(3PROC).
Multiple executables named
file may exist on
the
PATH. To determine the full path of the
executable pass a non-NULL
path pointer. Upon
successful completion of
Pcreate() or
Pxcreate() the
path pointer will contain the full path up to
len bytes, including the NUL character.
Upon successful completion of the
Pcreate()
or
Pxcreate() function, a handle to the
process is returned. This handle is usable with other
libproc routines and will persist until either
Pfree(3PROC) or
Prelease(3PROC) is called on the resulting
handle. The process created is stopped just after return from the
exec(2) family of system calls. The process will
not run, unless the caller sets it running or releases its handle to the
process.
A 32-bit process cannot use this interface to launch or control a 64-bit
process. However, a 64-bit process can create and control both 32-bit and
64-bit processes.
Upon successful completion, both the
Pcreate() and
Pxcreate() functions create a new process
and return a
libproc handle to it. Otherwise,
NULL is returned and
perr is filled in with the corresponding
error.
The
Pcreate() and
Pxcreate() functions will fail if:
-
-
C_FORK- The call to fork(2) failed.
-
-
C_INTR- The operation was interrupted by a signal.
-
-
C_LP64- The calling process is 32-bit, but it attempted to control a 64-bit
process.
-
-
C_NOEXEC- The specified file or the one found by
searching
PATH cannot be executed.
-
-
C_NOENT- The specified file does not exist or it
could not be found by searching
PATH.
-
-
C_PERM- The specified file or the one found by
searching
PATH is set-id or
unreadable.
-
-
C_STRANGE- An unanticipated system error occurred while trying to create the process
and its handle. When this occurs, then the value of
errno is meaningful. See
errno(3C) for more information and
Intro(2) for the list of possible
errors.
Uncommitted
MT-Safe
exec(2),
execvp(2),
fork(2),
Intro(2),
errno(3C),
libproc(3LIB),
Pcreate_error(3PROC),
Pfree(3PROC),
Prelease(3PROC)