prctl(1)                                                                                                                                  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 [-srx] [-v value] [-e | -d action]  [-p  pid]] [-i idtype] id...

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

       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 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. For example,  specifying  only  -v  modifies  the  first
           resource  control  with matching value, matching any privilege and recipient pid. If no matching resource control value is found, 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 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 the signal action.

           signal=signum   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.

           For a modify operation, the entity to which id operands are members is the target entity. For instance, setting a project resource con-
           trol on an -i process sets the resource control on the project to which each given process 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

           When manipulating (using -s, -r, -x, -d, or -e) a basic task project, or zone resource control values, a recipient 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 semi-colon delimited format.

       -r

           Replaces the first resource control value (matching with the -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 zone rctl, -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 is implied 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 modify privileged 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.

       -v value

           Specifies  the  value  for  the resource control for a set operation. If no value is specified, then the modification (deletion, action
           enabling or disabling) is carried out on the lowest-valued resource control with the given type.

       -x

           Deletes the specified resource control value. If the delete option is not provided, the default operation  of  prctl  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 dis-
           cussed more fully in setrctl(2).

       If none of the -d, -e, -v, or -x options is specified, the invocation is considered a get operation.

       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.

       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
       8
       example$ prctl -i task 8
       136150: /bin/ksh
       NAME    PRIVILEGE       VALUE    FLAG   ACTION             RECIPIENT
       task.max-cpu-time
               system          18.4Es    inf   none                -
       task.max-lwps
               system          2.15G     max   deny                -
       project.max-contracts
               privileged      10.0K       -   deny                -
       project.max-device-locked-memory
               privileged       127MB      -   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
               privileged       508MB      -   deny                -
       project.max-tasks
               system          2.15G     max   deny                -
       project.max-lwps
               system          2.15G     max   deny                -
       project.cpu-shares
               privileged          1       -   none                -
       zone.max-lwps
               system          2.15G     max   deny                -
       zone.cpu-shares
               privileged          1       -   none                -

       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
               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
               privileged         10       -   none                         -
               system          65.5K     max   none                         -

       Example 3: Adjusting Resources

       This example uses the project.max-device-locked-memory resource.

       First, use id -p to find out the project id:

       /home/garfield> id -p
               uid=77880(garfield) gid=10(staff) projid=10(group.staff)

       Identify the resource limit value before the change. Find a process id of the processes in that project id:

       /home/garfield> ps -eaf
               UID   PID  PPID   C    STIME TTY         TIME CMD
               .....
               garfield   530   528   0 11:24:18 pts/1       0:00 -ksh

               /home/garfield> prctl 530
               530:    -ksh
               project.max-device-locked-memory         [ no-basic deny ]
                                   261969408 privileged deny
                       18446744073709551615 system     deny           [ max ]
       ....
       current limit is 261969408 bytes.

       Next, adjust the project.max-device-locked-memory limit to 300000000 for project id 10:

       # prctl -n project.max-device-locked-memory -v 300000000 -r -i project 10

       The resource limit value after the change shows a new value of 300000000 bytes:

       /home/garfield> prctl 530
               530:    -ksh
               project.max-device-locked-memory         [ no-basic deny ]
                               3   00000000 privileged deny
                       18446744073709551615 system     deny           [ max ]

       The following exit values are returned:

       0        Success.

       1        Fatal error encountered.

       2        Invalid command line options were specified.

       /proc/pid/*     Process information and control files

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE         |      ATTRIBUTE VALUE        |
       +-----------------------------+-----------------------------+
       |Availability                 |SUNWesu                      |
       +-----------------------------+-----------------------------+
       |Interface Stability          |See below.                   |
       +-----------------------------+-----------------------------+

       The command-line syntax is Evolving. The human-readable output is Unstable. The parseable output is Evolving.

       rctladm(1M), setrctl(2), rctlblk_get_local_action(3C), attributes(5), resource_controls(5)

       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.

                                                                    18 Aug 2005                                                           prctl(1)