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 .ne 2
  53 .na
  54 \fB\fIaset\fR\fR
  55 .ad
  56 .RS 11n
  57 a bitset of one or more of device states
  58 .RE
  59 
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fIasetp\fR\fR
  64 .ad
  65 .RS 11n
  66 a pointer to a variable into which the current A-set is to be returned
  67 .RE
  68 
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fIbuf\fR\fR
  73 .ad
  74 .RS 11n
  75 a buffer into which the minor path is to be returned
  76 .RE
  77 
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fIbuflenp\fR\fR
  82 .ad
  83 .RS 11n
  84 a pointer to variable of type \fBsize_t\fR in which the size of the buffer
  85 \fIbuf\fR is passed in. If the buffer is too small the size of the buffer
  86 needed for a successful call is passed back to the caller.
  87 .RE
  88 
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fIfd\fR\fR
  93 .ad
  94 .RS 11n
  95 a file descriptor from an open of the device contract template file in the
  96 contract filesystem (ctfs)
  97 .RE
  98 
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fIminor\fR\fR
 103 .ad
 104 .RS 11n
 105 the \fBdevfs\fR path (the \fB/devices\fR path without the "\fB/devices\fR"
 106 prefix) of a minor which is to be the subject of a contract
 107 .RE
 108 
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fInonegp\fR\fR
 113 .ad
 114 .RS 11n
 115 a pointer to a \fIuint_t\fR variable for receiving the current setting of the
 116 "nonnegotiable" term in the template
 117 .RE
 118 
 119 .SH DESCRIPTION
 120 .LP
 121 These functions read and write device contract terms and operate on device
 122 contract template file descriptors obtained from the \fBcontract\fR(4)
 123 filesystem (ctfs).
 124 .sp
 125 .LP
 126 The \fBct_dev_tmpl_set_aset()\fR and \fBct_dev_tmpl_get_aset()\fR functions
 127 write and read the "acceptable states" set (or A-set for short).  This is the
 128 set of device states guaranteed by the contract. Any departure from these
 129 states will result in the breaking of the contract and a delivery of a critical
 130 contract event to the contract holder. The A-set value is a bitset of one or
 131 more of the following device states: \fBCT_DEV_EV_ONLINE\fR,
 132 \fBCT_DEV_EV_DEGRADED\fR, and \fBCT_DEV_EV_OFFLINE\fR.
 133 .sp
 134 .LP
 135 The \fBct_dev_tmpl_set_minor()\fR and \fBct_dev_tmpl_get_minor()\fR functions
 136 write and read the minor term (the device resource that is to be the subject of
 137 the contract.) The value is a \fBdevfs\fR path to a device minor node (minus
 138 the "\fB/devices\fR" prefix). For the \fBct_dev_tmpl_get_minor()\fR function, a
 139 buffer at least \fBPATH_MAX\fR in size must be passed in. If the buffer is
 140 smaller than \fBPATH_MAX\fR, then the minimum size of the buffer required
 141 (\fBPATH_MAX\fR) for this function is passed back to the caller via the
 142 \fIbuflenp\fR argument.
 143 .sp
 144 .LP
 145 The \fBct_dev_tmpl_set_noneg()\fR and \fBct_dev_tmpl_get_noneg()\fR functions
 146 write and read the nonnegotiable term. If this term is set, synchronous
 147 negotiation events are automatically NACKed on behalf of the contract holder.
 148 For \fBct_dev_tmpl_get_noneg()\fR, the variable pointed to by \fInonegp\fR is
 149 set to 1 if the "noneg" term is set or to 0 otherwise.  The
 150 \fBct_dev_tmpl_clear_noneg()\fR term clears the nonnegotiable term from a
 151 template.
 152 .SH RETURN VALUES
 153 .LP
 154 Upon successful completion, these functions return 0. Otherwise, they return a
 155 non-zero error value.
 156 .SH ERRORS
 157 .LP
 158 The \fBct_dev_tmpl_set_aset()\fR function will fail if:
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fBEINVAL\fR\fR
 163 .ad
 164 .RS 10n
 165 A template file descriptor or A-set is invalid
 166 .RE
 167 
 168 .sp
 169 .LP
 170 The \fBct_dev_tmpl_set_minor()\fR function will fail if:
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fBEINVAL\fR\fR
 175 .ad
 176 .RS 10n
 177 One or more arguments is invalid.
 178 .RE
 179 
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fBENXIO\fR\fR
 184 .ad
 185 .RS 10n
 186 The minor named by minor path does not exist.
 187 .RE
 188 
 189 .sp
 190 .LP
 191 The \fBct_dev_tmpl_set_noneg()\fR function will fail if:
 192 .sp
 193 .ne 2
 194 .na
 195 \fB\fBEPERM\fR\fR
 196 .ad
 197 .RS 9n
 198 A process lacks sufficient privilege to NACK a device state change.
 199 .RE
 200 
 201 .sp
 202 .LP
 203 The \fBct_dev_tmpl_get_aset()\fR and \fBct_dev_tmpl_get_minor()\fR functions
 204 will fail if:
 205 .sp
 206 .ne 2
 207 .na
 208 \fB\fBEINVAL\fR\fR
 209 .ad
 210 .RS 10n
 211 One or more arguments is invalid.
 212 .RE
 213 
 214 .sp
 215 .ne 2
 216 .na
 217 \fB\fBENOENT\fR\fR
 218 .ad
 219 .RS 10n
 220 The requested term is not set.
 221 .RE
 222 
 223 .sp
 224 .LP
 225 The \fBct_dev_tmpl_get_noneg()\fR function will fail if:
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fBEINVAL\fR\fR
 230 .ad
 231 .RS 10n
 232 One or more arguments is invalid.
 233 .RE
 234 
 235 .sp
 236 .LP
 237 The \fBct_dev_tmpl_get_minor()\fR function will fail if:
 238 .sp
 239 .ne 2
 240 .na
 241 \fB\fBEOVERFLOW\fR\fR
 242 .ad
 243 .RS 12n
 244 The supplied buffer is too small.
 245 .RE
 246 
 247 .SH ATTRIBUTES
 248 .LP
 249 See \fBattributes\fR(5) for descriptions of the following attributes:
 250 .sp
 251 
 252 .sp
 253 .TS
 254 box;
 255 c | c
 256 l | l .
 257 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 258 _
 259 Interface Stability     Committed
 260 _
 261 MT-Level        Safe
 262 .TE
 263 
 264 .SH SEE ALSO
 265 .LP
 266 \fBlibcontract\fR(3LIB), \fBcontract\fR(4), \fBdevices\fR(4),
 267 \fBattributes\fR(5), \fBlfcompile\fR(5)