1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH CT_DEV_TMPL_SET_ASET 3CONTRACT "Aug 9, 2007"
   7 .SH NAME
   8 ct_dev_tmpl_set_aset, ct_dev_tmpl_get_aset, ct_dev_tmpl_set_minor,
   9 ct_dev_tmpl_get_minor, ct_dev_tmpl_set_noneg, ct_dev_tmpl_clear_noneg,
  10 ct_dev_tmpl_get_noneg \- device contract template functions
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-D_LARGEFILE64_SOURCE\fR \fB -lcontract \fR [ \fIlibrary\fR\&.\|.\|. ]
  15 #include <libcontract.h>
  16 #include <sys/contract/device.h>
  17 
  18 int ct_dev_tmpl_set_aset(int fd, uint_t aset);
  19 .fi
  20 
  21 .LP
  22 .nf
  23 \fBint\fR \fBct_dev_tmpl_get_aset\fR(\fBint\fR \fIfd\fR, \fBuint_t *\fR\fIasetp\fR);
  24 .fi
  25 
  26 .LP
  27 .nf
  28 \fBint\fR \fBct_dev_tmpl_set_minor\fR(\fBint\fR \fIfd\fR, \fBchar *\fR\fIminor\fR);
  29 .fi
  30 
  31 .LP
  32 .nf
  33 \fBint\fR \fBct_dev_tmpl_get_minor\fR(\fBint\fR \fIfd\fR, \fBchar *\fR\fIbuf\fR, \fBsize_t *\fR\fIbuflenp\fR);
  34 .fi
  35 
  36 .LP
  37 .nf
  38 \fBint\fR \fBct_dev_tmpl_set_noneg\fR(\fBint\fR \fIfd\fR);
  39 .fi
  40 
  41 .LP
  42 .nf
  43 \fBint\fR \fBct_dev_tmpl_clear_noneg\fR(\fBint\fR \fIfd\fR);
  44 .fi
  45 
  46 .LP
  47 .nf
  48 \fBint\fR \fBct_dev_tmpl_get_noneg\fR(\fBint\fR \fIfd\fR, \fBuint_t *\fR\fInonegp\fR);
  49 .fi
  50 
  51 .SH PARAMETERS
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fIaset\fR\fR
  56 .ad
  57 .RS 11n
  58 a bitset of one or more of device states
  59 .RE
  60 
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fIasetp\fR\fR
  65 .ad
  66 .RS 11n
  67 a pointer to a variable into which the current A-set is to be returned
  68 .RE
  69 
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fIbuf\fR\fR
  74 .ad
  75 .RS 11n
  76 a buffer into which the minor path is to be returned
  77 .RE
  78 
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fIbuflenp\fR\fR
  83 .ad
  84 .RS 11n
  85 a pointer to variable of type \fBsize_t\fR in which the size of the buffer
  86 \fIbuf\fR is passed in. If the buffer is too small the size of the buffer
  87 needed for a successful call is passed back to the caller.
  88 .RE
  89 
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fIfd\fR\fR
  94 .ad
  95 .RS 11n
  96 a file descriptor from an open of the device contract template file in the
  97 contract filesystem (ctfs)
  98 .RE
  99 
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fIminor\fR\fR
 104 .ad
 105 .RS 11n
 106 the \fBdevfs\fR path (the \fB/devices\fR path without the "\fB/devices\fR"
 107 prefix) of a minor which is to be the subject of a contract
 108 .RE
 109 
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fInonegp\fR\fR
 114 .ad
 115 .RS 11n
 116 a pointer to a \fIuint_t\fR variable for receiving the current setting of the
 117 "nonnegotiable" term in the template
 118 .RE
 119 
 120 .SH DESCRIPTION
 121 .sp
 122 .LP
 123 These functions read and write device contract terms and operate on device
 124 contract template file descriptors obtained from the \fBcontract\fR(4)
 125 filesystem (ctfs).
 126 .sp
 127 .LP
 128 The \fBct_dev_tmpl_set_aset()\fR and \fBct_dev_tmpl_get_aset()\fR functions
 129 write and read the "acceptable states" set (or A-set for short).  This is the
 130 set of device states guaranteed by the contract. Any departure from these
 131 states will result in the breaking of the contract and a delivery of a critical
 132 contract event to the contract holder. The A-set value is a bitset of one or
 133 more of the following device states: \fBCT_DEV_EV_ONLINE\fR,
 134 \fBCT_DEV_EV_DEGRADED\fR, and \fBCT_DEV_EV_OFFLINE\fR.
 135 .sp
 136 .LP
 137 The \fBct_dev_tmpl_set_minor()\fR and \fBct_dev_tmpl_get_minor()\fR functions
 138 write and read the minor term (the device resource that is to be the subject of
 139 the contract.) The value is a \fBdevfs\fR path to a device minor node (minus
 140 the "\fB/devices\fR" prefix). For the \fBct_dev_tmpl_get_minor()\fR function, a
 141 buffer at least \fBPATH_MAX\fR in size must be passed in. If the buffer is
 142 smaller than \fBPATH_MAX\fR, then the minimum size of the buffer required
 143 (\fBPATH_MAX\fR) for this function is passed back to the caller via the
 144 \fIbuflenp\fR argument.
 145 .sp
 146 .LP
 147 The \fBct_dev_tmpl_set_noneg()\fR and \fBct_dev_tmpl_get_noneg()\fR functions
 148 write and read the nonnegotiable term. If this term is set, synchronous
 149 negotiation events are automatically NACKed on behalf of the contract holder.
 150 For \fBct_dev_tmpl_get_noneg()\fR, the variable pointed to by \fInonegp\fR is
 151 set to 1 if the "noneg" term is set or to 0 otherwise.  The
 152 \fBct_dev_tmpl_clear_noneg()\fR term clears the nonnegotiable term from a
 153 template.
 154 .SH RETURN VALUES
 155 .sp
 156 .LP
 157 Upon successful completion, these functions return 0. Otherwise, they return a
 158 non-zero error value.
 159 .SH ERRORS
 160 .sp
 161 .LP
 162 The \fBct_dev_tmpl_set_aset()\fR function will fail if:
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fBEINVAL\fR\fR
 167 .ad
 168 .RS 10n
 169 A template file descriptor or A-set is invalid
 170 .RE
 171 
 172 .sp
 173 .LP
 174 The \fBct_dev_tmpl_set_minor()\fR function will fail if:
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fBEINVAL\fR\fR
 179 .ad
 180 .RS 10n
 181 One or more arguments is invalid.
 182 .RE
 183 
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fBENXIO\fR\fR
 188 .ad
 189 .RS 10n
 190 The minor named by minor path does not exist.
 191 .RE
 192 
 193 .sp
 194 .LP
 195 The \fBct_dev_tmpl_set_noneg()\fR function will fail if:
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBEPERM\fR\fR
 200 .ad
 201 .RS 9n
 202 A process lacks sufficient privilege to NACK a device state change.
 203 .RE
 204 
 205 .sp
 206 .LP
 207 The \fBct_dev_tmpl_get_aset()\fR and \fBct_dev_tmpl_get_minor()\fR functions
 208 will fail if:
 209 .sp
 210 .ne 2
 211 .na
 212 \fB\fBEINVAL\fR\fR
 213 .ad
 214 .RS 10n
 215 One or more arguments is invalid.
 216 .RE
 217 
 218 .sp
 219 .ne 2
 220 .na
 221 \fB\fBENOENT\fR\fR
 222 .ad
 223 .RS 10n
 224 The requested term is not set.
 225 .RE
 226 
 227 .sp
 228 .LP
 229 The \fBct_dev_tmpl_get_noneg()\fR function will fail if:
 230 .sp
 231 .ne 2
 232 .na
 233 \fB\fBEINVAL\fR\fR
 234 .ad
 235 .RS 10n
 236 One or more arguments is invalid.
 237 .RE
 238 
 239 .sp
 240 .LP
 241 The \fBct_dev_tmpl_get_minor()\fR function will fail if:
 242 .sp
 243 .ne 2
 244 .na
 245 \fB\fBEOVEFLOW\fR\fR
 246 .ad
 247 .RS 12n
 248 The supplied buffer is too small.
 249 .RE
 250 
 251 .SH ATTRIBUTES
 252 .sp
 253 .LP
 254 See \fBattributes\fR(5) for descriptions of the following attributes:
 255 .sp
 256 
 257 .sp
 258 .TS
 259 box;
 260 c | c
 261 l | l .
 262 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 263 _
 264 Interface Stability     Committed
 265 _
 266 MT-Level        Safe
 267 .TE
 268 
 269 .SH SEE ALSO
 270 .sp
 271 .LP
 272 \fBlibcontract\fR(3LIB), \fBcontract\fR(4), \fBdevices\fR(4),
 273 \fBattributes\fR(5), \fBlfcompile\fR(5)