9842 man page typos and spelling

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH PRIOCNTL 1 "Apr 1, 2008"
   8 .SH NAME
   9 priocntl \- display or set scheduling parameters of specified process(es)
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBpriocntl\fR \fB-l\fR
  14 .fi
  15 
  16 .LP
  17 .nf
  18 \fBpriocntl\fR \fB-d\fR [\fB-i\fR \fIidtype\fR] [\fIidlist\fR]
  19 .fi
  20 
  21 .LP
  22 .nf
  23 \fBpriocntl\fR \fB-s\fR [\fB-c\fR \fIclass\fR] [\fIclass-specific\fR \fIoptions\fR]
  24      [\fB-i\fR \fIidtype\fR] [\fIidlist\fR]
  25 .fi
  26 
  27 .LP
  28 .nf
  29 \fBpriocntl\fR \fB-e\fR [\fB-c\fR \fIclass\fR] [\fIclass-specific\fR \fIoptions\fR] \fIcommand\fR
  30      [\fIargument(s)\fR]
  31 .fi
  32 
  33 .SH DESCRIPTION
  34 .sp
  35 .LP
  36 The \fBpriocntl\fR command displays or sets scheduling parameters of the
  37 specified process(es). It can also be used to display the current configuration
  38 information for the system's process scheduler or execute a command with
  39 specified scheduling parameters.
  40 .sp
  41 .LP
  42 Processes fall into distinct classes with a separate scheduling policy applied
  43 to each class. The process classes currently supported are the real-time class,
  44 time-sharing class, interactive class, fair-share class, and the fixed priority
  45 class. The characteristics of these classes and the class-specific options they
  46 accept are described below in the USAGE section under the headings \fBReal-Time
  47 Class\fR, \fBTime-Sharing Class\fR, \fBInter-Active Class\fR, \fBFair-Share
  48 Class\fR, and \fBFixed-Priority Class\fR. With appropriate permissions, the
  49 \fBpriocntl\fR command can change the class and other scheduling parameters
  50 associated with a running process.
  51 .sp
  52 .LP
  53 In the default configuration, a runnable real-time process runs before any
  54 other process. Therefore, inappropriate use of real-time processes can have a
  55 dramatic negative impact on system performance.
  56 .sp
  57 .LP
  58 If an \fIidlist\fR is present, it must appear last on the command line and the
  59 elements of the list must be separated by white space. If no \fIidlist\fR is
  60 present, an \fIidtype\fR argument of \fBpid\fR, \fBppid\fR, \fBpgid\fR,
  61 \fBsid\fR, \fBtaskid\fR, \fBclass\fR, \fBuid\fR, \fBgid\fR, \fBprojid\fR, or
  62 \fBzoneid\fR specifies the process \fBID\fR, parent process \fBID\fR, process
  63 group \fBID\fR, session \fBID\fR, task \fBID\fR, class, user \fBID\fR, group
  64 \fBID\fR, project \fBID\fR, or zone \fBID\fR, respectively, of the
  65 \fBpriocntl\fR command itself.
  66 .sp
  67 .LP
  68 The command
  69 .sp
  70 .in +2
  71 .nf
  72 \fBpriocntl -d [-i \fIidtype\fR] [\fIidlist\fR]\fR
  73 .fi
  74 .in -2
  75 .sp
  76 
  77 .sp
  78 .LP
  79 displays the class and class-specific scheduling parameters of the process(es)
  80 specified by \fIidtype\fR and \fIidlist\fR.
  81 .sp
  82 .LP
  83 The command
  84 .sp
  85 .in +2
  86 .nf
  87 \fBpriocntl -s [-c \fIclass\fR] [\fIclass-specific options\fR] \e
  88      [-i \fIidtype\fR] [\fIidlist\fR]\fR
  89 .fi
  90 .in -2
  91 .sp
  92 
  93 .sp
  94 .LP
  95 sets the class and class-specific parameters of the specified processes to the
  96 values given on the command line. The \fB-c\fR \fIclass\fR option specifies the
  97 class to be set. (The valid \fIclass\fR arguments are \fBRT\fR for real-time,
  98 \fBTS\fR for time-sharing, \fBIA\fR for inter-active, \fBFSS\fR for fair-share,
  99 or \fBFX\fR for fixed-priority.)
 100 .sp
 101 .LP
 102 The class-specific parameters to be set are specified by the class-specific
 103 options as explained under the appropriate heading below. If the \fB-c\fR
 104 \fIclass\fR option is omitted, \fIidtype\fR and \fIidlist\fR must specify a set
 105 of processes which are all in the same class, otherwise an error results. If no
 106 class-specific options are specified, the process's class-specific parameters
 107 are set to the default values for the class specified by \fB-c\fR \fIclass\fR
 108 (or to the default parameter values for the process's current class if the
 109 \fB-c\fR \fIclass\fR option is also omitted).
 110 .sp
 111 .LP
 112 In order to change the scheduling parameters of a process using \fBpriocntl\fR
 113 the real or effective user \fBID\fR (respectively, groupID) of the user
 114 invoking \fBpriocntl\fR must match the real or effective user \fBID\fR
 115 (respectively, groupID) of the receiving process or the effective user \fBID\fR
 116 of the user must be super-user. These are the minimum permission requirements
 117 enforced for all classes. An individual class can impose additional permissions
 118 requirements when setting processes to that class or when setting
 119 class-specific scheduling parameters.
 120 .sp
 121 .LP
 122 When \fIidtype\fR and \fIidlist\fR specify a set of processes, \fBpriocntl\fR
 123 acts on the processes in the set in an implementation-specific order. If
 124 \fBpriocntl\fR encounters an error for one or more of the target processes, it
 125 can or cannot continue through the set of processes, depending on the nature of
 126 the error.
 127 .sp
 128 .LP
 129 If the error is related to permissions, \fBpriocntl\fR prints an error message
 130 and then continues through the process set, resetting the parameters for all
 131 target processes for which the user has appropriate permissions. If
 132 \fBpriocntl\fR encounters an error other than permissions, it does not continue
 133 through the process set but prints an error message and exits immediately.
 134 .sp
 135 .LP
 136 A special \fBsys\fR scheduling class exists for the purpose of scheduling the
 137 execution of certain special system processes (such as the swapper process). It
 138 is not possible to change the class of any process to \fBsys\fR. In addition,
 139 any processes in the \fBsys\fR class that are included in the set of processes
 140 specified by \fIidtype\fR and \fIidlist\fR are disregarded by \fBpriocntl\fR.
 141 For example, if \fIidtype\fR were \fBuid\fR, an \fIidlist\fR consisting of a
 142 zero would specify all processes with a \fBUID\fR of \fB0\fR, except processes
 143 in the \fBsys\fR class and (if changing the parameters using the \fB-s\fR
 144 option) the \fBinit\fR process.
 145 .sp
 146 .LP
 147 The \fBinit\fR process (process \fBID\fR \fB1\fR) is a special case. In order
 148 for the \fBpriocntl\fR command to change the class or other scheduling
 149 parameters of the \fBinit\fR process, \fIidtype\fR must be \fBpid\fR and
 150 \fIidlist\fR must be consist of only a \fB1\fR. The \fBinit\fR process can be
 151 assigned to any class configured on the system, but the time-sharing class is
 152 almost always the appropriate choice. Other choices can be highly undesirable;
 153 see the \fISystem Administration Guide: Basic Administration\fR for more
 154 information.
 155 .sp
 156 .LP
 157 The command
 158 .sp
 159 .in +2
 160 .nf
 161 \fBpriocntl -e [-c \fIclass\fR\fR\fB]\fR\fB [\fIclass-specific options\fR] \fIcommand\fR \e
 162      [\fIargument...\fR]\fR
 163 .fi
 164 .in -2
 165 .sp
 166 
 167 .sp
 168 .LP
 169 executes the specified command with the class and scheduling parameters
 170 specified on the command line (\fIarguments\fR are the arguments to the
 171 command). If the \fB-c\fR \fIclass\fR option is omitted the command is run in
 172 the user's current class.
 173 .SH OPTIONS
 174 .sp
 175 .LP
 176 The following options are supported:
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fB-c\fR \fIclass\fR\fR
 181 .ad
 182 .RS 13n
 183 Specifies the \fIclass\fR to be set. (The valid \fIclass\fR arguments are
 184 \fBRT\fR for real-time, \fBTS\fR for time-sharing, \fBIA\fR for inter-active,
 185 \fBFSS\fR for fair-share, or \fBFX\fR for fixed-priority.) If the specified
 186 class is not already configured, it is automatically configured.
 187 .RE
 188 
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fB-d\fR\fR
 193 .ad
 194 .RS 13n
 195 Displays the scheduling parameters associated with a set of processes.
 196 .RE
 197 
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fB-e\fR\fR
 202 .ad
 203 .RS 13n
 204 Executes a specified command with the class and scheduling parameters
 205 associated with a set of processes.
 206 .RE
 207 
 208 .sp
 209 .ne 2
 210 .na
 211 \fB\fB-i\fR \fIidtype\fR\fR
 212 .ad
 213 .RS 13n
 214 This option, together with the \fIidlist\fR arguments (if any), specifies one
 215 or more processes to which the \fBpriocntl\fR command is to apply. The
 216 interpretation of \fIidlist\fR depends on the value of \fIidtype\fR. If the
 217 \fB-i\fR \fIidtype\fR option is omitted when using the \fB-d\fR or \fB-s\fR
 218 options the default \fIidtype\fR of \fBpid\fR is assumed.
 219 .sp
 220 The valid \fIidtype\fR arguments and corresponding interpretations of
 221 \fIidlist\fR are as follows:
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fB-i\fR \fBall\fR\fR
 226 .ad
 227 .RS 13n
 228 The \fBpriocntl\fR command applies to all existing processes. No \fIidlist\fR
 229 should be specified (if one is specified, it is ignored). The permission
 230 restrictions described below still apply.
 231 .RE
 232 
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fB-i\fR \fBctid\fR\fR
 237 .ad
 238 .RS 13n
 239 idlist is a list of process contract IDs. The \fBpriocntl\fR command applies to
 240 all processes with a process contract ID equal to an ID from the list.
 241 .RE
 242 
 243 .sp
 244 .ne 2
 245 .na
 246 \fB\fB-i\fR \fBclass\fR\fR
 247 .ad
 248 .RS 13n
 249 \fIidlist\fR consists of a single class name (\fBRT\fR for real-time, \fBTS\fR
 250 for time-sharing, \fBIA\fR for inter-active, \fBFSS\fR for fair-share, or
 251 \fBFX\fR for fixed-priority). The \fBpriocntl\fR command applies to all
 252 processes in the specified class.
 253 .RE
 254 
 255 .sp
 256 .ne 2
 257 .na
 258 \fB\fB-i\fR \fBgid\fR\fR
 259 .ad
 260 .RS 13n
 261 \fIidlist\fR is a list of group \fBID\fRs. The \fBpriocntl\fR command applies
 262 to all processes with an effective group \fBID\fR equal to an \fBID\fR from the
 263 list.
 264 .RE
 265 
 266 .sp
 267 .ne 2
 268 .na
 269 \fB\fB-i\fR \fBpgid\fR\fR
 270 .ad
 271 .RS 13n
 272 \fIidlist\fR is a list of process group \fBID\fRs. The \fBpriocntl\fR command
 273 applies to all processes in the specified process groups.
 274 .RE
 275 
 276 .sp
 277 .ne 2
 278 .na
 279 \fB\fB-i\fR \fBpid\fR\fR
 280 .ad
 281 .RS 13n
 282 \fIidlist\fR is a list of process \fBID\fRs. The \fBpriocntl\fR command applies
 283 to the specified processes.
 284 .RE
 285 
 286 .sp
 287 .ne 2
 288 .na
 289 \fB\fB-i\fR \fBppid\fR\fR
 290 .ad
 291 .RS 13n
 292 \fIidlist\fR is a list of parent process \fBID\fRs. The \fBpriocntl\fR command
 293 applies to all processes whose parent process \fBID\fR is in the list.
 294 .RE
 295 
 296 .sp
 297 .ne 2
 298 .na
 299 \fB\fB-i\fR \fBprojid\fR\fR
 300 .ad
 301 .RS 13n
 302 \fIidlist\fR is a list of project \fBID\fRs. The \fBpriocntl\fR command applies
 303 to all processes with an effective project \fBID\fR equal to an \fBID\fR from
 304 the list.
 305 .RE
 306 
 307 .sp
 308 .ne 2
 309 .na
 310 \fB\fB-i\fR \fBsid\fR\fR
 311 .ad
 312 .RS 13n
 313 \fIidlist\fR is a list of session \fBID\fRs. The \fBpriocntl\fR command applies
 314 to all processes in the specified sessions.
 315 .RE
 316 
 317 .sp
 318 .ne 2
 319 .na
 320 \fB\fB-i\fR \fBtaskid\fR\fR
 321 .ad
 322 .RS 13n
 323 \fIidlist\fR is a list of task \fBID\fRs. The \fBpriocntl\fR command applies to
 324 all processes in the specified tasks.
 325 .RE
 326 
 327 .sp
 328 .ne 2
 329 .na
 330 \fB\fB-i\fR \fBuid\fR\fR
 331 .ad
 332 .RS 13n
 333 \fIidlist\fR is a list of user \fBID\fRs. The \fBpriocntl\fR command applies to
 334 all processes with an effective user \fBID\fR equal to an \fBID\fR from the
 335 list.
 336 .RE
 337 
 338 .sp
 339 .ne 2
 340 .na
 341 \fB\fB-i\fR \fBzoneid\fR\fR
 342 .ad
 343 .RS 13n
 344 \fIidlist\fR is a list of zone \fBID\fRs. The \fBpriocntl\fR command applies to
 345 all processes with an effective zone \fBID\fR equal to an \fBID\fR from the
 346 list.
 347 .RE
 348 
 349 .RE
 350 
 351 .sp
 352 .ne 2
 353 .na
 354 \fB\fB-l\fR\fR
 355 .ad
 356 .RS 13n
 357 Displays a list of the classes currently configured in the system along with
 358 class-specific information about each class. The format of the class-specific
 359 information displayed is described under USAGE.
 360 .RE
 361 
 362 .sp
 363 .ne 2
 364 .na
 365 \fB\fB-s\fR\fR
 366 .ad
 367 .RS 13n
 368 Sets the scheduling parameters associated with a set of processes.
 369 .RE
 370 
 371 .sp
 372 .LP
 373 The valid class-specific options for setting real-time parameters are:
 374 .sp
 375 .ne 2
 376 .na
 377 \fB\fB-p\fR \fIrtpri\fR\fR
 378 .ad
 379 .RS 21n
 380 Sets the real-time priority of the specified process(es) to \fIrtpri\fR.
 381 .RE
 382 
 383 .sp
 384 .ne 2
 385 .na
 386 \fB\fB-t\fR \fItqntm\fR [\fB-r\fR \fIres\fR]\fR
 387 .ad
 388 .RS 21n
 389 Sets the time quantum of the specified process(es) to \fItqntm\fR. You can
 390 optionally specify a resolution as explained below.
 391 .RE
 392 
 393 .sp
 394 .ne 2
 395 .na
 396 \fB\fB-q\fR \fItqsig\fR\fR
 397 .ad
 398 .RS 21n
 399 Sets the real-time time quantum signal of the specified process(es) to
 400 \fItqsig\fR.
 401 .RE
 402 
 403 .sp
 404 .LP
 405 The valid class-specific options for setting time-sharing parameters are:
 406 .sp
 407 .ne 2
 408 .na
 409 \fB\fB-m\fR \fItsuprilim\fR\fR
 410 .ad
 411 .RS 16n
 412 Sets the user priority limit of the specified process(es) to \fItsuprilim\fR.
 413 .RE
 414 
 415 .sp
 416 .ne 2
 417 .na
 418 \fB\fB-p\fR \fItsupri\fR\fR
 419 .ad
 420 .RS 16n
 421 Sets the user priority of the specified process(es) to \fItsupri\fR.
 422 .RE
 423 
 424 .sp
 425 .LP
 426 The valid class-specific options for setting inter-active parameters are:
 427 .sp
 428 .ne 2
 429 .na
 430 \fB\fB-m\fR \fIiauprilim\fR\fR
 431 .ad
 432 .RS 16n
 433 Sets the user priority limit of the specified process(es) to \fIiauprilim\fR.
 434 .RE
 435 
 436 .sp
 437 .ne 2
 438 .na
 439 \fB\fB-p\fR \fIiaupri\fR\fR
 440 .ad
 441 .RS 16n
 442 Sets the user priority of the specified process(es) to \fIiaupri\fR.
 443 .RE
 444 
 445 .sp
 446 .LP
 447 The valid class-specific options for setting fair-share parameters are:
 448 .sp
 449 .ne 2
 450 .na
 451 \fB\fB-m\fR \fIfssuprilim\fR\fR
 452 .ad
 453 .RS 17n
 454 Sets the user priority limit of the specified process(es) to \fIfssuprilim\fR.
 455 .RE
 456 
 457 .sp
 458 .ne 2
 459 .na
 460 \fB\fB-p\fR \fIfssupri\fR\fR
 461 .ad
 462 .RS 17n
 463 Sets the user priority of the specified process(es) to \fIfssupri\fR.
 464 .RE
 465 
 466 .sp
 467 .LP
 468 The valid class-specific options for setting fixed-priority parameters are:
 469 .sp
 470 .ne 2
 471 .na
 472 \fB\fB-m\fR \fIfxuprilim\fR\fR
 473 .ad
 474 .RS 16n
 475 Sets the user priority limit of the specified process(es) to \fIfxuprilim\fR.
 476 .RE
 477 
 478 .sp
 479 .ne 2
 480 .na
 481 \fB\fB-p\fR \fIfxupri\fR\fR
 482 .ad
 483 .RS 16n
 484 Sets the user priority of the specified process(es) to \fIfxupri\fR.
 485 .RE
 486 
 487 .sp
 488 .ne 2
 489 .na
 490 \fB\fB-t\fR \fItqntm\fR\fR
 491 .ad
 492 .RS 16n
 493 [\fB-r\fR \fIres\fR] Sets the time quantum of the specified process(es) to
 494 \fItqntm\fR. You can optionally specify a resolution as explained below.
 495 .RE
 496 
 497 .SH USAGE
 498 .SS "Real-Time Class"
 499 .sp
 500 .LP
 501 The real-time class provides a fixed priority preemptive scheduling policy for
 502 those processes requiring fast and deterministic response and absolute
 503 user/application control of scheduling priorities. If the real-time class is
 504 configured in the system, it should have exclusive control of the highest range
 505 of scheduling priorities on the system. This ensures that a runnable real-time
 506 process is given \fBCPU\fR service before any process belonging to any other
 507 class.
 508 .sp
 509 .LP
 510 The real-time class has a range of real-time priority (\fIrtpri\fR) values that
 511 can be assigned to processes within the class. Real-time priorities range from
 512 0 to \fIx\fR, where the value of \fIx\fR is configurable and can be displayed
 513 for a specific installation that has already configured a real-time scheduler,
 514 by using the command
 515 .sp
 516 .in +2
 517 .nf
 518 \fBpriocntl -l\fR
 519 .fi
 520 .in -2
 521 .sp
 522 
 523 .sp
 524 .LP
 525 The real-time scheduling policy is a fixed priority policy. The scheduling
 526 priority of a real-time process never changes except as the result of an
 527 explicit request by the user/application to change the \fIrtpri\fR value of the
 528 process.
 529 .sp
 530 .LP
 531 For processes in the real-time class, the \fIrtpri\fR value is, for all
 532 practical purposes, equivalent to the scheduling priority of the process. The
 533 \fIrtpri\fR value completely determines the scheduling priority of a real-time
 534 process relative to other processes within its class. Numerically higher
 535 \fIrtpri\fR values represent higher priorities. Since the real-time class
 536 controls the highest range of scheduling priorities in the system, it is
 537 guaranteed that the runnable real-time process with the highest \fIrtpri\fR
 538 value is always selected to run before any other process in the system.
 539 .sp
 540 .LP
 541 In addition to providing control over priority, \fBpriocntl\fR provides for
 542 control over the length of the time quantum allotted to processes in the
 543 real-time class. The time quantum value specifies the maximum amount of time a
 544 process can run, assuming that it does not complete or enter a resource or
 545 event wait state (\fBsleep\fR). Notice that if another process becomes runnable
 546 at a higher priority, the currently running process can be preempted before
 547 receiving its full time quantum.
 548 .sp
 549 .LP
 550 The command
 551 .sp
 552 .in +2
 553 .nf
 554 \fBpriocntl -d [-i \fIidtype\fR] [\fIidlist\fR]\fR
 555 .fi
 556 .in -2
 557 .sp
 558 
 559 .sp
 560 .LP
 561 displays the real-time priority, time quantum (in millisecond resolution), and
 562 time quantum signal value for each real-time process in the set specified by
 563 \fIidtype\fR and \fIidlist\fR.
 564 .sp
 565 .LP
 566 Any combination of the \fB-p\fR, \fB-t\fR [\fB-r\fR], and \fB-q\fR options can
 567 be used with \fBpriocntl\fR \fB-s\fR or \fBpriocntl\fR \fB-e\fR for the
 568 real-time class. If an option is omitted and the process is currently
 569 real-time, the associated parameter is unaffected. If an option is omitted when
 570 changing the class of a process to real-time from some other class, the
 571 associated parameter is set to a default value. The default value for
 572 \fIrtpri\fR is \fB0\fR and the default for time quantum is dependent on the
 573 value of \fIrtpri\fR and on the system configuration; see \fBrt_dptbl\fR(4).
 574 .sp
 575 .LP
 576 When using the \fB-t\fR \fItqntm\fR option, you can optionally specify a
 577 resolution using the \fB-r\fR \fIres\fR option. (If no resolution is specified,
 578 millisecond resolution is assumed.) If \fIres\fR is specified, it must be a
 579 positive integer between \fB1\fR and \fB1,000,000,000\fR inclusively and the
 580 resolution used is the reciprocal of \fIres\fR in seconds. For example,
 581 specifying \fB-t\fR \fB10\fR \fB-r\fR \fB100\fR would set the resolution to
 582 hundredths of a second and the resulting time quantum length would be 10/100
 583 seconds (one tenth of a second). Although very fine (nanosecond) resolution can
 584 be specified, the time quantum length is rounded up by the system to the next
 585 integral multiple  of the system clock's resolution. Requests for time quantums
 586 of zero or quantums greater than the (typically very large)
 587 implementation-specific maximum quantum result in an error.
 588 .sp
 589 .LP
 590 The real-time time quantum signal can be used to notify runaway real-time
 591 processes about the consumption of their time quantum. Those processes, which
 592 are monitored by the real-time time quantum signal, receive the configured
 593 signal in the event of time quantum expiration. The default value (\fB0\fR) of
 594 the time quantum signal \fItqsig\fR denotes no signal delivery. A positive
 595 value denotes the delivery of the signal specified by the value. Like
 596 \fBkill\fR(1) and other commands operating on signals, the \fB-q\fR \fItqsig\fR
 597 option is also able to handle symbolically named signals, like \fBXCPU\fR or
 598 \fBKILL\fR.
 599 .sp
 600 .LP
 601 In order to change the class of a process to real-time (from any other class),
 602 the user invoking \fBpriocntl\fR must have super-user privilege. In order to
 603 change the \fIrtpri\fR value or time quantum of a real-time process, the user
 604 invoking \fBpriocntl\fR must either be super-user, or must currently be in the
 605 real-time class (shell running as a real-time process) with a real or effective
 606 user \fBID\fR matching the real or effective user \fBID\fR of the target
 607 process.
 608 .sp
 609 .LP
 610 The real-time priority, time quantum, and time quantum signal are inherited
 611 across the \fBfork\fR(2) and \fBexec\fR(2) system calls. When using the time
 612 quantum signal with a user defined signal handler across the \fBexec\fR(2)
 613 system call, the new image must install an appropriate user defined signal
 614 handler before the time quantum expires. Otherwise, unpredicable behavior would
 615 result.
 616 .SS "Time-Sharing Class"
 617 .sp
 618 .LP
 619 The time-sharing scheduling policy provides for a fair and effective allocation
 620 of the \fBCPU\fR resource among processes with varying \fBCPU\fR consumption
 621 characteristics. The objectives of the time-sharing policy are to provide good
 622 response time to interactive processes and good throughput to \fBCPU\fR-bound
 623 jobs, while providing a degree of user/application control over scheduling.
 624 .sp
 625 .LP
 626 The time-sharing class has a range of time-sharing user priority (\fItsupri\fR)
 627 values that can be assigned to processes within the class. User priorities
 628 range from \(mi\fIx\fR to +\fIx\fR, where the value of \fIx\fR is configurable.
 629 The range for a specific installation can be displayed by using the command
 630 .sp
 631 .in +2
 632 .nf
 633 \fBpriocntl -l\fR
 634 .fi
 635 .in -2
 636 .sp
 637 
 638 .sp
 639 .LP
 640 The purpose of the user priority is to provide some degree of user/application
 641 control over the scheduling of processes in the time-sharing class. Raising or
 642 lowering the \fItsupri\fR value of a process in the time-sharing class raises
 643 or lowers the scheduling priority of the process. It is not guaranteed,
 644 however, that a time-sharing process with a higher \fItsupri\fR value runs
 645 before one with a lower \fItsupri\fR value. This is because the \fItsupri\fR
 646 value is just one factor used to determine the scheduling priority of a
 647 time-sharing process. The system can dynamically adjust the internal scheduling
 648 priority of a time-sharing process based on other factors such as recent
 649 \fBCPU\fR usage.
 650 .sp
 651 .LP
 652 In addition to the system-wide limits on user priority (displayed with
 653 \fBpriocntl\fR \fB-l\fR), there is a per process user priority limit
 654 (\fItsuprilim\fR), which specifies the maximum \fItsupri\fR value that can be
 655 set for a given process.
 656 .sp
 657 .LP
 658 The command
 659 .sp
 660 .in +2
 661 .nf
 662 \fBpriocntl -d [-i \fIidtype\fR] [\fIidlist\fR]\fR
 663 .fi
 664 .in -2
 665 .sp
 666 
 667 .sp
 668 .LP
 669 displays the user priority and user priority limit for each time-sharing
 670 process in the set specified by \fIidtype\fR and \fIidlist\fR.
 671 .sp
 672 .LP
 673 Any time-sharing process can lower its own \fItsuprilim\fR (or that of another
 674 process with the same user \fBID\fR). Only a time-sharing process with
 675 super-user privilege can raise a \fItsuprilim\fR. When changing the class of a
 676 process to time-sharing from some other class, super-user privilege is required
 677 in order to set the initial \fItsuprilim\fR to a value greater than zero.
 678 .sp
 679 .LP
 680 Any time-sharing process can set its own \fItsupri\fR (or that of another
 681 process with the same user \fBID\fR) to any value less than or equal to the
 682 process's \fItsuprilim\fR. Attempts to set the \fItsupri\fR above the
 683 \fItsuprilim\fR (and/or set the \fItsuprilim\fR below the \fItsupri\fR) result
 684 in the \fItsupri\fR being set equal to the \fItsuprilim\fR.
 685 .sp
 686 .LP
 687 Any combination of the \fB-m\fR and \fB-p\fR options can be used with
 688 \fBpriocntl\fR \fB-s\fR or \fBpriocntl\fR \fB-e\fR for the time-sharing class.
 689 If an option is omitted and the process is currently time-sharing, the
 690 associated parameter is normally unaffected. The exception is when the \fB-p\fR
 691 option is omitted and \fB-m\fR is used to set a \fItsuprilim\fR below the
 692 current \fItsupri\fR. In this case, the \fItsupri\fR is set equal to the
 693 \fItsuprilim\fR which is being set. If an option is omitted when changing the
 694 class of a process to time-sharing from some other class, the associated
 695 parameter is set to a default value. The default value for \fItsuprilim\fR is
 696 \fB0\fR and the default for \fItsupri\fR is to set it equal to the
 697 \fItsuprilim\fR value which is being set.
 698 .sp
 699 .LP
 700 The time-sharing user priority and user priority limit are inherited across the
 701 \fBfork\fR(2) and \fBexec\fR(2) system calls.
 702 .SS "Inter-Active Class"
 703 .sp
 704 .LP
 705 The inter-active scheduling policy provides for a fair and effective allocation
 706 of the \fBCPU\fR resource among processes with varying \fBCPU\fR consumption
 707 characteristics while providing good responsiveness for user interaction. The
 708 objectives of the inter-active policy are to provide good response time to
 709 interactive processes and good throughput to \fBCPU\fR-bound jobs. The
 710 priorities of processes in the inter-active class can be changed in the same
 711 manner as those in the time-sharing class, though the modified priorities
 712 continue to be adjusted to provide good responsiveness for user interaction.
 713 .sp
 714 .LP
 715 The inter-active user priority limit, \fIiaupri\fR, is equivalent to
 716 \fItsupri\fR. The inter-active per process user priority, \fIiauprilim\fR, is
 717 equivalent to \fItsuprilim\fR.
 718 .sp
 719 .LP
 720 Inter-active class processes that have the \fIiamode\fR ("interactive mode")
 721 bit set are given a priority boost value of \fB10\fR, which is factored into
 722 the user mode priority of the process when that calculation is made, that is,
 723 every time a process's priority is adjusted. This feature is used by the X
 724 windowing system, which sets this bit for those processes that run inside of
 725 the current active window to give them a higher priority.
 726 .SS "Fair-Share Class"
 727 .sp
 728 .LP
 729 The fair-share scheduling policy provides a fair allocation of system \fBCPU\fR
 730 resources among projects, independent of the number of processes they own.
 731 Projects are given "shares" to control their entitlement to \fBCPU\fR
 732 resources. Resource usage is remembered over time, so that entitlement is
 733 reduced  for heavy usage, and increased for light usage, with respect to other
 734 projects. \fBCPU\fR time is scheduled among processes according to their
 735 owner's entitlements, independent of the number of processes each project owns.
 736 .sp
 737 .LP
 738 The \fBFSS\fR scheduling class supports the notion of per-process user priority
 739 and user priority limit for compatibility with the time-share scheduler. The
 740 fair share scheduler attempts to provide an evenly graded effect across the
 741 whole range of user priorities. Processes with negative \fIfssupri\fR values
 742 receive time slices less frequently than normal,  while processes with positive
 743 \fIfssupri\fR values receive time slices more  frequently than normal.  Notice
 744 that user priorities do not interfere with shares. That is, changing a
 745 \fIfssupri\fR value of a process is not going to affect its project's overall
 746 \fBCPU\fR usage which only relates to the amount of shares it is allocated
 747 compared to other projects.
 748 .sp
 749 .LP
 750 The priorities of processes in the fair-share class can be changed in the same
 751 manner as those in the time-share class.
 752 .SS "Fixed-Priority Class"
 753 .sp
 754 .LP
 755 The fixed-priority class provides a fixed priority preemptive scheduling policy
 756 for those processes requiring that the scheduling priorities do not get
 757 dynamically adjusted by the system and that the user/application have control
 758 of the scheduling priorities.
 759 .sp
 760 .LP
 761 The fixed-priority class shares the same range of scheduling priorities with
 762 the time-sharing class, by default. The fixed-priority class has a range of
 763 fixed-priority user priority (\fIfxupri\fR) values that can be assigned to
 764 processes within the class. User priorities range from 0 to \fIx\fR, where the
 765 value of \fIx\fR is configurable. The range for a specific installation can be
 766 displayed by using the command
 767 .sp
 768 .in +2
 769 .nf
 770 \fBpriocntl -l\fR
 771 .fi
 772 .in -2
 773 .sp
 774 
 775 .sp
 776 .LP
 777 The purpose of the user priority is to provide user/application control over
 778 the scheduling of processes in the fixed-priority class. For processes in the
 779 fixed-priority class, the \fIfxupri\fR value is, for all practical purposes,
 780 equivalent  to the scheduling priority of the process. The \fIfxupri\fR value
 781 completely determines the scheduling priority of a fixed-priority process
 782 relative to other processes within its class. Numerically higher \fIfxupri\fR
 783 values represent higher priorities.
 784 .sp
 785 .LP
 786 In addition to the system-wide limits on user priority (displayed with
 787 \fBpriocntl\fR  \fB-l\fR), there is a per process user priority  limit
 788 (\fIfxuprilim\fR), which specifies the maximum \fIfxupri\fR value that can be
 789 set for a given process.
 790 .sp
 791 .LP
 792 Any fixed-priority process can lower its own \fIfxuprilim\fR (or that of
 793 another process with the same user \fBID\fR). Only a process with super-user
 794 privilege can raise a \fIfxuprilim\fR. When changing the class of a process to
 795 fixed-priority from some other class, super-user privilege is required in order
 796 to set the initial \fIfxuprilim\fR to a value greater than zero.
 797 .sp
 798 .LP
 799 Any fixed-priority process can set its own \fIfxupri\fR (or that of another
 800 process with the same user \fBID\fR) to any value less than or equal to the
 801 process's \fIfxuprilim\fR. Attempts to set the \fIfxupri\fR above the
 802 \fIfxuprilim\fR (or set the \fIfxuprilim\fR below the \fIfxupri\fR) result in
 803 the \fIfxupri\fR being set equal to the \fIfxuprilim\fR.
 804 .sp
 805 .LP
 806 In addition to providing control over priority, \fBpriocntl\fR provides for
 807 control over the length of the time quantum allotted to processes in the
 808 fixed-priority class. The time quantum value specifies the maximum amount of
 809 time a process can run, before surrendering the \fBCPU\fR, assuming that it
 810 does not complete or enter a resource or event wait state (sleep). Notice that
 811 if another process becomes runnable at a higher priority, the currently running
 812 process can be preempted before receiving its full time quantum.
 813 .sp
 814 .LP
 815 Any combination of the \fB-m\fR, \fB-p\fR, and \fB-t\fR options can be used
 816 with \fBpriocntl\fR \fB-s\fR or \fBpriocntl\fR \fB-e\fR for the fixed-priority
 817 class. If an option is omitted and the process is currently fixed-priority, the
 818 associated parameter is normally unaffected. The exception is when the \fB-p\fR
 819 option is omitted and the \fB-m\fR option is used to set a \fIfxuprilim\fR
 820 below the current \fIfxupri\fR. In this case, the \fIfxupri\fR is set equal to
 821 the \fIfxuprilim\fR which is being set. If an option is omitted when changing
 822 the class of a process to fixed-priority from some other class, the associated
 823 parameter is set to a default value. The default value for \fIfxuprilim\fR is
 824 \fB0\fR. The default for \fIfxupri\fR is to set it equal to the \fIfxuprilim\fR
 825 value which is being set. The default for time quantum is dependent on the
 826 \fIfxupri\fR and on the system configuration. See \fBfx_dptbl\fR(4).
 827 .sp
 828 .LP
 829 The time quantum of processes in the fixed-priority class      can be changed
 830 in the same manner as those in the real-time class.
 831 .sp
 832 .LP
 833 The fixed-priority user priority, user priority limit, and time quantum are
 834 inherited across the \fBfork\fR(2) and \fBexec\fR(2) system calls.
 835 .SH EXAMPLES
 836 .sp
 837 .LP
 838 The following are real-time class examples:
 839 .LP
 840 \fBExample 1 \fRSetting the Class
 841 .sp
 842 .LP
 843 The following example sets the class of any non-real-time processes selected by
 844 \fIidtype\fR and \fIidlist\fR to real-time and sets their real-time priority to
 845 the default value of \fB0\fR. The real-time priorities of any processes
 846 currently in the real-time class are unaffected. The time quantums of all of
 847 the specified processes are set to \fB1/10\fR seconds.
 848 
 849 .sp
 850 .in +2
 851 .nf
 852 example% \fBpriocntl -s -c RT -t 1 -r 10 -i \fIidtype idlist\fR\fR
 853 .fi
 854 .in -2
 855 .sp
 856 
 857 .LP
 858 \fBExample 2 \fRExecuting a Command in Real-time
 859 .sp
 860 .LP
 861 The following example executes \fIcommand\fR in the real-time class with a
 862 real-time priority of \fB15\fR and a time quantum of \fB20\fR milliseconds:
 863 
 864 .sp
 865 .in +2
 866 .nf
 867 example% \fBpriocntl -e -c RT -p 15 -t 20 \fIcommand\fR\fR
 868 .fi
 869 .in -2
 870 .sp
 871 
 872 .LP
 873 \fBExample 3 \fRExecuting a Command in Real-time with a Specified Quantum
 874 Signal
 875 .sp
 876 .LP
 877 The following example executes \fIcommand\fR in the real-time class with a
 878 real-time priority of \fB11\fR, a time quantum of \fB250\fR milliseconds, and
 879 where the specified real-time quantum signal is \fBSIGXCPU\fR:
 880 
 881 .sp
 882 .in +2
 883 .nf
 884 example% \fBpriocntl -e -c RT -p 11 -t 250 -q XCPU \fIcommand\fR\fR
 885 .fi
 886 .in -2
 887 .sp
 888 
 889 .sp
 890 .LP
 891 The following are time-sharing class examples:
 892 .LP
 893 \fBExample 4 \fRSetting the Class of non-time-sharing Processes
 894 .sp
 895 .LP
 896 The following example sets the class of any non-time-sharing processes selected
 897 by \fIidtype\fR and \fIidlist\fR to time-sharing and sets both their user
 898 priority limit and user priority to \fB0\fR. Processes already in the
 899 time-sharing class are unaffected.
 900 
 901 .sp
 902 .in +2
 903 .nf
 904 example% \fBpriocntl -s -c TS -i \fIidtype idlist\fR\fR
 905 .fi
 906 .in -2
 907 .sp
 908 
 909 .LP
 910 \fBExample 5 \fRExecuting a Command in the Time-sharing Class
 911 .sp
 912 .LP
 913 The following example executes \fIcommand\fR with the arguments \fIarguments\fR
 914 in the time-sharing class with a user priority limit of \fB0\fR and a user
 915 priority of \fB\(mi15\fR:
 916 
 917 .sp
 918 .in +2
 919 .nf
 920 example% \fBpriocntl -e -c TS -m 0 -p \fR\fB-15\fR \fB\fIcommand\fR [\fIarguments\fR]\fR
 921 .fi
 922 .in -2
 923 .sp
 924 
 925 .LP
 926 \fBExample 6 \fRExecuting a Command in Fixed-Priority Class
 927 .sp
 928 .LP
 929 The following example executes a command in the fixed-priority  class with a
 930 user priority limit of \fB20\fR and user priority of \fB10\fR and time quantum
 931 of \fB250\fR milliseconds:
 932 
 933 .sp
 934 .in +2
 935 .nf
 936 example% \fBpriocntl -e -c FX -m 20 -p 10 -t 250 command\fR
 937 .fi
 938 .in -2
 939 .sp
 940 
 941 .SH EXIT STATUS
 942 .sp
 943 .LP
 944 The following exit values are returned:
 945 .sp
 946 .LP
 947 For options \fB-d\fR, \fB-l\fR, and \fB-s\fR:
 948 .sp
 949 .ne 2
 950 .na
 951 \fB\fB0\fR\fR
 952 .ad
 953 .RS 5n
 954 Successful operation.
 955 .RE
 956 
 957 .sp
 958 .ne 2
 959 .na
 960 \fB\fB1\fR\fR
 961 .ad
 962 .RS 5n
 963 Error condition.
 964 .RE
 965 
 966 .sp
 967 .LP
 968 For option \fB-e\fR:
 969 .sp
 970 .LP
 971 Return of the Exit Status of the executed command denotes successful operation.
 972 Otherwise,
 973 .sp
 974 .ne 2
 975 .na
 976 \fB\fB1\fR\fR
 977 .ad
 978 .RS 5n
 979 Command could not be executed at the specified priority.
 980 .RE
 981 
 982 .SH ATTRIBUTES
 983 .sp
 984 .LP
 985 See \fBattributes\fR(5) for descriptions of the following attributes:
 986 .sp
 987 
 988 .sp
 989 .TS
 990 box;
 991 c | c
 992 l | l .
 993 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 994 _
 995 CSI     Enabled
 996 .TE
 997 
 998 .SH SEE ALSO
 999 .sp
1000 .LP
1001 \fBkill\fR(1), \fBnice\fR(1), \fBps\fR(1), \fBdispadmin\fR(1M), \fBexec\fR(2),
1002 \fBfork\fR(2), \fBpriocntl\fR(2), \fBfx_dptbl\fR(4), \fBprocess\fR(4),
1003 \fBrt_dptbl\fR(4), \fBattributes\fR(5), \fBzones\fR(5), \fBFSS\fR(7)
1004 .sp
1005 .LP
1006 \fISystem Administration Guide: Basic Administration\fR
1007 .SH DIAGNOSTICS
1008 .sp
1009 .LP
1010 \fBpriocntl\fR prints the following error messages:
1011 .sp
1012 .ne 2
1013 .na
1014 \fB\fBProcess(es) not found\fR\fR
1015 .ad
1016 .sp .6
1017 .RS 4n
1018 None of the specified processes exists.
1019 .RE
1020 
1021 .sp
1022 .ne 2
1023 .na
1024 \fB\fBSpecified processes from different classes\fR\fR
1025 .ad
1026 .sp .6
1027 .RS 4n
1028 The \fB-s\fR option is being used to set parameters, the \fB-c\fR \fIclass\fR
1029 option is not present, and processes from more than one class are specified.
1030 .RE
1031 
1032 .sp
1033 .ne 2
1034 .na
1035 \fB\fBInvalid option or argument\fR\fR
1036 .ad
1037 .sp .6
1038 .RS 4n
1039 An unrecognized or invalid option or option argument is used.
1040 .RE
1041 
--- EOF ---