prctl man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

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

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.

OPTIONS
       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 dis‐
			    abled if the resource control has the deny	global
			    flag.

	   signal
			    This  action is only available with -d. It deacti‐
			    vates 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	 addi‐
			    tional 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 enti‐
	   ties 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 space 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  "lower‐
	   able" 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	 rctl‐
	   blk_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 sys‐
	   tem, 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.

	   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 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 -s, -r, -x, -v, -d, or -e	 options  are  specified,  the
       invocation is considered a get operation. Otherwise, it is considered a
       modify operation.

OPERANDS
       The following operand is supported:

       id
	     The ID of the entity (process, task, project, or zone) to	inter‐
	     rogate.  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 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
		 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 mem‐
       ber 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(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

       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(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 files

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

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │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.

				 Oct 30, 2013			      PRCTL(1)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net