System Calls setrctl(2)
NAME
setrctl, getrctl - set or get resource control values
SYNOPSIS
#include
int setrctl(const char *controlname, rctlblkt *oldblk,
rctlblkt *newblk, uintt flags);
int getrctl(const char *controlname, rctlblkt *oldblk,
rctlblkt *newblk, uintt 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 con-
trols that can be modified by the owner of the calling pro-
cess, 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
RCTLBASIC, RCTLPRIVILEGED, or RCTLSYSTEM with
rctlblksetprivilege() (see rctlblksetvalue(3C)).
For limits on collective entities such as the task or pro-
ject, the process ID of the calling process is associated
with the resource control value. This ID is available by
using rctlblkgetrecipientpid() (see
rctlblksetvalue(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 oldblk
set to NUL, a valid resource control block pointer in
newblk, and specifying RCTLFIRST in the flags argument.
Once a resource control block has been obtained, repeated
calls to getrctl() with RCTLNEXT in the flags argument and
the obtained control in the oldblk argument will return the
next resource control block in the sequence. The iteration
reports the end of the sequence by failing and setting errno
SunOS 5.11 Last change: 31 Jan 2007 1
System Calls setrctl(2)
to ENOENT.
The getrctl() function allows the calling process to get the
current usage of a controlled resource using RCTLUSAGE as
the flags value. The current value of the resource usage is
placed in the value field of the resource control block
specified by newblk. This value is obtained with
rctlblksetvalue(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 RCTLINSERT as the flags value, setrctl()
expects newblk to contain a new action-value pair for
insertion into the sequence. For RCTLDELETE, the block
indicated by newblk is deleted from the sequence. For
RCTLREPLACE, the block matching oldblk is deleted and
replaced by the block indicated by newblk. When (flags &
RCTLUSERECIPIENTPID) is non-zero, setrctl() uses the pro-
cess ID set by rctlblksetvalue(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 rctlblksetvalue(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 rctlblksetvalue(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.
SunOS 5.11 Last change: 31 Jan 2007 2
System Calls setrctl(2)
ERORS
The setrctl() and getrctl() functions will fail if:
EFAULT The controlname, oldblk, or newblk 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.
RCTLUSERECIPIENTPID was used to set a process
scope rctl and the process ID set by
rctlblksetvalue(3C) does not match the process
ID of calling process.
ENOENT No value beyond the given resource control block
exists.
RCTLUSERECIPIENTPID was used and the process
ID set by rctlblksetvalue(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 RCTLNEXT,
RCTLDELETE, or RCTLREPLACE.
ENOTSUP The resource control requested by RCTLUSAGE
does not support the usage operation.
The setrctl() function will fail if:
EACES 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.
SunOS 5.11 Last change: 31 Jan 2007 3
System Calls setrctl(2)
Obtain the lowest enforced rctl value on the rctl limiting
the number of LWPs in a task.
#include
#include
#include
#include
#include
...
rctlblkt *rblk;
if ((rblk = (rctlblkt *)malloc(rctlblksize())) == NUL) {
(void) fprintf(stderr, "malloc failed: %s\n",
strerror(errno));
exit(1);
}
if (getrctl("task.max-lwps", NUL, rblk, RCTLFIRST) == -1)
(void) fprintf(stderr, "failed to get rctl: %s\n",
strerror(errno));
else
(void) printf("task.max-lwps = %llu\n",
rctlblkgetvalue(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 rein-
serted, rather than replaced, to have the correct outcome.
Resource control blocks are sorted such that all blocks with
the same value that lack the RCTLOCALDENY flag precede
those having that flag set.
Only one RCPRIVBASIC resource control value is permitted
per process per control. Insertion of an RCPRIVBASIC value
will cause any existing RCPRIVBASIC value owned by that
process on the control to be deleted.
The resource control facility provides the backend implemen-
tation 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 ord-
ering issues above, as well as the limit equivalencies
SunOS 5.11 Last change: 31 Jan 2007 4
System Calls setrctl(2)
described in the following paragraph.
The hard and soft process limits made available with
setrlimit() and getrlimit() are mapped to the resource con-
trols implementation. (New process resource controls will
not be made available with the rlimit interface.) Because
of the RCTLINSERT and RCTLDELETE operations, it is possi-
ble 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 RCTLOCALDENY flag set, and the
hard limit is the resource control value with the lowest
priority equal to or exceeding RCPRIVPRIVILEGED with the
RCTLOCALDENY 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 con-
trol does not have the global RCTLGLOBALOWERABLE property
set, its hard limit will not allow lowering by unprivileged
callers.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level Async-Signal-Safe
SEE ALSO
rctladm(1M), getrlimit(2), errno(3C), rctlblksetvalue(3C),
attributes(5), resourcecontrols(5)
SunOS 5.11 Last change: 31 Jan 2007 5
|
