|
Hopefully, this page is exactly what you are looking for, but if not, you can always find further assistance on Unix/Linux Forum!
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 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
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 pro-
ject, 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
SunOS 5.10 Last change: 31 Aug 2006 1
System Calls setrctl(2)
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 pro-
cess ID set by rctlblk_set_recipient_pid(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_get_firing_time(3C) function. The insertion or dele-
tion 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 argu-
ment points to an illegal address.
SunOS 5.10 Last change: 31 Aug 2006 2
System Calls setrctl(2)
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_recipient_pid(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 pro-
cess ID set by rctlblk_set_recipient_pid(3C)
does not exist within the current task, pro-
ject, 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.
SunOS 5.10 Last change: 31 Aug 2006 3
System Calls setrctl(2)
Obtain the lowest enforced rctl value on the rctl limiting
the number of LWPs in a task.
#include <sys/types.h>
#include <rctl.h>
#include <stdio.h>
uint64_t value;
int cur_signal;
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",
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 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 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 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
described in the following paragraph.
SunOS 5.10 Last change: 31 Aug 2006 4
System Calls setrctl(2)
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 RCTL_INSERT and RCTL_DELETE 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 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 con-
trol does not have the global RCTL_GLOBAL_LOWERABLE property
set, its hard limit will not allow lowering by unprivileged
callers.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | Async-Signal-Safe |
|_____________________________|_____________________________|
SEE ALSO
rctladm(1M), getrlimit(2), errno(3C), rctlblk_set_value(3C),
attributes(5), resource_controls(5)
SunOS 5.10 Last change: 31 Aug 2006 5
Man(1) output converted with
man2html and wrapped by fishsponge
This page was generated on Wed Sep 12 11:27:08 GMT 2007
|
Your favourite pages:
No pages logged yet... Top 10 most popular pages:
prstat man page (24546 hits)
(Solaris 10 11_06)
netcat man page (17695 hits)
(Suse Linux 10.1)
ssh-socks5-proxy-connect man page (13531 hits)
(Solaris 10 11_06)
signal man page (12551 hits)
(Suse Linux 10.1)
startproc man page (11991 hits)
(Suse Linux 10.1)
raidctl man page (11357 hits)
(Solaris 10 11_06)
adv_cap_autoneg man page (10285 hits)
(Solaris 10 11_06)
sqlite3 man page (9729 hits)
(openSUSE 10.2)
CPAN man page (8947 hits)
(Suse Linux 10.1)
BusyBox man page (7702 hits)
(Suse Linux 10.1)
|
Man Pages 
