Manual Pages for UNIX Operating System command usage for man setrctl

System Calls                                           setrctl(2)



NAME
     setrctl, getrctl - set or get resource control values

SYNOPSIS
     #include 

     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  modification  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 con-
     trols  that can be modified by the owner of the calling pro-
     cess, privileged controls  that  can  be  modified  only  by
     privileged  callers,  and system controls 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 rctlblk_set_value(3C)).


     For limits on collective entities such as the task  or  pro-
     ject,  the  process  ID of the calling process is associated
     with the resource control 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



SunOS 5.11          Last change: 31 Jan 2007                    1






System Calls                                           setrctl(2)



     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 pro-
     cess 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 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 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  return  0. Otherwise they return -1 and set errno
     to indicate the error.



SunOS 5.11          Last change: 31 Jan 2007                    2






System Calls                                           setrctl(2)



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





SunOS 5.11          Last change: 31 Jan 2007                    3






System Calls                                           setrctl(2)



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


       #include 
       #include 
       #include 
       #include 
       #include 

       ...

       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  rein-
     serted,  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 existing RCPRIV_BASIC  value  owned  by  that
     process on the control to be deleted.


     The resource control facility provides the backend implemen-
     tation       for      both      setrctl()/getrctl()      and
     setrlimit()/getrlimit(). The facility  behaves  consistently
     when  either  of  these interfaces is used exclusively; when
     using both interfaces, the caller must be aware of the  ord-
     ering  issues  above,  as  well  as  the limit equivalencies



SunOS 5.11          Last change: 31 Jan 2007                    4






System Calls                                           setrctl(2)



     described in the following paragraph.


     The  hard  and  soft  process  limits  made  available  with
     setrlimit()  and getrlimit() are mapped to the resource con-
     trols 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  possi-
     ble 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 con-
     trol 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  attri-
     butes:



     ____________________________________________________________
    |       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          Last change: 31 Jan 2007                    5