Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

prctl(1)

Name

prctl - get or set the resource controls of running processes, tasks, and projects

Synopsis

prctl [-P] [-t basic|privileged|system] [-n name] [-o|-s|-r|-x]
     [-v value] [-e|-d action] [-p pid] [-i idtype] id...

Description

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:

    1. Specifying the –s option.

    2. 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.

    3. 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.

Options

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:

–d | –e action

Disables (–d) or enables (–e) the specified action on the rctl value.

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 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.

signal

This action is only available with –d. It deactivates any signal action.

signal=signum

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.

–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.

–n name

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.

–p pid

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.

–P

Displays resource control values in space delimited format. Allowed only for the get operation.

–r

Invokes the replacement operation.

–s

Invokes the insert operation.

–t basic|privileged|system

Specifies which resource control type to get or modify. The value priv is allowed instead of privileged.

–v value

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.

–x

Invokes the delete operation.

Operands

The following operand is supported:

id

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.

Examples

Example 1 Displaying Current Resource Control Settings

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

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 files

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/core-os
Interface Stability
See below.

The command-line syntax is Committed. The human-readable output is Uncommitted. The parseable output is Committed.

See Also

setrctl(2), rctlblk_get_local_action(3C), project(5), attributes(7), resource-controls(7), rctladm(8), zonecfg(8)