share/man/man3contract/ct_status_read.3contract

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH CT_STATUS_READ 3CONTRACT "Apr 1, 2004"
   7 .SH NAME
   8 ct_status_read, ct_status_free, ct_status_get_id, ct_status_get_zoneid,
   9 ct_status_get_type, ct_status_get_state, ct_status_get_holder,
  10 ct_status_get_nevents, ct_status_get_ntime, ct_status_get_qtime,
  11 ct_status_get_nevid, ct_status_get_cookie, ct_status_get_informative,
  12 ct_status_get_critical \- common contract status functions
  13 .SH SYNOPSIS
  14 .LP
  15 .nf
  16 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB -lcontract \fR [ \fIlibrary\fR\&.\|.\|. ]
  17 #include <libcontract.h>
  18
  19 \fBint\fR \fBct_status_read\fR(\fBint\fR \fIfd\fR, \fBint\fR \fIdetail\fR, \fBct_stathdl_t *\fR\fIstathdlp\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBvoid\fR \fBct_status_free\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBctid_t\fR \fBct_status_get_id\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBzoneid_t\fR \fBct_status_get_zoneid\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBchar *\fR\fBct_status_get_type\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
  40 .fi
  41
  42 .LP
  43 .nf
  44 \fBuint_t\fR \fBct_status_get_state\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
  45 .fi
  46
  47 .LP
  48 .nf
  49 \fBpid_t\fR \fBct_status_get_holder\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
  50 .fi
  51
  52 .LP
  53 .nf
  54 \fBint\fR \fBct_status_get_nevents\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
  55 .fi
  56
  57 .LP
  58 .nf
  59 \fBint\fR \fBct_status_get_ntime\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
  60 .fi
  61
  62 .LP
  63 .nf
  64 \fBint\fR \fBct_status_get_qtime\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
  65 .fi
  66
  67 .LP
  68 .nf
  69 \fBctevid_t\fR \fBct_status_get_nevid\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
  70 .fi
  71
  72 .LP
  73 .nf
  74 \fBuint64_t\fR \fBct_status_get_cookie\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
  75 .fi
  76
  77 .LP
  78 .nf
  79 \fBctevid_t\fR \fBct_status_get_informative\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
  80 .fi
  81
  82 .LP
  83 .nf
  84 \fBuint_t\fR \fBct_status_get_critical\fR(\fBct_stathdl_t\fR \fIstathdl\fR);
  85 .fi
  86
  87 .SH DESCRIPTION
  88 .sp
  89 .LP
  90 These functions operate on contract status file descriptors obtained from the
  91 \fBcontract\fR(4) file system and status object handles returned by
  92 \fBct_status_read()\fR.
  93 .sp
  94 .LP
  95 The \fBct_status_read()\fR function reads the contract's status and initializes
  96 the status object handle pointed to by \fIstathdlp\fR. After a successful call
  97 to \fBct_status_read()\fR, the caller is responsible for calling
  98 \fBct_status_free()\fR on this status object handle when it has finished using
  99 it. Because the amount of information available for a contract might be large,
 100 the \fIdetail\fR argument allows the caller to specify how much information
 101 \fBct_status_read()\fR should obtain. A value of \fBCTD_COMMON\fR fetches only
 102 those data accessible by the functions on this manual page. \fBCTD_FIXED\fR
 103 fetches \fBCTD_COMMON\fR data as well as fixed-size contract type-specific
 104 data. \fBCTD_ALL\fR fetches \fBCTD_FIXED\fR data as well as variable lengthed
 105 data, such as arrays. See the manual pages for contract type-specific status
 106 accessor functions for information concerning which data are fetched by
 107 \fBCTD_FIXED\fR and \fBCTD_ALL\fR.
 108 .sp
 109 .LP
 110 The \fBct_status_free()\fR function frees any storage associated with the
 111 specified status object handle.
 112 .sp
 113 .LP
 114 The remaining functions all return contract information obtained from a status
 115 object.
 116 .sp
 117 .LP
 118 The \fBct_status_get_id()\fR function returns the contract's ID.
 119 .sp
 120 .LP
 121 The \fBct_status_get_zoneid()\fR function returns the contract's creator's zone
 122 ID, or \(mi1 if the creator's zone no longer exists.
 123 .sp
 124 .LP
 125 The \fBct_status_get_type()\fR function returns the contract's type. The string
 126 should be neither modified nor freed.
 127 .sp
 128 .LP
 129 The \fBct_status_get_state()\fR function returns the state of the contract.
 130 Valid state values are:
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fBCTS_OWNED\fR\fR
 135 .ad
 136 .RS 17n
 137 a contract that is currently owned by a process
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fBCTS_INHERITED\fR\fR
 144 .ad
 145 .RS 17n
 146 a contract that has been inherited by a regent process contract
 147 .RE
 148
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fBCTS_ORPHAN\fR\fR
 153 .ad
 154 .RS 17n
 155 a contract that has no owner and has not been inherited
 156 .RE
 157
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBCTS_DEAD\fR\fR
 162 .ad
 163 .RS 17n
 164 a contract that is no longer in effect and will be automatically removed from
 165 the system as soon as the last reference to it is release (for example, an open
 166 status file descriptor)
 167 .RE
 168
 169 .sp
 170 .LP
 171 The \fBct_status_get_holder()\fR function returns the process ID of the
 172 contract's owner if the contract is in the \fBCTS_OWNED\fR state, or the ID of
 173 the regent process contract if the contract is in the \fBCTS_INHERITED\fR
 174 state.
 175 .sp
 176 .LP
 177 The \fBct_status_get_nevents()\fR function returns the number of unacknowledged
 178 critical events on the contract's event queue.
 179 .sp
 180 .LP
 181 The \fBct_status_get_ntime()\fR function returns the amount of time remaining
 182 (in seconds) before the ongoing exit negotiation times out, or -1 if there is
 183 no negotiation ongoing.
 184 .sp
 185 .LP
 186 The \fBct_status_get_qtime()\fR function returns the amount of time remaining
 187 (in seconds) in the quantum before the ongoing exit negotiation times out, or
 188 -1 if there is no negotiation ongoing.
 189 .sp
 190 .LP
 191 The \fBct_status_get_nevid()\fR function returns the event ID of the ongoing
 192 negotiation, or 0 if there are none.
 193 .sp
 194 .LP
 195 The \fBct_status_get_cookie()\fR function returns the cookie term of the
 196 contract.
 197 .sp
 198 .LP
 199 The \fBct_status_get_critical()\fR function is used to read the critical event
 200 set term. The value is a collection of bits as described in the contract type's
 201 manual page.
 202 .sp
 203 .LP
 204 The \fBct_status_get_informative()\fR function is used to read the informative
 205 event set term. The value is a collection of bits as described in the contract
 206 type's manual page.
 207 .SH RETURN VALUES
 208 .sp
 209 .LP
 210 Upon successful completion, \fBct_status_read()\fR returns 0. Otherwise, it
 211 returns a non-zero error value.
 212 .sp
 213 .LP
 214 Upon successful completion, \fBct_status_get_id()\fR,
 215 \fBct_status_get_type()\fR, \fBct_status_get_holder()\fR,
 216 \fBct_status_get_state()\fR, \fBct_status_get_nevents()\fR,
 217 \fBct_status_get_ntime()\fR, \fBct_status_get_qtime()\fR,
 218 \fBct_status_get_nevid()\fR, \fBct_status_get_cookie()\fR,
 219 \fBct_status_get_critical()\fR, and \fBct_status_get_informative()\fR return
 220 the data described in the DESCRIPTION.
 221 .SH ERRORS
 222 .sp
 223 .LP
 224 The \fBct_status_read()\fR function will fail if:
 225 .sp
 226 .ne 2
 227 .na
 228 \fB\fBEINVAL\fR\fR
 229 .ad
 230 .RS 10n
 231 The \fIdetail\fR level specified is invalid.
 232 .RE
 233
 234 .SH ATTRIBUTES
 235 .sp
 236 .LP
 237 See \fBattributes\fR(5) for descriptions of the following attributes:
 238 .sp
 239
 240 .sp
 241 .TS
 242 box;
 243 c | c
 244 l | l .
 245 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 246 _
 247 Interface Stability     Evolving
 248 _
 249 MT-Level        Safe
 250 .TE
 251
 252 .SH SEE ALSO
 253 .sp
 254 .LP
 255 \fBlibcontract\fR(3LIB), \fBcontract\fR(4), \fBattributes\fR(5)