Contract Management Library Functions ctstatusread(3CONTRACT)
NAME
ctstatusread, ctstatusfree, ctstatusgetid,
ctstatusgetzoneid, ctstatusgettype,
ctstatusgetstate, ctstatusgetholder,
ctstatusgetnevents, ctstatusgetntime,
ctstatusgetqtime, ctstatusgetnevid,
ctstatusgetcookie, ctstatusgetinformative,
ctstatusgetcritical - common contract status functions
SYNOPSIS
cc [ flag... ] file... -DLARGEFILE64SOURCE -lcontract [ library... ]
#include
int ctstatusread(int fd, int detail, ctstathdlt *stathdlp);
void ctstatusfree(ctstathdlt stathdl);
ctidt ctstatusgetid(ctstathdlt stathdl);
zoneidt ctstatusgetzoneid(ctstathdlt stathdl);
char *ctstatusgettype(ctstathdlt stathdl);
uintt ctstatusgetstate(ctstathdlt stathdl);
pidt ctstatusgetholder(ctstathdlt stathdl);
int ctstatusgetnevents(ctstathdlt stathdl);
int ctstatusgetntime(ctstathdlt stathdl);
int ctstatusgetqtime(ctstathdlt stathdl);
ctevidt ctstatusgetnevid(ctstathdlt stathdl);
uint64t ctstatusgetcookie(ctstathdlt stathdl);
ctevidt ctstatusgetinformative(ctstathdlt stathdl);
SunOS 5.11 Last change: 1 Apr 2004 1
Contract Management Library Functions ctstatusread(3CONTRACT)
uintt ctstatusgetcritical(ctstathdlt stathdl);
DESCRIPTION
These functions operate on contract status file descriptors
obtained from the contract(4) file system and status object
handles returned by ctstatusread().
The ctstatusread() function reads the contract's status
and initializes the status object handle pointed to by
stathdlp. After a successful call to ctstatusread(), the
caller is responsible for calling ctstatusfree() 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 ctstatusread() should obtain. A value of
CTDCOMON fetches only those data accessible by the func-
tions on this manual page. CTDFIXED fetches CTDCOMON data
as well as fixed-size contract type-specific data. CTDAL
fetches CTDFIXED data as well as variable lengthed data,
such as arrays. See the manual pages for contract type-
specific status accessor functions for information concern-
ing which data are fetched by CTDFIXED and CTDAL.
The ctstatusfree() function frees any storage associated
with the specified status object handle.
The remaining functions all return contract information
obtained from a status object.
The ctstatusgetid() function returns the contract's ID.
The ctstatusgetzoneid() function returns the contract's
creator's zone ID, or -1 if the creator's zone no longer
exists.
The ctstatusgettype() function returns the contract's
type. The string should be neither modified nor freed.
The ctstatusgetstate() function returns the state of the
contract. Valid state values are:
CTSOWNED a contract that is currently owned by a
process
SunOS 5.11 Last change: 1 Apr 2004 2
Contract Management Library Functions ctstatusread(3CONTRACT)
CTSINHERITED a contract that has been inherited by a
regent process contract
CTSORPHAN a contract that has no owner and has not
been inherited
CTSDEAD a contract that is no longer in effect and
will be automatically removed from the sys-
tem as soon as the last reference to it is
release (for example, an open status file
descriptor)
The ctstatusgetholder() function returns the process ID
of the contract's owner if the contract is in the CTSOWNED
state, or the ID of the regent process contract if the con-
tract is in the CTSINHERITED state.
The ctstatusgetnevents() function returns the number of
unacknowledged critical events on the contract's event
queue.
The ctstatusgetntime() function returns the amount of
time remaining (in seconds) before the ongoing exit negotia-
tion times out, or -1 if there is no negotiation ongoing.
The ctstatusgetqtime() function returns the amount of
time remaining (in seconds) in the quantum before the ongo-
ing exit negotiation times out, or -1 if there is no nego-
tiation ongoing.
The ctstatusgetnevid() function returns the event ID of
the ongoing negotiation, or 0 if there are none.
The ctstatusgetcookie() function returns the cookie term
of the contract.
The ctstatusgetcritical() 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.
SunOS 5.11 Last change: 1 Apr 2004 3
Contract Management Library Functions ctstatusread(3CONTRACT)
The ctstatusgetinformative() 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, ctstatusread() returns 0. Oth-
erwise, it returns a non-zero error value.
Upon successful completion, ctstatusgetid(),
ctstatusgettype(), ctstatusgetholder(),
ctstatusgetstate(), ctstatusgetnevents(),
ctstatusgetntime(), ctstatusgetqtime(),
ctstatusgetnevid(), ctstatusgetcookie(),
ctstatusgetcritical(), and ctstatusgetinformative()
return the data described in the DESCRIPTION.
ERORS
The ctstatusread() function will fail if:
EINVAL The detail level specified is invalid.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Evolving
MT-Level Safe
SEE ALSO
libcontract(3LIB), contract(4), attributes(5), lfcompile(5)
SunOS 5.11 Last change: 1 Apr 2004 4
|
