8322 nl: misleading-indentation

[unleashed/tickless.git] / usr / src / man / man3contract / ct_dev_status_get_dev_state.3contract

'\" 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_STATUS_GET_DEV_STATE 3CONTRACT "Aug 9, 2007"
.SH NAME
ct_dev_status_get_dev_state, ct_dev_status_get_aset, ct_dev_status_get_minor,
ct_dev_status_get_noneg \- read contract status information from a status
object
.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>

\fBint\fR \fBct_dev_status_get_dev_state\fR(\fBct_stathdl_t\fR \fIstathdl\fR,
     \fBuint_t *\fR\fIstatep\fR);
.fi

.LP
.nf
\fBint\fR \fBct_dev_status_get_aset\fR(\fBct_stathdl_t\fR \fIstathdl\fR,
     \fBuint_t *\fR\fIasetp\fR);
.fi

.LP
.nf
\fBint\fR \fBct_dev_status_get_minor\fR(\fBct_stathdl_t\fR \fIstathdl\fR, \fBchar *\fR\fIbuf\fR,
     \fBsize_t *\fR\fIbuflenp\fR);
.fi

.LP
.nf
\fBint\fR \fBct_dev_status_get_noneg\fR(\fBct_stathdl_t\fR \fIstathdl\fR,
     \fBuint_t *\fR\fInonegp\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIasetp\fR\fR
.ad
.RS 11n
a pointer to a \fBuint_t\fR variable for receiving the acceptable state set
(such as A-set) for the contract
.RE

.sp
.ne 2
.na
\fB\fIbuf\fR\fR
.ad
.RS 11n
a buffer for receiving the \fBdevfs\fR path of a minor in a contract
.RE

.sp
.ne 2
.na
\fB\fIbuflenp\fR\fR
.ad
.RS 11n
a pointer to a variable of type \fBsize_t\fR for passing the size of the buffer
\fIbuf\fR. If the buffer is too small (< \fBPATH_MAX\fR), the minimum size of
the buffer needed (\fBPATH_MAX\fR) is passed back to the caller with this
argument.
.RE

.sp
.ne 2
.na
\fB\fInonegp\fR\fR
.ad
.RS 11n
a pointer to a \fBuint_t\fR variable for receiving the setting of the "noneg"
term
.RE

.sp
.ne 2
.na
\fB\fIstathdl\fR\fR
.ad
.RS 11n
a status object returned by \fBct_status_read\fR(3CONTRACT)
.RE

.sp
.ne 2
.na
\fB\fIstatep\fR\fR
.ad
.RS 11n
a pointer to a \fBuint_t\fR variable for receiving the current state of the
device which is the subject of the contract
.RE

.SH DESCRIPTION
.sp
.LP
These functions read contract status information from a status object
\fIstathdl\fR returned by \fBct_status_read()\fR. The detail level in the call
to \fBct_status_read()\fR needs to be at least \fBCTD_FIXED\fR for the
following calls to be successful. The one exception is
\fBct_dev_status_get_minor()\fR, which requires a detail level of
\fBCTD_ALL\fR.
.sp
.LP
The \fBct_dev_status_get_dev_state()\fR function returns the current state of
the device which is the subject of the contract. This can be one of the
following:
.sp
.ne 2
.na
\fB\fBCT_DEV_EV_ONLINE\fR\fR
.ad
.RS 22n
The device is online and functioning normally.
.RE

.sp
.ne 2
.na
\fB\fBCT_DEV_EV_DEGRADED\fR\fR
.ad
.RS 22n
The device is online but degraded.
.RE

.sp
.ne 2
.na
\fB\fBCT_DEV_EV_OFFLINE\fR\fR
.ad
.RS 22n
The device is offline and not configured.
.RE

.sp
.LP
The \fBct_dev_status_get_aset()\fR function returns the A-set of the contract.
This can be the bitset of one or more of the following states:
\fBCT_DEV_EV_ONLINE\fR, \fBCT_DEV_EV_DEGRADED\fR, or \fBCT_DEV_EV_OFFLINE\fR.
.sp
.LP
The \fBct_dev_status_get_minor()\fR function reads the \fBdevfs\fR path of the
minor participating in the contract. The \fBdevfs\fR path returned does not
include the \fB/devices\fR prefix. If the buffer passed in by the caller is too
small (< \fBPATH_MAX\fR), the minimum size of the buffer required (
\fBPATH_MAX\fR) is returned to the caller via the \fIbuflenp\fR argument.
.sp
.LP
The \fBct_dev_status_get_noneg()\fR function returns the "noneg" setting for
the contract. A value of 1 is returned in the \fInonegp\fR argument if
\fBNONEG\fR is set, else 0 is returned.
.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_status_get_minor()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEOVERFLOW\fR\fR
.ad
.RS 13n
The buffer size is too small to hold the result.
.RE

.sp
.LP
The \fBct_dev_status_get_dev_state()\fR, \fBct_dev_status_get_aset()\fR,
\fBct_dev_status_get_minor()\fR and \fBct_dev_status_get_noneg()\fR  functions
will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
An invalid argument was specified.
.RE

.sp
.ne 2
.na
\fB\fBENOENT\fR\fR
.ad
.RS 10n
The requested data is not present in the status object.
.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
\fBct_status_free\fR(3CONTRACT), \fBct_status_read\fR(3CONTRACT),
\fBlibcontract\fR(3LIB), \fBcontract\fR(4), \fBdevices\fR(4),
\fBattributes\fR(5), \fBlfcompile\fR(5)