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