ct_status_read(3CONTRACT)			       Contract Management Library Functions				 ct_status_read(3CONTRACT)

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

SYNOPSIS

       cc [ flag... ] file... -D_LARGEFILE64_SOURCE  -lcontract  [ library... ]
       #include <libcontract.h>

       int ct_status_read(int fd, int detail, ct_stathdl_t *stathdlp);

       void ct_status_free(ct_stathdl_t stathdl);

       ctid_t ct_status_get_id(ct_stathdl_t stathdl);

       zoneid_t ct_status_get_zoneid(ct_stathdl_t stathdl);

       char *ct_status_get_type(ct_stathdl_t stathdl);

       uint_t ct_status_get_state(ct_stathdl_t stathdl);

       pid_t ct_status_get_holder(ct_stathdl_t stathdl);

       int ct_status_get_nevents(ct_stathdl_t stathdl);

       int ct_status_get_ntime(ct_stathdl_t stathdl);

       int ct_status_get_qtime(ct_stathdl_t stathdl);

       ctevid_t ct_status_get_nevid(ct_stathdl_t stathdl);

       uint64_t ct_status_get_cookie(ct_stathdl_t stathdl);

       ctevid_t ct_status_get_informative(ct_stathdl_t stathdl);

       uint_t ct_status_get_critical(ct_stathdl_t stathdl);

DESCRIPTION

       These functions operate on contract status file descriptors obtained from the contract(4) file system and status object handles returned by
       ct_status_read().

       The ct_status_read() function reads the contract's status and initializes the status object handle pointed to by stathdlp. After a success-
       ful  call  to  ct_status_read(),  the  caller is responsible for calling ct_status_free() on this status object handle when it has finished
       using it. Because the amount of information available for a contract might be large, the detail argument allows the caller to  specify  how
       much  information  ct_status_read() should obtain. A value of CTD_COMMON fetches only those data accessible by the functions on this manual
       page. CTD_FIXED fetches CTD_COMMON data as well as fixed-size contract type-specific data. CTD_ALL fetches CTD_FIXED data as well as  vari-
       able  lengthed  data,  such as arrays. See the manual pages for contract type-specific status accessor functions for information concerning
       which data are fetched by CTD_FIXED and CTD_ALL.

       The ct_status_free() function frees any storage associated with the specified status object handle.

       The remaining functions all return contract information obtained from a status object.

       The ct_status_get_id() function returns the contract's ID.

       The ct_status_get_zoneid() function returns the contract's creator's zone ID, or -1 if the creator's zone no longer exists.

       The ct_status_get_type() function returns the contract's type. The string should be neither modified nor freed.

       The ct_status_get_state() function returns the state of the contract. Valid state values are:

       CTS_OWNED	a contract that is currently owned by a process

       CTS_INHERITED	a contract that has been inherited by a regent process contract

       CTS_ORPHAN	a contract that has no owner and has not been inherited

       CTS_DEAD 	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)

       The  ct_status_get_holder() function returns the process ID of the contract's owner if the contract is in the CTS_OWNED state, or the ID of
       the regent process contract if the contract is in the CTS_INHERITED state.

       The ct_status_get_nevents() function returns the number of unacknowledged critical events on the contract's event queue.

       The ct_status_get_ntime() function returns the amount of time remaining (in seconds) before the ongoing exit negotiation times out,  or	-1
       if there is no negotiation ongoing.

       The  ct_status_get_qtime()  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.

       The ct_status_get_nevid() function returns the event ID of the ongoing negotiation, or 0 if there are none.

       The ct_status_get_cookie() function returns the cookie term of the contract.

       The ct_status_get_critical() 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.

       The  ct_status_get_informative() 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.

RETURN VALUES

       Upon successful completion, ct_status_read() returns 0. Otherwise, it returns a non-zero error value.

       Upon   successful   completion,	 ct_status_get_id(),   ct_status_get_type(),   ct_status_get_holder(),	 ct_status_get_state(),    ct_sta-
       tus_get_nevents(),  ct_status_get_ntime(),  ct_status_get_qtime(), ct_status_get_nevid(), ct_status_get_cookie(), ct_status_get_critical(),
       and ct_status_get_informative() return the data described in the DESCRIPTION.

ERRORS

       The ct_status_read() function will fail if:

       EINVAL	 The detail level specified is invalid.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       libcontract(3LIB), contract(4), attributes(5), lfcompile(5)

SunOS 5.11							    1 Apr 2004						 ct_status_read(3CONTRACT)