Go to main content

man pages section 3: Extended Library Functions, Volume 3

Exit Print View

Updated: Wednesday, July 27, 2022

Pcreate_error (3PROC)


Pcreate, Pcreate_error - create a victim process


#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);


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.


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


Unanticipated error, errno is meaningful


Unable to fork


No permission (file set-id or unreadable)


Cannot execute file


Interrupt received while creating


Program is _LP64, self is _ILP32


Cannot find executable file


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

Interface Stability

See Also

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