1rctlblk_set_value(3C) Standard C Library Functions rctlblk_set_value(3C)
2
6 rctlblk_set_value, rctlblk_get_firing_time, rctlblk_get_global_action,
7 rctlblk_get_global_flags, rctlblk_get_local_action, rctl‐
8 blk_get_local_flags, rctlblk_get_privilege, rctlblk_get_recipient_pid,
9 rctlblk_get_value, rctlblk_get_enforced_value, rctl‐
10 blk_set_local_action, rctlblk_set_local_flags, rctlblk_set_privilege,
11 rctlblk_set_recipient_pid, rctlblk_size - manipulate resource control
12 blocks
13
15 #include <rctl.h>
16 hrtime_t rctlblk_get_firing_time(rctlblk_t *rblk);
18 int rctlblk_get_global_action(rctlblk_t *rblk);
21 int rctlblk_get_global_flags(rctlblk_t *rblk);
24 int rctlblk_get_local_action(rctlblk_t *rblk, int *signalp);
27 int rctlblk_get_local_flags(rctlblk_t *rblk);
30 rctl_priv_t rctlblk_get_privilege(rctlblk_t *rblk);
33 id_t rctlblk_get_recipient_pid(rctlblk_t *rblk);
36 rctl_qty_t rctlblk_get_value(rctlblk_t *rblk);
39 rctl_qty_t rctlblk_get_enforced_value(rctlblk_t *rblk);
42 void rctlblk_set_local_action(rctlblk_t *rblk, rctl_action_t action,
45 int signal);
46 void rctlblk_set_local_flags(rctlblk_t *rblk, int flags);
49 void rctlblk_set_privilege(rctlblk_t *rblk, rctl_priv_t privilege);
52 void rctlblk_set_value(rctlblk_t *rblk, rctl_qty_t value);
55 void rctlblk_set_recipient_pid(id_tpid);
58 size_t rctlblk_size(void);
61
64 The resource control block routines allow the establishment or
65 retrieval of values from a resource control block used to transfer
66 information using the getrctl(2) and setrctl(2) functions. Each of the
67 routines accesses or sets the resource control block member correspond‐
68 ing to its name. Certain of these members are read-only and do not
69 possess set routines.
70 The firing time of a resource control block is 0 if the resource con‐
73 trol action-value has not been exceeded for its lifetime on the
74 process. Otherwise the firing time is the value of gethrtime(3C) at
75 the moment the action on the resource control value was taken.
76 The global actions and flags are the action and flags set by rct‐
79 ladm(1M). These values cannot be set with setrctl(2). Valid global
80 actions are listed in the table below. Global flags are generally a
81 published property of the control and are not modifiable.
82 RCTL_GLOBAL_DENY_ALWAYS The action taken when a control value is
84 exceeded on this control will always
85 include denial of the resource.
86 RCTL_GLOBAL_DENY_NEVER The action taken when a control value is
89 exceeded on this control will always
90 exclude denial of the resource; the
91 resource will always be granted, although
92 other actions can also be taken.
93 RCTL_GLOBAL_SIGNAL_NEVER No signal actions are permitted on this
96 control.
97 RCTL_GLOBAL_CPU_TIME The valid signals available as local
100 actions include the SIGXCPU signal.
101 RCTL_GLOBAL_FILE_SIZE The valid signals available as local
104 actions include the SIGXFSZ signal.
105 RCTL_GLOBAL_INFINITE This resource control supports the concept
108 of an unlimited value; generally true only
109 of accumulation-oriented resources, such as
110 CPU time.
111 RCTL_GLOBAL_LOWERABLE Non-privileged callers are able to lower
114 the value of privileged resource control
115 values on this control.
116 RCTL_GLOBAL_NOACTION No global action will be taken when a
119 resource control value is exceeded on this
120 control.
121 RCTL_GLOBAL_NOBASIC No values with the RCPRIV_BASIC privilege
124 are permitted on this control.
125 RCTL_GLOBAL_SYSLOG A standard message will be logged by the
128 syslog(3C) facility when any resource con‐
129 trol value on a sequence associated with
130 this control is exceeded.
131 RCTL_GLOBAL_SYSLOG_NEVER The resource control does not support the
134 syslog() global action. Exceeding a
135 resource control value on this control will
136 not result in a message logged by the sys‐
137 log() facility.
138 RCTL_GLOBAL_UNOBSERVABLE The resource control (generally on a task-
141 or project-related control) does not sup‐
142 port observational control values. An
143 RCPRIV_BASIC privileged control value
144 placed by a process on the task or process
145 will generate an action only if the value
146 is exceeded by that process.
147 RCTL_GLOBAL_BYTES This resource control represents a number
150 of bytes.
151 RCTL_GLOBAL_SECONDS This resource control represents a quantity
154 of time in seconds.
155 RCTL_GLOBAL_COUNT This resource control represents an integer
158 count.
159 The local action and flags are those on the current resource control
163 value represented by this resource control block. Valid actions and
164 flags are listed in the table below. In the case of RCTL_LOCAL_SIGNAL,
165 the second argument to rctlblk_set_local_action() contains the signal
166 to be sent. Similarly, the signal to be sent is copied into the integer
167 location specified by the second argument to rctl‐
168 blk_get_local_action(). A restricted set of signals is made available
169 for normal use by the resource control facility: SIGBART, SIGXRES,
170 SIGHUP, SIGSTOP, SIGTERM, and SIGKILL. Other signals are permitted due
171 to global properties of a specific control. Calls to setrctl() with
172 illegal signals will fail.
173 RCTL_LOCAL_DENY When this resource control value is encountered,
175 the request for the resource will be denied. Set
176 on all values if RCTL_GLOBAL_DENY_ALWAYS is set
177 for this control; cleared on all values if
178 RCTL_GLOBAL_DENY_NEVER is set for this control.
179 RCTL_LOCAL_MAXIMAL This resource control value represents a request
182 for the maximum amount of resource for this con‐
183 trol. If RCTL_GLOBAL_INFINITE is set for this
184 resource control, RCTL_LOCAL_MAXIMAL indicates
185 an unlimited resource control value, one that
186 will never be exceeded.
187 RCTL_LOCAL_NOACTION No local action will be taken when this resource
190 control value is exceeded.
191 RCTL_LOCAL_SIGNAL The specified signal, sent by rctl‐
194 blk_set_local_action(), will be sent to the
195 process that placed this resource control value
196 in the value sequence. This behavior is also
197 true for signal actions on project and task
198 resource controls. The specified signal is sent
199 only to the recipient process, not all processes
200 within the project or task.
201 The rctlblk_get_recipient_pid() function returns the value of the
205 process ID that placed the resource control value for basic rctls. For
206 privileged or system rctls, rctlblk_get_recipient_pid() returns -1.
207 The rctlblk_set_recipient_pid() function sets the recipient pid for a
210 basic rctl. When setrctl(2) is called with the flag RCTL_USE_RECIPI‐
211 ENT_PID, this pid is used. Otherwise, the PID of the calling process is
212 used. Only privileged users can set the recipient PID to one other than
213 the PID of the calling process. Process-scoped rctls must have a
214 recipient PID that matches the PID of the calling process.
215 The rctlblk_get_privilege() function returns the privilege of the
218 resource control block. Valid privileges are RCPRIV_BASIC, RCPRIV_PRIV‐
219 ILEGED, and RCPRIV_SYSTEM. System resource controls are read-only.
220 Privileged resource controls require the {PRIV_SYS_RESOURCE} privilege
221 to write, unless the RCTL_GLOBAL_LOWERABLE global flag is set, in which
222 case unprivileged applications can lower the value of a privileged con‐
223 trol.
224 The rctlblk_get_value() and rctlblk_set_value() functions return or
227 establish the enforced value associated with the resource control. In
228 cases where the process, task, or project associated with the control
229 possesses fewer capabilities than allowable by the current value, the
230 value returned by rctlblk_get_enforced_value() will differ from that
231 returned by rctlblk_get_value(). This capability difference arises with
232 processes using an address space model smaller than the maximum address
233 space model supported by the system.
234 The rctlblk_size() function returns the size of a resource control
237 block for use in memory allocation. The rctlblk_t * type is an opaque
238 pointer whose size is not connected with that of the resource control
239 block itself. Use of rctlblk_size() is illustrated in the example
240 below.
241
243 The various set routines have no return values. Incorrectly composed
244 resource control blocks will generate errors when used with setrctl(2)
245 or getrctl(2).
246
248 No error values are returned. Incorrectly constructed resource control
249 blocks will be rejected by the system calls.
250
252 Example 1 Display the contents of a fetched resource control block.
253 The following example displays the contents of a fetched resource con‐
256 trol block.
257 #include <rctl.h>
260 #include <stdio.h>
261 #include <stdlib.h>
262 rctlblk_t *rblk;
264 int rsignal;
265 int raction;
266 if ((rblk = malloc(rctlblk_size())) == NULL) {
268 (void) perror("rblk malloc");
269 exit(1);
270 }
271 if (getrctl("process.max-cpu-time", NULL, rblk, RCTL_FIRST) == -1) {
273 (void) perror("getrctl");
274 exit(1);
275 }
276 main()
278 {
279 raction = rctlblk_get_local_action(rblk, &rsignal),
280 (void) printf("Resource control for %s\n",
281 "process.max-cpu-time");
282 (void) printf("Process ID: %d\n",
283 rctlblk_get_recipient_pid(rblk));
284 (void) printf("Privilege: %x\n"
285 rctlblk_get_privilege(rblk));
286 (void) printf("Global flags: %x\n"
287 rctlblk_get_global_flags(rblk));
288 (void) printf("Global actions: %x\n"
289 rctlblk_get_global_action(rblk));
290 (void) printf("Local flags: %x\n"
291 rctlblk_get_local_flags(rblk));
292 (void) printf("Local action: %x (%d)\n"
293 raction, raction == RCTL_LOCAL_SIGNAL ? rsignal : 0);
294 (void) printf("Value: %llu\n",
295 rctlblk_get_value(rblk));
296 (void) printf("Enforced value: %llu\n",
297 rctlblk_get_enforced_value(rblk));
298 }
299
302 See attributes(5) for descriptions of the following attributes:
303 ┌─────────────────────────────┬─────────────────────────────┐
308 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
309 ├─────────────────────────────┼─────────────────────────────┤
310 │Interface Stability │Evolving │
311 ├─────────────────────────────┼─────────────────────────────┤
312 │MT-Level │MT-Safe │
313 └─────────────────────────────┴─────────────────────────────┘
314
316 rctladm(1M), getrctl(2), setrctl(2), gethrtime(3C), attributes(5)
317SunOS 5.11 15 May 2006 rctlblk_set_value(3C)