getrctl man page on OpenIndiana

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

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
       entities	 on  the  system,  such as processes, tasks, or projects.  All
       resource controls are unsigned 64-bit integers; however,	 a  collection
       of  flags  are  defined	that  modify  which rctl value is to be set or
       retrieved.

       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,
       repeated 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_value(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_set_value(3C) function. The insertion or dele‐
       tion 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
       enforced	 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
       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
       return 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
		   illegal address.

       EINVAL	   No resource control with the given name  is	known  to  the
		   system,  or	the resource control block contains properties
		   that are not valid for the resource control specified.

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

       ENOENT	   No value beyond the given resource control block exists.

		   RCTL_USE_RECIPIENT_PID was used and the process ID  set  by
		   rctlblk_set_value(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_REPLACE.

       ENOTSUPP	   The resource control requested by RCTL_USAGE does not  sup‐
		   port the usage operation.

       The setrctl() function will fail if:

       EACCES	 The  rctl  value  specified  cannot be changed by the current
		 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.

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 <rctl.h>
	 #include <stdio.h>
	 #include <stdlib.h>
	 #include <string.h>
	 #include <errno.h>

	 ...

	 rctlblk_t *rblk;

	 if ((rblk = (rctlblk_t *)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\n",
		     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.  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
       deleted.

       The resource control facility provides the backend  implementation  for
       both  setrctl()/getrctl()  and  setrlimit()/getrlimit().	 The  facility
       behaves consistently when either of these  interfaces  is  used	exclu‐
       sively;	when  using  both  interfaces, the caller must be aware of the
       ordering issues above, as well as the limit equivalencies described  in
       the following 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
       exists  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
       allow 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
       rctladm(1M),    getrlimit(2),	 errno(3C),	rctlblk_set_value(3C),
       attributes(5), resource_controls(5)

SunOS 5.11			  31 Jan 2007			    setrctl(2)
[top]

List of man pages available for OpenIndiana

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