'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
.TH ct_status_read 3CONTRACT "1 Apr 2004" "SunOS 5.11" "Contract Management Library Functions"
.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
.mk
.na
\fB\fBCTS_OWNED\fR\fR
.ad
.RS 17n
.rt  
a contract that is currently owned by a process
.RE

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

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

.sp
.ne 2
.mk
.na
\fB\fBCTS_DEAD\fR\fR
.ad
.RS 17n
.rt  
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
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
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
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelSafe
.TE

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