325 lines
8.6 KiB
Groff
325 lines
8.6 KiB
Groff
'\"macro stdmacro
|
|
.TH PRCTL 2 LOCAL
|
|
.SH NAME
|
|
prctl \- operations on a process
|
|
.Op c p a
|
|
.SH C SYNOPSIS
|
|
.B #include <sys/types.h>
|
|
.br
|
|
.B #include <sys/resource.h>
|
|
.br
|
|
.B #include <sys/prctl.h>
|
|
.PP
|
|
.B "ptrdiff_t prctl (unsigned option, ...);"
|
|
.Op
|
|
.Op f
|
|
.SH FORTRAN SYNOPSIS
|
|
.B #include <sys/prctl.h>
|
|
.PP
|
|
.B "integer*4 function prctl (option, value, value2)"
|
|
.br
|
|
.B integer*4 option, value, value2
|
|
.Op
|
|
.SH DESCRIPTION
|
|
\f4prctl\fP
|
|
provides information about processes and the ability to control certain
|
|
of their attributes.
|
|
The return type \f2ptrdiff_t\fP is used so that \f4prctl\fP can
|
|
return an integral value that is large
|
|
enough to return a pointer/address.
|
|
.Op f
|
|
All three arguments must always be given, supply 0 if any is not required.
|
|
.Op
|
|
\f2option\fP
|
|
specifies one of the following actions:
|
|
.TP 17
|
|
.SM
|
|
.B PR_MAXPROCS
|
|
returns the system imposed limit on the number of processes per user.
|
|
.TP
|
|
.SM
|
|
.B PR_MAXPPROCS
|
|
returns the maximum number of processors the calling process can utilize.
|
|
If the caller is restricted (see \f4sysmp\fP(2))
|
|
to run on a particular processor then
|
|
.B PR_MAXPPROCS
|
|
will return 1.
|
|
If some of the processors in the complex have been restricted (see
|
|
\f4mpadmin\fP(1))
|
|
these will not be counted.
|
|
.TP
|
|
.SM
|
|
.B PR_ISBLOCKED
|
|
returns 1 if the specified process is currently blocked.
|
|
The second argument, interpreted as type \f4pid_t\fP,
|
|
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.
|
|
.TP
|
|
.SM
|
|
.B 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 argument, interpreted as an \f4rlim_t\fP,
|
|
defines the desired stack size in bytes.
|
|
This option and the
|
|
.SM
|
|
.B RLIMIT_STACK
|
|
option of
|
|
\f4setrlimit\fP(2)
|
|
act on the same value.
|
|
.TP
|
|
.SM
|
|
.B 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.
|
|
.TP
|
|
.SM
|
|
.B PR_UNBLKONEXEC
|
|
sets a flag so that when the calling process subsequently calls \f4exec\f1(2),
|
|
the process whose pid is specified by the second argument
|
|
is unblocked.
|
|
This can be used in conjunction with the
|
|
.SM
|
|
.B PR_BLOCK
|
|
option of
|
|
\f4sproc\fP(2)
|
|
to provide race-free process creation.
|
|
.TP
|
|
.SM
|
|
.B PR_ATOMICSIM
|
|
set a flag so that the kernel provides assistance for performing
|
|
atomic operations on hardware that requires it.
|
|
It is for use by \f2libc\fP and shouldn't be called by a user application.
|
|
.TP
|
|
.SM
|
|
.B PR_SETEXITSIG
|
|
controls whether all members of a share group will be signaled if any one of
|
|
them leaves the share group (whether via \f4exit\fP(2) or \f4exec\fP(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 \f4int\fP
|
|
is 0, then normal
|
|
.SM
|
|
.B IRIX
|
|
process termination rules apply, namely that the parent might be sent a
|
|
.SM
|
|
.B SIGCLD
|
|
upon death of child, but no indication of death of parent is given.
|
|
If the second argument is a valid signal number [see
|
|
\f4signal\fP(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.
|
|
.TP
|
|
.SM
|
|
.B 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
|
|
.B PR_SETEXITSIG ,
|
|
except that the signal is not generated if the share group member exits
|
|
normally, that is, by way of
|
|
\f4exit\fP(2) or \f4exec\fP(2).
|
|
Further, the
|
|
.B PR_SETABORTSIG
|
|
and
|
|
.B PR_SETEXITSIG
|
|
actions cannot be in effect simultaneously;
|
|
a call which specifies either
|
|
of these nullifies any previous calls for these actions.
|
|
.TP
|
|
.SM
|
|
.B PR_RESIDENT
|
|
makes the process immune to process swapout.
|
|
Its pages are still subject to paging - these can be locked by using
|
|
\f4mpin\fP(2).
|
|
.TP
|
|
.SM
|
|
.B PR_TERMCHILD
|
|
causes the calling process to be automatically sent a
|
|
.SM
|
|
.B SIGHUP
|
|
when its parent
|
|
process dies. This effect is
|
|
.SM
|
|
.B NOT
|
|
inherited: it applies
|
|
.I only
|
|
to the process that requested it.
|
|
The caller must have set its handler for
|
|
.SM
|
|
.B SIGHUP
|
|
to either be caught or
|
|
.SM
|
|
.BR SIG_DFL .
|
|
Note that processes started in the background have their
|
|
.SM
|
|
.B SIGHUP
|
|
handler set to
|
|
.SM
|
|
.B SIG_IGN
|
|
by the shell.
|
|
Child processes getting a
|
|
.SM
|
|
.B SIGHUP
|
|
signal should probably check the value of
|
|
\f4getppid\fP(2)
|
|
to be sure their parent really died (and thus their parent pid will be
|
|
set to 1).
|
|
.TP
|
|
.SM
|
|
.B 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 \f4pid_t\fP.
|
|
The third argument (address) is interpreted as a \f4caddr_t\fP.
|
|
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.
|
|
.TP
|
|
.SM
|
|
.B 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.
|
|
Intended for use by MPI libraries.
|
|
.TP
|
|
.SM
|
|
.B PR_DETACHADDR
|
|
is not implemented yet.
|
|
.TP
|
|
.SM
|
|
.B 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 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.
|
|
.TP
|
|
.SM
|
|
.B 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.
|
|
.TP
|
|
.SM
|
|
.B PR_COREPID
|
|
Changes the name of the file used to hold the core image of the process
|
|
from \f4core\fP to \f4core.\f2pid\f1.
|
|
The second argument is interpreted as a \f4pid_t\fP and specifies which
|
|
process to act on.
|
|
A value of 0 signifies the calling process.
|
|
If the third argument, interpreted as an \f4int\fP, is zero then the
|
|
core file name is changed back to the standard name - \f4core\fP.
|
|
This state is inherited on \f4fork\fP(2) and \f4sproc\fP(2) and is reset
|
|
on \f4exec\fP(2).
|
|
Note that this mechanism may be defeated by some system wide configuration
|
|
settings.
|
|
.PP
|
|
\f4prctl\fP
|
|
will fail if one or more of the following are true:
|
|
.TP 12
|
|
.SM
|
|
\%[EINVAL]
|
|
\f2option\fP is not valid.
|
|
.TP
|
|
.SM
|
|
\%[ESRCH]
|
|
The second argument passed with the
|
|
.SM
|
|
.BR PR_ISBLOCKED ,
|
|
.SM
|
|
.BR PR_UNBLKONEXEC ,
|
|
.SM
|
|
.BR PR_COREPID ,
|
|
or
|
|
.SM
|
|
.B PR_GETSHMASK
|
|
option doesn't match the pid of any process.
|
|
.TP
|
|
.SM
|
|
\%[EINVAL]
|
|
The value given for the new maximum stack size is negative
|
|
or exceeds the maximum
|
|
process size allowed.
|
|
.TP
|
|
.SM
|
|
\%[EINVAL]
|
|
The value given for the
|
|
.SM
|
|
.B PR_SETEXITSIG
|
|
option is not a valid signal number.
|
|
.TP
|
|
.SM
|
|
\%[EINVAL]
|
|
The calling process already has specified a process (or the
|
|
specified process is the caller itself) to be unblocked on exec
|
|
via the
|
|
.SM
|
|
.B PR_UNBLKONEXEC
|
|
option.
|
|
.TP
|
|
.SM
|
|
\%[EPERM]
|
|
The caller does not have permission to unblock or query the process
|
|
specified by the second argument for the
|
|
.SM
|
|
.BR PR_UNBLKONEXEC ,
|
|
.SM
|
|
.BR PR_ISBLOCKED ,
|
|
.SM
|
|
.BR PR_COREPID ,
|
|
or
|
|
.SM
|
|
.B PR_GETSHMASK
|
|
options.
|
|
.TP
|
|
.SM
|
|
\%[EINVAL]
|
|
The
|
|
.SM
|
|
.B 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.
|
|
.TP
|
|
.SM
|
|
\%[EINVAL]
|
|
The
|
|
.SM
|
|
.B PR_GETSHMASK
|
|
option was specified and
|
|
the caller is not a share group member.
|
|
.SH "SEE ALSO"
|
|
blockproc(2), signal(2), setrlimit(2), sproc(2), usinit(3P).
|
|
.SH DIAGNOSTICS
|
|
Upon successful completion,
|
|
\f4prctl\fP
|
|
returns the requested information.
|
|
Otherwise, a value of \-1 is
|
|
returned to the calling process, and
|
|
\f4errno\fP\^
|
|
is set to indicate the error.
|