te
Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
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_set_recipient_pid, rctlblk_size - manipulate resource control blocks

#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);

void rctlblk_set_recipient_pid(id_tpid);

size_t rctlblk_size(void);

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

RCTL_GLOBAL_DENY_NEVER RCTL_GLOBAL_SIGNAL_NEVER RCTL_GLOBAL_CPU_TIME RCTL_GLOBAL_FILE_SIZE RCTL_GLOBAL_INFINITE RCTL_GLOBAL_LOWERABLE RCTL_GLOBAL_NOACTION RCTL_GLOBAL_NOBASIC RCTL_GLOBAL_SYSLOG RCTL_GLOBAL_SYSLOG_NEVER RCTL_GLOBAL_UNOBSERVABLE RCTL_GLOBAL_BYTES RCTL_GLOBAL_SECONDS RCTL_GLOBAL_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 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 are permitted due to global properties of a specific control. Calls to setrctl() with illegal signals will fail. RCTL_LOCAL_DENY

RCTL_LOCAL_MAXIMAL RCTL_LOCAL_NOACTION RCTL_LOCAL_SIGNAL

The rctlblk_get_recipient_pid() function returns the value of the process ID that placed the resource control value for basic rctls. For privileged or system rctls, rctlblk_get_recipient_pid() returns -1.

The rctlblk_set_recipient_pid() function sets the recipient pid for a basic rctl. When setrctl(2) is called with the flag RCTL_USE_RECIPIENT_PID, 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 recipient PID that matches the PID of the calling process.

The rctlblk_get_privilege() function returns the privilege of the resource control block. Valid privileges are RCPRIV_BASIC, RCPRIV_PRIVILEGED, and RCPRIV_SYSTEM. System resource controls are read-only. Privileged resource controls require the {PRIV_SYS_RESOURCE} 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 possesses 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.

The various set routines have no return values. Incorrectly composed resource control blocks will generate errors when used with setrctl(2) or getrctl(2).

No error values are returned. Incorrectly constructed resource control blocks will be rejected by the system calls.

Example 1 Display the contents of a fetched resource control block.

The following example displays the contents of a fetched resource control block.

#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);
}

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

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

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Evolving

MT-Level MT-Safe

rctladm(1M), getrctl(2), setrctl(2), gethrtime(3C), attributes(5)