prctl() — Operate on a process or thread

Standards

Standards / Extensions	C or C++	Dependencies
z/OS® UNIX	both

Format

#define _XPLATFORM_SOURCE
#include <sys/prctl.h>

int prctl(int option, unsigned long arg2, unsigned long arg3, unsigned long arg4, unsigned long arg5);

General description

prctl() manipulates various aspects of the behavior of a calling thread or process.

prctl() is called with a first argument that describes what to do (with values that are defined in <sys/prctl.h>), and further arguments that depend on the first one. The first argument can be:

PR_SET_CHILD_SUBREAPER

If arg2 is nonzero, set the "child subreaper" attribute of the calling process; if arg2 is zero, unset the attribute.

When a process becomes orphaned (that is, its immediate parent terminates), that process is reparented to the nearest living ancestor subreaper. Then, calls to getppid() in the orphaned process return the PID of the subreaper process, and when the orphan terminates, it is the subreaper process that receives a SIGCHLD signal. The setting of the "child subreaper" attribute is not inherited by the children that are created by fork() and clone(). The setting is preserved across execve().

Establishing a subreaper process is useful in session management frameworks where a hierarchical group of processes is managed by a subreaper process, which needs to be informed when one of the processes (for example, a double-forked daemon) terminates (so that it can restart that process).

PR_GET_CHILD_SUBREAPER

Return the "child subreaper" setting of the caller in the location that is pointed to by (int *) arg2.

PR_SET_DUMPABLE

Set the state of the "dumpable" attribute, which determines whether core dumps are produced for the calling process upon delivery of a signal whose default behavior is to produce a core dump. arg2 must be either 0 (process is not dumpable) or 1 (process is dumpable). Normally, the "dumpable" attribute is set to 1. However, it is reset to value 0 in the following circumstances:

The process's effective user or group ID is changed.
The process's file system user or group ID is changed.
The process calls execve() to execute a set-user-ID or set-group-ID program, resulting in a change of either the effective user ID or the effective group ID.

As a security measure, the ownership is made root:root if the process's "dumpable" attribute is set to a value other than 1.

PR_GET_DUMPABLE

Return the current state of the calling process's dumpable attribute as the function result.

PR_SET_NAME

Set the name of the calling thread by using the value in the location that is pointed to by (char *) arg2. The name can be a null-terminated string with the max length of 16 characters. If the length of the string, including the terminating null byte, exceeds 16 bytes, the string is truncated.

PR_GET_NAME

Return the name of the calling thread in the buffer that is pointed to by

(char *)
arg2

. The name can be a string with the max length of 16 characters. The returned string is null-terminated if it is shorter than that.

PR_SET_NO_NEW_PRIVS

Set the calling thread's no_new_privs attribute to the value in arg2. With no_new_privs set to 1, execve() promises not to grant privileges to do anything that cannot be done without the execve() call. Once set, the no_new_privs attribute cannot be unset. The setting of this attribute is inherited by the children that are created by fork() and clone() and preserved across execve().

PR_GET_NO_NEW_PRIVS

Return the value of the no_new_privs attribute for the calling thread as the function result. A value of 0 indicates the regular execve(2) behavior. A value of 1 indicates execve() operates in the privilege-restricting mode.

PR_SET_PDEATHSIG

Set the parent-death signal of the calling process to arg2 (0 to clear). This is the signal that the calling process gets when its parent dies.

Warning: The "parent" in this case is considered to be the thread that created this process. The signal is sent when that thread terminates (for example, by calling


pthread_exit()

), rather than after all of the threads in the parent process terminate. The parent-death signal is sent upon subsequent termination of the parent thread and also upon termination of each subreaper process to which the caller is then reparented. If the parent thread and all ancestor subreapers are terminated by the time of the PR_SET_PDEATHSIG operation, no parent-death signal is sent to the caller.

The parent-death signal setting is cleared for the child of a fork(). It is also cleared when executing a set-user-ID or set-group-ID binary; otherwise, this value is preserved across execve(). The parent-death signal setting is also cleared upon changes to any of the following thread credentials: effective user ID, effective group ID, file system user ID, or file system group ID.

PR_GET_PDEATHSIG

Return the current value of the parent process death signal in the location that is pointed to by (int *) arg2.

Returned value

If successful, PR_GET_DUMPABLE and PR_GET_NO_NEW_PRIVS return the nonnegative values that are described previously. All other option values return 0.

If unsuccessful, prctl() returns -1 and sets errno to one of the following values:

Error Code: Description
EFAULT: arg2 is an invalid address.
EINVAL: option is PR_SET_PDEATHSIG or PR_GET_Name and arg2 is not a valid signal number.

Related information

sys/prctl.h — Operations on a process or thread