'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
.TH ct_event_read 3CONTRACT "1 Apr 2004" "SunOS 5.11" "Contract Management Library Functions"
.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
.mk
.na
\fB\fBCTE_INFO\fR\fR
.ad
.RS 12n
.rt  
The event is an informative event.
.RE

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

.sp
.ne 2
.mk
.na
\fB\fBCTE_NEG\fR\fR
.ad
.RS 12n
.rt  
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
.mk
.na
\fB\fBEPERM\fR\fR
.ad
.RS 9n
.rt  
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
.mk
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
.rt  
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
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
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
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelSafe
.TE

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