Description

The resource control block routines allow the establishment or retrieval of values
from a resource control block used to transfer information using the getrctl(2) and
setrctl(2) functions. Each of the routines accesses or sets the resource control
block member corresponding to its name. Certain of these members are
read-only and do not possess set routines.

The firing time of a resource control block is 0 if the
resource control action-value has not been exceeded for its lifetime on the
process. Otherwise the firing time is the value of gethrtime(3C) at the
moment the action on the resource control value was taken.

The global actions and flags are the action and flags set by
rctladm(1M). These values cannot be set with setrctl(2). Valid global actions
are listed in the table below. Global flags are generally a published
property of the control and are not modifiable.

RCTL_GLOBAL_DENY_ALWAYS

The action taken when a control value is exceeded on this control will always include denial of the resource.

RCTL_GLOBAL_DENY_NEVER

The action taken when a control value is exceeded on this control will always exclude denial of the resource; the resource will always be granted, although other actions can also be taken.

RCTL_GLOBAL_SIGNAL_NEVER

No signal actions are permitted on this control.

RCTL_GLOBAL_CPU_TIME

The valid signals available as local actions include the SIGXCPU signal.

RCTL_GLOBAL_FILE_SIZE

The valid signals available as local actions include the SIGXFSZ signal.

RCTL_GLOBAL_INFINITE

This resource control supports the concept of an unlimited value; generally true only of accumulation-oriented resources, such as CPU time.

RCTL_GLOBAL_LOWERABLE

Non-privileged callers are able to lower the value of privileged resource control values on this control.

RCTL_GLOBAL_NOACTION

No global action will be taken when a resource control value is exceeded on this control.

RCTL_GLOBAL_NOBASIC

No values with the RCPRIV_BASIC privilege are permitted on this control.

RCTL_GLOBAL_SYSLOG

A standard message will be logged by the syslog(3C) facility when any resource control value on a sequence associated with this control is exceeded.

RCTL_GLOBAL_UNOBSERVABLE

The resource control (generally on a task- or project-related control) does not support observational control values. An RCPRIV_BASIC privileged control value placed by a process on the task or process will generate an action only if the value is exceeded by that process.

RCTL_GLOBAL_BYTES

This resource control represents a number of bytes.

RCTL_GLOBAL_SECONDS

This resource control represents a quantity of time in seconds.

RCTL_GLOBAL_COUNT

This resource control represents an integer count.

The local action and flags are those on the current resource control
value represented by this resource control block. Valid actions and flags are
listed in the table below. In the case of RCTL_LOCAL_SIGNAL, the second
argument to rctlblk_set_local_action() contains the signal to be sent. Similarly, the signal
to be sent is copied into the integer location specified by the
second argument to rctlblk_get_local_action(). A restricted set of signals is made available
for normal use by the resource control facility: SIGBART, SIGXRES, SIGHUP, SIGSTOP,
SIGTERM, and SIGKILL. Other signals are permitted due to global properties of
a specific control. Calls to setrctl() with illegal signals will fail.

RCTL_LOCAL_DENY

When this resource control value is encountered, the request for the resource will be denied. Set on all values if RCTL_GLOBAL_DENY_ALWAYS is set for this control; cleared on all values if RCTL_GLOBAL_DENY_NEVER is set for this control.

RCTL_LOCAL_MAXIMAL

This resource control value represents a request for the maximum amount of resource for this control. If RCTL_GLOBAL_INFINITE is set for this resource control, RCTL_LOCAL_MAXIMAL indicates an unlimited resource control value, one that will never be exceeded.

RCTL_LOCAL_NOACTION

No local action will be taken when this resource control value is exceeded.

RCTL_LOCAL_SIGNAL

The specified signal, sent by rctlblk_set_local_action(), will be sent to the process that placed this resource control value in the value sequence. This behavior is also true for signal actions on project and task resource controls. The specified signal is sent only to the recipient process, not all processes within the project or task.

The rctlblk_get_recipient_pid() function returns the value of the process ID that placed
the resource control value for basic rctls. For privileged or system rctls,
rctlblk_get_recipient_pid() returns -1.

The rctlblk_set_recipient_pid() function sets the recipient pid for a basic rctl. When
setrctl(2) is called with the flag RCTL_USE_RECIPIENT_PID, this pid is used. Otherwise, the
PID of the calling process is used. Only privileged users can set
the recipient PID to one other than the PID of the calling
process. Process-scoped rctls must have a recipient PID that matches the PID
of the calling process.

The rctlblk_get_privilege() function returns the privilege of the resource control block. Valid
privileges are RCPRIV_BASIC, RCPRIV_PRIVILEGED, and RCPRIV_SYSTEM. System resource controls are read-only. Privileged
resource controls require the {PRIV_SYS_RESOURCE} privilege to write, unless the RCTL_GLOBAL_LOWERABLE global flag
is set, in which case unprivileged applications can lower the value of
a privileged control.

The rctlblk_get_value() and rctlblk_set_value() functions return or establish the enforced value associated
with the resource control. In cases where the process, task, or project
associated with the control possesses fewer capabilities than allowable by the current value,
the value returned by rctlblk_get_enforced_value() will differ from that returned by rctlblk_get_value().
This capability difference arises with processes using an address space model smaller
than the maximum address space model supported by the system.

The rctlblk_size() function returns the size of a resource control block for
use in memory allocation. The rctlblk_t * type is an opaque pointer whose
size is not connected with that of the resource control block itself.
Use of rctlblk_size() is illustrated in the example below.

Return Values

The various set routines have no return values. Incorrectly composed resource control
blocks will generate errors when used with setrctl(2) or getrctl(2).

Errors

No error values are returned. Incorrectly constructed resource control blocks will be
rejected by the system calls.

Examples

Example 1 Display the contents of a fetched resource control block.

The following example displays the contents of a fetched resource control block.