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