PCREATE(3PROC) Process Control Library Functions PCREATE(3PROC)
NAME
Pcreate,
Pxcreate,
Pcreate_callback - create and control a process
LIBRARY
Process Control Library (libproc, -lproc)
SYNOPSIS
#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);
DESCRIPTION
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(7).
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.
RETURN VALUES
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.
ERRORS
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.
INTERFACE STABILITY
UncommittedMT-LEVEL MT-SafeSEE ALSO
exec(2),
execvp(2),
fork(2),
Intro(2),
errno(3C),
libproc(3LIB),
Pcreate_error(3PROC),
Pfree(3PROC),
Prelease(3PROC)illumos May 11, 2016 illumos