RCTLBLK_SET_VALUE(3C) Standard C Library Functions RCTLBLK_SET_VALUE(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_set_recipient_pid, 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);
void rctlblk_set_recipient_pid(
id_tpid);
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(8).
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_SYSLOG_NEVER The resource control does not support the
syslog() global action. Exceeding a resource
control value on this control will not result
in a message logged by the
syslog() facility.
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.
#include <rctl.h>
#include <stdio.h>
#include <stdlib.h>
int
main()
{
rctlblk_t *rblk;
int rsignal, 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",
(int)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("\tEnforced value: %llu\n",
rctlblk_get_enforced_value(rblk));
return (0);
}
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Evolving |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+
SEE ALSO
getrctl(2),
setrctl(2),
gethrtime(3C),
attributes(7),
rctladm(8) August 2, 2016
RCTLBLK_SET_VALUE(3C)