'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH CT_EVENT_READ 3CONTRACT "Apr 1, 2004"
.SH NAME
ct_event_read, ct_event_read_critical, ct_event_reset, ct_event_reliable,
ct_event_free, ct_event_get_flags, ct_event_get_ctid, ct_event_get_evid,
ct_event_get_type, ct_event_get_nevid, ct_event_get_newct \- common contract
event 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_event_read\fR(\fBint\fR \fIfd\fR, \fBct_evthdl_t *\fR\fIevthndlp\fR);
.fi

.LP
.nf
\fBint\fR \fBct_event_read_critical\fR(\fBint\fR \fIfd\fR, \fBct_evthdl_t *\fR\fIevthndlp\fR);
.fi

.LP
.nf
\fBint\fR \fBct_event_reset\fR(\fBint\fR \fIfd\fR);
.fi

.LP
.nf
\fBint\fR \fBct_event_reliable\fR(\fBint\fR \fIfd\fR);
.fi

.LP
.nf
\fBvoid\fR \fBct_event_free\fR(\fBct_evthdl_t\fR \fIevthndl\fR);
.fi

.LP
.nf
\fBctid_t\fR \fBct_event_get_ctid\fR(\fBct_evthdl_t\fR \fIevthndl\fR);
.fi

.LP
.nf
\fBctevid_t\fR \fBct_event_get_evid\fR(\fBct_evthdl_t\fR \fIevthndl\fR);
.fi

.LP
.nf
\fBuint_t\fR \fBct_event_get_flags\fR(\fBct_evthdl_t\fR \fIevthndl\fR);
.fi

.LP
.nf
\fBuint_t\fR \fBct_event_get_type\fR(\fBct_evthdl_t\fR \fIevthndl\fR);
.fi

.LP
.nf
\fBint\fR \fBct_event_get_nevid\fR(\fBct_evthdl_t\fR \fIevthndl\fR, \fBctevid_t *\fR\fIevidp\fR);
.fi

.LP
.nf
\fBint\fR \fBct_event_get_newct\fR(\fBct_evthdl_t\fR \fIevthndl\fR, \fBctid_t *\fR\fIctidp\fR);
.fi

.SH DESCRIPTION
.sp
.LP
These functions operate on contract event endpoint file descriptors obtained
from the \fBcontract\fR(4) file system and event object handles returned by
\fBct_event_read()\fR and \fBct_event_read_critical()\fR.
.sp
.LP
The \fBct_event_read()\fR function reads the next event from the queue
referenced by the file descriptor \fIfd\fR and initializes the event object
handle pointed to by \fIevthndlp\fR. After a successful call to
\fBct_event_read()\fR, the caller is responsible for calling
\fBct_event_free()\fR on this event object handle when it has finished using
it.
.sp
.LP
The \fBct_event_read_critical()\fR function behaves like \fBct_event_read()\fR
except that it reads the next critical event from the queue, skipping any
intermediate events.
.sp
.LP
The \fBct_event_reset()\fR function resets the location of the listener to the
beginning of the queue. This function can be used to re-read events, or read
events that were sent before the event endpoint was opened. Informative and
acknowledged critical events, however, might have been removed from the queue.
.sp
.LP
The \fBct_event_reliable()\fR function indicates that no event published to the
specified event queue should be dropped by the system until the specified
listener has read the event. This function requires that the caller have the
{\fBPRIV_CONTRACT_EVENT\fR} privilege in its effective set.
.sp
.LP
The \fBct_event_free()\fR function frees any storage associated with the event
object handle specified by \fIevthndl\fR.
.sp
.LP
The \fBct_event_get_ctid()\fR function returns the ID of the contract that sent
the specified event.
.sp
.LP
The \fBct_event_get_evid()\fR function returns the ID of the specified event.
.sp
.LP
The \fBct_event_get_flags()\fR function returns the event flags for the
specified event. Valid event flags are:
.sp
.ne 2
.na
\fB\fBCTE_INFO\fR\fR
.ad
.RS 12n
The event is an informative event.
.RE

.sp
.ne 2
.na
\fB\fBCTE_ACK\fR\fR
.ad
.RS 12n
The event has been acknowledged (for critical and negotiation messages).
.RE

.sp
.ne 2
.na
\fB\fBCTE_NEG\fR\fR
.ad
.RS 12n
The message represents an exit negotiation.
.RE

.sp
.LP
The \fBct_event_get_type()\fR function reads the event type. The value is one
of the event types described in \fBcontract\fR(4) or the contract type's manual
page.
.sp
.LP
 The \fBct_event_get_nevid()\fR function reads the negotiation ID from an
\fBCT_EV_NEGEND\fR event.
.sp
.LP
The \fBct_event_get_newct()\fR function obtains the ID of the contract created
when the negotiation referenced by the \fBCT_EV_NEGEND\fR event succeeded. If
no contract was created, \fIctidp\fR will be 0.  If the operation was
cancelled, *\fIctidp\fR will equal the ID of the existing contract.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBct_event_read()\fR,
\fBct_event_read_critical()\fR, \fBct_event_reset()\fR,
\fBct_event_reliable()\fR, \fBct_event_get_nevid()\fR, and
\fBct_event_get_newct()\fR return 0. Otherwise, they return a non-zero error
value.
.sp
.LP
The \fBct_event_get_flags()\fR, \fBct_event_get_ctid()\fR,
\fBct_event_get_evid()\fR, and \fBct_event_get_type()\fR functions return data
as described in the DESCRIPTION.
.SH ERRORS
.sp
.LP
The \fBct_event_reliable()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEPERM\fR\fR
.ad
.RS 9n
The caller does not have {\fBPRIV_CONTRACT_EVENT\fR} in its effective set.
.RE

.sp
.LP
The \fBct_event_read()\fR and \fBct_event_read_critical()\fR functions will
fail if:
.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
The event endpoint was opened \fBO_NONBLOCK\fR and no applicable events were
available to be read.
.RE

.sp
.LP
The The \fBct_event_get_nevid()\fR and \fBct_event_get_newct()\fR functions
will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The \fIevthndl\fR argument is not a \fBCT_EV_NEGEND\fR event object.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
_
MT-Level	Safe
.TE

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