1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH RCTLBLK_SET_VALUE 3C "May 15, 2006"
   7 .SH NAME
   8 rctlblk_set_value, rctlblk_get_firing_time, rctlblk_get_global_action,
   9 rctlblk_get_global_flags, rctlblk_get_local_action, rctlblk_get_local_flags,
  10 rctlblk_get_privilege, rctlblk_get_recipient_pid, rctlblk_get_value,
  11 rctlblk_get_enforced_value, rctlblk_set_local_action, rctlblk_set_local_flags,
  12 rctlblk_set_privilege, rctlblk_set_recipient_pid, rctlblk_size \- manipulate
  13 resource control blocks
  14 .SH SYNOPSIS
  15 .LP
  16 .nf
  17 #include <rctl.h>
  18 
  19 \fBhrtime_t\fR  \fBrctlblk_get_firing_time\fR(\fBrctlblk_t *\fR\fIrblk\fR);
  20 .fi
  21 
  22 .LP
  23 .nf
  24 \fBint\fR \fBrctlblk_get_global_action\fR(\fBrctlblk_t *\fR\fIrblk\fR);
  25 .fi
  26 
  27 .LP
  28 .nf
  29 \fBint\fR \fBrctlblk_get_global_flags\fR(\fBrctlblk_t *\fR\fIrblk\fR);
  30 .fi
  31 
  32 .LP
  33 .nf
  34 \fBint\fR \fBrctlblk_get_local_action\fR(\fBrctlblk_t *\fR\fIrblk\fR, \fBint *\fR\fIsignalp\fR);
  35 .fi
  36 
  37 .LP
  38 .nf
  39 \fBint\fR \fBrctlblk_get_local_flags\fR(\fBrctlblk_t *\fR\fIrblk\fR);
  40 .fi
  41 
  42 .LP
  43 .nf
  44 \fBrctl_priv_t\fR  \fBrctlblk_get_privilege\fR(\fBrctlblk_t *\fR\fIrblk\fR);
  45 .fi
  46 
  47 .LP
  48 .nf
  49 \fBid_t\fR \fBrctlblk_get_recipient_pid\fR(\fBrctlblk_t *\fR\fIrblk\fR);
  50 .fi
  51 
  52 .LP
  53 .nf
  54 \fBrctl_qty_t\fR  \fBrctlblk_get_value\fR(\fBrctlblk_t *\fR\fIrblk\fR);
  55 .fi
  56 
  57 .LP
  58 .nf
  59 \fBrctl_qty_t\fR  \fBrctlblk_get_enforced_value\fR(\fBrctlblk_t *\fR\fIrblk\fR);
  60 .fi
  61 
  62 .LP
  63 .nf
  64 \fBvoid\fR \fBrctlblk_set_local_action\fR(\fBrctlblk_t *\fR\fIrblk\fR, \fBrctl_action_t\fR \fIaction\fR,
  65      \fBint\fR \fIsignal\fR);
  66 .fi
  67 
  68 .LP
  69 .nf
  70 \fBvoid\fR \fBrctlblk_set_local_flags\fR(\fBrctlblk_t *\fR\fIrblk\fR, \fBint\fR \fIflags\fR);
  71 .fi
  72 
  73 .LP
  74 .nf
  75 \fBvoid\fR \fBrctlblk_set_privilege\fR(\fBrctlblk_t *\fR\fIrblk\fR, \fBrctl_priv_t\fR \fIprivilege\fR);
  76 .fi
  77 
  78 .LP
  79 .nf
  80 \fBvoid\fR \fBrctlblk_set_value\fR(\fBrctlblk_t *\fR\fIrblk\fR, \fBrctl_qty_t\fR \fIvalue\fR);
  81 .fi
  82 
  83 .LP
  84 .nf
  85 \fBvoid\fR  \fBrctlblk_set_recipient_pid\fR(\fBid_t\fR\fIpid\fR);
  86 .fi
  87 
  88 .LP
  89 .nf
  90 \fBsize_t\fR \fBrctlblk_size\fR(\fBvoid\fR);
  91 .fi
  92 
  93 .SH DESCRIPTION
  94 .sp
  95 .LP
  96 The resource control block routines allow the establishment or retrieval of
  97 values from a resource control block used to transfer information using the
  98 \fBgetrctl\fR(2) and \fBsetrctl\fR(2) functions. Each of the routines accesses
  99 or sets the resource control block member corresponding to its name.  Certain
 100 of these members are read-only and do not possess set routines.
 101 .sp
 102 .LP
 103 The firing time of a resource control block is 0 if the resource control
 104 action-value has not been exceeded for its lifetime on the process.  Otherwise
 105 the firing time is the value of \fBgethrtime\fR(3C) at the moment the action on
 106 the resource control value was taken.
 107 .sp
 108 .LP
 109 The global actions and flags are the action and flags set by \fBrctladm\fR(1M).
 110 These values cannot be set with \fBsetrctl\fR(2).  Valid global actions are
 111 listed in the table below. Global flags are generally a published property of
 112 the control and are not modifiable.
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fBRCTL_GLOBAL_DENY_ALWAYS\fR\fR
 117 .ad
 118 .RS 28n
 119 The action taken when a control value is exceeded on this control will always
 120 include denial of the resource.
 121 .RE
 122 
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fBRCTL_GLOBAL_DENY_NEVER\fR\fR
 127 .ad
 128 .RS 28n
 129 The action taken when a control value is exceeded on this control will always
 130 exclude denial of the resource; the resource will always be granted, although
 131 other actions can also be taken.
 132 .RE
 133 
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBRCTL_GLOBAL_SIGNAL_NEVER\fR\fR
 138 .ad
 139 .RS 28n
 140 No signal actions are permitted on this control.
 141 .RE
 142 
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fBRCTL_GLOBAL_CPU_TIME\fR\fR
 147 .ad
 148 .RS 28n
 149 The valid signals available as local actions include the \fBSIGXCPU\fR signal.
 150 .RE
 151 
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fBRCTL_GLOBAL_FILE_SIZE\fR\fR
 156 .ad
 157 .RS 28n
 158 The valid signals available as local actions include the \fBSIGXFSZ\fR signal.
 159 .RE
 160 
 161 .sp
 162 .ne 2
 163 .na
 164 \fB\fBRCTL_GLOBAL_INFINITE\fR\fR
 165 .ad
 166 .RS 28n
 167 This resource control supports the concept of an unlimited value; generally
 168 true only of accumulation-oriented resources, such as CPU time.
 169 .RE
 170 
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fBRCTL_GLOBAL_LOWERABLE\fR\fR
 175 .ad
 176 .RS 28n
 177 Non-privileged callers are able to lower the value of privileged resource
 178 control values on this control.
 179 .RE
 180 
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fBRCTL_GLOBAL_NOACTION\fR\fR
 185 .ad
 186 .RS 28n
 187 No global action will be taken when a resource control value is exceeded on
 188 this control.
 189 .RE
 190 
 191 .sp
 192 .ne 2
 193 .na
 194 \fB\fBRCTL_GLOBAL_NOBASIC\fR\fR
 195 .ad
 196 .RS 28n
 197 No values with the \fBRCPRIV_BASIC\fR privilege are permitted on this control.
 198 .RE
 199 
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fBRCTL_GLOBAL_SYSLOG\fR\fR
 204 .ad
 205 .RS 28n
 206 A standard message will be logged by the \fBsyslog\fR(3C) facility when any
 207 resource control value on a sequence associated with this control is exceeded.
 208 .RE
 209 
 210 .sp
 211 .ne 2
 212 .na
 213 \fB\fBRCTL_GLOBAL_SYSLOG_NEVER\fR\fR
 214 .ad
 215 .RS 28n
 216 The resource control does not support the \fBsyslog()\fR global action.
 217 Exceeding a resource control value on this control will not result in a message
 218 logged by the \fBsyslog()\fR facility.
 219 .RE
 220 
 221 .sp
 222 .ne 2
 223 .na
 224 \fB\fBRCTL_GLOBAL_UNOBSERVABLE\fR\fR
 225 .ad
 226 .RS 28n
 227 The resource control (generally on a task- or project-related control) does not
 228 support observational control values. An \fBRCPRIV_BASIC\fR privileged control
 229 value placed by a process on the task or process will generate an action only
 230 if the value is exceeded by that process.
 231 .RE
 232 
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fBRCTL_GLOBAL_BYTES\fR\fR
 237 .ad
 238 .RS 28n
 239 This resource control represents a number of bytes.
 240 .RE
 241 
 242 .sp
 243 .ne 2
 244 .na
 245 \fB\fBRCTL_GLOBAL_SECONDS\fR\fR
 246 .ad
 247 .RS 28n
 248 This resource control represents a quantity of time in seconds.
 249 .RE
 250 
 251 .sp
 252 .ne 2
 253 .na
 254 \fB\fBRCTL_GLOBAL_COUNT\fR\fR
 255 .ad
 256 .RS 28n
 257 This resource control represents an integer count.
 258 .RE
 259 
 260 .sp
 261 .LP
 262 The local action and flags are those on the current resource control value
 263 represented by this resource control block. Valid actions and flags are listed
 264 in the table below. In the case of \fBRCTL_LOCAL_SIGNAL\fR, the second argument
 265 to \fBrctlblk_set_local_action()\fR contains the signal to be sent. Similarly,
 266 the signal to be sent is copied into the integer location specified by the
 267 second argument to \fBrctlblk_get_local_action()\fR. A restricted set of
 268 signals is made available for normal use by the resource control facility:
 269 \fBSIGBART\fR, \fBSIGXRES\fR, \fBSIGHUP\fR, \fBSIGSTOP\fR, \fBSIGTERM\fR, and
 270 \fBSIGKILL\fR. Other signals are permitted due to global properties of a
 271 specific control. Calls to \fBsetrctl()\fR with illegal signals will fail.
 272 .sp
 273 .ne 2
 274 .na
 275 \fB\fBRCTL_LOCAL_DENY\fR\fR
 276 .ad
 277 .RS 23n
 278 When this resource control value is encountered, the request for the resource
 279 will be denied. Set on all values if \fBRCTL_GLOBAL_DENY_ALWAYS\fR is set for
 280 this control; cleared on all values if \fBRCTL_GLOBAL_DENY_NEVER\fR is set for
 281 this control.
 282 .RE
 283 
 284 .sp
 285 .ne 2
 286 .na
 287 \fB\fBRCTL_LOCAL_MAXIMAL\fR\fR
 288 .ad
 289 .RS 23n
 290 This resource control value represents a request for the maximum amount of
 291 resource for this control. If \fBRCTL_GLOBAL_INFINITE\fR is set for this
 292 resource control, \fBRCTL_LOCAL_MAXIMAL\fR indicates an unlimited resource
 293 control value, one that will never be exceeded.
 294 .RE
 295 
 296 .sp
 297 .ne 2
 298 .na
 299 \fB\fBRCTL_LOCAL_NOACTION\fR\fR
 300 .ad
 301 .RS 23n
 302 No local action will be taken when this resource control value is exceeded.
 303 .RE
 304 
 305 .sp
 306 .ne 2
 307 .na
 308 \fB\fBRCTL_LOCAL_SIGNAL\fR\fR
 309 .ad
 310 .RS 23n
 311 The specified signal, sent by \fBrctlblk_set_local_action()\fR, will be sent to
 312 the process that placed this resource control value in the value sequence. This
 313 behavior is also true for signal actions on project and task resource controls.
 314 The specified signal is sent only to the recipient process, not all processes
 315 within the project or task.
 316 .RE
 317 
 318 .sp
 319 .LP
 320 The \fBrctlblk_get_recipient_pid()\fR function returns the value of the process
 321 ID that placed the resource control value for basic rctls. For privileged or
 322 system rctls, \fBrctlblk_get_recipient_pid()\fR returns -1.
 323 .sp
 324 .LP
 325 The \fBrctlblk_set_recipient_pid()\fR function sets the recipient \fIpid\fR for
 326 a basic rctl. When \fBsetrctl\fR(2) is called with the flag
 327 \fBRCTL_USE_RECIPIENT_PID\fR, this \fIpid\fR is used. Otherwise, the PID of the
 328 calling process is used. Only privileged users can set the recipient PID to one
 329 other than the PID of the calling process.  Process-scoped rctls must have a
 330 recipient PID that matches the PID of the calling process.
 331 .sp
 332 .LP
 333 The \fBrctlblk_get_privilege()\fR function returns the privilege of the
 334 resource control block. Valid privileges are \fBRCPRIV_BASIC\fR,
 335 \fBRCPRIV_PRIVILEGED\fR, and \fBRCPRIV_SYSTEM\fR. System resource controls are
 336 read-only. Privileged resource controls require the {\fBPRIV_SYS_RESOURCE\fR}
 337 privilege to write, unless the \fBRCTL_GLOBAL_LOWERABLE\fR global flag is set,
 338 in which case unprivileged applications can lower the value of a privileged
 339 control.
 340 .sp
 341 .LP
 342 The \fBrctlblk_get_value()\fR and \fBrctlblk_set_value()\fR functions return or
 343 establish the enforced value associated with the resource control. In cases
 344 where the process, task, or project associated with the control possesses fewer
 345 capabilities than allowable by the current value, the value returned by
 346 \fBrctlblk_get_enforced_value()\fR will differ from that returned by
 347 \fBrctlblk_get_value()\fR. This capability difference arises with processes
 348 using an address space model smaller than the maximum address space model
 349 supported by the system.
 350 .sp
 351 .LP
 352 The \fBrctlblk_size()\fR function returns the size of a resource control block
 353 for use in memory allocation. The \fBrctlblk_t *\fR type is an opaque pointer
 354 whose size is not connected with that of the resource control block itself. Use
 355 of \fBrctlblk_size()\fR is illustrated in the example below.
 356 .SH RETURN VALUES
 357 .sp
 358 .LP
 359 The various set routines have no return values. Incorrectly composed resource
 360 control blocks will generate errors when used with \fBsetrctl\fR(2) or
 361 \fBgetrctl\fR(2).
 362 .SH ERRORS
 363 .sp
 364 .LP
 365 No error values are returned. Incorrectly constructed resource control blocks
 366 will be rejected by the system calls.
 367 .SH EXAMPLES
 368 .LP
 369 \fBExample 1 \fRDisplay the contents of a fetched resource control block.
 370 .sp
 371 .LP
 372 The following example displays the contents of a fetched resource control
 373 block.
 374 
 375 .sp
 376 .in +2
 377 .nf
 378 #include <rctl.h>
 379 #include <stdio.h>
 380 #include <stdlib.h>
 381 
 382 rctlblk_t *rblk;
 383 int rsignal;
 384 int raction;
 385 
 386 if ((rblk = malloc(rctlblk_size())) == NULL) {
 387        (void) perror("rblk malloc");
 388        exit(1);
 389 }
 390 
 391 if (getrctl("process.max-cpu-time", NULL, rblk, RCTL_FIRST) == -1) {
 392        (void) perror("getrctl");
 393        exit(1);
 394 }
 395 
 396 main()
 397 {
 398     raction = rctlblk_get_local_action(rblk, &rsignal),
 399     (void) printf("Resource control for %s\en",
 400         "process.max-cpu-time");
 401     (void) printf("Process ID:     %d\en",
 402         rctlblk_get_recipient_pid(rblk));
 403     (void) printf("Privilege:      %x\en"
 404         rctlblk_get_privilege(rblk));
 405     (void) printf("Global flags:   %x\en"
 406         rctlblk_get_global_flags(rblk));
 407     (void) printf("Global actions: %x\en"
 408         rctlblk_get_global_action(rblk));
 409     (void) printf("Local flags:    %x\en"
 410         rctlblk_get_local_flags(rblk));
 411     (void) printf("Local action:   %x (%d)\en"
 412         raction, raction == RCTL_LOCAL_SIGNAL ? rsignal : 0);
 413     (void) printf("Value:          %llu\en",
 414         rctlblk_get_value(rblk));
 415     (void) printf("\tEnforced value: %llu\en",
 416         rctlblk_get_enforced_value(rblk));
 417 }
 418 .fi
 419 .in -2
 420 
 421 .SH ATTRIBUTES
 422 .sp
 423 .LP
 424 See \fBattributes\fR(5) for descriptions of the following attributes:
 425 .sp
 426 
 427 .sp
 428 .TS
 429 box;
 430 c | c
 431 l | l .
 432 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 433 _
 434 Interface Stability     Evolving
 435 _
 436 MT-Level        MT-Safe
 437 .TE
 438 
 439 .SH SEE ALSO
 440 .sp
 441 .LP
 442 \fBrctladm\fR(1M), \fBgetrctl\fR(2), \fBsetrctl\fR(2), \fBgethrtime\fR(3C),
 443 \fBattributes\fR(5)