'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH CT_DEV_TMPL_SET_ASET 3CONTRACT "Aug 9, 2007"
.SH NAME
ct_dev_tmpl_set_aset, ct_dev_tmpl_get_aset, ct_dev_tmpl_set_minor,
ct_dev_tmpl_get_minor, ct_dev_tmpl_set_noneg, ct_dev_tmpl_clear_noneg,
ct_dev_tmpl_get_noneg \- device contract template functions
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-D_LARGEFILE64_SOURCE\fR \fB -lcontract \fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libcontract.h>
#include <sys/contract/device.h>

int ct_dev_tmpl_set_aset(int fd, uint_t aset);
.fi

.LP
.nf
\fBint\fR \fBct_dev_tmpl_get_aset\fR(\fBint\fR \fIfd\fR, \fBuint_t *\fR\fIasetp\fR);
.fi

.LP
.nf
\fBint\fR \fBct_dev_tmpl_set_minor\fR(\fBint\fR \fIfd\fR, \fBchar *\fR\fIminor\fR);
.fi

.LP
.nf
\fBint\fR \fBct_dev_tmpl_get_minor\fR(\fBint\fR \fIfd\fR, \fBchar *\fR\fIbuf\fR, \fBsize_t *\fR\fIbuflenp\fR);
.fi

.LP
.nf
\fBint\fR \fBct_dev_tmpl_set_noneg\fR(\fBint\fR \fIfd\fR);
.fi

.LP
.nf
\fBint\fR \fBct_dev_tmpl_clear_noneg\fR(\fBint\fR \fIfd\fR);
.fi

.LP
.nf
\fBint\fR \fBct_dev_tmpl_get_noneg\fR(\fBint\fR \fIfd\fR, \fBuint_t *\fR\fInonegp\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIaset\fR\fR
.ad
.RS 11n
a bitset of one or more of device states
.RE

.sp
.ne 2
.na
\fB\fIasetp\fR\fR
.ad
.RS 11n
a pointer to a variable into which the current A-set is to be returned
.RE

.sp
.ne 2
.na
\fB\fIbuf\fR\fR
.ad
.RS 11n
a buffer into which the minor path is to be returned
.RE

.sp
.ne 2
.na
\fB\fIbuflenp\fR\fR
.ad
.RS 11n
a pointer to variable of type \fBsize_t\fR in which the size of the buffer
\fIbuf\fR is passed in. If the buffer is too small the size of the buffer
needed for a successful call is passed back to the caller.
.RE

.sp
.ne 2
.na
\fB\fIfd\fR\fR
.ad
.RS 11n
a file descriptor from an open of the device contract template file in the
contract filesystem (ctfs)
.RE

.sp
.ne 2
.na
\fB\fIminor\fR\fR
.ad
.RS 11n
the \fBdevfs\fR path (the \fB/devices\fR path without the "\fB/devices\fR"
prefix) of a minor which is to be the subject of a contract
.RE

.sp
.ne 2
.na
\fB\fInonegp\fR\fR
.ad
.RS 11n
a pointer to a \fIuint_t\fR variable for receiving the current setting of the
"nonnegotiable" term in the template
.RE

.SH DESCRIPTION
.sp
.LP
These functions read and write device contract terms and operate on device
contract template file descriptors obtained from the \fBcontract\fR(4)
filesystem (ctfs).
.sp
.LP
The \fBct_dev_tmpl_set_aset()\fR and \fBct_dev_tmpl_get_aset()\fR functions
write and read the "acceptable states" set (or A-set for short).  This is the
set of device states guaranteed by the contract. Any departure from these
states will result in the breaking of the contract and a delivery of a critical
contract event to the contract holder. The A-set value is a bitset of one or
more of the following device states: \fBCT_DEV_EV_ONLINE\fR,
\fBCT_DEV_EV_DEGRADED\fR, and \fBCT_DEV_EV_OFFLINE\fR.
.sp
.LP
The \fBct_dev_tmpl_set_minor()\fR and \fBct_dev_tmpl_get_minor()\fR functions
write and read the minor term (the device resource that is to be the subject of
the contract.) The value is a \fBdevfs\fR path to a device minor node (minus
the "\fB/devices\fR" prefix). For the \fBct_dev_tmpl_get_minor()\fR function, a
buffer at least \fBPATH_MAX\fR in size must be passed in. If the buffer is
smaller than \fBPATH_MAX\fR, then the minimum size of the buffer required
(\fBPATH_MAX\fR) for this function is passed back to the caller via the
\fIbuflenp\fR argument.
.sp
.LP
The \fBct_dev_tmpl_set_noneg()\fR and \fBct_dev_tmpl_get_noneg()\fR functions
write and read the nonnegotiable term. If this term is set, synchronous
negotiation events are automatically NACKed on behalf of the contract holder.
For \fBct_dev_tmpl_get_noneg()\fR, the variable pointed to by \fInonegp\fR is
set to 1 if the "noneg" term is set or to 0 otherwise.  The
\fBct_dev_tmpl_clear_noneg()\fR term clears the nonnegotiable term from a
template.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, these functions return 0. Otherwise, they return a
non-zero error value.
.SH ERRORS
.sp
.LP
The \fBct_dev_tmpl_set_aset()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
A template file descriptor or A-set is invalid
.RE

.sp
.LP
The \fBct_dev_tmpl_set_minor()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
One or more arguments is invalid.
.RE

.sp
.ne 2
.na
\fB\fBENXIO\fR\fR
.ad
.RS 10n
The minor named by minor path does not exist.
.RE

.sp
.LP
The \fBct_dev_tmpl_set_noneg()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEPERM\fR\fR
.ad
.RS 9n
A process lacks sufficient privilege to NACK a device state change.
.RE

.sp
.LP
The \fBct_dev_tmpl_get_aset()\fR and \fBct_dev_tmpl_get_minor()\fR functions
will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
One or more arguments is invalid.
.RE

.sp
.ne 2
.na
\fB\fBENOENT\fR\fR
.ad
.RS 10n
The requested term is not set.
.RE

.sp
.LP
The \fBct_dev_tmpl_get_noneg()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
One or more arguments is invalid.
.RE

.sp
.LP
The \fBct_dev_tmpl_get_minor()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEOVEFLOW\fR\fR
.ad
.RS 12n
The supplied buffer is too small.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBlibcontract\fR(3LIB), \fBcontract\fR(4), \fBdevices\fR(4),
\fBattributes\fR(5), \fBlfcompile\fR(5)