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

FreeBSD Manual Pages

  
 
  

home | help
setrctl(2)			 System	Calls			    setrctl(2)

NAME
       setrctl,	getrctl	- set or get resource control values

SYNOPSIS
       #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);

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

       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-
       blk_set_value(3C)).

       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()	(see 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 flag 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.

       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()   function	  (see	 rctl-
       blk_set_value(3C)).   The  insertion  or	deletion of a resource control
       value at	or below the currently enforced	value  might  cause  the  cur-
       rently enforced value to	be reset.  In the case of insertion, the newly
       inserted	value becomes the actively enforced value.  All	higher	values
       that have previously triggered will have	their firing times zeroed.  In
       the case	of deletion of the currently enforced value, the  next	higher
       value becomes the actively enforced 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.

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

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

       EFAULT
	     The controlname, old_blk, or new_blk argument points to an	 ille-
	     gal address.

       EINVAL
	     No	rctl with the given name is known to the system.

       ENOENT
	     No	value beyond the given resource	control	block exists.

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

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

       The setrctl() function will fail	if:

       EACCESS
	     The  rctl	value  specified  cannot  be  changed  by  the current
	     process.

       EPERM An	attempt	to set a system	limit was attempted.

EXAMPLES
       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 = malloc(rctlblk_size())) == NULL) {
	       (void) fprintf(stderr, "malloc failed: %s\n",
		   strerror(errno);
	       exit(1);
       }

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

USAGE
       Resource	 control blocks	are matched on the value and privilege fields.
       Resource	control	operations act on the first matching resource  control
       block. Multiple blocks of equal value and privilege will	likely 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
       deleted.

       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.

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

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

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

SunOS 5.9			  24 Sep 2001			    setrctl(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | USAGE | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=setrctl&sektion=2&manpath=SunOS+5.9>

home | help