| blob | 035a56fa1c0119383925a5b2b8e1a480df15873a |
1 '\" te
2 .\" Copyright (c) 2013, Joyent, Inc. All Rights Reserved
3 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
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 PSRSET 8 "Mar 11, 2013"
8 .SH NAME
9 psrset \- creation and management of processor sets
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBpsrset\fR \fB-a\fR [\fB-F\fR] \fIprocessor_set_id\fR \fIprocessor_id\fR...
14 .fi
16 .LP
17 .nf
18 \fBpsrset\fR \fB-b\fR \fIprocessor_set_id\fR \fIpid\fR [\fI/lwpid\fR]...
19 .fi
21 .LP
22 .nf
23 \fBpsrset\fR \fB-b\fR \fB-z\fR \fIzone name\fR \fIprocessor_set_id\fR
24 .fi
26 .LP
27 .nf
28 \fBpsrset\fR \fB-c\fR [\fB-F\fR] [\fIprocessor_id\fR]...
29 .fi
31 .LP
32 .nf
33 \fBpsrset\fR \fB-d\fR \fIprocessor_set_id\fR...
34 .fi
36 .LP
37 .nf
38 \fBpsrset\fR \fB-e\fR \fIprocessor_set_id\fR \fIcommand\fR [\fIargument(s)\fR]
39 .fi
41 .LP
42 .nf
43 \fBpsrset\fR \fB-f\fR \fIprocessor_set_id\fR
44 .fi
46 .LP
47 .nf
48 \fBpsrset\fR [\fB-i\fR] [\fIprocessor_set_id\fR]...
49 .fi
51 .LP
52 .nf
53 \fBpsrset\fR \fB-n\fR \fIprocessor_set_id\fR
54 .fi
56 .LP
57 .nf
58 \fBpsrset\fR \fB-p\fR [\fIprocessor_id\fR]...
59 .fi
61 .LP
62 .nf
63 \fBpsrset\fR [\fB-q\fR] [\fIpid\fR [\fI/lwpid\fR]]...
64 .fi
66 .LP
67 .nf
68 \fBpsrset\fR \fB-Q\fR [\fIprocessor_set_id\fR]...
69 .fi
71 .LP
72 .nf
73 \fBpsrset\fR \fB-r\fR [\fB-F\fR] \fIprocessor_id\fR...
74 .fi
76 .LP
77 .nf
78 \fBpsrset\fR \fB-u\fR \fIpid\fR [\fI/lwpid\fR]...
79 .fi
81 .LP
82 .nf
83 \fBpsrset\fR \fB-U\fR [\fIprocessor_set_id\fR]...
84 .fi
86 .SH DESCRIPTION
87 .LP
88 The \fBpsrset\fR utility controls the management of processor sets. Processor
89 sets allow the binding of processes or LWPs to groups of processors, rather
90 than just a single processor. Processors assigned to processor sets can run
91 only LWPs that have been bound to that processor set.
92 .sp
93 .LP
94 This command cannot be used to modify processor disposition when pools are
95 enabled. Use \fBpooladm\fR(8) and \fBpoolcfg\fR(8) to modify processor set
96 configuration through the resource pools facility.
97 .SH OPTIONS
98 .LP
99 The following options are supported:
100 .sp
101 .ne 2
102 .na
103 \fB\fB-a\fR\fR
104 .ad
105 .RS 6n
106 Assign the specified processors to the specified processor set. With the
107 additional \fB-F\fR option, all LWPs bound to the specified processors will be
108 unbound prior to changing processor sets.
109 .sp
110 This option is restricted to users with the \fBPRIV_SYS_RES_CONFIG\fR
111 privilege.
112 .RE
114 .sp
115 .ne 2
116 .na
117 \fB-b\fR [\fB-z\fR \fIzonename\fR]
118 .ad
119 .RS 6n
120 Bind all or a subset of the \fBLWP\fRs of the specified processes to the
121 specified processor set. If \fB-z\fR is specified, all processes and threads
122 inside the specified zone are bound to the processor set.
123 .sp
124 LWPs bound to a processor set are restricted to run only on the processors in
125 that set. Processes can only be bound to non-empty processor sets, that is,
126 processor sets that have had processors assigned to them.
127 .sp
128 Bindings are inherited, so new LWPs and processes created by a bound LWP have
129 the same binding. Binding an interactive shell to a processor, for example,
130 binds all commands executed by the shell.
131 .sp
132 This option is restricted to users with the \fBPRIV_SYS_RES_CONFIG\fR
133 privilege.
134 .RE
136 .sp
137 .ne 2
138 .na
139 \fB\fB-c\fR\fR
140 .ad
141 .RS 6n
142 Create a new processor set and displays the new processor set \fBID\fR. With
143 the additional \fB-F\fR option, all LWPs bound to the specified processors will
144 be unbound prior to assigning them to the processor set being created.
145 .sp
146 If a list of processors is given, it also attempts to assign those processors
147 to the processor set. If this succeeds, the processors are idle until
148 \fBLWP\fRs are bound to the processor set. This option is restricted to users
149 with the \fBPRIV_SYS_RES_CONFIG\fR privilege.
150 .sp
151 Only a limited number of processor sets can be active (created and not
152 destroyed) at a given time. This limit is always be greater than the number of
153 processors in the system. If the \fB-c\fR option is used when the maximum
154 number of processor sets is already active, the command fails.
155 .sp
156 The following format is used for the first line of output of the \fB-c\fR
157 option when the \fBLC_MESSAGES\fR locale category specifies the "C" locale. In
158 other locales, the strings \fBcreated\fR, \fBprocessor\fR, and \fBset\fR can be
159 replaced with more appropriate strings corresponding to the locale.
160 .sp
161 .in +2
162 .nf
163 "created processor set %d\en" \fIprocessor set ID\fR
164 .fi
165 .in -2
166 .sp
168 .RE
170 .sp
171 .ne 2
172 .na
173 \fB\fB-d\fR\fR
174 .ad
175 .RS 6n
176 Remove the specified processor set, releasing all processors and processes
177 associated with it.
178 .sp
179 This option is restricted to users with the \fBPRIV_SYS_RES_CONFIG\fR
180 privilege.
181 .RE
183 .sp
184 .ne 2
185 .na
186 \fB\fB-e\fR\fR
187 .ad
188 .RS 6n
189 Execute a command (with optional arguments) in the specified processor set.
190 .sp
191 The command process and any child processes are executed only by processors in
192 the processor set.
193 .sp
194 This option is restricted to users with the \fBPRIV_SYS_RES_CONFIG\fR
195 privilege.
196 .RE
198 .sp
199 .ne 2
200 .na
201 \fB\fB-f\fR\fR
202 .ad
203 .RS 6n
204 Disables interrupts for all processors within the specified processor set. See
205 \fBpsradm\fR(8).
206 .sp
207 If some processors in the set cannot have their interrupts disabled, the other
208 processors still have their interrupts disabled, and the command reports an
209 error and return non-zero exit status.
210 .sp
211 This option is restricted to users with the \fBPRIV_SYS_RES_CONFIG\fR
212 privilege.
213 .RE
215 .sp
216 .ne 2
217 .na
218 \fB\fB-F\fR\fR
219 .ad
220 .RS 6n
221 Forces the specified processor set operation by unbinding all threads bound to
222 the specified processor. Only the \fB-a\fR or the \fB-r\fR option can be used
223 in combination with this option. Administrators are encouraged to use the
224 \fB-Q\fR option for \fBpbind\fR(8) to find out which threads will be affected
225 by such operation.
226 .RE
228 .sp
229 .ne 2
230 .na
231 \fB\fB-i\fR\fR
232 .ad
233 .RS 6n
234 Display a list of processors assigned to each named processor set. If no
235 argument is given, a list of all processor sets and the processors assigned to
236 them is displayed. This is also the default operation if the \fBpsrset\fR
237 command is not given an option.
238 .RE
240 .sp
241 .ne 2
242 .na
243 \fB\fB-n\fR\fR
244 .ad
245 .RS 6n
246 Enable interrupts for all processors within the specified processor set. See
247 \fBpsradm\fR(8).
248 .sp
249 This option is restricted to users with the \fBPRIV_SYS_RES_CONFIG\fR
250 privilege.
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fB\fB-p\fR\fR
257 .ad
258 .RS 6n
259 Display the processor set assignments for the specified list of processors. If
260 no argument is given, the processor set assignments for all processors in the
261 system is given.
262 .RE
264 .sp
265 .ne 2
266 .na
267 \fB\fB-q\fR\fR
268 .ad
269 .RS 6n
270 Display the processor set bindings of the specified processes or of all
271 processes. If a process is composed of multiple \fBLWP\fRs which have different
272 bindings and the LWPs are not explicitly specified, the bindings of only one of
273 the bound \fBLWP\fRs is displayed. The bindings of a subset of LWPs can be
274 displayed by appending "/lwpids" to the process \fBID\fRs. Multiple LWPs may be
275 selected using "-" and "," delimiters. See EXAMPLES.
276 .RE
278 .sp
279 .ne 2
280 .na
281 \fB\fB-Q\fR\fR
282 .ad
283 .RS 6n
284 Display the LWPs bound to the specified list of processor sets, or all LWPs
285 with processor set bindings.
286 .RE
288 .sp
289 .ne 2
290 .na
291 \fB\fB-r\fR\fR
292 .ad
293 .RS 6n
294 Remove a list of processors from their current processor sets. Processors that
295 are removed return to the general pool of processors.
296 .sp
297 Processors with \fBLWP\fRs bound to them using \fBpbind\fR(8) can be assigned
298 to or removed from processor sets using the \fB-F\fR option.
299 .sp
300 This option is restricted to users with the \fBPRIV_SYS_RES_CONFIG\fR
301 privilege.
302 .RE
304 .sp
305 .ne 2
306 .na
307 \fB\fB-u\fR\fR
308 .ad
309 .RS 6n
310 Remove the processor set bindings of a subset or all the \fBLWP\fRs of the
311 specified processes, allowing them to be executed on any on-line processor if
312 they are not bound to individual processors through \fBpbind\fR.
313 .sp
314 Users with the \fBPRIV_SYS_RES_CONFIG\fR privilege can unbind any process or
315 LWP from any active processor set. Other users can unbind processes and LWPs
316 from processor sets that do not have the \fBPSET_NOESCAPE\fR attribute set. In
317 addition, the user must have permission to control the affected processes; the
318 real or effective user ID of the user must match the real or saved user ID of
319 the target processes.
320 .RE
322 .sp
323 .ne 2
324 .na
325 \fB\fB-U\fR\fR
326 .ad
327 .RS 6n
328 Removes the bindings of all LWPs bound to the specified list of processor sets,
329 or to any processor set if no argument is specified.
330 .RE
332 .SH OPERANDS
333 .LP
334 The following operands are supported:
335 .sp
336 .ne 2
337 .na
338 \fB\fIpid\fR\fR
339 .ad
340 .RS 20n
341 Specify \fIpid\fR as a process \fBID\fR.
342 .RE
344 .sp
345 .ne 2
346 .na
347 \fB\fIlwpid\fR\fR
348 .ad
349 .RS 20n
350 The set of LWP\fBID\fRs of the specified process to be controlled or queried.
351 The syntax for selecting LWP \fBID\fRs is as follows:
352 .sp
353 .in +2
354 .nf
355 2,3,4-8 LWP IDs 2, 3, and 4 through 8
356 -4 LWPs whose IDs are 4 or below
357 4- LWPs whose IDs are 4 or above
358 .fi
359 .in -2
361 .RE
363 .sp
364 .ne 2
365 .na
366 \fB\fIprocessor_id\fR\fR
367 .ad
368 .RS 20n
369 Specify \fIprocessor_id\fR as an individual processor number (for example,
370 \fB3\fR), multiple processor numbers separated by spaces (for example, \fB1 2
371 3\fR), or a range of processor numbers (for example, \fB1-4\fR). It is also
372 possible to combine ranges and (individual or multiple) \fIprocessor_id\fRs
373 (for example, \fB1-3 5 7-8 9\fR).
374 .RE
376 .sp
377 .ne 2
378 .na
379 \fB\fIprocessor_set_id\fR\fR
380 .ad
381 .RS 20n
382 Specify \fIprocessor_set_id\fR as a processor set \fBID\fR.
383 .RE
385 .SH EXIT STATUS
386 .LP
387 The following exit values are returned:
388 .sp
389 .ne 2
390 .na
391 \fB\fB0\fR\fR
392 .ad
393 .RS 9n
394 Successful completion.
395 .RE
397 .sp
398 .ne 2
399 .na
400 \fBnon-0\fR
401 .ad
402 .RS 9n
403 An error occurred.
404 .RE
406 .SH ATTRIBUTES
407 .LP
408 See \fBattributes\fR(5) for descriptions of the following attributes:
409 .sp
411 .sp
412 .TS
413 box;
414 c | c
415 l | l .
416 ATTRIBUTE TYPE ATTRIBUTE VALUE
417 _
418 Stability Level Stable
419 .TE
421 .SH SEE ALSO
422 .LP
423 \fBpbind\fR(8), \fBpooladm\fR(8), \fBpoolcfg\fR(8), \fBpsradm\fR(8),
424 \fBpsrinfo\fR(8), \fBprocessor_bind\fR(2), \fBprocessor_info\fR(2),
425 \fBpset_bind\fR(2), \fBpset_create\fR(2), \fBpset_info\fR(2),
426 \fBsysconf\fR(3C), \fBlibpool\fR(3LIB), \fBattributes\fR(5),
427 \fBprivileges\fR(5)
428 .SH DIAGNOSTICS
429 .LP
430 The following output indicates that the specified process did not exist or has
431 exited:
432 .sp
433 .in +2
434 .nf
435 psrset: cannot query pid 31: No such process
436 .fi
437 .in -2
438 .sp
440 .sp
441 .LP
442 The following output indicates that the user does not have permission to bind
443 the process:
444 .sp
445 .in +2
446 .nf
447 psrset: cannot bind pid 31: Not owner
448 .fi
449 .in -2
450 .sp
452 .sp
453 .LP
454 The following output indicates that the user does not have permission to assign
455 the processor:
456 .sp
457 .in +2
458 .nf
459 psrset: cannot assign processor 4: Not owner
460 .fi
461 .in -2
462 .sp
464 .sp
465 .LP
466 The following output indicates that the specified processor is not on-line, or
467 the specified processor does not exist.
468 .sp
469 .in +2
470 .nf
471 psrset: cannot assign processor 8: Invalid argument
472 .fi
473 .in -2
474 .sp
476 .sp
477 .LP
478 The following output indicates that an \fBLWP\fR in the specified process is
479 bound to a processor and cannot be bound to a processor set that does not
480 include that processor:
481 .sp
482 .in +2
483 .nf
484 psrset: cannot bind pid 67: Device busy
485 .fi
486 .in -2
487 .sp
489 .sp
490 .LP
491 The following output indicates that the specified processor could not be added
492 to the processor set. This can be due to bound \fBLWP\fRs on that processor, or
493 because that processor cannot be combined in the same processor set with other
494 processors in that set, or because the processor is the last one in its current
495 processor set:
496 .sp
497 .in +2
498 .nf
499 psrset: cannot assign processor 7: Device busy
500 .fi
501 .in -2
502 .sp
504 .sp
505 .LP
506 The following output indicates that the specified processor set does not exist:
507 .sp
508 .in +2
509 .nf
510 psrset: cannot execute in processor set 8: Invalid argument
511 .fi
512 .in -2
513 .sp
515 .sp
516 .LP
517 The following output indicates that the maximum number of processor sets
518 allowed in the system is already active:
519 .sp
520 .in +2
521 .nf
522 psrset: cannot create processor set: Not enough space
523 .fi
524 .in -2
525 .sp
527 .sp
528 .LP
529 The following output indicates that the pools facility is active.
530 .sp
531 .in +2
532 .nf
533 psrset: cannot assign processor 7: Operation not supported
534 psrset: cannot bind pid 31: Operation not supported
535 psrset: cannot bind pid 31: Operation not supported
536 psrset: could not create processor set: Operation not supported
537 psrset: could not remove processor set 1: Operation not supported
538 psrset: cannot exec in processor set 1: Operation not supported
539 psrset: cannot remove processor 7: Operation not supported
540 psrset: cannot unbind pid 31: Operation not supported
541 .fi
542 .in -2
543 .sp