1setrctl(2) System Calls setrctl(2)
2
6 setrctl, getrctl - set or get resource control values
7
9 #include <rctl.h>
10 int setrctl(const char *controlname, rctlblk_t *old_blk,
12 rctlblk_t *new_blk, uint_t flags);
13 int getrctl(const char *controlname, rctlblk_t *old_blk,
16 rctlblk_t *new_blk, uint_t flags);
17
20 The setrctl() and getrctl() functions provide interfaces for the modi‐
21 fication and retrieval of resource control (rctl) values on active
22 entities on the system, such as processes, tasks, or projects. All
23 resource controls are unsigned 64-bit integers; however, a collection
24 of flags are defined that modify which rctl value is to be set or
25 retrieved.
26 Resource controls are restricted to three levels: basic controls that
29 can be modified by the owner of the calling process, privileged con‐
30 trols that can be modified only by privileged callers, and system con‐
31 trols that are fixed for the duration of the operating system instance.
32 Setting or retrieving each of these controls is performed by setting
33 the privilege field of the resource control block to RCTL_BASIC,
34 RCTL_PRIVILEGED, or RCTL_SYSTEM with rctlblk_set_privilege() (see rctl‐
35 blk_set_value(3C)).
36 For limits on collective entities such as the task or project, the
39 process ID of the calling process is associated with the resource con‐
40 trol value. This ID is available by using rctlblk_get_recipient_pid()
41 (see rctlblk_set_value(3C)). These values are visible only to that
42 process and privileged processes within the collective.
43 The getrctl() function provides a mechanism for iterating through all
46 of the established values on a resource control. The iteration is
47 primed by calling getrctl() with old_blk set to NULL, a valid resource
48 control block pointer in new_blk, and specifying RCTL_FIRST in the
49 flags argument. Once a resource control block has been obtained,
50 repeated calls to getrctl() with RCTL_NEXT in the flags argument and
51 the obtained control in the old_blk argument will return the next
52 resource control block in the sequence. The iteration reports the end
53 of the sequence by failing and setting errno to ENOENT.
54 The getrctl() function allows the calling process to get the current
57 usage of a controlled resource using RCTL_USAGE as the flags value. The
58 current value of the resource usage is placed in the value field of the
59 resource control block specified by new_blk. This value is obtained
60 with rctlblk_set_value(3C). All other members of the returned block are
61 undefined and might be invalid.
62 The setrctl() function allows the creation, modification, or deletion
65 of action-value pairs on a given resource control. When passed
66 RCTL_INSERT as the flags value, setrctl() expects new_blk to contain a
67 new action-value pair for insertion into the sequence. For RCTL_DELETE,
68 the block indicated by new_blk is deleted from the sequence. For
69 RCTL_REPLACE, the block matching old_blk is deleted and replaced by the
70 block indicated by new_blk. When (flags & RCTL_USE_RECIPIENT_PID) is
71 non-zero, setrctl() uses the process ID set by rctlblk_set_value(3C)
72 when selecting the rctl value to insert, delete, or replace basic
73 rctls. Otherwise, the process ID of the calling process is used.
74 The kernel maintains a history of which resource control values have
77 triggered for a particular entity, retrievable from a resource control
78 block with the rctlblk_set_value(3C) function. The insertion or dele‐
79 tion of a resource control value at or below the currently enforced
80 value might cause the currently enforced value to be reset. In the
81 case of insertion, the newly inserted value becomes the actively
82 enforced value. All higher values that have previously triggered will
83 have their firing times zeroed. In the case of deletion of the cur‐
84 rently enforced value, the next higher value becomes the actively
85 enforced value.
86 The various resource control block properties are described on the
89 rctlblk_set_value(3C) manual page.
90 Resource controls are inherited from the predecessor process or task.
93 One of the exec(2) functions can modify the resource controls of a
94 process by resetting their histories, as noted above for insertion or
95 deletion operations.
96
98 Upon successful completion, the setrctl() and getrctl() functions
99 return 0. Otherwise they return −1 and set errno to indicate the error.
100
102 The setrctl() and getrctl() functions will fail if:
103 EFAULT The controlname, old_blk, or new_blk argument points to an
105 illegal address.
106 EINVAL No resource control with the given name is known to the
109 system, or the resource control block contains properties
110 that are not valid for the resource control specified.
111 RCTL_USE_RECIPIENT_PID was used to set a process scope rctl
113 and the process ID set by rctlblk_set_value(3C) does not
114 match the process ID of calling process.
115 ENOENT No value beyond the given resource control block exists.
118 RCTL_USE_RECIPIENT_PID was used and the process ID set by
120 rctlblk_set_value(3C) does not exist within the current
121 task, project, or zone, depending on the resource control
122 name.
123 ESRCH No value matching the given resource control block was
126 found for any of RCTL_NEXT, RCTL_DELETE, or RCTL_REPLACE.
127 ENOTSUPP The resource control requested by RCTL_USAGE does not sup‐
130 port the usage operation.
131 The setrctl() function will fail if:
135 EACCES The rctl value specified cannot be changed by the current
137 process, including the case where the recipient process ID
138 does not match the calling process and the calling process is
139 unprivileged.
140 EPERM An attempt to set a system limit was attempted.
143
146 Example 1 Retrieve a rctl value.
147 Obtain the lowest enforced rctl value on the rctl limiting the number
150 of LWPs in a task.
151 #include <rctl.h>
154 #include <stdio.h>
155 #include <stdlib.h>
156 #include <string.h>
157 #include <errno.h>
158 ...
160 rctlblk_t *rblk;
162 if ((rblk = (rctlblk_t *)malloc(rctlblk_size())) == NULL) {
164 (void) fprintf(stderr, "malloc failed: %s\n",
165 strerror(errno));
166 exit(1);
167 }
168 if (getrctl("task.max-lwps", NULL, rblk, RCTL_FIRST) == -1)
170 (void) fprintf(stderr, "failed to get rctl: %s\n",
171 strerror(errno));
172 else
173 (void) printf("task.max-lwps = %llu\n",
174 rctlblk_get_value(rblk));
175
178 Resource control blocks are matched on the value and privilege fields.
179 Resource control operations act on the first matching resource control
180 block. Duplicate resource control blocks are not permitted. Multiple
181 blocks of equal value and privilege need to be entirely deleted and
182 reinserted, rather than replaced, to have the correct outcome. Resource
183 control blocks are sorted such that all blocks with the same value that
184 lack the RCTL_LOCAL_DENY flag precede those having that flag set.
185 Only one RCPRIV_BASIC resource control value is permitted per process
188 per control. Insertion of an RCPRIV_BASIC value will cause any exist‐
189 ing RCPRIV_BASIC value owned by that process on the control to be
190 deleted.
191 The resource control facility provides the backend implementation for
194 both setrctl()/getrctl() and setrlimit()/getrlimit(). The facility
195 behaves consistently when either of these interfaces is used exclu‐
196 sively; when using both interfaces, the caller must be aware of the
197 ordering issues above, as well as the limit equivalencies described in
198 the following paragraph.
199 The hard and soft process limits made available with setrlimit() and
202 getrlimit() are mapped to the resource controls implementation. (New
203 process resource controls will not be made available with the rlimit
204 interface.) Because of the RCTL_INSERT and RCTL_DELETE operations, it
205 is possible that the set of values defined on a resource control has
206 more or fewer than the two values defined for an rlimit. In this case,
207 the soft limit is the lowest priority resource control value with the
208 RCTL_LOCAL_DENY flag set, and the hard limit is the resource control
209 value with the lowest priority equal to or exceeding RCPRIV_PRIVILEGED
210 with the RCTL_LOCAL_DENY flag set. If no identifiable soft limit
211 exists on the resource control and setrlimit() is called, a new
212 resource control value is created. If a resource control does not have
213 the global RCTL_GLOBAL_LOWERABLE property set, its hard limit will not
214 allow lowering by unprivileged callers.
215
217 See attributes(5) for descriptions of the following attributes:
218 ┌─────────────────────────────┬─────────────────────────────┐
223 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
224 ├─────────────────────────────┼─────────────────────────────┤
225 │MT-Level │Async-Signal-Safe │
226 └─────────────────────────────┴─────────────────────────────┘
227
229 rctladm(1M), getrlimit(2), errno(3C), rctlblk_set_value(3C),
230 attributes(5), resource_controls(5)
231SunOS 5.11 31 Jan 2007 setrctl(2)