prctl - get or set the resource controls of running processes, tasks, and projects
prctl [-P] [-t basic|privileged|system] [-n name] [-o|-s|-r|-x]
[-v value] [-e|-d action] [-p pid] [-i idtype] id...
The prctl utility allows the examination and modification of the resource controls (rctl) associated with an active process, task, project or zone on the system. It allows access to the basic and privileged limits and the current usage on the specified entity.
There are two modes of operation. First is the get operation, which prints the rctl values of target rctls. It is run when none of –d, –e, –o, –s, –r, –v, or –x options are given. If privilege is given by –t option, only rctl values that match privilege will be printed. Otherwise rctl values of any privilege are printed.
See resource-controls(7) for a description of the resource controls supported in the current release of the Solaris operating system.
If name is given by –n option, only rctl values of the rctl pointed by name are printed. Otherwise, all rctls of the target entity and entities that target entity belongs to are printed. For example, invoking prctl to a task without giving a name will print all rctl values of the target task as well as rctl values of the project and the zone of the target task.
For an rctl which has a rctl value to print, its usage is also printed if the usage exists. If there are multiple rctl values in an rctl, they are printed in ascending order. In addition, the caller can get machine-parseable output by specifying –P option. The accepted list of options for get operation are –i, –n, –t, and –P.
The second type of operation is the modify operation. In modify operation, the name or rctl must be explicitly given by –n option. Modify operation can be divided as follows:
Insert operation: Insert a new rctl value with given value and privilege. If action modification or recipient pid is given and valid, they are applied to the inserted rctl value. The value must be explicitly given, and if privilege is not given explicitly, it is assumed as basic. There are three ways that insert operation can be invoked:
Specifying the –s option.
None of –d, –e, –o, –s, –r, –x options are given, but –v option is given. It is effectively same as invoking the same command with addition of –s option.
Action modification operation failed because there is no match, and the –v option is explicitly given. It is effectively same as invoking the same command with addition of –s option.
Overwrite operation: Deletes all rctl values of given privilege, and inserts a new rctl value with given value and privilege. If action modification or recipient pid is given and valid, they are applied to the inserted rctl value. As insert operation, –v option must be explicitly given, and if privilege is not given explicitly, it is assumed as basic. This operation is invoked by specifying –o option.
Delete operation: Deletes the rctl value matched by given value and privilege. This operation is invoked by –x option. –d or –e options are not allowed in delete operation.
Replace operation: Matches an rctl value by given privilege, and replaces its value. If action modification or recipient pid is given and valid, they are applied to the replaced rctl value. The value must be explicitly given. This operation is invoked by –r option.
Action modification operation: Matches an rctl value by given value and privilege, and modifies its action. If recipient pid is given and valid, it is applied to the modified rctl value. This operation is invoked by –d or –e option without –o, –r, –s, –x option. If there is no matching rctl value to modify and the value is explicitly given, insert operation is called as if invoking same command with addition of –s option.
Some operations find a target rctl value by matching based on given value or privilege. The matching returns the first rctl value that matches the given condition. When any of these arguments are not given for searching, then corresponding property is always considered as matched. As a result, if none of searching argument is given, the first rctl values of the target rctl will be the matched one.
A basic rctl value with a signal action has a recipient pid. When inserting a new rctl value or replacing an existing rctl value, if the resulting rctl value has a recipient pid, then the caller may explicitly give it by –p option. If the caller does not give recipient pid when the resulting rctl value has the recipient pid, prctl chooses the recipient pid in following cases:
If the target entity is a process, then pid of that process is used.
If prctl is modifying existing rctl value and that rctl value has a recipient pid, prctl uses the same value.
If prctl cannot choose the recipient pid based on above rules, it fails. Some reasons that can fail this command includes the following:
Invalid argument for the target rctl value, especially, specifying RCPRIV_BASIC when it is not allowed by RCTL_GLOBAL_NOBASIC flag. For more information, see the rctlblk_get_global_flags(3C) man page.
Insertion and overwriting can fail if there are too many rctl values in the target rctl.
When inserting or modifying a new rctl value, if the resulting rctl value is already in the rctl, prctl fails since there can be no duplicate rctl values in an rctl.
Searching for matching rctl value fails, except the case mentioned in action modification operation which attempts to insert a new rctl value.
Requested rctl value modification out of the caller's privilege. For more information, see the setrctl(2) man page.
See resource-controls(7) man page for a description of the resource controls supported in the current release of the Oracle Solaris operating system.
If none of the –s, –r, –x, –v, –d, or –e options are specified, the invocation is considered a get operation. Otherwise, it is considered a modify operation.
The following options are supported:
Disables (–d) or enables (–e) the specified action on the rctl value.
Actions:
This action is only available with –d. It disables all actions. This fails on resource control values that have the deny global flag.
Indicates that the resource control attempts to deny granting the resource to the process, task, project, or zone on a request for resources in excess of the resource control value. deny actions can not be enabled if the resource control has the no-deny global flag. deny actions can not be disabled if the resource control has the deny global flag.
This action is only available with –d. It deactivates any signal action.
Enables or disables specific signal action. signum is a signal number or string representation of a signal, it may omit the "SIG" prefix and the string is case-insensitive, that is, "TERm" is recognized as SIGTERM. Setting a signal action on a resource control with the no-local-action global flag fails. The valid signals that can be set on a rctl value are SIGABRT, SIGXRES, SIGHUP, SIGSTOP, SIGTERM, and SIGKILL. Additionally, CPU time related controls can issue the SIGXCPU signal, and file size related controls can send the SIGXFSZ signal.
In the signal=signum action, signum is a signal number (or string representation of a signal). Setting a signal action on a resource control with the no-local-action global flag fails. A limited set of signals can be sent. See NOTES for additional details.
Specifies the type of the id operands. Valid idtypes are process, task, project, or zone. Also allowed are pid, taskid, projid, and zoneid. The default id type, if the –i option is omitted, is process.
Specifies the name of the resource control to get or modify. The name must refer to a rctl of an entity, and it should belong to the target entity given by –i option. For example, passing the –n option, a project rctl of a task (–i taskid) is allowed, but not vice versa.
Specifies the recipient pid for the inserted or modified rctl value when it is needed. This option is not allowed when basic privilege is not allowed, or a privilege other than basic is explicitly given.
Displays resource control values in space delimited format. Allowed only for the get operation.
Invokes the replacement operation.
Invokes the insert operation.
Specifies which resource control type to get or modify. The value priv is allowed instead of privileged.
Specifies the value for the resource control for modify operation.
See resource-controls(7) for a description of unit modifiers and scaling factors you can use to express large values when setting a resource control value.
Invokes the delete operation.
The following operand is supported:
The ID of the entity (process, task, project, or zone) to interrogate. For project and zone, entity names instead of numeric IDs are also recognized. If no id is specified, an error message is returned.
The following example displays current resource control settings for a task to which the current shell belongs:
example$ ps -o taskid -p $$
TASKID
234
example$ prctl -i task 234
task: 234
NAME PRIVILEGE VALUE FLAG ACTION RECIPIENT
task.max-cpu-time
usage 8s
system 18.4Es inf none -
task.max-lwps
usage 39
system 2.15G max deny -
project.max-contracts
privileged 10.0K - deny -
project.max-locked-memory
usage 0B
privileged 508MB - deny -
project.max-port-ids
privileged 8.19K - deny -
project.max-shm-memory
privileged 508MB - deny -
project.max-shm-ids
privileged 128 - deny -
project.max-msg-ids
privileged 128 - deny -
project.max-sem-ids
privileged 128 - deny -
project.max-crypto-memory
usage 0B
privileged 508MB - deny -
project.max-tasks
usage 2
system 2.15G max deny -
project.max-lwps
usage 39
system 2.15G max deny -
project.cpu-shares
usage 1
privileged 1 - none -
zone.max-shm-memory
system 16.0EB max deny -
zone.max-shm-ids
system 16.8M max deny -
zone.max-sem-ids
system 16.8M max deny -
zone.max-msg-ids
system 16.8M max deny -
zone.max-lwps
system 2.15G max deny -
zone.cpu-shares
privileged 1 - none -
zone.max-locked-memory
usage 0B
privileged 508MB - deny -
Example 2 Displaying, Replacing, and Verifying the Value of a Specific Control
The following examples displays, replaces, and verifies the value of a specific control on an existing project:
example# prctl -n project.cpu-shares -i project group.staff
project: 10: group.staff
NAME PRIVILEGE VALUE FLAG ACTION RECIPIENT
project.cpu-shares
usage 1
privileged 1 - none -
system 65.5K max none -
example# prctl -n project.cpu-shares -v 10 -r -i project group.staff
example# prctl -n project.cpu-shares -i project group.staff
project: 10: group.staff
NAME PRIVILEGE VALUE FLAG ACTION RECIPIENT
project.cpu-shares
usage 10
privileged 10 - none -
system 65.5K max none -
Example 3 Adjusting Resources
The following example uses the project.max-locked-memory resource.
First, use id –p to find out which project the current shell is a member of:
/home/garfield> id -p
uid=77880(garfield) gid=10(staff) projid=10(group.staff)
Using the target project, identify the resource limit value before the change:
/home/garfield> prctl -n project.max-locked-memory -i project \
group.staff
project 10: group.staff
project.max-locked-memory
privileged 256MB - deny -
system 16.0EB max deny -
current limit is 256 Megabytes.
Next, adjust the project.max-locked-memory limit to 300 Megabytes for the target project:
# prctl -n project.max-locked-memory -v 300M -r -i project group.staff
The resource limit value after the change shows a new value of 300 Megabytes:
# prctl -n project.max-locked-memory -i project group.staff
project 10:group.staff
project.max-locked-memory
usage 200MG
privileged 300MB - deny -
system 16.0EB max deny -
Example 4 Modifying CPU Caps for a Project
The prctl command can use the project.cpu-cap resource control (see resource-controls(7)) to set and modify CPU caps for a project. (The same resource control can be used in the /etc/project file. See project(5)) The following command modifies the CPU cap to limit user.smith to three CPUs:
# prctl -r -t privileged -n project.cpu-cap -v 300 -i project user.smith
The prctl –r option, used above, is used to dynamically change a CPU cap for a project or zone. For example, the following command will change the cap set in the preceding command to 80 percent:
# prctl -r -t privileged -n project.cpu-cap -v 80 -i project user.smith
To remove a CPU cap, enter:
# prctl -x -n project.cpu-cap $$Example 5 Modifying CPU Caps for a Zone
The prctl command can use the zone.cpu-cap resource control (see resource-controls(7)) to set and modify CPU caps for a zone. (The same resource control can be manipulated using the zonecfg(8) command.) The following command modifies the CPU cap to limit the global zone to 80 percent of a CPU:
# prctl -t privileged -n zone.cpu-cap -v 80 -i zone global
The cap can be lowered to 50% using:
# prctl -r -t privileged -n zone.cpu-cap -v 50 -i zone global
The following exit values are returned:
Success.
Fatal error encountered.
Invalid command line options were specified.
Process information and control files
See attributes(7) for descriptions of the following attributes:
|
The command-line syntax is Committed. The human-readable output is Uncommitted. The parseable output is Committed.
setrctl(2), rctlblk_get_local_action(3C), project(5), attributes(7), resource-controls(7), rctladm(8), zonecfg(8)