Standard C Library Functions rctlblksetvalue(3C)
NAME
rctlblksetvalue, rctlblkgetfiringtime,
rctlblkgetglobalaction, rctlblkgetglobalflags,
rctlblkgetlocalaction, rctlblkgetlocalflags,
rctlblkgetprivilege, rctlblkgetrecipientpid,
rctlblkgetvalue, rctlblkgetenforcedvalue,
rctlblksetlocalaction, rctlblksetlocalflags,
rctlblksetprivilege, rctlblksetrecipientpid,
rctlblksize - manipulate resource control blocks
SYNOPSIS
#include
hrtimet rctlblkgetfiringtime(rctlblkt *rblk);
int rctlblkgetglobalaction(rctlblkt *rblk);
int rctlblkgetglobalflags(rctlblkt *rblk);
int rctlblkgetlocalaction(rctlblkt *rblk, int *signalp);
int rctlblkgetlocalflags(rctlblkt *rblk);
rctlprivt rctlblkgetprivilege(rctlblkt *rblk);
idt rctlblkgetrecipientpid(rctlblkt *rblk);
rctlqtyt rctlblkgetvalue(rctlblkt *rblk);
rctlqtyt rctlblkgetenforcedvalue(rctlblkt *rblk);
void rctlblksetlocalaction(rctlblkt *rblk, rctlactiont action,
int signal);
void rctlblksetlocalflags(rctlblkt *rblk, int flags);
void rctlblksetprivilege(rctlblkt *rblk, rctlprivt privilege);
void rctlblksetvalue(rctlblkt *rblk, rctlqtyt value);
SunOS 5.11 Last change: 15 May 2006 1
Standard C Library Functions rctlblksetvalue(3C)
void rctlblksetrecipientpid(idtpid);
sizet rctlblksize(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(2).
Valid global actions are listed in the table below. Global
flags are generally a published property of the control and
are not modifiable.
RCTLGLOBALDENYALWAYS The action taken when a control
value is exceeded on this con-
trol will always include denial
of the resource.
RCTLGLOBALDENYNEVER The action taken when a control
value is exceeded on this con-
trol will always exclude denial
of the resource; the resource
will always be granted, although
other actions can also be taken.
RCTLGLOBALSIGNALNEVER No signal actions are permitted
on this control.
RCTLGLOBALCPUTIME The valid signals available as
local actions include the
SIGXCPU signal.
SunOS 5.11 Last change: 15 May 2006 2
Standard C Library Functions rctlblksetvalue(3C)
RCTLGLOBALFILESIZE The valid signals available as
local actions include the
SIGXFSZ signal.
RCTLGLOBALINFINITE This resource control supports
the concept of an unlimited
value; generally true only of
accumulation-oriented resources,
such as CPU time.
RCTLGLOBALOWERABLE Non-privileged callers are able
to lower the value of privileged
resource control values on this
control.
RCTLGLOBALNOACTION No global action will be taken
when a resource control value is
exceeded on this control.
RCTLGLOBALNOBASIC No values with the RCPRIVBASIC
privilege are permitted on this
control.
RCTLGLOBALSYSLOG A standard message will be
logged by the syslog(3C) facil-
ity when any resource control
value on a sequence associated
with this control is exceeded.
RCTLGLOBALSYSLOGNEVER 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.
RCTLGLOBALUNOBSERVABLE The resource control (generally
on a task- or project-related
control) does not support obser-
vational control values. An
RCPRIVBASIC 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.
SunOS 5.11 Last change: 15 May 2006 3
Standard C Library Functions rctlblksetvalue(3C)
RCTLGLOBALBYTES This resource control represents
a number of bytes.
RCTLGLOBALSECONDS This resource control represents
a quantity of time in seconds.
RCTLGLOBALCOUNT 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 RCTLOCALSIGNAL, the second argument to
rctlblksetlocalaction() contains the signal to be sent.
Similarly, the signal to be sent is copied into the integer
location specified by the second argument to
rctlblkgetlocalaction(). A restricted set of signals is
made available for normal use by the resource control facil-
ity: SIGBART, SIGXRES, SIGHUP, SIGSTOP, SIGTERM, and SIG-
KIL. Other signals are permitted due to global properties
of a specific control. Calls to setrctl() with illegal sig-
nals will fail.
RCTLOCALDENY When this resource control value is
encountered, the request for the
resource will be denied. Set on all
values if RCTLGLOBALDENYALWAYS is
set for this control; cleared on all
values if RCTLGLOBALDENYNEVER is
set for this control.
RCTLOCALMAXIMAL This resource control value
represents a request for the maximum
amount of resource for this control.
If RCTLGLOBALINFINITE is set for
this resource control,
RCTLOCALMAXIMAL indicates an
unlimited resource control value, one
that will never be exceeded.
RCTLOCALNOACTION No local action will be taken when
this resource control value is
exceeded.
SunOS 5.11 Last change: 15 May 2006 4
Standard C Library Functions rctlblksetvalue(3C)
RCTLOCALSIGNAL The specified signal, sent by
rctlblksetlocalaction(), 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 rctlblkgetrecipientpid() function returns the value
of the process ID that placed the resource control value for
basic rctls. For privileged or system rctls,
rctlblkgetrecipientpid() returns -1.
The rctlblksetrecipientpid() function sets the recipient
pid for a basic rctl. When setrctl(2) is called with the
flag RCTLUSERECIPIENTPID, 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 reci-
pient PID that matches the PID of the calling process.
The rctlblkgetprivilege() function returns the privilege
of the resource control block. Valid privileges are
RCPRIVBASIC, RCPRIVPRIVILEGED, and RCPRIVSYSTEM. System
resource controls are read-only. Privileged resource con-
trols require the {PRIVSYSRESOURCE} privilege to write,
unless the RCTLGLOBALOWERABLE global flag is set, in
which case unprivileged applications can lower the value of
a privileged control.
The rctlblkgetvalue() and rctlblksetvalue() 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 possesses fewer capabili-
ties than allowable by the current value, the value returned
by rctlblkgetenforcedvalue() will differ from that
returned by rctlblkgetvalue(). This capability difference
arises with processes using an address space model smaller
than the maximum address space model supported by the sys-
tem.
The rctlblksize() function returns the size of a resource
control block for use in memory allocation. The rctlblkt *
SunOS 5.11 Last change: 15 May 2006 5
Standard C Library Functions rctlblksetvalue(3C)
type is an opaque pointer whose size is not connected with
that of the resource control block itself. Use of
rctlblksize() 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).
ERORS
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
#include
#include
rctlblkt *rblk;
int rsignal;
int raction;
if ((rblk = malloc(rctlblksize())) == NUL) {
(void) perror("rblk malloc");
exit(1);
}
if (getrctl("process.max-cpu-time", NUL, rblk, RCTLFIRST) == -1) {
(void) perror("getrctl");
exit(1);
}
main()
{
raction = rctlblkgetlocalaction(rblk, &rsignal),
(void) printf("Resource control for %s\n",
"process.max-cpu-time");
(void) printf("Process ID: %d\n",
rctlblkgetrecipientpid(rblk));
(void) printf("Privilege: %x\n"
rctlblkgetprivilege(rblk));
(void) printf("Global flags: %x\n"
rctlblkgetglobalflags(rblk));
SunOS 5.11 Last change: 15 May 2006 6
Standard C Library Functions rctlblksetvalue(3C)
(void) printf("Global actions: %x\n"
rctlblkgetglobalaction(rblk));
(void) printf("Local flags: %x\n"
rctlblkgetlocalflags(rblk));
(void) printf("Local action: %x (%d)\n"
raction, raction == RCTLOCALSIGNAL ? rsignal : 0);
(void) printf("Value: %llu\n",
rctlblkgetvalue(rblk));
(void) printf("Enforced value: %llu\n",
rctlblkgetenforcedvalue(rblk));
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Evolving
MT-Level MT-Safe
SEE ALSO
rctladm(1M), getrctl(2), setrctl(2), gethrtime(3C), attri-
butes(5)
SunOS 5.11 Last change: 15 May 2006 7
|
