Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
setrctl(2)							    setrctl(2)

       setrctl,	getrctl	- set or get resource control values

       #include	<rctl.h>

       int  setrctl(const  char	 *controlname,	rctlblk_t  *old_blk, rctlblk_t
       *new_blk, uint_t	flags);

       int getrctl(const  char	*controlname,  rctlblk_t  *old_blk,  rctlblk_t
       *new_blk, uint_t	flags);

       The  setrctl() and getrctl() functions provide interfaces for the modi-
       fication	and retrieval of resource control (rctl) values	on active  en-
       tities  on  the system, such as processes, tasks, or projects.  All re-
       source controls are unsigned 64-bit integers; however, a	collection  of
       flags  are  defined  that  modify  which	rctl value is to be set	or re-

       Resource	controls are restricted	to three levels: basic	controls  that
       can  be	modified  by the owner of the calling process, privileged con-
       trols that can be modified only by privileged callers, and system  con-
       trols that are fixed for	the duration of	the operating system instance.
       Setting or retrieving each of these controls is	performed  by  setting
       the  privilege  field  of  the  resource	 control  block	to RCTL_BASIC,
       RCTL_PRIVILEGED,	or RCTL_SYSTEM with rctlblk_set_privilege() (see rctl-

       For  limits  on	collective  entities  such as the task or project, the
       process ID of the calling process is associated with the	resource  con-
       trol  value.  This ID is	available by using rctlblk_get_recipient_pid()
       (see rctlblk_set_value(3C)). These values  are  visible	only  to  that
       process and privileged processes	within the collective.

       The  getrctl()  function	provides a mechanism for iterating through all
       of the established values on a  resource	 control.   The	 iteration  is
       primed  by calling getrctl() with old_blk set to	NULL, a	valid resource
       control block pointer in	new_blk,  and  specifying  RCTL_FIRST  in  the
       flags  argument.	  Once a resource control block	has been obtained, re-
       peated calls to getrctl() with RCTL_NEXT	in the flags argument and  the
       obtained	 control in the	old_blk	argument will return the next resource
       control block in	the sequence.  The iteration reports the  end  of  the
       sequence	by failing and setting errno to	ENOENT.

       The  getrctl()  function	 allows	the calling process to get the current
       usage of	a controlled resource using RCTL_USAGE as the flags value. The
       current value of	the resource usage is placed in	the value field	of the
       resource	control	block specified	by new_blk.  This  value  is  obtained
       with rctlblk_set_value(3C). All other members of	the returned block are
       undefined and might be invalid.

       The setrctl() function allows the creation, modification,  or  deletion
       of  action-value	 pairs	on  a  given  resource	control.   When	passed
       RCTL_INSERT as the flags	value, setrctl() expects new_blk to contain  a
       new action-value	pair for insertion into	the sequence. For RCTL_DELETE,
       the block indicated by  new_blk	is  deleted  from  the	sequence.  For
       RCTL_REPLACE, the block matching	old_blk	is deleted and replaced	by the
       block indicated by new_blk. When	(flags	&  RCTL_USE_RECIPIENT_PID)  is
       non-zero,  setrctl()  uses  the	process	 ID set	by rctlblk_set_recipi-
       ent_pid(3C) when	selecting the rctl value to insert, delete, or replace
       basic rctls. Otherwise, the process ID of the calling process is	used.

       The  kernel  maintains  a history of which resource control values have
       triggered for a particular entity, retrievable from a resource  control
       block  with  the	rctlblk_get_firing_time(3C) function. The insertion or
       deletion	of a resource control value at or below	the currently enforced
       value  might  cause  the	 currently enforced value to be	reset.	In the
       case of insertion, the newly inserted value becomes  the	 actively  en-
       forced  value.	All  higher values that	have previously	triggered will
       have their firing times zeroed.	In the case of deletion	 of  the  cur-
       rently  enforced	 value,	the next higher	value becomes the actively en-
       forced value.

       The various resource control block  properties  are  described  on  the
       rctlblk_set_value(3C) manual page.

       Resource	 controls  are inherited from the predecessor process or task.
       One of the exec(2) functions can	modify	the  resource  controls	 of  a
       process	by  resetting their histories, as noted	above for insertion or
       deletion	operations.

       Upon successful completion, the setrctl() and getrctl()	functions  re-
       turn 0. Otherwise they return -1	and set	errno to indicate the error.

       The setrctl() and getrctl() functions will fail if:

       EFAULT	       The controlname,	old_blk, or new_blk argument points to
		       an illegal address.

       EINVAL	       No resource control with	the given name is known	to the
		       system,	or the resource	control	block contains proper-
		       ties that are not valid for the resource	control	speci-

		       RCTL_USE_RECIPIENT_PID  was used	to set a process scope
		       rctl and	the  process  ID  set  by  rctlblk_set_recipi-
		       ent_pid(3C)  does  not  match the process ID of calling

       ENOENT	       No value	beyond the given resource  control  block  ex-

		       RCTL_USE_RECIPIENT_PID  was used	and the	process	ID set
		       by rctlblk_set_recipient_pid(3C)	does not exist	within
		       the  current  task,  project, or	zone, depending	on the
		       resource	control	name.

       ESRCH	       No value	matching the given resource control block  was
		       found  for  any	of RCTL_NEXT, RCTL_DELETE, or RCTL_RE-

       ENOTSUPP	       The resource control requested by RCTL_USAGE  does  not
		       support the usage operation.

       The setrctl() function will fail	if:

       EACCES	       The  rctl value specified cannot	be changed by the cur-
		       rent process, including the case	 where	the  recipient
		       process	ID  does not match the calling process and the
		       calling process is unprivileged.

       EPERM	       An attempt to set a system limit	was attempted.

       Example 1: Retrieve a rctl value.

       Obtain the lowest enforced rctl value on	the rctl limiting  the	number
       of LWPs in a task.

       #include	<sys/types.h>
       #include	<rctl.h>
       #include	<stdio.h>

       uint64_t	value;
       int cur_signal;
       rctlblk_t *rblk;


       if ((rblk = (rctlblk_t *)malloc(rctlblk_size()))	== NULL) {
	       (void) fprintf(stderr, "malloc failed: %s\n",

       if (getrctl("task.max-lwps", NULL, rblk,	RCTL_FIRST) == -1)
	       (void) fprintf(stderr, "failed to get rctl: %s\n",
	       (void) printf("task.max-lwps = %llu",

       Resource	 control blocks	are matched on the value and privilege fields.
       Resource	control	operations act on the first matching resource  control
       block.  Duplicate  resource  control blocks are not permitted. Multiple
       blocks of equal value and privilege need	to  be	entirely  deleted  and
       reinserted, rather than replaced, to have the correct outcome. Resource
       control blocks are sorted such that all blocks with the same value that
       lack the	RCTL_LOCAL_DENY	flag precede those having that flag set.

       Only  one  RCPRIV_BASIC resource	control	value is permitted per process
       per control.  Insertion of an RCPRIV_BASIC value	will cause any	exist-
       ing  RCPRIV_BASIC  value	 owned	by  that  process on the control to be

       The resource control facility provides the backend  implementation  for
       both  setrctl()/getrctl() and setrlimit()/getrlimit(). The facility be-
       haves consistently when either of these interfaces is used exclusively;
       when  using  both  interfaces, the caller must be aware of the ordering
       issues above, as	well as	the limit equivalencies	described in the  fol-
       lowing paragraph.

       The  hard  and  soft process limits made	available with setrlimit() and
       getrlimit() are mapped to the resource controls	implementation.	  (New
       process	resource  controls  will not be	made available with the	rlimit
       interface.)  Because of the RCTL_INSERT and RCTL_DELETE operations,  it
       is  possible  that  the set of values defined on	a resource control has
       more or fewer than the two values defined for an	rlimit.	 In this case,
       the  soft  limit	is the lowest priority resource	control	value with the
       RCTL_LOCAL_DENY flag set, and the hard limit is	the  resource  control
       value  with the lowest priority equal to	or exceeding RCPRIV_PRIVILEGED
       with the	RCTL_LOCAL_DENY	flag set.  If no identifiable soft  limit  ex-
       ists  on	the resource control and setrlimit() is	called,	a new resource
       control value is	created.  If a resource	 control  does	not  have  the
       global  RCTL_GLOBAL_LOWERABLE property set, its hard limit will not al-
       low lowering by unprivileged callers.

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

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |MT-Level		     |Async-Signal-Safe		   |

       getrlimit(2), errno(3C),	rctlblk_set_value(3C), attributes(5)

				  10 Feb 2005			    setrctl(2)


Want to link to this manual page? Use this URL:

home | help