1 '\" te
   2 .\" Copyright (c) 2009 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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. 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
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PRCTL 1 "Aug 25, 2009"
   7 .SH NAME
   8 prctl \- get or set the resource controls of running processes, tasks, and
   9 projects
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBprctl\fR [\fB-P\fR] [\fB-t\fR [basic | privileged | system]]
  14      [\fB-n\fR \fIname\fR [\fB-srx\fR] [\fB-v\fR \fIvalue\fR] [\fB-e\fR | \fB-d\fR \fIaction\fR] [\fB-p\fR \fIpid\fR]]
  15      [\fB-i\fR \fIidtype\fR] \fIid\fR...
  16 .fi
  17 
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBprctl\fR utility allows the examination and modification of the resource
  22 controls associated with an active process, task, or project on the system. It
  23 allows access to the  basic and privileged limits and the  current  usage  on
  24 the     specified entity.
  25 .sp
  26 .LP
  27 See \fBresource_controls\fR(5) for a description of the resource controls
  28 supported in the current release of the Solaris operating system.
  29 .SH OPTIONS
  30 .sp
  31 .LP
  32 If none of the \fB-s\fR, \fB-r\fR, \fB-x\fR, \fB-v\fR, \fB-d\fR, or \fB-e\fR
  33 options are specified, the invocation is considered a get operation. Otherwise,
  34 it is considered a modify operation.
  35 .sp
  36 .LP
  37 The following options are supported:
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fB-d\fR | \fB-e\fR \fIaction\fR\fR
  42 .ad
  43 .sp .6
  44 .RS 4n
  45 Disables (\fB-d\fR) or enables (\fB-e\fR) the specified \fIaction\fR on the
  46 resource control value specified by \fB-v\fR, \fB-t\fR, and \fB-p\fR. If any of
  47 the \fB-v\fR, \fB-t\fR, or \fB-p\fR options are unspecified, they match any
  48 value, privilege, or recipient pid. For example, specifying only \fB-v\fR
  49 modifies the first resource control with matching value, matching any privilege
  50 and recipient pid. If no matching resource control value is found, a new value
  51 is added as if \fB-s\fR were specified.
  52 .sp
  53 \fBActions:\fR
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fBall\fR\fR
  58 .ad
  59 .RS 17n
  60 This action is only available with \fB-d\fR. It disables all actions. This
  61 fails on resource control values that have the \fBdeny\fR global flag.
  62 .RE
  63 
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fBdeny\fR\fR
  68 .ad
  69 .RS 17n
  70 Indicates that the resource control attempts to deny granting the resource to
  71 the process, task, project, or zone on a request for resources in excess of the
  72 resource control value. \fBdeny\fR actions can not be enabled if the resource
  73 control has the \fBno-deny\fR global flag. \fBdeny\fR actions can not be
  74 disabled if the resource control has the \fBdeny\fR global flag.
  75 .RE
  76 
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fBsignal\fR\fR
  81 .ad
  82 .RS 17n
  83 This action is only available with \fB-d\fR. It deactivates the \fBsignal\fR
  84 action.
  85 .RE
  86 
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBsignal\fR=\fIsignum\fR\fR
  91 .ad
  92 .RS 17n
  93 In the \fBsignal=\fR\fIsignum\fR action, \fIsignum\fR is a signal number (or
  94 string representation of a signal). Setting a \fBsignal\fR action on a resource
  95 control with the \fBno-local-action\fR global flag fails. A limited set of
  96 signals can be sent. See \fBNOTES\fR for additional details.
  97 .RE
  98 
  99 .RE
 100 
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fB-i\fR \fIidtype\fR\fR
 105 .ad
 106 .sp .6
 107 .RS 4n
 108 Specifies the type of the id operands. Valid \fIidtype\fRs are \fBprocess\fR,
 109 \fBtask\fR, \fBproject\fR, or \fBzone\fR. Also allowed are \fBpid\fR,
 110 \fBtaskid\fR, \fBprojid\fR, and \fBzoneid\fR. The default id type, if the
 111 \fB-i\fR option is omitted, is \fBprocess\fR.
 112 .sp
 113 For a modify operation, the entity to which id operands are members is the
 114 target entity. For instance, setting a project resource control on an \fB-i\fR
 115 \fBprocess\fR sets the resource control on the project to which each given
 116 process argument is a member.
 117 .sp
 118 For a get operation, the resource controls are listed for all entities to which
 119 the id operands are members. For example, \fB-i\fR \fBtask\fR \fItaskid\fR
 120 lists the task, project, and zone resource controls for the task, and for the
 121 project and zone to which that task is a member.
 122 .RE
 123 
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fB-n\fR \fIname\fR\fR
 128 .ad
 129 .sp .6
 130 .RS 4n
 131 Specifies the name of the resource control to get or set. If the \fIname\fR is
 132 unspecified, all resource controls are retrieved.
 133 .RE
 134 
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fB-p\fR \fIpid\fR\fR
 139 .ad
 140 .sp .6
 141 .RS 4n
 142 When manipulating (using \fB-s\fR, \fB-r\fR, \fB-x\fR, \fB-d\fR, or \fB-e\fR) a
 143 basic task project, or zone resource control values, a recipient \fIpid\fR can
 144 be specified using \fB-p\fR. When setting a new basic resource control or
 145 controls on a task, project, or zone, the \fB-p\fR option is required if the
 146 \fB-i\fR \fIidtype\fR option argument is not \fBprocess\fR.
 147 .RE
 148 
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fB-P\fR\fR
 153 .ad
 154 .sp .6
 155 .RS 4n
 156 Display resource control values in space delimited format.
 157 .RE
 158 
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fB-r\fR\fR
 163 .ad
 164 .sp .6
 165 .RS 4n
 166 Replaces the first resource control value (matching with the \fB-t\fR
 167 \fBprivilege\fR) with the new value specified through the \fB-v\fR option.
 168 .RE
 169 
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fB-s\fR\fR
 174 .ad
 175 .sp .6
 176 .RS 4n
 177 Set a new resource control value.
 178 .sp
 179 This option requires the \fB-v\fR option.
 180 .sp
 181 If you do not specify the \fB-t\fR option, basic privilege is used. If you want
 182 to set a basic task, process, or zone rctl, \fB-p\fR is required. If \fB-e\fR
 183 or \fB-d\fR are also specified, the action on the new \fBrctl\fR is set as
 184 well.
 185 .sp
 186 For compatibility with prior releases, this option is implied if \fB-v\fR is
 187 specified, without any of \fB-e\fR, \fB-d\fR, \fB-r\fR, or \fB-x\fR.
 188 .sp
 189 See \fBresource_controls\fR(5) for a description of unit modifiers and scaling
 190 factors you can use to express large values when setting a resource control
 191 value.
 192 .RE
 193 
 194 .sp
 195 .ne 2
 196 .na
 197 \fB\fB-t\fR [ \fBbasic\fR | \fBprivileged\fR | \fBsystem\fR ]\fR
 198 .ad
 199 .sp .6
 200 .RS 4n
 201 Specifies which resource control type to set. Unless the "lowerable" flag is
 202 set for a resource control, only invocations by users (or setuid programs) who
 203 have privileges equivalent to those of root can modify privileged resource
 204 controls. See \fBrctlblk_set_value\fR(3C) for a description of the
 205 \fBRCTL_GLOBAL_LOWERABLE\fR flag. If the type is not specified, \fBbasic\fR is
 206 assumed. For a get operation, the values of all resource control types,
 207 including \fBsystem\fR, are displayed if no type is specified.
 208 .RE
 209 
 210 .sp
 211 .ne 2
 212 .na
 213 \fB\fB-v\fR \fIvalue\fR\fR
 214 .ad
 215 .sp .6
 216 .RS 4n
 217 Specifies the value for the resource control for a set operation. If no
 218 \fIvalue\fR is specified, then the modification (deletion, action enabling or
 219 disabling) is carried out on the lowest-valued resource control with the given
 220 type.
 221 .sp
 222 See \fBresource_controls\fR(5) for a description of unit modifiers and scaling
 223 factors you can use to express large values when setting a resource control
 224 value.
 225 .RE
 226 
 227 .sp
 228 .ne 2
 229 .na
 230 \fB\fB-x\fR\fR
 231 .ad
 232 .sp .6
 233 .RS 4n
 234 Deletes the specified resource control value. If the delete option is not
 235 provided, the default operation of \fBprctl\fR is to modify a resource control
 236 value of matching value and privilege, or insert a new value with the given
 237 privilege. The matching criteria are discussed more fully in \fBsetrctl\fR(2).
 238 .RE
 239 
 240 .sp
 241 .LP
 242 If none of the \fB-d\fR, \fB-e\fR, \fB-v\fR, or \fB-x\fR options is specified,
 243 the invocation is considered a get operation.
 244 .SH OPERANDS
 245 .sp
 246 .LP
 247 The following operand is supported:
 248 .sp
 249 .ne 2
 250 .na
 251 \fB\fIid\fR\fR
 252 .ad
 253 .RS 6n
 254 The \fBID\fR of the entity (\fBprocess\fR, \fBtask\fR, \fBproject\fR, or
 255 \fBzone\fR) to interrogate. If the invoking user's credentials are unprivileged
 256 and the entity being interrogated possesses different credentials, the
 257 operation fails. If no \fIid\fR is specified, an error message is returned.
 258 .RE
 259 
 260 .SH EXAMPLES
 261 .LP
 262 \fBExample 1 \fRDisplaying Current Resource Control Settings
 263 .sp
 264 .LP
 265 The following example displays current resource control settings for a task to
 266 which the current shell belongs:
 267 
 268 .sp
 269 .in +2
 270 .nf
 271  example$ ps -o taskid -p $$
 272 TASKID
 273 8
 274 example$ prctl -i task 8
 275 136150: /bin/ksh
 276 NAME    PRIVILEGE       VALUE    FLAG   ACTION             RECIPIENT
 277 task.max-cpu-time
 278         usage            8s
 279         system          18.4Es    inf   none                -
 280 task.max-lwps
 281         usage              39
 282         system          2.15G     max   deny                -
 283 project.max-contracts
 284         privileged      10.0K       -   deny                -
 285 project.max-locked-memory
 286         usage               0B
 287         privileged       508MB      -   deny                -
 288 project.max-port-ids
 289         privileged      8.19K       -   deny                -
 290 project.max-shm-memory
 291         privileged       508MB      -   deny                -
 292 project.max-shm-ids
 293         privileged        128       -   deny                -
 294 project.max-msg-ids
 295         privileged        128       -   deny                -
 296 project.max-sem-ids
 297         privileged        128       -   deny                -
 298 project.max-crypto-memory
 299          usage            0B
 300 privileged       508MB      -   deny                -
 301 project.max-tasks
 302         usage               2
 303         system          2.15G     max   deny                -
 304 project.max-lwps
 305          usage             39
 306         system          2.15G     max   deny                -
 307 project.cpu-shares
 308         usage               1
 309         privileged          1       -   none                -
 310 zone.max-shm-memory
 311         system          16.0EB    max   deny                -
 312 zone.max-shm-ids
 313         system          16.8M     max   deny                -
 314 zone.max-sem-ids
 315         system          16.8M     max   deny                -
 316 zone.max-msg-ids
 317         system          16.8M     max   deny                -
 318 zone.max-lwps
 319         system          2.15G     max   deny                -
 320 zone.cpu-shares
 321         privileged          1       -   none                -
 322 zone.max-locked-memory
 323         usage               0B
 324         privileged       508MB      -   deny                -
 325 .fi
 326 .in -2
 327 .sp
 328 
 329 .LP
 330 \fBExample 2 \fRDisplaying, Replacing, and Verifying the Value of a Specific
 331 Control
 332 .sp
 333 .LP
 334 The following examples displays, replaces, and verifies the value of a specific
 335 control on an existing project:
 336 
 337 .sp
 338 .in +2
 339 .nf
 340 example# prctl -n project.cpu-shares -i project group.staff
 341 project: 10: group.staff
 342 NAME    PRIVILEGE       VALUE    FLAG   ACTION               RECIPIENT
 343 project.cpu-shares
 344         usage               1
 345         privileged          1       -   none                         -
 346         system          65.5K     max   none                         -
 347 
 348 example# prctl -n project.cpu-shares -v 10 -r -i project group.staff
 349 example# prctl -n project.cpu-shares -i project group.staff
 350 project: 10: group.staff
 351 NAME    PRIVILEGE       VALUE    FLAG   ACTION               RECIPIENT
 352 project.cpu-shares
 353         usage              10
 354         privileged         10       -   none                         -
 355         system          65.5K     max   none                         -
 356 .fi
 357 .in -2
 358 .sp
 359 
 360 .LP
 361 \fBExample 3 \fRAdjusting Resources
 362 .sp
 363 .LP
 364 The following example uses the \fBproject.max-locked-memory\fR resource.
 365 
 366 .sp
 367 .LP
 368 First, use \fBid\fR \fB-p\fR to find out which project the current shell is a
 369 member of:
 370 
 371 .sp
 372 .in +2
 373 .nf
 374 /home/garfield> id -p
 375           uid=77880(garfield) gid=10(staff) projid=10(group.staff)
 376 .fi
 377 .in -2
 378 .sp
 379 
 380 .sp
 381 .LP
 382 Using the target project, identify the resource limit value before the change:
 383 
 384 .sp
 385 .in +2
 386 .nf
 387 /home/garfield> prctl -n project.max-locked-memory -i project \e
 388                       group.staff
 389         project 10: group.staff
 390         project.max-locked-memory
 391             privileged         256MB       -    deny                  -
 392             system            16.0EB     max    deny                  -
 393 
 394 current limit is 256 Megabytes.
 395 .fi
 396 .in -2
 397 .sp
 398 
 399 .sp
 400 .LP
 401 Next, adjust the \fBproject.max-locked-memory\fR limit to 300 Megabytes for the
 402 target project:
 403 
 404 .sp
 405 .in +2
 406 .nf
 407 # prctl -n project.max-locked-memory -v 300M -r -i project group.staff
 408 .fi
 409 .in -2
 410 .sp
 411 
 412 .sp
 413 .LP
 414 The resource limit value after the change shows a new value of 300 Megabytes:
 415 
 416 .sp
 417 .in +2
 418 .nf
 419 # prctl -n project.max-locked-memory -i project group.staff
 420         project 10:group.staff
 421         project.max-locked-memory
 422             usage              200MG
 423      privileged         300MB       -    deny                           -
 424            system            16.0EB     max    deny                           -
 425 .fi
 426 .in -2
 427 .sp
 428 
 429 .LP
 430 \fBExample 4 \fRModifying CPU Caps for a Project
 431 .sp
 432 .LP
 433 The \fBprctl\fR command can use the \fBproject.cpu-cap\fR resource control (see
 434 \fBresource_controls\fR(5)) to set and modify CPU caps for a project. (The same
 435 resource control can be used in the \fB/etc/project\fR file. See
 436 \fBproject\fR(4)) The following command modifies the CPU cap to limit
 437 \fBuser.smith\fR  to three CPUs:
 438 
 439 .sp
 440 .in +2
 441 .nf
 442 # \fBprctl -r -t privileged -n project.cpu-cap -v 300 -i project user.smith\fR
 443 .fi
 444 .in -2
 445 .sp
 446 
 447 .sp
 448 .LP
 449 The \fBprctl\fR \fB-r\fR option, used above, is used to dynamically change a
 450 CPU cap for a project or zone. For example, the following command will change
 451 the cap set in the preceding command to 80 percent:
 452 
 453 .sp
 454 .in +2
 455 .nf
 456 # \fBprctl -r -t privileged -n project.cpu-cap -v 80 -i project user.smith\fR
 457 .fi
 458 .in -2
 459 .sp
 460 
 461 .sp
 462 .LP
 463 To remove a CPU cap, enter:
 464 
 465 .sp
 466 .in +2
 467 .nf
 468 # \fBprctl -x -n project.cpu-cap $$\fR
 469 .fi
 470 .in -2
 471 .sp
 472 
 473 .LP
 474 \fBExample 5 \fRModifying CPU Caps for a Zone
 475 .sp
 476 .LP
 477 The \fBprctl\fR command can use the \fBzone.cpu-cap\fR resource control (see
 478 \fBresource_controls\fR(5)) to set and modify CPU caps for a zone. (The same
 479 resource control can be manipulated using the \fBzonecfg\fR(1M) command.) The
 480 following command modifies the CPU cap to limit the global zone to 80 percent
 481 of a CPU:
 482 
 483 .sp
 484 .in +2
 485 .nf
 486 # \fBprctl -t privileged -n zone.cpu-cap -v 80 -i zone global\fR
 487 .fi
 488 .in -2
 489 .sp
 490 
 491 .sp
 492 .LP
 493 The cap can be lowered to 50% using:
 494 
 495 .sp
 496 .in +2
 497 .nf
 498 # \fBprctl -r -t privileged -n zone.cpu-cap -v 50 -i zone global\fR
 499 .fi
 500 .in -2
 501 .sp
 502 
 503 .SH EXIT STATUS
 504 .sp
 505 .LP
 506 The following exit values are returned:
 507 .sp
 508 .ne 2
 509 .na
 510 \fB\fB0\fR\fR
 511 .ad
 512 .RS 5n
 513 Success.
 514 .RE
 515 
 516 .sp
 517 .ne 2
 518 .na
 519 \fB\fB1\fR\fR
 520 .ad
 521 .RS 5n
 522 Fatal error encountered.
 523 .RE
 524 
 525 .sp
 526 .ne 2
 527 .na
 528 \fB\fB2\fR\fR
 529 .ad
 530 .RS 5n
 531 Invalid command line options were specified.
 532 .RE
 533 
 534 .SH FILES
 535 .sp
 536 .ne 2
 537 .na
 538 \fB\fB/proc/pid/*\fR\fR
 539 .ad
 540 .RS 15n
 541 Process information and control files
 542 .RE
 543 
 544 .SH ATTRIBUTES
 545 .sp
 546 .LP
 547 See \fBattributes\fR(5) for descriptions of the following attributes:
 548 .sp
 549 
 550 .sp
 551 .TS
 552 box;
 553 c | c
 554 l | l .
 555 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 556 _
 557 Interface Stability     See below.
 558 .TE
 559 
 560 .sp
 561 .LP
 562 The command-line syntax is Committed. The human-readable output is Uncommitted.
 563 The parseable output is Committed.
 564 .SH SEE ALSO
 565 .sp
 566 .LP
 567 \fBrctladm\fR(1M), \fBzonecfg\fR(1M), \fBsetrctl\fR(2),
 568 \fBrctlblk_get_local_action\fR(3C), \fBproject\fR(4), \fBattributes\fR(5),
 569 \fBresource_controls\fR(5)
 570 .SH NOTES
 571 .sp
 572 .LP
 573 The valid signals that can be set on a resource control block allowing local
 574 actions are \fBSIGABRT\fR, \fBSIGXRES\fR, \fBSIGHUP\fR, \fBSIGSTOP\fR,
 575 \fBSIGTERM\fR, and \fBSIGKILL\fR. Additionally, CPU time related controls can
 576 issue the \fBSIGXCPU\fR signal, and file size related controls can send the
 577 \fBSIGXFSZ\fR signal.