SETRCTL(2) System Calls SETRCTL(2)
NAME
setrctl, getrctl - set or get resource control values
SYNOPSIS
#include <rctl.h>
int setrctl(
const char *controlname,
rctlblk_t *old_blk,
rctlblk_t *new_blk,
uint_t flags);
int getrctl(
const char *controlname,
rctlblk_t *old_blk,
rctlblk_t *new_blk,
uint_t flags);
DESCRIPTION
The
setrctl() and
getrctl() functions provide interfaces for the
modification and retrieval of resource control (rctl) values on active
entities on the system, such as processes, tasks, or projects. All
resource controls are unsigned 64-bit integers; however, a collection of
flags are defined that modify which rctl value is to be set or retrieved.
Resource controls are restricted to three levels: basic controls that can
be modified by the owner of the calling process, privileged controls that
can be modified only by privileged callers, and system controls that are
fixed for the duration of the operating system instance. Setting or
retrieving each of these controls is performed by setting the privilege
field of the resource control block to
RCTL_BASIC,
RCTL_PRIVILEGED, or
RCTL_SYSTEM with
rctlblk_set_privilege() (see
rctlblk_set_value(3C)).
For limits on collective entities such as the task or project, the
process ID of the calling process is associated with the resource control
value. This ID is available by using
rctlblk_get_recipient_pid() (see
rctlblk_set_value(3C)). These values are visible only to that process and
privileged processes within the collective.
The
getrctl() function provides a mechanism for iterating through all of
the established values on a resource control. The iteration is primed by
calling
getrctl() with
old_blk set to
NULL, a valid resource control
block pointer in
new_blk, and specifying
RCTL_FIRST in the
flags argument. Once a resource control block has been obtained, repeated
calls to
getrctl() with
RCTL_NEXT in the
flags argument and the obtained
control in the
old_blk argument will return the next resource control
block in the sequence. The iteration reports the end of the sequence by
failing and setting
errno to
ENOENT.
The
getrctl() function allows the calling process to get the current
usage of a controlled resource using
RCTL_USAGE as the
flags value. The
current value of the resource usage is placed in the value field of the
resource control block specified by
new_blk. This value is obtained with
rctlblk_set_value(3C). All other members of the returned block are
undefined and might be invalid.
The
setrctl() function allows the creation, modification, or deletion of
action-value pairs on a given resource control. When passed
RCTL_INSERT as the
flags value,
setrctl() expects
new_blk to contain a new action-
value pair for insertion into the sequence. For
RCTL_DELETE, the block
indicated by
new_blk is deleted from the sequence. For
RCTL_REPLACE, the
block matching
old_blk is deleted and replaced by the block indicated by
new_blk. When (
flags &
RCTL_USE_RECIPIENT_PID) is non-zero,
setrctl() uses the process ID set by
rctlblk_set_value(3C) when selecting the rctl
value to insert, delete, or replace basic rctls. Otherwise, the process
ID of the calling process is used.
The kernel maintains a history of which resource control values have
triggered for a particular entity, retrievable from a resource control
block with the
rctlblk_set_value(3C) function. The insertion or deletion
of a resource control value at or below the currently enforced value
might cause the currently enforced value to be reset. In the case of
insertion, the newly inserted value becomes the actively enforced value.
All higher values that have previously triggered will have their firing
times zeroed. In the case of deletion of the currently enforced value,
the next higher value becomes the actively enforced value.
The various resource control block properties are described on the
rctlblk_set_value(3C) manual page.
Resource controls are inherited from the predecessor process or task.
One of the
exec(2) functions can modify the resource controls of a
process by resetting their histories, as noted above for insertion or
deletion operations.
RETURN VALUES
Upon successful completion, the
setrctl() and
getrctl() functions return
0. Otherwise they return -1 and set
errno to indicate the error.
ERRORS
The
setrctl() and
getrctl() functions will fail if:
EFAULT The
controlname,
old_blk, or
new_blk argument points to an
illegal address.
EINVAL No resource control with the given name is known to the
system, or the resource control block contains properties
that are not valid for the resource control specified.
RCTL_USE_RECIPIENT_PID was used to set a process scope rctl
and the process ID set by
rctlblk_set_value(3C) does not
match the process ID of calling process.
ENOENT No value beyond the given resource control block exists.
RCTL_USE_RECIPIENT_PID was used and the process ID set by
rctlblk_set_value(3C) does not exist within the current task,
project, or zone, depending on the resource control name.
ESRCH No value matching the given resource control block was found
for any of
RCTL_NEXT,
RCTL_DELETE, or
RCTL_REPLACE.
ENOTSUPP The resource control requested by
RCTL_USAGE does not support
the usage operation.
The
setrctl() function will fail if:
EACCES The rctl value specified cannot be changed by the current
process, including the case where the recipient process ID does
not match the calling process and the calling process is
unprivileged.
EPERM An attempt to set a system limit was attempted.
EXAMPLES
Example 1: Retrieve a rctl value.
Obtain the lowest enforced rctl value on the rctl limiting the number of
LWPs in a task.
#include <rctl.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
...
rctlblk_t *rblk;
if ((rblk = (rctlblk_t *)malloc(rctlblk_size())) == NULL) {
(void) fprintf(stderr, "malloc failed: %s\n",
strerror(errno));
exit(1);
}
if (getrctl("task.max-lwps", NULL, rblk, RCTL_FIRST) == -1)
(void) fprintf(stderr, "failed to get rctl: %s\n",
strerror(errno));
else
(void) printf("task.max-lwps = %llu\n",
rctlblk_get_value(rblk));
USAGE
Resource control blocks are matched on the value and privilege fields.
Resource control operations act on the first matching resource control
block. Duplicate resource control blocks are not permitted. Multiple
blocks of equal value and privilege need to be entirely deleted and
reinserted, rather than replaced, to have the correct outcome. Resource
control blocks are sorted such that all blocks with the same value that
lack the
RCTL_LOCAL_DENY flag precede those having that flag set.
Only one
RCPRIV_BASIC resource control value is permitted per process per
control. Insertion of an
RCPRIV_BASIC value will cause any existing
RCPRIV_BASIC value owned by that process on the control to be deleted.
The resource control facility provides the backend implementation for
both
setrctl()/
getrctl() and
setrlimit()/
getrlimit(). The facility
behaves consistently when either of these interfaces is used exclusively;
when using both interfaces, the caller must be aware of the ordering
issues above, as well as the limit equivalencies described in the
following paragraph.
The hard and soft process limits made available with
setrlimit() and
getrlimit() are mapped to the resource controls implementation. (New
process resource controls will not be made available with the rlimit
interface.) Because of the
RCTL_INSERT and
RCTL_DELETE operations, it is
possible that the set of values defined on a resource control has more or
fewer than the two values defined for an rlimit. In this case, the soft
limit is the lowest priority resource control value with the
RCTL_LOCAL_DENY flag set, and the hard limit is the resource control
value with the lowest priority equal to or exceeding
RCPRIV_PRIVILEGED with the
RCTL_LOCAL_DENY flag set. If no identifiable soft limit exists
on the resource control and
setrlimit() is called, a new resource control
value is created. If a resource control does not have the global
RCTL_GLOBAL_LOWERABLE property set, its hard limit will not allow
lowering by unprivileged callers.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+---------------+-------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-------------------+
|MT-Level | Async-Signal-Safe |
+---------------+-------------------+
SEE ALSO
getrlimit(2),
errno(3C),
rctlblk_set_value(3C),
attributes(7),
resource_controls(7),
rctladm(8) January 31, 2007
SETRCTL(2)