Tribblix: manual page: Pcreate.3proc

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

Uncommitted

MT-LEVEL
MT-Safe