rctlblk_get_enforced_value(3C)




NAME

     rctlblk_set_value,                  rctlblk_get_firing_time,
     rctlblk_get_global_action,         rctlblk_get_global_flags,
     rctlblk_get_local_action,           rctlblk_get_local_flags,
     rctlblk_get_privilege,            rctlblk_get_recipient_pid,
     rctlblk_get_value,               rctlblk_get_enforced_value,
     rctlblk_set_local_action,           rctlblk_set_local_flags,
     rctlblk_set_privilege, rctlblk_size  -  manipulate  resource
     control blocks


SYNOPSIS

     #include <rctl.h>

     hrtime_t  rctlblk_get_firing_time(rctlblk_t *rblk);

     int rctlblk_get_global_action(rctlblk_t *rblk);

     int rctlblk_get_global_flags(rctlblk_t *rblk);

     int rctlblk_get_local_action(rctlblk_t *rblk, int *signalp);

     int rctlblk_get_local_flags(rctlblk_t *rblk);

     rctl_priv_t  rctlblk_get_privilege(rctlblk_t *rblk);

     id_t rctlblk_get_recipient_pid(rctlblk_t *rblk);

     rctl_qty_t  rctlblk_get_value(rctlblk_t *rblk);

     rctl_qty_t  rctlblk_get_enforced_value(rctlblk_t *rblk);

     void rctlblk_set_local_action(rctlblk_t *rblk, rctl_action_t
     action, int signal);

     void rctlblk_set_local_flags(rctlblk_t *rblk, int flags);

     void  rctlblk_set_privilege(rctlblk_t   *rblk,   rctl_priv_t
     privilege);

     void rctlblk_set_value(rctlblk_t *rblk, rctl_qty_t value);

     size_t rctlblk_size(void);


DESCRIPTION

     The resource control block routines allow the  establishment
     or retrieval of values from a resource control block used to
     transfer information using  the  getrctl(2)  and  setrctl(2)
     functions.  Each  of  the  routines  accesses  or  sets  the
     resource control block member  corresponding  to  its  name.
     Certain  of  these  members are read-only and do not possess
     set routines.

     The firing time of a resource control  block  is  0  if  the
     resource  control action-value has not been exceeded for its
     lifetime on the process.  Otherwise the firing time  is  the
     value  of  gethrtime(3C)  at  the  moment  the action on the
     resource control value was taken.

     The global actions and flags are the action and flags set by
     rctladm(1M).  These  values  cannot  be  set with setrctl().
     Valid global actions are listed in the table  below.  Global
     flags  are generally a published property of the control and
     are not modifiable.

     RCTL_GLOBAL_DENY_ALWAYS
           The action taken when a control value is  exceeded  on
           this   control  will  always  include  denial  of  the
           resource.

     RCTL_GLOBAL_DENY_NEVER
           The action taken when a control value is  exceeded  on
           this   control  will  always  exclude  denial  of  the
           resource;  the  resource  will  always   be   granted,
           although other actions can also be taken.

     RCTL_GLOBAL_CPU_TIME
           The valid signals available as local  actions  include
           the SIGXCPU signal.

     RCTL_GLOBAL_FILE_SIZE
           The valid signals available as local  actions  include
           the SIGXFSZ signal.

     RCTL_GLOBAL_INFINITE
           This resource  control  supports  the  concept  of  an
           unlimited  value; generally true only of accumulation-
           oriented resources, such as CPU time.

     RCTL_GLOBAL_LOWERABLE
           Non-privileged callers are able to lower the value  of
           privileged resource control values on this control.

     RCTL_GLOBAL_NOACTION
           No global action will be taken when a resource control
           value is exceeded on this control.

     RCTL_GLOBAL_NOBASIC
           No values with the RCPRIV_BASIC privilege are  permit-
           ted on this control.

     RCTL_GLOBAL_NOLOCALACTION
           No local actions are permitted on this control.

     RCTL_GLOBAL_SYSLOG
           A standard message will  be  logged  by  the  syslog()
           facility when any resource control value on a sequence
           associated with this control is exceeded.

     RCTL_GLOBAL_UNOBSERVABLE
           The  resource  control  (generally  on  a   task-   or
           project-related  control)  does  not  support observa-
           tional control values. AnRCPRIV_BASIC privileged  con-
           trol  value placed by a process on the task or process
           will generate an action only if the value is  exceeded
           by that process.

     The local action and flags are those on the current resource
     control  value  represented  by this resource control block.
     Valid actions and flags are listed in the  table  below.  In
     the  case  of  RCTL_LOCAL_SIGNAL,  the  second  argument  to
     rctlblk_set_local_action() contains the signal to  be  sent.
     Similarly,  the signal to be sent is copied into the integer
     location   specified   by    the    second    argument    to
     rctlblk_get_local_action().  A  restricted set of signals is
     made available for normal use by the resource control facil-
     ity:  SIGBART,  SIGXRES,  SIGHUP, SIGSTOP, SIGTERM, and SIG-
     KILL. Other signals are permitted due to  global  properites
     of  a specific control. Calls to setrctl() with illegal sig-
     nals will fail.

     RCTL_LOCAL_DENY
           When this resource control value is  encountered,  the
           request  for  the  resource will be denied. Set on all
           values if RCTL_GLOBAL_DENY_ALWAYS is set for this con-
           trol;  cleared on all values if RCTL_GLOBAL_DENY_NEVER
           is set for this control.

     RCTL_LOCAL_MAXIMAL
           This resource control value represents a  request  for
           the  maximum  amount  of resource for this control. If
           RCTL_GLOBAL_INFINITE is set for this resource control,
           RCTL_LOCAL_MAXIMAL  indicates  an  unlimited  resource
           control value, one that will never be exceeded.

     RCTL_LOCAL_NOACTION
           No local action will be taken when this resource  con-
           trol value is exceeded.

     RCTL_LOCAL_SIGNAL
           The       specified       dignal,       sent        by
           rctlblk_set_local_action(),  will  be sent to the pro-
           cess that placed this resource control  value  in  the
           value sequence.

     The rctlblk_get_recipient_pid() function returns  the  value
     of  the  process  ID that placed the resource control value.
     This ID is set by the kernel by a caller invoking setrctl().

     The rctlblk_get_privilege() function returns  the  privilege
     of   the   resource  contorl  block.  Valid  privileges  are
     RCPRIV_BASIC, RCPRIV_PRIVILEGED, and  RCPRIV_SYSTEM.  System
     resource  controls  are  read-only. Privileged resource con-
     trols require  superuser  privilege  to  write,  unless  the
     RCTL_GLOBAL_LOWERABLE  global  flag  is  set,  in which case
     unprivileged  applications  can  lower  the   value   of   a
     privileged control.

     The rctlblk_get_value()  and  rctlblk_set_value()  functions
     return  or  establish the enforced value associated with the
     resource control. In cases where the process, task, or  pro-
     ject  associated  with the control possesess fewer capabili-
     ties than allowable by the current value, the value returned
     by   rctlblk_get_enforced_value()   will  differ  from  that
     returned by rctlblk_get_value(). This capability  difference
     arises  with  processes using an address space model smaller
     than the maximum address space model supported by  the  sys-
     tem.

     The rctlblk_size() function returns the size of  a  resource
     control  block for use in memory allocation. The rctlblk_t *
     type is an opaque pointer whose size is not  connected  with
     that   of   the   resource  control  block  itself.  Use  of
     rctlblk_size() is illustrated in the example below.


