path: root/usr/src/man/man3contract/ct_status_read.3contract

'\" te
.\" Copyright (c) 2004, 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_STATUS_READ 3CONTRACT "Apr 1, 2004"
.SH NAME
ct_status_read, ct_status_free, ct_status_get_id, ct_status_get_zoneid,
ct_status_get_type, ct_status_get_state, ct_status_get_holder,
ct_status_get_nevents, ct_status_get_ntime, ct_status_get_qtime,
ct_status_get_nevid, ct_status_get_cookie, ct_status_get_informative,
ct_status_get_critical \- common contract status functions
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-D_LARGEFILE64_SOURCE\fR \fB -lcontract \fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libcontract.h>

\fBint\fR \fBct_status_read\fR(\fBint\fR \fIfd\fR, \fBint\fR \fIdetail\fR, \fBct_stathdl_t *\fR\fIstathdlp\fR);
.fi

.LP
.nf
\fBvoid\fR \fBct_status_free\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
.fi

.LP
.nf
\fBctid_t\fR \fBct_status_get_id\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
.fi

.LP
.nf
\fBzoneid_t\fR \fBct_status_get_zoneid\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
.fi

.LP
.nf
\fBchar *\fR\fBct_status_get_type\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
.fi

.LP
.nf
\fBuint_t\fR \fBct_status_get_state\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
.fi

.LP
.nf
\fBpid_t\fR \fBct_status_get_holder\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
.fi

.LP
.nf
\fBint\fR \fBct_status_get_nevents\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
.fi

.LP
.nf
\fBint\fR \fBct_status_get_ntime\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
.fi

.LP
.nf
\fBint\fR \fBct_status_get_qtime\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
.fi

.LP
.nf
\fBctevid_t\fR \fBct_status_get_nevid\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
.fi

.LP
.nf
\fBuint64_t\fR \fBct_status_get_cookie\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
.fi

.LP
.nf
\fBctevid_t\fR \fBct_status_get_informative\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
.fi

.LP
.nf
\fBuint_t\fR \fBct_status_get_critical\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
.fi

.SH DESCRIPTION
.sp
.LP
These functions operate on contract status file descriptors obtained from the
\fBcontract\fR(4) file system and status object handles returned by
\fBct_status_read()\fR.
.sp
.LP
The \fBct_status_read()\fR function reads the contract's status and initializes
the status object handle pointed to by \fIstathdlp\fR. After a successful call
to \fBct_status_read()\fR, the caller is responsible for calling
\fBct_status_free()\fR on this status object handle when it has finished using
it. Because the amount of information available for a contract might be large,
the \fIdetail\fR argument allows the caller to specify how much information
\fBct_status_read()\fR should obtain. A value of \fBCTD_COMMON\fR fetches only
those data accessible by the functions on this manual page. \fBCTD_FIXED\fR
fetches \fBCTD_COMMON\fR data as well as fixed-size contract type-specific
data. \fBCTD_ALL\fR fetches \fBCTD_FIXED\fR data as well as variable lengthed
data, such as arrays. See the manual pages for contract type-specific status
accessor functions for information concerning which data are fetched by
\fBCTD_FIXED\fR and \fBCTD_ALL\fR.
.sp
.LP
The \fBct_status_free()\fR function frees any storage associated with the
specified status object handle.
.sp
.LP
The remaining functions all return contract information obtained from a status
object.
.sp
.LP
The \fBct_status_get_id()\fR function returns the contract's ID.
.sp
.LP
The \fBct_status_get_zoneid()\fR function returns the contract's creator's zone
ID, or \(mi1 if the creator's zone no longer exists.
.sp
.LP
The \fBct_status_get_type()\fR function returns the contract's type. The string
should be neither modified nor freed.
.sp
.LP
The \fBct_status_get_state()\fR function returns the state of the contract.
Valid state values are:
.sp
.ne 2
.na
\fB\fBCTS_OWNED\fR\fR
.ad
.RS 17n
a contract that is currently owned by a process
.RE

.sp
.ne 2
.na
\fB\fBCTS_INHERITED\fR\fR
.ad
.RS 17n
a contract that has been inherited by a regent process contract
.RE

.sp
.ne 2
.na
\fB\fBCTS_ORPHAN\fR\fR
.ad
.RS 17n
a contract that has no owner and has not been inherited
.RE

.sp
.ne 2
.na
\fB\fBCTS_DEAD\fR\fR
.ad
.RS 17n
a contract that is no longer in effect and will be automatically removed from
the system as soon as the last reference to it is release (for example, an open
status file descriptor)
.RE

.sp
.LP
The \fBct_status_get_holder()\fR function returns the process ID of the
contract's owner if the contract is in the \fBCTS_OWNED\fR state, or the ID of
the regent process contract if the contract is in the \fBCTS_INHERITED\fR
state.
.sp
.LP
The \fBct_status_get_nevents()\fR function returns the number of unacknowledged
critical events on the contract's event queue.
.sp
.LP
The \fBct_status_get_ntime()\fR function returns the amount of time remaining
(in seconds) before the ongoing exit negotiation times out, or -1 if there is
no negotiation ongoing.
.sp
.LP
The \fBct_status_get_qtime()\fR function returns the amount of time remaining
(in seconds) in the quantum before the ongoing exit negotiation times out, or
-1 if there is no negotiation ongoing.
.sp
.LP
The \fBct_status_get_nevid()\fR function returns the event ID of the ongoing
negotiation, or 0 if there are none.
.sp
.LP
The \fBct_status_get_cookie()\fR function returns the cookie term of the
contract.
.sp
.LP
The \fBct_status_get_critical()\fR function is used to read the critical event
set term. The value is a collection of bits as described in the contract type's
manual page.
.sp
.LP
The \fBct_status_get_informative()\fR function is used to read the informative
event set term. The value is a collection of bits as described in the contract
type's manual page.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBct_status_read()\fR returns 0. Otherwise, it
returns a non-zero error value.
.sp
.LP
Upon successful completion, \fBct_status_get_id()\fR,
\fBct_status_get_type()\fR, \fBct_status_get_holder()\fR,
\fBct_status_get_state()\fR, \fBct_status_get_nevents()\fR,
\fBct_status_get_ntime()\fR, \fBct_status_get_qtime()\fR,
\fBct_status_get_nevid()\fR, \fBct_status_get_cookie()\fR,
\fBct_status_get_critical()\fR, and \fBct_status_get_informative()\fR return
the data described in the DESCRIPTION.
.SH ERRORS
.sp
.LP
The \fBct_status_read()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The \fIdetail\fR level specified is invalid.
.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	Evolving
_
MT-Level	Safe
.TE

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