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