Go to main content

man pages section 3: Extended Library Functions, Volume 3

Exit Print View

Updated: Thursday, June 13, 2019
 
 

Pcreate_error (3PROC)

Name

Pcreate, Pcreate_error - create a victim process

Synopsis

#include <libproc.h>
ps_prochandle_t *Pcreate(const char *file, char *const *argv,
         char *const *envp, int *perr, char *path, size_t len);
const char *Pcreate_error(int error);

Description

The Pcreate() function creates a victim process, a child of the controlling process. On successful return of Pcreate(), the victim process is in a stopped state, stopped on completion of the exec() function that created it, before it has executed its first user-level instruction.

The file, argv, and envp arguments are the same as those passed to execve. However, if file contains no slash character, it is treated as in execve, that is, the path prefix for this file is obtained by a search of the directories contained in the PATH environment variable. If the envp argument is NULL, the environment of the victim process is the same as that of the controlling process. For more information, see the environ(7) man page.

The perr variable points to an integer that will contain an error code in the event that the Pcreate() function fails.

On successful completion of the Pcreate() function, if the path argument is not NULL and the len argument is non-zero, the character array pointed to by path is filled with the path name of the executable file found by the search of the PATH environment variable.

The Pcreate_error() function maps the error code from a failing call to Pcreate() to an error message string and returns a pointer to that string.

Return Values

On successful completion, the Pcreate() function returns a pointer to an opaque structure, allocated by the library, which must be used by almost all of the remaining functions in libproc to effect inspection and control of the victim process. On failure, Pcreate() returns a NULL pointer and sets the integer pointed to by the perr argument to an error code. For more information, see the libproc.h(3HEAD) man page.

Errors

If a Pcreate() failure occurs, the following possible values are returned in the integer pointed to by the perr argument:

C_STRANGE

Unanticipated error, errno is meaningful

C_FORK

Unable to fork

C_PERM

No permission (file set-id or unreadable)

C_NOEXEC

Cannot execute file

C_INTR

Interrupt received while creating

C_LP64

Program is _LP64, self is _ILP32

C_NOENT

Cannot find executable file

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Unsafe

See Also

libproc.h(3HEAD), libproc(3LIB), Pgrab(3PROC), Prelease(3PROC)