Print this page
7264 Example code is rctlblk_set_value(3c) manpage does not compile.
Reviewed by: Robert Mustacchi <rm@joyent.com>
Reviewed by: Toomas Soome <tsoome@me.com>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/rctlblk_set_value.3c.man.txt
+++ new/usr/src/man/man3c/rctlblk_set_value.3c.man.txt
1 1 RCTLBLK_SET_VALUE(3C) Standard C Library Functions RCTLBLK_SET_VALUE(3C)
2 2
3 3
4 4
5 5 NAME
6 6 rctlblk_set_value, rctlblk_get_firing_time, rctlblk_get_global_action,
7 7 rctlblk_get_global_flags, rctlblk_get_local_action,
8 8 rctlblk_get_local_flags, rctlblk_get_privilege,
9 9 rctlblk_get_recipient_pid, rctlblk_get_value,
10 10 rctlblk_get_enforced_value, rctlblk_set_local_action,
11 11 rctlblk_set_local_flags, rctlblk_set_privilege,
12 12 rctlblk_set_recipient_pid, rctlblk_size - manipulate resource control
13 13 blocks
14 14
15 15 SYNOPSIS
16 16 #include <rctl.h>
17 17
18 18 hrtime_t rctlblk_get_firing_time(rctlblk_t *rblk);
19 19
20 20
21 21 int rctlblk_get_global_action(rctlblk_t *rblk);
22 22
23 23
24 24 int rctlblk_get_global_flags(rctlblk_t *rblk);
25 25
26 26
27 27 int rctlblk_get_local_action(rctlblk_t *rblk, int *signalp);
28 28
29 29
30 30 int rctlblk_get_local_flags(rctlblk_t *rblk);
31 31
32 32
33 33 rctl_priv_t rctlblk_get_privilege(rctlblk_t *rblk);
34 34
35 35
36 36 id_t rctlblk_get_recipient_pid(rctlblk_t *rblk);
37 37
38 38
39 39 rctl_qty_t rctlblk_get_value(rctlblk_t *rblk);
40 40
41 41
42 42 rctl_qty_t rctlblk_get_enforced_value(rctlblk_t *rblk);
43 43
44 44
45 45 void rctlblk_set_local_action(rctlblk_t *rblk, rctl_action_t action,
46 46 int signal);
47 47
48 48
49 49 void rctlblk_set_local_flags(rctlblk_t *rblk, int flags);
50 50
51 51
52 52 void rctlblk_set_privilege(rctlblk_t *rblk, rctl_priv_t privilege);
53 53
54 54
55 55 void rctlblk_set_value(rctlblk_t *rblk, rctl_qty_t value);
56 56
57 57
58 58 void rctlblk_set_recipient_pid(id_tpid);
59 59
60 60
61 61 size_t rctlblk_size(void);
62 62
63 63
64 64 DESCRIPTION
65 65 The resource control block routines allow the establishment or
66 66 retrieval of values from a resource control block used to transfer
67 67 information using the getrctl(2) and setrctl(2) functions. Each of the
68 68 routines accesses or sets the resource control block member
69 69 corresponding to its name. Certain of these members are read-only and
70 70 do not possess set routines.
71 71
72 72
73 73 The firing time of a resource control block is 0 if the resource
74 74 control action-value has not been exceeded for its lifetime on the
75 75 process. Otherwise the firing time is the value of gethrtime(3C) at
76 76 the moment the action on the resource control value was taken.
77 77
78 78
79 79 The global actions and flags are the action and flags set by
80 80 rctladm(1M). These values cannot be set with setrctl(2). Valid global
81 81 actions are listed in the table below. Global flags are generally a
82 82 published property of the control and are not modifiable.
83 83
84 84 RCTL_GLOBAL_DENY_ALWAYS
85 85 The action taken when a control value is
86 86 exceeded on this control will always
87 87 include denial of the resource.
88 88
89 89
90 90 RCTL_GLOBAL_DENY_NEVER
91 91 The action taken when a control value is
92 92 exceeded on this control will always
93 93 exclude denial of the resource; the
94 94 resource will always be granted, although
95 95 other actions can also be taken.
96 96
97 97
98 98 RCTL_GLOBAL_SIGNAL_NEVER
99 99 No signal actions are permitted on this
100 100 control.
101 101
102 102
103 103 RCTL_GLOBAL_CPU_TIME
104 104 The valid signals available as local
105 105 actions include the SIGXCPU signal.
106 106
107 107
108 108 RCTL_GLOBAL_FILE_SIZE
109 109 The valid signals available as local
110 110 actions include the SIGXFSZ signal.
111 111
112 112
113 113 RCTL_GLOBAL_INFINITE
114 114 This resource control supports the concept
115 115 of an unlimited value; generally true only
116 116 of accumulation-oriented resources, such as
117 117 CPU time.
118 118
119 119
120 120 RCTL_GLOBAL_LOWERABLE
121 121 Non-privileged callers are able to lower
122 122 the value of privileged resource control
123 123 values on this control.
124 124
125 125
126 126 RCTL_GLOBAL_NOACTION
127 127 No global action will be taken when a
128 128 resource control value is exceeded on this
129 129 control.
130 130
131 131
132 132 RCTL_GLOBAL_NOBASIC
133 133 No values with the RCPRIV_BASIC privilege
134 134 are permitted on this control.
135 135
136 136
137 137 RCTL_GLOBAL_SYSLOG
138 138 A standard message will be logged by the
139 139 syslog(3C) facility when any resource
140 140 control value on a sequence associated with
141 141 this control is exceeded.
142 142
143 143
144 144 RCTL_GLOBAL_SYSLOG_NEVER
145 145 The resource control does not support the
146 146 syslog() global action. Exceeding a
147 147 resource control value on this control will
148 148 not result in a message logged by the
149 149 syslog() facility.
150 150
151 151
152 152 RCTL_GLOBAL_UNOBSERVABLE
153 153 The resource control (generally on a task-
154 154 or project-related control) does not
155 155 support observational control values. An
156 156 RCPRIV_BASIC privileged control value
157 157 placed by a process on the task or process
158 158 will generate an action only if the value
159 159 is exceeded by that process.
160 160
161 161
162 162 RCTL_GLOBAL_BYTES
163 163 This resource control represents a number
164 164 of bytes.
165 165
166 166
167 167 RCTL_GLOBAL_SECONDS
168 168 This resource control represents a quantity
169 169 of time in seconds.
170 170
171 171
172 172 RCTL_GLOBAL_COUNT
173 173 This resource control represents an integer
174 174 count.
175 175
176 176
177 177
178 178 The local action and flags are those on the current resource control
179 179 value represented by this resource control block. Valid actions and
180 180 flags are listed in the table below. In the case of RCTL_LOCAL_SIGNAL,
181 181 the second argument to rctlblk_set_local_action() contains the signal
182 182 to be sent. Similarly, the signal to be sent is copied into the integer
183 183 location specified by the second argument to
184 184 rctlblk_get_local_action(). A restricted set of signals is made
185 185 available for normal use by the resource control facility: SIGBART,
186 186 SIGXRES, SIGHUP, SIGSTOP, SIGTERM, and SIGKILL. Other signals are
187 187 permitted due to global properties of a specific control. Calls to
188 188 setrctl() with illegal signals will fail.
189 189
190 190 RCTL_LOCAL_DENY
191 191 When this resource control value is encountered,
192 192 the request for the resource will be denied. Set
193 193 on all values if RCTL_GLOBAL_DENY_ALWAYS is set
194 194 for this control; cleared on all values if
195 195 RCTL_GLOBAL_DENY_NEVER is set for this control.
196 196
197 197
198 198 RCTL_LOCAL_MAXIMAL
199 199 This resource control value represents a request
200 200 for the maximum amount of resource for this
201 201 control. If RCTL_GLOBAL_INFINITE is set for this
202 202 resource control, RCTL_LOCAL_MAXIMAL indicates
203 203 an unlimited resource control value, one that
204 204 will never be exceeded.
205 205
206 206
207 207 RCTL_LOCAL_NOACTION
208 208 No local action will be taken when this resource
209 209 control value is exceeded.
210 210
211 211
212 212 RCTL_LOCAL_SIGNAL
213 213 The specified signal, sent by
214 214 rctlblk_set_local_action(), will be sent to the
215 215 process that placed this resource control value
216 216 in the value sequence. This behavior is also
217 217 true for signal actions on project and task
218 218 resource controls. The specified signal is sent
219 219 only to the recipient process, not all processes
220 220 within the project or task.
221 221
222 222
223 223
224 224 The rctlblk_get_recipient_pid() function returns the value of the
225 225 process ID that placed the resource control value for basic rctls. For
226 226 privileged or system rctls, rctlblk_get_recipient_pid() returns -1.
227 227
228 228
229 229 The rctlblk_set_recipient_pid() function sets the recipient pid for a
230 230 basic rctl. When setrctl(2) is called with the flag
231 231 RCTL_USE_RECIPIENT_PID, this pid is used. Otherwise, the PID of the
232 232 calling process is used. Only privileged users can set the recipient
233 233 PID to one other than the PID of the calling process. Process-scoped
234 234 rctls must have a recipient PID that matches the PID of the calling
235 235 process.
236 236
237 237
238 238 The rctlblk_get_privilege() function returns the privilege of the
239 239 resource control block. Valid privileges are RCPRIV_BASIC,
240 240 RCPRIV_PRIVILEGED, and RCPRIV_SYSTEM. System resource controls are
241 241 read-only. Privileged resource controls require the {PRIV_SYS_RESOURCE}
242 242 privilege to write, unless the RCTL_GLOBAL_LOWERABLE global flag is
243 243 set, in which case unprivileged applications can lower the value of a
244 244 privileged control.
245 245
246 246
247 247 The rctlblk_get_value() and rctlblk_set_value() functions return or
248 248 establish the enforced value associated with the resource control. In
249 249 cases where the process, task, or project associated with the control
250 250 possesses fewer capabilities than allowable by the current value, the
251 251 value returned by rctlblk_get_enforced_value() will differ from that
252 252 returned by rctlblk_get_value(). This capability difference arises with
253 253 processes using an address space model smaller than the maximum address
254 254 space model supported by the system.
255 255
256 256
257 257 The rctlblk_size() function returns the size of a resource control
258 258 block for use in memory allocation. The rctlblk_t * type is an opaque
259 259 pointer whose size is not connected with that of the resource control
260 260 block itself. Use of rctlblk_size() is illustrated in the example
261 261 below.
262 262
263 263 RETURN VALUES
264 264 The various set routines have no return values. Incorrectly composed
265 265 resource control blocks will generate errors when used with setrctl(2)
266 266 or getrctl(2).
267 267
268 268 ERRORS
269 269 No error values are returned. Incorrectly constructed resource control
270 270 blocks will be rejected by the system calls.
271 271
272 272 EXAMPLES
273 273 Example 1 Display the contents of a fetched resource control block.
|
↓ open down ↓ |
273 lines elided |
↑ open up ↑ |
274 274
275 275
276 276 The following example displays the contents of a fetched resource
277 277 control block.
278 278
279 279
280 280 #include <rctl.h>
281 281 #include <stdio.h>
282 282 #include <stdlib.h>
283 283
284 - rctlblk_t *rblk;
285 - int rsignal;
286 - int raction;
284 + int
285 + main()
286 + {
287 + rctlblk_t *rblk;
288 + int rsignal, raction;
287 289
288 - if ((rblk = malloc(rctlblk_size())) == NULL) {
289 - (void) perror("rblk malloc");
290 - exit(1);
291 - }
290 + if ((rblk = malloc(rctlblk_size())) == NULL) {
291 + (void) perror("rblk malloc");
292 + exit(1);
293 + }
292 294
293 - if (getrctl("process.max-cpu-time", NULL, rblk, RCTL_FIRST) == -1) {
294 - (void) perror("getrctl");
295 - exit(1);
296 - }
295 + if (getrctl("process.max-cpu-time", NULL, rblk, RCTL_FIRST) == -1) {
296 + (void) perror("getrctl");
297 + exit(1);
298 + }
297 299
298 - main()
299 - {
300 - raction = rctlblk_get_local_action(rblk, &rsignal),
301 - (void) printf("Resource control for %s\n",
302 - "process.max-cpu-time");
303 - (void) printf("Process ID: %d\n",
304 - rctlblk_get_recipient_pid(rblk));
305 - (void) printf("Privilege: %x\n"
306 - rctlblk_get_privilege(rblk));
307 - (void) printf("Global flags: %x\n"
308 - rctlblk_get_global_flags(rblk));
309 - (void) printf("Global actions: %x\n"
310 - rctlblk_get_global_action(rblk));
311 - (void) printf("Local flags: %x\n"
312 - rctlblk_get_local_flags(rblk));
313 - (void) printf("Local action: %x (%d)\n"
314 - raction, raction == RCTL_LOCAL_SIGNAL ? rsignal : 0);
315 - (void) printf("Value: %llu\n",
316 - rctlblk_get_value(rblk));
317 - (void) printf("Enforced value: %llu\n",
318 - rctlblk_get_enforced_value(rblk));
300 + raction = rctlblk_get_local_action(rblk, &rsignal),
301 + (void) printf("Resource control for %s\n",
302 + "process.max-cpu-time");
303 + (void) printf("Process ID: %d\n",
304 + (int)rctlblk_get_recipient_pid(rblk));
305 + (void) printf("Privilege: %x\n",
306 + rctlblk_get_privilege(rblk));
307 + (void) printf("Global flags: %x\n",
308 + rctlblk_get_global_flags(rblk));
309 + (void) printf("Global actions: %x\n",
310 + rctlblk_get_global_action(rblk));
311 + (void) printf("Local flags: %x\n",
312 + rctlblk_get_local_flags(rblk));
313 + (void) printf("Local action: %x (%d)\n",
314 + raction, raction == RCTL_LOCAL_SIGNAL ? rsignal : 0);
315 + (void) printf("Value: %llu\n",
316 + rctlblk_get_value(rblk));
317 + (void) printf("Enforced value: %llu\n",
318 + rctlblk_get_enforced_value(rblk));
319 +
320 + return (0);
319 321 }
320 322
321 323
322 324 ATTRIBUTES
323 325 See attributes(5) for descriptions of the following attributes:
324 326
325 327
326 328
327 329
328 330 +--------------------+-----------------+
329 331 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
330 332 +--------------------+-----------------+
|
↓ open down ↓ |
2 lines elided |
↑ open up ↑ |
331 333 |Interface Stability | Evolving |
332 334 +--------------------+-----------------+
333 335 |MT-Level | MT-Safe |
334 336 +--------------------+-----------------+
335 337
336 338 SEE ALSO
337 339 rctladm(1M), getrctl(2), setrctl(2), gethrtime(3C), attributes(5)
338 340
339 341
340 342
341 - May 15, 2006 RCTLBLK_SET_VALUE(3C)
343 + August 2, 2016 RCTLBLK_SET_VALUE(3C)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX