SunOS man pages


	www.sun.com	docs.sun.com \| \| \|

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Standard C Library Functions

rctlblk_set_value(3C)

DESCRIPTION
RETURN VALUES
ERRORS
EXAMPLES
ATTRIBUTES
SEE ALSO

NAME

rctlblk_set_value, rctlblk_get_firing_time, rctlblk_get_global_action, rctlblk_get_global_flags, rctlblk_get_local_action, rctlblk_get_local_flags, rctlblk_get_privilege, rctlblk_get_recipient_pid, rctlblk_get_value, rctlblk_get_enforced_value, rctlblk_set_local_action, rctlblk_set_local_flags, rctlblk_set_privilege, rctlblk_size - manipulate resource control blocks

SYNOPSIS

#include <rctl.h> hrtime_t rctlblk_get_firing_time(rctlblk_t *rblk);

int rctlblk_get_global_action(rctlblk_t *rblk);

int rctlblk_get_global_flags(rctlblk_t *rblk);

int rctlblk_get_local_action(rctlblk_t *rblk, int *signalp);

int rctlblk_get_local_flags(rctlblk_t *rblk);

rctl_priv_t rctlblk_get_privilege(rctlblk_t *rblk);

id_t rctlblk_get_recipient_pid(rctlblk_t *rblk);

rctl_qty_t rctlblk_get_value(rctlblk_t *rblk);

rctl_qty_t rctlblk_get_enforced_value(rctlblk_t *rblk);

void rctlblk_set_local_action(rctlblk_t *rblk, rctl_action_t action, int signal);

void rctlblk_set_local_flags(rctlblk_t *rblk, int flags);

void rctlblk_set_privilege(rctlblk_t *rblk, rctl_priv_t privilege);

void rctlblk_set_value(rctlblk_t *rblk, rctl_qty_t value);

size_t rctlblk_size(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(). Valid global actions are listed in the table below. Global flags are generally a published property of the control and are not modifiable.

RCTL_GLOBAL_DENY_ALWAYS: The action taken when a control value is exceeded on this control will always include denial of the resource.
RCTL_GLOBAL_DENY_NEVER: The action taken when a control value is exceeded on this control will always exclude denial of the resource; the resource will always be granted, although other actions can also be taken.
RCTL_GLOBAL_CPU_TIME: The valid signals available as local actions include the SIGXCPU signal.
RCTL_GLOBAL_FILE_SIZE: The valid signals available as local actions include the SIGXFSZ signal.
RCTL_GLOBAL_INFINITE: This resource control supports the concept of an unlimited value; generally true only of accumulation-oriented resources, such as CPU time.
RCTL_GLOBAL_LOWERABLE: Non-privileged callers are able to lower the value of privileged resource control values on this control.
RCTL_GLOBAL_NOACTION: No global action will be taken when a resource control value is exceeded on this control.
RCTL_GLOBAL_NOBASIC: No values with the RCPRIV_BASIC privilege are permitted on this control.
RCTL_GLOBAL_NOLOCALACTION: No local actions are permitted on this control.
RCTL_GLOBAL_SYSLOG: A standard message will be logged by the syslog() facility when any resource control value on a sequence associated with this control is exceeded.
RCTL_GLOBAL_UNOBSERVABLE: The resource control (generally on a task- or project-related control) does not support observational control values. AnRCPRIV_BASIC 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.

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 RCTL_LOCAL_SIGNAL, the second argument to rctlblk_set_local_action() contains the signal to be sent. Similarly, the signal to be sent is copied into the integer location specified by the second argument to rctlblk_get_local_action(). A restricted set of signals is made available for normal use by the resource control facility: SIGBART, SIGXRES, SIGHUP, SIGSTOP, SIGTERM, and SIGKILL. Other signals may be permitted due to global properites of a specific control. Calls to setrctl() with illegal signals will fail.

RCTL_LOCAL_DENY: When this resource control value is encountered, the request for the resource will be denied. Set on all values if RCTL_GLOBAL_DENY_ALWAYS is set for this control; cleared on all values if RCTL_GLOBAL_DENY_NEVER is set for this control.
RCTL_LOCAL_INFINITE: This resource control value represents an infinite value and will never be reached.
RCTL_LOCAL_MAXIMAL: This resource control value represents a request for the maximum amount of resource for this control. If RCTL_GLOBAL_INFINITE is set for this resource control, RCTL_LOCAL_MAXIMAL indicates an unlimited resource control value, one that will never be exceeded.
RCTL_LOCAL_NOACTION: No local action will be taken when this resource control value is exceeded.
RCTL_LOCAL_SIGNAL: The specified dignal, sent by rctlblk_set_local_action(), will be sent to the process that placed this resource control value in the value sequence.

The rctlblk_get_recipient_pid() function returns the value of the process ID that placed the resource control value. This ID is set by the kernel by a caller invoking setrctl().

The rctlblk_get_privilege() function returns the privilege of the resource contorl block. Valid privileges are RCPRIV_BASIC, RCPRIV_PRIVILEGED, and RCPRIV_SYSTEM. System resource controls are read-only. Privileged resource controls require superuser privilege to write, unless the RCTL_GLOBAL_LOWERABLE global flag is set, in which case unprivileged applications can lower the value of a privileged control.

The rctlblk_get_value() and rctlblk_set_value() functions return or establish the enforced value associated with the resource control. In cases where the process, task, or project associated with the control possesess fewer capabilities than allowable by the current value, the value returned by rctlblk_get_enforced_value() will differ from that returned by rctlblk_get_value(). This capability difference arises with processes using an address space model smaller than the maximum address space model supported by the system.

The rctlblk_size() function returns the size of a resource control block for use in memory allocation. The rctlblk_t * type is an opaque pointer whose size is not connected with that of the resource control block itself. Use of rctlblk_size() is illustrated in the example below.

#include <rctl.h>
#include <stdio.h>
#include <stdlib.h>

rctlblk_t *rblk;
int rsignal;
int raction;

if ((rblk = malloc(rctlblk_size())) == NULL) {
       (void) perror("rblk malloc");
       exit(1);
}

if (getrctl("process.max-cpu-time", NULL, rblk, RCTL_FIRST) == -1) {
       (void) perror("getrctl");
       exit(1);
}
raction = rctlblk_get_local_action(rblk, &rsignal),
(void) printf("Resource control for %s\n",
    "process.max-cpu-time");
(void) printf("Process ID:     %d\n",
    rctlblk_get_recipient_pid(rblk));
(void) printf("Privilege:      %x\n"
    rctlblk_get_privilege(rblk),
(void) printf("Global flags:   %x\n"
    rctlblk_get_global_flags(rblk),
(void) printf("Global actions: %x\n"
    rctlblk_get_global_action(rblk),
(void) printf("Local flags:    %x\n"
    rctlblk_get_local_flags(rblk),
(void) printf("Local action:   %x (%d)\n"
    raction, raction == RCTL_LOCAL_SIGNAL ? rsignal : 0);
(void) printf("Value:          %llu\n",
    rctlblk_get_value(rblk));
(void) printf("\tEnforced value: %llu\n",
    rctlblk_get_enforced_value(rblk));

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving
MT-Level	MT-Safe

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

EXAMPLES

ATTRIBUTES

SEE ALSO