1rctlblk_set_value(3C)    Standard C Library Functions    rctlblk_set_value(3C)
2
3
4

NAME

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

SYNOPSIS

15       #include <rctl.h>
16
17       hrtime_t  rctlblk_get_firing_time(rctlblk_t *rblk);
18
19
20       int rctlblk_get_global_action(rctlblk_t *rblk);
21
22
23       int rctlblk_get_global_flags(rctlblk_t *rblk);
24
25
26       int rctlblk_get_local_action(rctlblk_t *rblk, int *signalp);
27
28
29       int rctlblk_get_local_flags(rctlblk_t *rblk);
30
31
32       rctl_priv_t  rctlblk_get_privilege(rctlblk_t *rblk);
33
34
35       id_t rctlblk_get_recipient_pid(rctlblk_t *rblk);
36
37
38       rctl_qty_t  rctlblk_get_value(rctlblk_t *rblk);
39
40
41       rctl_qty_t  rctlblk_get_enforced_value(rctlblk_t *rblk);
42
43
44       void rctlblk_set_local_action(rctlblk_t *rblk, rctl_action_t action,
45            int signal);
46
47
48       void rctlblk_set_local_flags(rctlblk_t *rblk, int flags);
49
50
51       void rctlblk_set_privilege(rctlblk_t *rblk, rctl_priv_t privilege);
52
53
54       void rctlblk_set_value(rctlblk_t *rblk, rctl_qty_t value);
55
56
57       void  rctlblk_set_recipient_pid(id_tpid);
58
59
60       size_t rctlblk_size(void);
61
62

DESCRIPTION

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
71
72       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
77
78       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
83       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
87
88       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
94
95       RCTL_GLOBAL_SIGNAL_NEVER    No signal actions  are  permitted  on  this
96                                   control.
97
98
99       RCTL_GLOBAL_CPU_TIME        The   valid   signals  available  as  local
100                                   actions include the SIGXCPU signal.
101
102
103       RCTL_GLOBAL_FILE_SIZE       The  valid  signals  available   as   local
104                                   actions include the SIGXFSZ signal.
105
106
107       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
112
113       RCTL_GLOBAL_LOWERABLE       Non-privileged callers are  able  to  lower
114                                   the  value  of  privileged resource control
115                                   values on this control.
116
117
118       RCTL_GLOBAL_NOACTION        No global  action  will  be  taken  when  a
119                                   resource  control value is exceeded on this
120                                   control.
121
122
123       RCTL_GLOBAL_NOBASIC         No values with the  RCPRIV_BASIC  privilege
124                                   are permitted on this control.
125
126
127       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
132
133       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
139
140       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
148
149       RCTL_GLOBAL_BYTES           This resource control represents  a  number
150                                   of bytes.
151
152
153       RCTL_GLOBAL_SECONDS         This resource control represents a quantity
154                                   of time in seconds.
155
156
157       RCTL_GLOBAL_COUNT           This resource control represents an integer
158                                   count.
159
160
161
162       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
174       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
180
181       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
188
189       RCTL_LOCAL_NOACTION    No local action will be taken when this resource
190                              control value is exceeded.
191
192
193       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
202
203
204       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
208
209       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
216
217       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
225
226       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
235
236       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

RETURN VALUES

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

ERRORS

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

EXAMPLES

252       Example 1 Display the contents of a fetched resource control block.
253
254
255       The  following example displays the contents of a fetched resource con‐
256       trol block.
257
258
259         #include <rctl.h>
260         #include <stdio.h>
261         #include <stdlib.h>
262
263         rctlblk_t *rblk;
264         int rsignal;
265         int raction;
266
267         if ((rblk = malloc(rctlblk_size())) == NULL) {
268                (void) perror("rblk malloc");
269                exit(1);
270         }
271
272         if (getrctl("process.max-cpu-time", NULL, rblk, RCTL_FIRST) == -1) {
273                (void) perror("getrctl");
274                exit(1);
275         }
276
277         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
300

ATTRIBUTES

302       See attributes(5) for descriptions of the following attributes:
303
304
305
306
307       ┌─────────────────────────────┬─────────────────────────────┐
308       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
309       ├─────────────────────────────┼─────────────────────────────┤
310       │Interface Stability          │Evolving                     │
311       ├─────────────────────────────┼─────────────────────────────┤
312       │MT-Level                     │MT-Safe                      │
313       └─────────────────────────────┴─────────────────────────────┘
314

SEE ALSO

316       rctladm(1M), getrctl(2), setrctl(2), gethrtime(3C), attributes(5)
317
318
319
320SunOS 5.11                        15 May 2006            rctlblk_set_value(3C)
Impressum