Windows PowerShell command on Get-command getrctl

Manual Pages for UNIX Operating System command usage for man getrctl

System Calls setrctl(2)

NAME

setrctl, getrctl - set or get resource control values

SYNOPSIS

#include

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

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 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 pro-

cess 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.

SunOS 5.11 Last change: 31 Jan 2007 2

System Calls setrctl(2)

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.

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

...

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 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

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 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 |