1 CT_DEV_TMPL_SET_ASET(3CONTRACT)          Contract Management Library Functions
   2 
   3 
   4 
   5 NAME
   6        ct_dev_tmpl_set_aset, ct_dev_tmpl_get_aset, ct_dev_tmpl_set_minor,
   7        ct_dev_tmpl_get_minor, ct_dev_tmpl_set_noneg, ct_dev_tmpl_clear_noneg,
   8        ct_dev_tmpl_get_noneg - device contract template functions
   9 
  10 SYNOPSIS
  11        cc [ flag... ] file... -D_LARGEFILE64_SOURCE  -lcontract  [ library... ]
  12        #include <libcontract.h>
  13        #include <sys/contract/device.h>
  14 
  15        int ct_dev_tmpl_set_aset(int fd, uint_t aset);
  16 
  17 
  18        int ct_dev_tmpl_get_aset(int fd, uint_t *asetp);
  19 
  20 
  21        int ct_dev_tmpl_set_minor(int fd, char *minor);
  22 
  23 
  24        int ct_dev_tmpl_get_minor(int fd, char *buf, size_t *buflenp);
  25 
  26 
  27        int ct_dev_tmpl_set_noneg(int fd);
  28 
  29 
  30        int ct_dev_tmpl_clear_noneg(int fd);
  31 
  32 
  33        int ct_dev_tmpl_get_noneg(int fd, uint_t *nonegp);
  34 
  35 
  36 PARAMETERS
  37        aset
  38                   a bitset of one or more of device states
  39 
  40 
  41        asetp
  42                   a pointer to a variable into which the current A-set is to
  43                   be returned
  44 
  45 
  46        buf
  47                   a buffer into which the minor path is to be returned
  48 
  49 
  50        buflenp
  51                   a pointer to variable of type size_t in which the size of
  52                   the buffer buf is passed in. If the buffer is too small the
  53                   size of the buffer needed for a successful call is passed
  54                   back to the caller.
  55 
  56 
  57        fd
  58                   a file descriptor from an open of the device contract
  59                   template file in the contract filesystem (ctfs)
  60 
  61 
  62        minor
  63                   the devfs path (the /devices path without the "/devices"
  64                   prefix) of a minor which is to be the subject of a contract
  65 
  66 
  67        nonegp
  68                   a pointer to a uint_t variable for receiving the current
  69                   setting of the "nonnegotiable" term in the template
  70 
  71 
  72 DESCRIPTION
  73        These functions read and write device contract terms and operate on
  74        device contract template file descriptors obtained from the contract(4)
  75        filesystem (ctfs).
  76 
  77 
  78        The ct_dev_tmpl_set_aset() and ct_dev_tmpl_get_aset() functions write
  79        and read the "acceptable states" set (or A-set for short).  This is the
  80        set of device states guaranteed by the contract. Any departure from
  81        these states will result in the breaking of the contract and a delivery
  82        of a critical contract event to the contract holder. The A-set value is
  83        a bitset of one or more of the following device states:
  84        CT_DEV_EV_ONLINE, CT_DEV_EV_DEGRADED, and CT_DEV_EV_OFFLINE.
  85 
  86 
  87        The ct_dev_tmpl_set_minor() and ct_dev_tmpl_get_minor() functions write
  88        and read the minor term (the device resource that is to be the subject
  89        of the contract.) The value is a devfs path to a device minor node
  90        (minus the "/devices" prefix). For the ct_dev_tmpl_get_minor()
  91        function, a buffer at least PATH_MAX in size must be passed in. If the
  92        buffer is smaller than PATH_MAX, then the minimum size of the buffer
  93        required (PATH_MAX) for this function is passed back to the caller via
  94        the buflenp argument.
  95 
  96 
  97        The ct_dev_tmpl_set_noneg() and ct_dev_tmpl_get_noneg() functions write
  98        and read the nonnegotiable term. If this term is set, synchronous
  99        negotiation events are automatically NACKed on behalf of the contract
 100        holder.  For ct_dev_tmpl_get_noneg(), the variable pointed to by nonegp
 101        is set to 1 if the "noneg" term is set or to 0 otherwise.  The
 102        ct_dev_tmpl_clear_noneg() term clears the nonnegotiable term from a
 103        template.
 104 
 105 RETURN VALUES
 106        Upon successful completion, these functions return 0. Otherwise, they
 107        return a non-zero error value.
 108 
 109 ERRORS
 110        The ct_dev_tmpl_set_aset() function will fail if:
 111 
 112        EINVAL
 113                  A template file descriptor or A-set is invalid
 114 
 115 
 116 
 117        The ct_dev_tmpl_set_minor() function will fail if:
 118 
 119        EINVAL
 120                  One or more arguments is invalid.
 121 
 122 
 123        ENXIO
 124                  The minor named by minor path does not exist.
 125 
 126 
 127 
 128        The ct_dev_tmpl_set_noneg() function will fail if:
 129 
 130        EPERM
 131                 A process lacks sufficient privilege to NACK a device state
 132                 change.
 133 
 134 
 135 
 136        The ct_dev_tmpl_get_aset() and ct_dev_tmpl_get_minor() functions will
 137        fail if:
 138 
 139        EINVAL
 140                  One or more arguments is invalid.
 141 
 142 
 143        ENOENT
 144                  The requested term is not set.
 145 
 146 
 147 
 148        The ct_dev_tmpl_get_noneg() function will fail if:
 149 
 150        EINVAL
 151                  One or more arguments is invalid.
 152 
 153 
 154 
 155        The ct_dev_tmpl_get_minor() function will fail if:
 156 
 157        EOVERFLOW
 158                    The supplied buffer is too small.
 159 
 160 
 161 ATTRIBUTES
 162        See attributes(5) for descriptions of the following attributes:
 163 
 164 
 165 
 166 
 167        +--------------------+-----------------+
 168        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 169        +--------------------+-----------------+
 170        |Interface Stability | Committed       |
 171        +--------------------+-----------------+
 172        |MT-Level            | Safe            |
 173        +--------------------+-----------------+
 174 
 175 SEE ALSO
 176        libcontract(3LIB), contract(4), devices(4), attributes(5), lfcompile(5)
 177 
 178 
 179 
 180                                 August 9, 2007 CT_DEV_TMPL_SET_ASET(3CONTRACT)