| Skip Navigation Links | |
| Exit Print View | |
 | man pages section 2: System Calls Oracle Solaris 11 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
| man pages section 2: System Calls Oracle Solaris 11 Information Library |
- set or get resource control values
#include <rctl.h>intsetrctl(const char *controlname,rctlblk_t *old_blk,rctlblk_t *new_blk,uint_tflags);
intgetrctl(const char *controlname,rctlblk_t *old_blk,rctlblk_t *new_blk,uint_tflags);
Thesetrctl() andgetrctl() functions provide interfaces for the modification and retrievalof resource control (rctl) values on active entities on the system, suchas processes, tasks, or projects. All resource controls are unsigned 64-bitintegers; however, a collection of flags are defined that modify which rctl valueis to be set or retrieved.
Resource controls are restricted to three levels: basic controls that can bemodified by the owner of the calling process, privileged controls that canbe modified only by privileged callers, and system controls that are fixedfor the duration of the operating system instance. Setting or retrieving eachof these controls is performed by setting the privilege field of theresource control block toRCTL_BASIC,RCTL_PRIVILEGED, orRCTL_SYSTEM withrctlblk_set_privilege() (seerctlblk_set_value(3C)).
For limits on collective entities such as the task or project, theprocess ID of the calling process is associated with the resource controlvalue. This ID is available by usingrctlblk_get_recipient_pid() (seerctlblk_set_value(3C)). These valuesare visible only to that process and privileged processes within the collective.
Thegetrctl() function provides a mechanism for iterating through all of theestablished values on a resource control. The iteration is primed bycallinggetrctl() withold_blk set toNULL, a valid resource control block pointerinnew_blk, and specifyingRCTL_FIRST in theflags argument. Once aresource control block has been obtained, repeated calls togetrctl() withRCTL_NEXTin theflags argument and the obtained control in theold_blk argumentwill return the next resource control block in the sequence. Theiteration reports the end of the sequence by failing and settingerrnotoENOENT.
Thegetrctl() function allows the calling process to get the current usageof a controlled resource usingRCTL_USAGE as theflags value. The currentvalue of the resource usage is placed in the value field ofthe resource control block specified bynew_blk. This value is obtained withrctlblk_set_value(3C).All other members of the returned block are undefined and might be invalid.
Thesetrctl() function allows the creation, modification, or deletion of action-value pairson a given resource control. When passedRCTL_INSERT as theflagsvalue,setrctl() expectsnew_blk to contain a new action-value pair for insertion intothe sequence. ForRCTL_DELETE, the block indicated bynew_blk is deleted fromthe sequence. ForRCTL_REPLACE, the block matchingold_blk is deleted and replaced bythe block indicated bynew_blk. When (flags &RCTL_USE_RECIPIENT_PID) is non-zero,setrctl()uses the process ID set byrctlblk_set_value(3C) when selecting the rctl valueto insert, delete, or replace basic rctls. Otherwise, the process ID ofthe calling process is used.
The kernel maintains a history of which resource control values have triggeredfor a particular entity, retrievable from a resource control block with therctlblk_set_value(3C) function. The insertion or deletion of a resource control value ator below the currently enforced value might cause the currently enforced valueto be reset. In the case of insertion, the newly insertedvalue becomes the actively enforced value. All higher values that have previouslytriggered will have their firing times zeroed. In the case ofdeletion of the currently enforced value, the next higher value becomes theactively enforced value.
The various resource control block properties are described on therctlblk_set_value(3C) manualpage.
Resource controls are inherited from the predecessor process or task. Oneof theexec(2) functions can modify the resource controls of a processby resetting their histories, as noted above for insertion or deletion operations.
Upon successful completion, thesetrctl() andgetrctl() functions return 0. Otherwise theyreturn -1 and seterrno to indicate the error.
Thesetrctl() andgetrctl() functions will fail if:
Thecontrolname,old_blk, ornew_blk argument points to an illegal address.
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 byrctlblk_set_value(3C) does not match the process ID of calling process.
No value beyond the given resource control block exists.
RCTL_USE_RECIPIENT_PID was used and the process ID set byrctlblk_set_value(3C) does not exist within the current task, project, or zone, depending on the resource control name.
No value matching the given resource control block was found for any ofRCTL_NEXT,RCTL_DELETE, orRCTL_REPLACE.
The resource control requested byRCTL_USAGE does not support the usage operation.
Thesetrctl() function will fail if:
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.
An attempt to set a system limit was attempted.
Example 1 Retrieve a rctl value.
Obtain the lowest enforced rctl value on the rctl limiting the numberof 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));Resource control blocks are matched on the value and privilege fields. Resource control operations act on the first matching resource control block. Duplicateresource control blocks are not permitted. Multiple blocks of equal value andprivilege need to be entirely deleted and reinserted, rather than replaced, to havethe correct outcome. Resource control blocks are sorted such that all blockswith the same value that lack theRCTL_LOCAL_DENY flag precede those havingthat flag set.
Only oneRCPRIV_BASIC resource control value is permitted per process per control. Insertion of anRCPRIV_BASIC value will cause any existingRCPRIV_BASIC valueowned by that process on the control to be deleted.
The resource control facility provides the backend implementation for bothsetrctl()/getrctl() andsetrlimit()/getrlimit(). The facility behaves consistently when either of these interfaces is usedexclusively; when using both interfaces, the caller must be aware of the orderingissues above, as well as the limit equivalencies described in the followingparagraph.
The hard and soft process limits made available withsetrlimit() andgetrlimit()are mapped to the resource controls implementation. (New process resource controlswill not be made available with the rlimit interface.) Because oftheRCTL_INSERT andRCTL_DELETE operations, it is possible that the set ofvalues defined on a resource control has more or fewer than thetwo values defined for an rlimit. In this case, the softlimit is the lowest priority resource control value with theRCTL_LOCAL_DENY flagset, and the hard limit is the resource control value with the lowestpriority equal to or exceedingRCPRIV_PRIVILEGED with theRCTL_LOCAL_DENY flag set. If no identifiable soft limit exists on the resource control andsetrlimit()is called, a new resource control value is created. If a resourcecontrol does not have the globalRCTL_GLOBAL_LOWERABLE property set, its hard limitwill not allow lowering by unprivileged callers.
Seeattributes(5) for descriptions of the following attributes:
|
rctladm(1M),getrlimit(2),errno(3C),rctlblk_set_value(3C),attributes(5),resource_controls(5)
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.Legal Notices |   |