rctlblk_get_privilege(3C)
NAME
rctlblk_set_value, rctlblk_get_firing_time,
rctlblk_get_global_action, rctlblk_get_global_flags,
rctlblk_get_local_action, rctlblk_get_local_flags,
rctlblk_get_privilege, rctlblk_get_recipient_pid,
rctlblk_get_value, rctlblk_get_enforced_value,
rctlblk_set_local_action, rctlblk_set_local_flags,
rctlblk_set_privilege, rctlblk_size - manipulate resource
control blocks
SYNOPSIS
#include <rctl.h>
hrtime_t rctlblk_get_firing_time(rctlblk_t *rblk);
int rctlblk_get_global_action(rctlblk_t *rblk);
int rctlblk_get_global_flags(rctlblk_t *rblk);
int rctlblk_get_local_action(rctlblk_t *rblk, int *signalp);
int rctlblk_get_local_flags(rctlblk_t *rblk);
rctl_priv_t rctlblk_get_privilege(rctlblk_t *rblk);
id_t rctlblk_get_recipient_pid(rctlblk_t *rblk);
rctl_qty_t rctlblk_get_value(rctlblk_t *rblk);
rctl_qty_t rctlblk_get_enforced_value(rctlblk_t *rblk);
void rctlblk_set_local_action(rctlblk_t *rblk, rctl_action_t
action, int signal);
void rctlblk_set_local_flags(rctlblk_t *rblk, int flags);
void rctlblk_set_privilege(rctlblk_t *rblk, rctl_priv_t
privilege);
void rctlblk_set_value(rctlblk_t *rblk, rctl_qty_t value);
size_t rctlblk_size(void);
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().
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_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 permit-
ted on this control.
RCTL_GLOBAL_NOLOCALACTION
No local actions are permitted on this control.
RCTL_GLOBAL_SYSLOG
A standard message will be logged by the syslog()
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 observa-
tional control values. AnRCPRIV_BASIC privileged con-
trol value placed by a process on the task or process
will generate an action only if the value is exceeded
by that process.
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 facil-
ity: SIGBART, SIGXRES, SIGHUP, SIGSTOP, SIGTERM, and SIG-
KILL. Other signals are permitted due to global properites
of a specific control. Calls to setrctl() with illegal sig-
nals 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 con-
trol; 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 con-
trol value is exceeded.
RCTL_LOCAL_SIGNAL
The specified dignal, sent by
rctlblk_set_local_action(), will be sent to the pro-
cess that placed this resource control value in the
value sequence.
The rctlblk_get_recipient_pid() function returns the value
of the process ID that placed the resource control value.
This ID is set by the kernel by a caller invoking setrctl().
The rctlblk_get_privilege() function returns the privilege
of the resource contorl block. Valid privileges are
RCPRIV_BASIC, RCPRIV_PRIVILEGED, and RCPRIV_SYSTEM. System
resource controls are read-only. Privileged resource con-
trols require superuser 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 pro-
ject associated with the control possesess fewer capabili-
ties 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 sys-
tem.
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 con-
trol block.
The following example displays the contents of a fetched
resource control block.
#include <rctl.h>
#include <stdio.h>
#include <stdlib.h>
rctlblk_t *rblk;
int rsignal;
int raction;
if ((rblk = malloc(rctlblk_size())) == NULL) {
(void) perror("rblk malloc");
exit(1);
}
if (getrctl("process.max-cpu-time", NULL, rblk, RCTL_FIRST) == -1) {
(void) perror("getrctl");
exit(1);
}
raction = rctlblk_get_local_action(rblk, &rsignal),
(void) printf("Resource control for %s\n",
"process.max-cpu-time");
(void) printf("Process ID: %d\n",
rctlblk_get_recipient_pid(rblk));
(void) printf("Privilege: %x\n"
rctlblk_get_privilege(rblk),
(void) printf("Global flags: %x\n"
rctlblk_get_global_flags(rblk),
(void) printf("Global actions: %x\n"
rctlblk_get_global_action(rblk),
(void) printf("Local flags: %x\n"
rctlblk_get_local_flags(rblk),
(void) printf("Local action: %x (%d)\n"
raction, raction == RCTL_LOCAL_SIGNAL ? rsignal : 0);
(void) printf("Value: %llu\n",
rctlblk_get_value(rblk));
(void) printf("Enforced value: %llu\n",
rctlblk_get_enforced_value(rblk));
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Evolving |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
rctladm(1M), getrctl(2), setrctl(2), gethrtime(3C), attri-
butes(5)
Man(1) output converted with
man2html