RETURN VALUES

     The various set routines have no return values.  Incorrectly
     composed  resource  control blocks will generate errors when
     used with setrctl(2) or getrctl(2).


ERRORS

     No  error  values  are  returned.  Incorrectly   constructed
     resource  control  blocks  will  be  rejected  by the system
     calls.


EXAMPLES

     Example 1: Display the contents of a fetched  resource  con-
     trol block.

     The following example displays the  contents  of  a  fetched
     resource control block.

     #include <rctl.h>
     #include <stdio.h>
     #include <stdlib.h>

     rctlblk_t *rblk;
     int rsignal;
     int raction;
     if ((rblk = malloc(rctlblk_size())) == NULL) {
            (void) perror("rblk malloc");
            exit(1);
     }

     if (getrctl("process.max-cpu-time", NULL, rblk, RCTL_FIRST) == -1) {
            (void) perror("getrctl");
            exit(1);
     }
     raction = rctlblk_get_local_action(rblk, &rsignal),
     (void) printf("Resource control for %s\n",
         "process.max-cpu-time");
     (void) printf("Process ID:     %d\n",
         rctlblk_get_recipient_pid(rblk));
     (void) printf("Privilege:      %x\n"
         rctlblk_get_privilege(rblk),
     (void) printf("Global flags:   %x\n"
         rctlblk_get_global_flags(rblk),
     (void) printf("Global actions: %x\n"
         rctlblk_get_global_action(rblk),
     (void) printf("Local flags:    %x\n"
         rctlblk_get_local_flags(rblk),
     (void) printf("Local action:   %x (%d)\n"
         raction, raction == RCTL_LOCAL_SIGNAL ? rsignal : 0);
     (void) printf("Value:          %llu\n",
         rctlblk_get_value(rblk));
     (void) printf("Enforced value: %llu\n",
         rctlblk_get_enforced_value(rblk));


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Evolving                    |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|


SEE ALSO

     rctladm(1M), getrctl(2), setrctl(2),  gethrtime(3C),  attri-
     butes(5)


Man(1) output converted with man2html