unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

setrctl(2)                       System Calls                       setrctl(2)



NAME
       setrctl, getrctl - set or get resource control values

SYNOPSIS
       #include <&lt;rctl.h>&gt;

       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_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
       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 proper-
                       ties that are not valid for the resource control speci-
                       fied.

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



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


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE MT-LevelAsync-Signal-Safe


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



SunOS 5.10                        24 Mar 2004                       setrctl(2)