PRCTL(2)PRCTL(2)NAMEprctl - operations on a process
C SYNOPSIS
#include <sys/types.h>
#include <sys/resource.h>
#include <sys/prctl.h>
ptrdiff_t prctl (unsigned option, ...);
struct prattach_args_t {
__int64_t local_vaddr;
__int64_t vaddr;
pid_t pid;
__uint32_t prots;
__uint32_t flags;
};
DESCRIPTIONprctl provides information about processes and the ability to control
certain of their attributes. The return type ptrdiff_t is used so that
prctl can return an integral value that is large enough to return a
pointer/address. option specifies one of the following actions:
PR_MAXPROCS returns the system imposed limit on the number of
processes per user.
PR_MAXPPROCS returns the maximum number of processors the calling
process can utilize. If the caller is restricted (see
sysmp(2)) to run on a particular processor then
PR_MAXPPROCS will return 1. If some of the processors
in the complex have been restricted (see mpadmin(1))
these will not be counted. Open and Exclusive cpusets
are taken into account. If run on a processor within
the global cpuset, the number of processors in the
global cpuset plus the open cpusets will be returned.
PR_ISBLOCKED returns 1 if the specified process is currently blocked.
The second argument, interpreted as type pid_t,
specifies the target process's pid. Passing in 0
implies the caller. Since other processes could have
subsequently unblocked the subject process, the result
should be considered as a snapshot only.
PR_GETSTACKSIZE returns the current process's maximum stack size in
bytes. This size is an upper limit on the size of the
current process's stack.
PR_SETSTACKSIZE sets the maximum stack size for the current process.
This affects future stack growths and forks only. The
new value, suitably rounded, is returned. The second
Page 1
PRCTL(2)PRCTL(2)
argument, interpreted as an rlim_t, defines the desired
stack size in bytes. This option and the RLIMIT_STACK
option of setrlimit(2) act on the same value.
PR_UNBLKONEXEC sets a flag so that when the calling process
subsequently calls exec(2), the process whose pid is
specified by the second argument (interpreted as type
pid_t) is unblocked. This can be used in conjunction
with the PR_BLOCK option of sproc(2) to provide race-
free process creation.
PR_SETEXITSIG controls whether all members of a share group will be
signaled if any one of them leaves the share group
(whether via exit(2) or exec(2) or as the result of an
abnormal termination, such as caused by a segmentation
violation or an uncatchable signal). If the second
argument, interpreted as an int is 0, then normal IRIX
process termination rules apply, namely that the parent
might be sent a SIGCLD upon death of child, but no
indication of death of parent is given. If the second
argument is a valid signal number [see signal(2)] then
if any member of a share group leaves the share group, a
signal is sent to ALL surviving members of the share
group.
PR_SETABORTSIG controls whether all members of a share group will be
signaled if any one of them exits the share group
unnaturally. This option works like PR_SETEXITSIG ,
except that the signal is not generated if the share
group member exits normally, that is, by way of exit(2)
or exec(2). Further, the PR_SETABORTSIG and
PR_SETEXITSIG actions cannot be in effect
simultaneously; a call which specifies either of these
nullifies any previous calls for these actions.
PR_RESIDENT makes the process immune to process swapout. Its pages
are still subject to paging - these can be locked by
using mpin(2).
PR_TERMCHILD causes the calling process to be automatically sent a
SIGHUP when its parent process dies. This effect is NOT
inherited: it applies only to the process that requested
it. The caller must have set its handler for SIGHUP to
either be caught or SIG_DFL. Note that processes
started in the background have their SIGHUP handler set
to SIG_IGN by the shell. Child processes getting a
SIGHUP signal should probably check the value of
getppid(2) to be sure their parent really died (and thus
their parent pid will be set to 1).
Page 2
PRCTL(2)PRCTL(2)
PR_ATTACHADDR attaches the virtual segment containing the address
given by the third argument in the process whose pid is
given by the second argument to the calling process.
The second argument (pid) is interpreted as a pid_t.
The third argument (address) is interpreted as a
caddr_t. Both processes must be members of the same
share group. The address of where the virtual segment
was attached is returned. This address has the same
logical offset into the virtual space as the passed in
address. A process may always attach a portion of its
address space back onto itself without being a share
group process.
PR_ATTACHADDRPERM
performs the same function as PR_ATTACHADDR but allows
the caller to specify the desired protection attributes
of the attach which must be a subset of the attributes
on the region being attached. Also returns to the
caller additional information about the region attached,
like base address and size of region. In order to allow
the additional attributes, the second argument is a
pointer to the input parameter block which is of type
prattach_args_t and the third argument is a pointer to
the return values and is of type prattach_results_t.
The input parameter block member vaddr is the virtual
region of process pid attached to local virtual address
local_vaddr. If local_vaddr is set to -1, the kernel
will assign the local virtual address and return that to
the caller. The pid member of the input parameter block
is the pid of the process containing the virtual address
to be attached. The prots member of the input parameter
block is the protections to be used for the attach,
which are a subset of the protection attributes of the
virtual region being attached. The attach can also be
directed to the caller's shared or private space by the
flags member of the input parameter block. By setting
the flags value to zero, the attach is performed in
shared address space. By setting the PRATTACH_PRIVATE
flag bit in the flags the attach will be performed in
the caller private address space. Intended for use by
MPI libraries.
PR_DETACHADDR is not implemented yet.
PR_GETSHMASK returns the mask stating which resources are being
shared with the share group member whose pid is
specified by the second argument. It can also be used
to gather information about the existence of other
processes. If the second argument is 0 or equal to the
callers pid, then the callers share mask is returned.
If the caller is not a member of a share group then an
error is returned. If the process specified by the
Page 3
PRCTL(2)PRCTL(2)
second argument does not exist, is not a member of the
callers share group, or the caller does not have
permission to query the process, an error is returned.
If the caller and target process are in the same share
group the bit-wise 'and' of the callers share mask and
the target process's share mask is returned.
PR_GETNSHARE returns the number of processes in the share group. If
the calling process has never been part of a share group
0 is returned.
PR_COREPID Changes the name of the file used to hold the core image
of the process from core to core.pid. The second
argument is interpreted as a pid_t and specifies which
process to act on. A value of 0 signifies the calling
process. If the third argument, interpreted as an int,
is zero then the core file name is changed back to the
standard name - core. This state is inherited on
fork(2) and sproc(2) and is reset on exec(2). Note that
this mechanism may be defeated by some system wide
configuration settings.
PR_INIT_THREADS prepares a process for multi-threaded operation.
PR_THREAD_CTL Detailed control operations for threaded processes.
PR_LASTSHEXIT Reserved for last sproc exit
prctl will fail if one or more of the following are true:
[ESRCH] The second argument passed with the PR_ISBLOCKED,
PR_UNBLKONEXEC, PR_COREPID, or PR_GETSHMASK option doesn't
match the pid of any process.
[EINVAL] option is not valid.
[EINVAL] The value given for the new maximum stack size is negative or
exceeds the maximum process size allowed.
[EINVAL] The value given for the PR_SETEXITSIG option is not a valid
signal number.
[EINVAL] The calling process already has specified a process (or the
specified process is the caller itself) to be unblocked on
exec via the PR_UNBLKONEXEC option.
[EINVAL] The PR_GETSHMASK option was specified and the second argument
does not correspond to a pid of a process that is in the
caller's share group.
Page 4
PRCTL(2)PRCTL(2)
[EINVAL] The PR_GETSHMASK option was specified and the caller is not a
share group member.
[EINVAL] the PR_ATTACHADDRPERM call has an invalid flag set in the
flag member of the input argument of type struct
prattach_args_t. The only valid flag is PRATTACH_ALIGN.
[EACCES] The caller of the PR_ATTACHADDR does not have the correct
permissions to attach to the address space.
[EACCES] The caller of the PR_ATTACHADDRPERM does not have the correct
permissions to attach to the address space.
[EBUSY] There is no kernel memory available at the moment to complete
the PR_INIT_THREADS operation.
[EFAULT] The third argument of the PR_ATTACHADDR points to a memory
address that is not in a valid part of the process address
space.
[EFAULT] The second argument of the PR_ATTACHADDRPERM points to a
memory address that is not in a valid part of the process
address space.
[EPERM] The caller does not have permission to unblock or query the
process specified by the second argument for the
PR_UNBLKONEXEC, PR_ISBLOCKED, PR_COREPID, or PR_GETSHMASK
options.
SEE ALSOblockproc(2), signal(2), setrlimit(2), sproc(2), usinit(3P).
DIAGNOSTICS
Upon successful completion, prctl returns the requested information.
Otherwise, a value of -1 is returned to the calling process, and errno is
set to indicate the error.
Page 5
