ct_event_read_critical(3contract)

1ct_event_read(3CONTRACCTo)ntract Management Library Functicotn_sevent_read(3CONTRACT)
2
3
4

NAME

6       ct_event_read,  ct_event_read_critical,  ct_event_reset, ct_event_reli‐
7       able,     ct_event_free,     ct_event_get_flags,     ct_event_get_ctid,
8       ct_event_get_evid,        ct_event_get_type,        ct_event_get_nevid,
9       ct_event_get_newct - common contract event functions
10

SYNOPSIS

12       cc [ flag... ] file... -D_LARGEFILE64_SOURCE  -lcontract  [ library... ]
13       #include <libcontract.h>
14
15       int ct_event_read(int fd, ct_evthdl_t *evthndlp);
16
17
18       int ct_event_read_critical(int fd, ct_evthdl_t *evthndlp);
19
20
21       int ct_event_reset(int fd);
22
23
24       int ct_event_reliable(int fd);
25
26
27       void ct_event_free(ct_evthdl_t evthndl);
28
29
30       ctid_t ct_event_get_ctid(ct_evthdl_t evthndl);
31
32
33       ctevid_t ct_event_get_evid(ct_evthdl_t evthndl);
34
35
36       uint_t ct_event_get_flags(ct_evthdl_t evthndl);
37
38
39       uint_t ct_event_get_type(ct_evthdl_t evthndl);
40
41
42       int ct_event_get_nevid(ct_evthdl_t evthndl, ctevid_t *evidp);
43
44
45       int ct_event_get_newct(ct_evthdl_t evthndl, ctid_t *ctidp);
46
47

DESCRIPTION

49       These functions operate on contract  event  endpoint  file  descriptors
50       obtained  from  the  contract(4)  file  system and event object handles
51       returned by ct_event_read() and ct_event_read_critical().
52
53
54       The ct_event_read() function reads the next event from the queue refer‐
55       enced by the file descriptor fd and initializes the event object handle
56       pointed to by evthndlp. After a successful call to ct_event_read(), the
57       caller  is responsible for calling ct_event_free() on this event object
58       handle when it has finished using it.
59
60
61       The  ct_event_read_critical()  function  behaves  like  ct_event_read()
62       except  that  it reads the next critical event from the queue, skipping
63       any intermediate events.
64
65
66       The ct_event_reset() function resets the location of  the  listener  to
67       the  beginning  of  the  queue.  This  function  can be used to re-read
68       events, or read events that were sent before  the  event  endpoint  was
69       opened.  Informative  and  acknowledged critical events, however, might
70       have been removed from the queue.
71
72
73       The ct_event_reliable() function indicates that no event  published  to
74       the  specified  event  queue  should be dropped by the system until the
75       specified listener has read the event. This function requires that  the
76       caller have the {PRIV_CONTRACT_EVENT} privilege in its effective set.
77
78
79       The  ct_event_free()  function  frees  any  storage associated with the
80       event object handle specified by evthndl.
81
82
83       The ct_event_get_ctid() function returns the ID of  the  contract  that
84       sent the specified event.
85
86
87       The ct_event_get_evid() function returns the ID of the specified event.
88
89
90       The ct_event_get_flags() function returns the event flags for the spec‐
91       ified event. Valid event flags are:
92
93       CTE_INFO    The event is an informative event.
94
95
96       CTE_ACK     The event has been acknowledged (for critical and  negotia‐
97                   tion messages).
98
99
100       CTE_NEG     The message represents an exit negotiation.
101
102
103
104       The ct_event_get_type() function reads the event type. The value is one
105       of the event types described in contract(4) or the contract type's man‐
106       ual page.
107
108
109        The  ct_event_get_nevid()  function  reads  the negotiation ID from an
110       CT_EV_NEGEND event.
111
112
113       The ct_event_get_newct() function obtains the ID of the  contract  cre‐
114       ated  when  the  negotiation  referenced by the CT_EV_NEGEND event suc‐
115       ceeded. If no contract was created, ctidp will be 0.  If the  operation
116       was cancelled, *ctidp will equal the ID of the existing contract.
117

RETURN VALUES

119       Upon  successful completion, ct_event_read(), ct_event_read_critical(),
120       ct_event_reset(),   ct_event_reliable(),   ct_event_get_nevid(),    and
121       ct_event_get_newct()  return 0. Otherwise, they return a non-zero error
122       value.
123
124
125       The ct_event_get_flags(), ct_event_get_ctid(), ct_event_get_evid(), and
126       ct_event_get_type()  functions return data as described in the DESCRIP‐
127       TION.
128

ERRORS

130       The ct_event_reliable() function will fail if:
131
132       EPERM    The caller does not have {PRIV_CONTRACT_EVENT} in  its  effec‐
133                tive set.
134
135
136
137       The  ct_event_read()  and  ct_event_read_critical() functions will fail
138       if:
139
140       EAGAIN    The event endpoint was opened O_NONBLOCK  and  no  applicable
141                 events were available to be read.
142
143
144
145       The  The  ct_event_get_nevid()  and ct_event_get_newct() functions will
146       fail if:
147
148       EINVAL    The evthndl argument is not a CT_EV_NEGEND event object.
149
150

ATTRIBUTES

152       See attributes(5) for descriptions of the following attributes:
153
154
155
156
157       ┌─────────────────────────────┬─────────────────────────────┐
158       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
159       ├─────────────────────────────┼─────────────────────────────┤
160       │Interface Stability          │Evolving                     │
161       ├─────────────────────────────┼─────────────────────────────┤
162       │MT-Level                     │Safe                         │
163       └─────────────────────────────┴─────────────────────────────┘
164

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

ATTRIBUTES

SEE ALSO