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


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

     getrlimit(2),   errno(3C),   rctlblk_set_value(3C),   attri-
     butes(5)


Man(1) output converted with man2html