share/man/man3contract/ct_event_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_EVENT_READ 3CONTRACT "April 9, 2016"
   7 .SH NAME
   8 ct_event_read, ct_event_read_critical, ct_event_reset, ct_event_reliable,
   9 ct_event_free, ct_event_get_flags, ct_event_get_ctid, ct_event_get_evid,
  10 ct_event_get_type, ct_event_get_nevid, ct_event_get_newct \- common contract
  11 event functions
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB -lcontract \fR [ \fIlibrary\fR\&.\|.\|. ]
  16 #include <libcontract.h>
  17
  18 \fBint\fR \fBct_event_read\fR(\fBint\fR \fIfd\fR, \fBct_evthdl_t *\fR\fIevthndlp\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBint\fR \fBct_event_read_critical\fR(\fBint\fR \fIfd\fR, \fBct_evthdl_t *\fR\fIevthndlp\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBint\fR \fBct_event_reset\fR(\fBint\fR \fIfd\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBint\fR \fBct_event_reliable\fR(\fBint\fR \fIfd\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBvoid\fR \fBct_event_free\fR(\fBct_evthdl_t\fR \fIevthndl\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBctid_t\fR \fBct_event_get_ctid\fR(\fBct_evthdl_t\fR \fIevthndl\fR);
  44 .fi
  45
  46 .LP
  47 .nf
  48 \fBctevid_t\fR \fBct_event_get_evid\fR(\fBct_evthdl_t\fR \fIevthndl\fR);
  49 .fi
  50
  51 .LP
  52 .nf
  53 \fBuint_t\fR \fBct_event_get_flags\fR(\fBct_evthdl_t\fR \fIevthndl\fR);
  54 .fi
  55
  56 .LP
  57 .nf
  58 \fBuint_t\fR \fBct_event_get_type\fR(\fBct_evthdl_t\fR \fIevthndl\fR);
  59 .fi
  60
  61 .LP
  62 .nf
  63 \fBint\fR \fBct_event_get_nevid\fR(\fBct_evthdl_t\fR \fIevthndl\fR, \fBctevid_t *\fR\fIevidp\fR);
  64 .fi
  65
  66 .LP
  67 .nf
  68 \fBint\fR \fBct_event_get_newct\fR(\fBct_evthdl_t\fR \fIevthndl\fR, \fBctid_t *\fR\fIctidp\fR);
  69 .fi
  70
  71 .SH DESCRIPTION
  72 .LP
  73 These functions operate on contract event endpoint file descriptors obtained
  74 from the \fBcontract\fR(4) file system and event object handles returned by
  75 \fBct_event_read()\fR and \fBct_event_read_critical()\fR.
  76 .sp
  77 .LP
  78 The \fBct_event_read()\fR function reads the next event from the queue
  79 referenced by the file descriptor \fIfd\fR and initializes the event object
  80 handle pointed to by \fIevthndlp\fR. After a successful call to
  81 \fBct_event_read()\fR, the caller is responsible for calling
  82 \fBct_event_free()\fR on this event object handle when it has finished using
  83 it.
  84 .sp
  85 .LP
  86 The \fBct_event_read_critical()\fR function behaves like \fBct_event_read()\fR
  87 except that it reads the next critical event from the queue, skipping any
  88 intermediate events.
  89 .sp
  90 .LP
  91 The \fBct_event_reset()\fR function resets the location of the listener to the
  92 beginning of the queue. This function can be used to re-read events, or read
  93 events that were sent before the event endpoint was opened. Informative and
  94 acknowledged critical events, however, might have been removed from the queue.
  95 .sp
  96 .LP
  97 The \fBct_event_reliable()\fR function indicates that no event published to the
  98 specified event queue should be dropped by the system until the specified
  99 listener has read the event. This function requires that the caller have the
 100 {\fBPRIV_CONTRACT_EVENT\fR} privilege in its effective set.
 101 .sp
 102 .LP
 103 The \fBct_event_free()\fR function frees any storage associated with the event
 104 object handle specified by \fIevthndl\fR.
 105 .sp
 106 .LP
 107 The \fBct_event_get_ctid()\fR function returns the ID of the contract that sent
 108 the specified event.
 109 .sp
 110 .LP
 111 The \fBct_event_get_evid()\fR function returns the ID of the specified event.
 112 .sp
 113 .LP
 114 The \fBct_event_get_flags()\fR function returns the event flags for the
 115 specified event. Valid event flags are:
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBCTE_INFO\fR\fR
 120 .ad
 121 .RS 12n
 122 The event is an informative event.
 123 .RE
 124
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fBCTE_ACK\fR\fR
 129 .ad
 130 .RS 12n
 131 The event has been acknowledged (for critical and negotiation messages).
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBCTE_NEG\fR\fR
 138 .ad
 139 .RS 12n
 140 The message represents an exit negotiation.
 141 .RE
 142
 143 .sp
 144 .LP
 145 The \fBct_event_get_type()\fR function reads the event type. The value is one
 146 of the event types described in \fBcontract\fR(4) or the contract type's manual
 147 page.
 148 .sp
 149 .LP
 150  The \fBct_event_get_nevid()\fR function reads the negotiation ID from an
 151 \fBCT_EV_NEGEND\fR event.
 152 .sp
 153 .LP
 154 The \fBct_event_get_newct()\fR function obtains the ID of the contract created
 155 when the negotiation referenced by the \fBCT_EV_NEGEND\fR event succeeded. If
 156 no contract was created, \fIctidp\fR will be 0.  If the operation was
 157 cancelled, *\fIctidp\fR will equal the ID of the existing contract.
 158 .SH RETURN VALUES
 159 .LP
 160 Upon successful completion, \fBct_event_read()\fR,
 161 \fBct_event_read_critical()\fR, \fBct_event_reset()\fR,
 162 \fBct_event_reliable()\fR, \fBct_event_get_nevid()\fR, and
 163 \fBct_event_get_newct()\fR return 0. Otherwise, they return a non-zero error
 164 value.
 165 .sp
 166 .LP
 167 The \fBct_event_get_flags()\fR, \fBct_event_get_ctid()\fR,
 168 \fBct_event_get_evid()\fR, and \fBct_event_get_type()\fR functions return data
 169 as described in the DESCRIPTION.
 170 .SH ERRORS
 171 .LP
 172 The \fBct_event_reliable()\fR function will fail if:
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fBEPERM\fR\fR
 177 .ad
 178 .RS 9n
 179 The caller does not have {\fBPRIV_CONTRACT_EVENT\fR} in its effective set.
 180 .RE
 181
 182 .sp
 183 .LP
 184 The \fBct_event_read()\fR and \fBct_event_read_critical()\fR functions will
 185 fail if:
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fBEAGAIN\fR\fR
 190 .ad
 191 .RS 10n
 192 The event endpoint was opened \fBO_NONBLOCK\fR and no applicable events were
 193 available to be read.
 194 .RE
 195
 196 .sp
 197 .LP
 198 The \fBct_event_get_nevid()\fR and \fBct_event_get_newct()\fR functions
 199 will fail if:
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fBEINVAL\fR\fR
 204 .ad
 205 .RS 10n
 206 The \fIevthndl\fR argument is not a \fBCT_EV_NEGEND\fR event object.
 207 .RE
 208
 209 .SH ATTRIBUTES
 210 .LP
 211 See \fBattributes\fR(5) for descriptions of the following attributes:
 212 .sp
 213
 214 .sp
 215 .TS
 216 box;
 217 c | c
 218 l | l .
 219 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 220 _
 221 Interface Stability     Evolving
 222 _
 223 MT-Level        Safe
 224 .TE
 225
 226 .SH SEE ALSO
 227 .LP
 228 \fBlibcontract\fR(3LIB), \fBcontract\fR(4), \fBattributes\fR(5)