User Commands prctl(1)
NAME
prctl - get or set the resource controls of running
processes, tasks, and projectsSYNOPSIS
prctl [-P] [-t [basic | privileged | system]]
[-n name [-srx] [-v value] [-e | -d action] [-p pid]]
[-i idtype] id...
DESCRIPTION
The prctl utility allows the examination and modification of
the resource controls associated with an active process, task, or project on the system. It allows access to the basic and privileged limits and the current usage on the specified entity.See resource_controls(5) for a description of the resource
controls supported in the current release of the Solaris operating system. OPTIONSIf none of the -s, -r, -x, -v, -d, or -e options are speci-
fied, the invocation is considered a get operation. Other-
wise, it is considered a modify operation. The following options are supported:-d | -e action
Disables (-d) or enables (-e) the specified action on
the resource control value specified by -v, -t, and -p.
If any of the -v, -t, or -p options are unspecified,
they match any value, privilege, or recipient pid. Forexample, specifying only -v modifies the first resource
control with matching value, matching any privilege and recipient pid. If no matching resource control value isfound, a new value is added as if -s were specified.
Actions:all This action is only available with -d.
It disables all actions. This fails on resource control values that have the deny global flag. deny Indicates that the resource control attempts to deny granting the resource to the process, task, project, or zoneSunOS 5.11 Last change: 25 Aug 2009 1
User Commands prctl(1)
on a request for resources in excess of the resource control value. deny actions can not be enabled if theresource control has the no-deny global
flag. deny actions can not be disabled if the resource control has the deny global flag.signal This action is only available with -d.
It deactivates the signal action. signal=signum In the signal=signum action, signum isa signal number (or string representa-
tion of a signal). Setting a signal action on a resource control with theno-local-action global flag fails. A
limited set of signals can be sent. See NOTES for additional details.-i idtype
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.
For a modify operation, the entity to which id operands are members is the target entity. For instance, settinga project resource control on an -i process sets the
resource control on the project to which each given pro-
cess argument is a member. For a get operation, the resource controls are listed for all entities to which the id operands are members.For example, -i task taskid lists the task, project, and
zone resource controls for the task, and for the project and zone to which that task is a member.-n name
Specifies the name of the resource control to get or set. If the name is unspecified, all resource controls are retrieved.-p pid
SunOS 5.11 Last change: 25 Aug 2009 2
User Commands prctl(1)
When manipulating (using -s, -r, -x, -d, or -e) a basic
task project, or zone resource control values, a reci-
pient pid can be specified using -p. When setting a new
basic resource control or controls on a task, project,or zone, the -p option is required if the -i idtype
option argument is not process.-P
Display resource control values in space delimited for-
mat.-r
Replaces the first resource control value (matching withthe -t privilege) with the new value specified through
the -v option.
-s
Set a new resource control value.This option requires the -v option.
If you do not specify the -t option, basic privilege is
used. If you want to set a basic task, process, or zonerctl, -p is required. If -e or -d are also specified,
the action on the new rctl is set as well. For compatibility with prior releases, this option isimplied if -v is specified, without any of -e, -d, -r,
or -x.
See resource_controls(5) for a description of unit
modifiers and scaling factors you can use to express large values when setting a resource control value.-t [ basic | privileged | system ]
Specifies which resource control type to set. Unless the "lowerable" flag is set for a resource control, only invocations by users (or setuid programs) who have privileges equivalent to those of root can modifyprivileged resource controls. See rctlblk_set_value(3C)
for a description of the RCTL_GLOBAL_LOWERABLE flag. If
the type is not specified, basic is assumed. For a get operation, the values of all resource control types, including system, are displayed if no type is specified.SunOS 5.11 Last change: 25 Aug 2009 3
User Commands prctl(1)
-v value
Specifies the value for the resource control for a setoperation. If no value is specified, then the modifica-
tion (deletion, action enabling or disabling) is carriedout on the lowest-valued resource control with the given
type.See resource_controls(5) for a description of unit
modifiers and scaling factors you can use to express large values when setting a resource control value.-x
Deletes the specified resource control value. If the delete option is not provided, the default operation ofprctl is to modify a resource control value of matching
value and privilege, or insert a new value with the given privilege. The matching criteria are discussed more fully in setrctl(2).If none of the -d, -e, -v, or -x options is specified, the
invocation is considered a get operation. OPERANDS The following operand is supported: id The ID of the entity (process, task, project, or zone) to interrogate. If the invoking user's credentials are unprivileged and the entity being interrogated possesses different credentials, the operation fails. If no id is specified, an error message is returned.EXAMPLES
Example 1 Displaying Current Resource Control SettingsThe following example displays current resource control set-
tings for a task to which the current shell belongs:example$ ps -o taskid -p $$
TASKID 8example$ prctl -i task 8
136150: /bin/kshNAME PRIVILEGE VALUE FLAG ACTION RECIPIENT
task.max-cpu-time
SunOS 5.11 Last change: 25 Aug 2009 4
User Commands prctl(1)
usage 8ssystem 18.4Es inf none -
task.max-lwps
usage 39system 2.15G max deny -
project.max-contracts
privileged 10.0K - deny -
project.max-locked-memory
usage 0Bprivileged 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 0Bprivileged 508MB - deny -
project.max-tasks
usage 2system 2.15G max deny -
project.max-lwps
usage 39system 2.15G max deny -
project.cpu-shares
usage 1privileged 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 0Bprivileged 508MB - deny -
Example 2 Displaying, Replacing, and Verifying the Value of a Specific ControlSunOS 5.11 Last change: 25 Aug 2009 5
User Commands prctl(1)
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.staffNAME PRIVILEGE VALUE FLAG ACTION RECIPIENT
project.cpu-shares
usage 1privileged 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.staffNAME PRIVILEGE VALUE FLAG ACTION RECIPIENT
project.cpu-shares
usage 10privileged 10 - none -
system 65.5K max none -
Example 3 Adjusting ResourcesThe 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.staffproject.max-locked-memory
privileged 256MB - deny -
system 16.0EB max deny -
SunOS 5.11 Last change: 25 Aug 2009 6
User Commands prctl(1)
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.staffproject.max-locked-memory
usage 200MGprivileged 300MB - deny -
system 16.0EB max deny -
Example 4 Modifying CPU Caps for a ProjectThe prctl command can use the project.cpu-cap resource con-
trol (see resource_controls(5)) to set and modify CPU caps
for a project. (The same resource control can be used in the /etc/project file. See project(4)) 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
SunOS 5.11 Last change: 25 Aug 2009 7
User Commands prctl(1)
To remove a CPU cap, enter:# prctl -x -n project.cpu-cap $$
Example 5 Modifying CPU Caps for a ZoneThe prctl command can use the zone.cpu-cap resource control
(see resource_controls(5)) to set and modify CPU caps for a
zone. (The same resource control can be manipulated using the zonecfg(1M) 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
EXIT STATUS The following exit values are returned: 0 Success. 1 Fatal error encountered. 2 Invalid command line options were specified. FILES /proc/pid/* Process information and control filesATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 25 Aug 2009 8
User Commands prctl(1)
________________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_________________________________|
| Availability | system/extended-system-utilities|
|_____________________________|_________________________________|
| Interface Stability | See below. ||_____________________________|_________________________________|
The command-line syntax is Committed. The human-readable
output is Uncommitted. The parseable output is Committed.SEE ALSO
rctladm(1M), zonecfg(1M), setrctl(2),rctlblk_get_local_action(3C), project(4), attributes(5),
resource_controls(5)
NOTES The valid signals that can be set on a resource control block allowing local actions 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.SunOS 5.11 Last change: 25 Aug 2009 9