xref: /freebsd/crypto/openssl/doc/man3/SSL_poll.pod (revision e7be843b4a162e68651d3911f0357ed464915629) 
1*e7be843bSPierre Pronchery=pod
2*e7be843bSPierre Pronchery
3*e7be843bSPierre Pronchery=head1 NAME
4*e7be843bSPierre Pronchery
5*e7be843bSPierre ProncherySSL_poll,
6*e7be843bSPierre ProncherySSL_POLL_EVENT_NONE,
7*e7be843bSPierre ProncherySSL_POLL_EVENT_F,
8*e7be843bSPierre ProncherySSL_POLL_EVENT_EC,
9*e7be843bSPierre ProncherySSL_POLL_EVENT_ECD,
10*e7be843bSPierre ProncherySSL_POLL_EVENT_ER,
11*e7be843bSPierre ProncherySSL_POLL_EVENT_EW,
12*e7be843bSPierre ProncherySSL_POLL_EVENT_R,
13*e7be843bSPierre ProncherySSL_POLL_EVENT_W,
14*e7be843bSPierre ProncherySSL_POLL_EVENT_ISB,
15*e7be843bSPierre ProncherySSL_POLL_EVENT_ISU,
16*e7be843bSPierre ProncherySSL_POLL_EVENT_OSB,
17*e7be843bSPierre ProncherySSL_POLL_EVENT_OSU,
18*e7be843bSPierre ProncherySSL_POLL_EVENT_RW,
19*e7be843bSPierre ProncherySSL_POLL_EVENT_RE,
20*e7be843bSPierre ProncherySSL_POLL_EVENT_WE,
21*e7be843bSPierre ProncherySSL_POLL_EVENT_RWE,
22*e7be843bSPierre ProncherySSL_POLL_EVENT_E,
23*e7be843bSPierre ProncherySSL_POLL_EVENT_IS,
24*e7be843bSPierre ProncherySSL_POLL_EVENT_ISE,
25*e7be843bSPierre ProncherySSL_POLL_EVENT_I,
26*e7be843bSPierre ProncherySSL_POLL_EVENT_OS,
27*e7be843bSPierre ProncherySSL_POLL_EVENT_OSE,
28*e7be843bSPierre ProncherySSL_POLL_FLAG_NO_HANDLE_EVENTS
29*e7be843bSPierre Pronchery- determine or await readiness conditions for one or more pollable objects
30*e7be843bSPierre Pronchery
31*e7be843bSPierre Pronchery=head1 SYNOPSIS
32*e7be843bSPierre Pronchery
33*e7be843bSPierre Pronchery #include <openssl/ssl.h>
34*e7be843bSPierre Pronchery
35*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_NONE        0
36*e7be843bSPierre Pronchery
37*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_F           /* F   (Failure) */
38*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_EC          /* EC  (Exception on Conn) */
39*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_ECD         /* ECD (Exception on Conn Drained) */
40*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_ER          /* ER  (Exception on Read) */
41*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_EW          /* EW  (Exception on Write) */
42*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_R           /* R   (Readable) */
43*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_W           /* W   (Writable) */
44*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_ISB         /* ISB (Incoming Stream: Bidi) */
45*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_ISU         /* ISU (Incoming Stream: Uni) */
46*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_OSB         /* OSB (Outgoing Stream: Bidi) */
47*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_OSU         /* OSU (Outgoing Stream: Uni) */
48*e7be843bSPierre Pronchery
49*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_RW          /* R   | W         */
50*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_RE          /* R   | ER        */
51*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_WE          /* W   | EW        */
52*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_RWE         /* RE  | WE        */
53*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_E           /* EC  | ER  | EW  */
54*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_IS          /* ISB | ISU       */
55*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_ISE         /* IS  | EC        */
56*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_I           /* IS              */
57*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_OS          /* OSB | OSU       */
58*e7be843bSPierre Pronchery #define SSL_POLL_EVENT_OSE         /* OS  | EC        */
59*e7be843bSPierre Pronchery
60*e7be843bSPierre Pronchery typedef struct ssl_poll_item_st {
61*e7be843bSPierre Pronchery     BIO_POLL_DESCRIPTOR desc;
62*e7be843bSPierre Pronchery     uint64_t            events, revents;
63*e7be843bSPierre Pronchery } SSL_POLL_ITEM;
64*e7be843bSPierre Pronchery
65*e7be843bSPierre Pronchery #define SSL_POLL_FLAG_NO_HANDLE_EVENTS
66*e7be843bSPierre Pronchery
67*e7be843bSPierre Pronchery int SSL_poll(SSL_POLL_ITEM         *items,
68*e7be843bSPierre Pronchery              size_t                num_items,
69*e7be843bSPierre Pronchery              size_t                stride,
70*e7be843bSPierre Pronchery              const struct timeval  *timeout,
71*e7be843bSPierre Pronchery              uint64_t              flags,
72*e7be843bSPierre Pronchery              size_t                *result_count);
73*e7be843bSPierre Pronchery
74*e7be843bSPierre Pronchery=head1 DESCRIPTION
75*e7be843bSPierre Pronchery
76*e7be843bSPierre ProncherySSL_poll() allows the readiness conditions of the resources represented by one
77*e7be843bSPierre Proncheryor more BIO_POLL_DESCRIPTOR structures to be determined. In particular, it can
78*e7be843bSPierre Proncherybe used to query for readiness conditions on QUIC connection SSL objects and
79*e7be843bSPierre ProncheryQUIC stream SSL objects in a single call. It can also be used to block until at
80*e7be843bSPierre Proncheryleast one of the given resources is ready.
81*e7be843bSPierre Pronchery
82*e7be843bSPierre ProncheryA call to SSL_poll() specifies an array of B<SSL_POLL_ITEM> structures, each of
83*e7be843bSPierre Proncherywhich designates a resource which is being polled for readiness, and a set of
84*e7be843bSPierre Proncheryevent flags which indicate the specific readiness events which the caller is
85*e7be843bSPierre Proncheryinterested in in relation to the specified resource.
86*e7be843bSPierre Pronchery
87*e7be843bSPierre ProncheryThe fields of B<SSL_POLL_ITEM> are as follows:
88*e7be843bSPierre Pronchery
89*e7be843bSPierre Pronchery=over 4
90*e7be843bSPierre Pronchery
91*e7be843bSPierre Pronchery=item I<desc>
92*e7be843bSPierre Pronchery
93*e7be843bSPierre ProncheryThe resource being polled for readiness, as represented by a
94*e7be843bSPierre ProncheryB<BIO_POLL_DESCRIPTOR>. Currently, this must be a poll descriptor of type
95*e7be843bSPierre ProncheryB<BIO_POLL_DESCRIPTOR_TYPE_SSL>, representing an SSL object pointer, and the SSL
96*e7be843bSPierre Proncheryobject must be a QUIC connection SSL object or QUIC stream SSL object.
97*e7be843bSPierre Pronchery
98*e7be843bSPierre ProncheryIf a B<SSL_POLL_ITEM> has a poll descriptor type of
99*e7be843bSPierre ProncheryB<BIO_POLL_DESCRIPTOR_TYPE_NONE>, or the SSL object pointer is NULL, the
100*e7be843bSPierre ProncheryB<SSL_POLL_ITEM> array entry is ignored and I<revents> will be set to 0 on
101*e7be843bSPierre Proncheryreturn.
102*e7be843bSPierre Pronchery
103*e7be843bSPierre Pronchery=item I<events>
104*e7be843bSPierre Pronchery
105*e7be843bSPierre ProncheryThis is the set of zero or more events which the caller is interested in
106*e7be843bSPierre Proncherylearning about in relation to the resource described by I<desc>. It is a
107*e7be843bSPierre Proncherycollection of zero or more B<SSL_POLL_EVENT> flags. See L</EVENT TYPES> for a
108*e7be843bSPierre Proncherydescription of each of the event types.
109*e7be843bSPierre Pronchery
110*e7be843bSPierre Pronchery=item I<revents>
111*e7be843bSPierre Pronchery
112*e7be843bSPierre ProncheryAfter SSL_poll() returns, this is the set of zero or more events which are
113*e7be843bSPierre Proncheryactually applicable to the resource described by I<desc>. As for I<events>,
114*e7be843bSPierre Proncheryit is a collection of zero or more B<SSL_POLL_EVENT> flags.
115*e7be843bSPierre Pronchery
116*e7be843bSPierre ProncheryI<revents> need not be a subset of the events specified in I<events>, as some
117*e7be843bSPierre Proncheryevent types are defined as always being enabled (non-maskable). See L</EVENT
118*e7be843bSPierre ProncheryTYPES> for more information.
119*e7be843bSPierre Pronchery
120*e7be843bSPierre Pronchery=back
121*e7be843bSPierre Pronchery
122*e7be843bSPierre ProncheryTo use SSL_poll(), call it with an array of B<SSL_POLL_ITEM> structures. The
123*e7be843bSPierre Proncheryarray need remain allocated only for the duration of the call. I<num_items> must
124*e7be843bSPierre Proncherybe set to the number of entries in the array, and I<stride> must be set to
125*e7be843bSPierre ProncheryC<sizeof(SSL_POLL_ITEM)>.
126*e7be843bSPierre Pronchery
127*e7be843bSPierre ProncheryThe I<timeout> argument specifies the timeout to use, and, implicitly, whether
128*e7be843bSPierre Proncheryto use SSL_poll() in blocking or nonblocking mode:
129*e7be843bSPierre Pronchery
130*e7be843bSPierre Pronchery=over 4
131*e7be843bSPierre Pronchery
132*e7be843bSPierre Pronchery=item *
133*e7be843bSPierre Pronchery
134*e7be843bSPierre ProncheryIf I<timeout> is NULL, the function blocks indefinitely until at least one
135*e7be843bSPierre Proncheryresource is ready.
136*e7be843bSPierre Pronchery
137*e7be843bSPierre Pronchery=item *
138*e7be843bSPierre Pronchery
139*e7be843bSPierre ProncheryIf I<timeout> is non-NULL, and it points to a B<struct timeval> which is set to
140*e7be843bSPierre Proncheryzero, the function operates in nonblocking mode and returns immediately with
141*e7be843bSPierre Proncheryreadiness information.
142*e7be843bSPierre Pronchery
143*e7be843bSPierre Pronchery=item *
144*e7be843bSPierre Pronchery
145*e7be843bSPierre ProncheryIf I<timeout> is non-NULL, and it points to a B<struct timeval> which is set to
146*e7be843bSPierre Proncherya value other than zero, the function blocks for the specified interval or until
147*e7be843bSPierre Proncheryat least one of the specified resources is ready, whichever comes first.
148*e7be843bSPierre Pronchery
149*e7be843bSPierre Pronchery=back
150*e7be843bSPierre Pronchery
151*e7be843bSPierre ProncheryThe present implementation of SSL_poll() is a subset of the functionality which
152*e7be843bSPierre Proncherywill eventually be available. For more information, see L</LIMITATIONS>.
153*e7be843bSPierre Pronchery
154*e7be843bSPierre ProncheryThe following flags are currently defined for the I<flags> argument:
155*e7be843bSPierre Pronchery
156*e7be843bSPierre Pronchery=over 4
157*e7be843bSPierre Pronchery
158*e7be843bSPierre Pronchery=item B<SSL_POLL_FLAG_NO_HANDLE_EVENTS>
159*e7be843bSPierre Pronchery
160*e7be843bSPierre ProncheryThis flag indicates that internal state machine processing should not be
161*e7be843bSPierre Proncheryperformed in an attempt to generate new readiness events. Only existing
162*e7be843bSPierre Proncheryreadiness events will be reported.
163*e7be843bSPierre Pronchery
164*e7be843bSPierre ProncheryIf this flag is used in nonblocking mode (with a timeout of zero), no internal
165*e7be843bSPierre Proncherystate machine processing is performed.
166*e7be843bSPierre Pronchery
167*e7be843bSPierre ProncheryIf this flag is used in blocking mode (for example, with I<timeout> set to
168*e7be843bSPierre ProncheryNULL), event processing does not occur unless the function blocks.
169*e7be843bSPierre Pronchery
170*e7be843bSPierre Pronchery=back
171*e7be843bSPierre Pronchery
172*e7be843bSPierre ProncheryThe I<result_count> argument is optional. If it is non-NULL, it is used to
173*e7be843bSPierre Proncheryoutput the number of entries in the array which have nonzero I<revents> fields
174*e7be843bSPierre Proncherywhen the call to SSL_poll() returns; see L</RETURN VALUES> for details.
175*e7be843bSPierre Pronchery
176*e7be843bSPierre Pronchery=head1 EVENT TYPES
177*e7be843bSPierre Pronchery
178*e7be843bSPierre ProncheryThe SSL_poll() interface reports zero or more event types on a given resource,
179*e7be843bSPierre Proncheryrepresented by a bit mask.
180*e7be843bSPierre Pronchery
181*e7be843bSPierre ProncheryAll of the event types are level triggered and represent a readiness or
182*e7be843bSPierre Proncherypermanent exception condition; as such, after an event has been reported by
183*e7be843bSPierre ProncherySSL_poll() for a resource, it will continue to be reported in future SSL_poll()
184*e7be843bSPierre Proncherycalls until the condition ceases to be in effect. A caller must mask the given
185*e7be843bSPierre Proncheryevent type bit in future SSL_poll() calls if it does not wish to receive
186*e7be843bSPierre Proncheryrepeated notifications and has not caused the underlying readiness condition
187*e7be843bSPierre Pronchery(for example, consuming all available data using L<SSL_read_ex(3)> after
188*e7be843bSPierre ProncheryB<SSL_POLL_EVENT_R> is reported) to be deasserted.
189*e7be843bSPierre Pronchery
190*e7be843bSPierre ProncherySome event types do not make sense on a given kind of resource. In this case,
191*e7be843bSPierre Proncheryspecifying that event type in I<events> is a no-op and will be ignored, and the
192*e7be843bSPierre Proncherygiven event will never be reported in I<revents>.
193*e7be843bSPierre Pronchery
194*e7be843bSPierre ProncheryFailure of the polling mechanism itself is considered distinct from an exception
195*e7be843bSPierre Proncherycondition on a resource which was successfully polled. See B<SSL_POLL_EVENT_F>
196*e7be843bSPierre Proncheryand L</RETURN VALUES> for details.
197*e7be843bSPierre Pronchery
198*e7be843bSPierre ProncheryIn general, an application should always listen for the event types
199*e7be843bSPierre Proncherycorresponding to exception conditions if it is listening to the corresponding
200*e7be843bSPierre Proncherynon-exception event types (e.g. B<SSL_POLL_EVENT_EC> and B<SSL_POLL_EVENT_ER>
201*e7be843bSPierre Proncheryfor B<SSL_POLL_EVENT_R>), as not doing so is unlikely to be a sound design.
202*e7be843bSPierre Pronchery
203*e7be843bSPierre ProncherySome event types are non-maskable and may be reported in I<revents> regardless
204*e7be843bSPierre Proncheryof whether they were requested in I<events>.
205*e7be843bSPierre Pronchery
206*e7be843bSPierre ProncheryThe following event types are supported:
207*e7be843bSPierre Pronchery
208*e7be843bSPierre Pronchery=over 4
209*e7be843bSPierre Pronchery
210*e7be843bSPierre Pronchery=item B<SSL_POLL_EVENT_F>
211*e7be843bSPierre Pronchery
212*e7be843bSPierre ProncheryPolling failure. This event is raised when a resource could not be polled. It is
213*e7be843bSPierre Proncherydistinct from an exception condition reported on a resource which was
214*e7be843bSPierre Proncherysuccessfully polled and represents a failure of the polling process itself in
215*e7be843bSPierre Proncheryrelation to a resource. This may mean that SSL_poll() does not support the kind
216*e7be843bSPierre Proncheryof resource specified.
217*e7be843bSPierre Pronchery
218*e7be843bSPierre ProncheryWhere this event is raised on at least one item in I<items>, SSL_poll() will
219*e7be843bSPierre Proncheryreturn 0 and the ERR stack will contain information pertaining to the first item
220*e7be843bSPierre Proncheryin I<items> with B<SSL_POLL_EVENT_F> set. See L</RETURN VALUES> for more
221*e7be843bSPierre Proncheryinformation.
222*e7be843bSPierre Pronchery
223*e7be843bSPierre ProncheryThis event type may be raised even if it was not requested in I<events>;
224*e7be843bSPierre Proncheryspecifying this event type in I<events> does nothing.
225*e7be843bSPierre Pronchery
226*e7be843bSPierre Pronchery=item B<SSL_POLL_EVENT_EL>
227*e7be843bSPierre Pronchery
228*e7be843bSPierre ProncheryError at listener level. This event is raised when a listener has failed, for
229*e7be843bSPierre Proncheryexample if a network BIO has encountered a permanent error.
230*e7be843bSPierre Pronchery
231*e7be843bSPierre ProncheryThis event is never raised on objects which are not listeners, but its
232*e7be843bSPierre Proncheryoccurrence will cause B<SSL_POLL_EVENT_EC> to be raised on all dependent
233*e7be843bSPierre Proncheryconnections.
234*e7be843bSPierre Pronchery
235*e7be843bSPierre Pronchery=item B<SSL_POLL_EVENT_EC>
236*e7be843bSPierre Pronchery
237*e7be843bSPierre ProncheryError at connection level. This event is raised when a connection has failed.
238*e7be843bSPierre ProncheryIn particular, it is raised when a connection begins terminating.
239*e7be843bSPierre Pronchery
240*e7be843bSPierre ProncheryThis event is never raised on objects which are not connections.
241*e7be843bSPierre Pronchery
242*e7be843bSPierre Pronchery=item B<SSL_POLL_EVENT_ECD>
243*e7be843bSPierre Pronchery
244*e7be843bSPierre ProncheryError at connection level (drained). This event is raised when a connection has
245*e7be843bSPierre Proncheryfinished terminating, and has reached the terminated state. This event will
246*e7be843bSPierre Proncherygenerally occur after an interval of time passes after the B<SSL_POLL_EVENT_EC>
247*e7be843bSPierre Proncheryevent is raised on a connection.
248*e7be843bSPierre Pronchery
249*e7be843bSPierre ProncheryThis event is never raised on objects which are not connections.
250*e7be843bSPierre Pronchery
251*e7be843bSPierre Pronchery=item B<SSL_POLL_EVENT_ER>
252*e7be843bSPierre Pronchery
253*e7be843bSPierre ProncheryError in read direction. For QUIC, this is raised only in the event that a
254*e7be843bSPierre Proncherystream has a read part and that read part has been reset by the peer (for
255*e7be843bSPierre Proncheryexample, using a B<RESET_STREAM> frame).
256*e7be843bSPierre Pronchery
257*e7be843bSPierre Pronchery=item B<SSL_POLL_EVENT_EW>
258*e7be843bSPierre Pronchery
259*e7be843bSPierre ProncheryError in write direction. For QUIC, this is raised only in the event that a
260*e7be843bSPierre Proncherystream has a write part and that write part has been reset by the peer using a
261*e7be843bSPierre ProncheryB<STOP_SENDING> frame.
262*e7be843bSPierre Pronchery
263*e7be843bSPierre Pronchery=item B<SSL_POLL_EVENT_R>
264*e7be843bSPierre Pronchery
265*e7be843bSPierre ProncheryReadable. This event is raised when a QUIC stream SSL object (or a QUIC
266*e7be843bSPierre Proncheryconnection SSL object with a default stream attached) has application data
267*e7be843bSPierre Proncherywaiting to be read using L<SSL_read_ex(3)>, or a FIN event as represented by
268*e7be843bSPierre ProncheryB<SSL_ERROR_ZERO_RETURN> waiting to be read.
269*e7be843bSPierre Pronchery
270*e7be843bSPierre ProncheryIt is not raised in the event of the receiving part of the QUIC stream being
271*e7be843bSPierre Proncheryreset by the peer; see B<SSL_POLL_EVENT_ER>.
272*e7be843bSPierre Pronchery
273*e7be843bSPierre Pronchery=item B<SSL_POLL_EVENT_W>
274*e7be843bSPierre Pronchery
275*e7be843bSPierre ProncheryWritable. This event is raised when a QUIC stream SSL object (or a QUIC
276*e7be843bSPierre Proncheryconnection SSL object with a default stream attached) could accept more
277*e7be843bSPierre Proncheryapplication data using L<SSL_write_ex(3)>.
278*e7be843bSPierre Pronchery
279*e7be843bSPierre ProncheryThis event is never raised by a receive-only stream.
280*e7be843bSPierre Pronchery
281*e7be843bSPierre ProncheryThis event is never raised by a stream which has had its send part concluded
282*e7be843bSPierre Proncherynormally (as with L<SSL_stream_conclude(3)>) or locally reset (as with
283*e7be843bSPierre ProncheryL<SSL_stream_reset(3)>).
284*e7be843bSPierre Pronchery
285*e7be843bSPierre ProncheryThis event does not guarantee that a subsequent call to L<SSL_write_ex(3)> will
286*e7be843bSPierre Proncherysucceed.
287*e7be843bSPierre Pronchery
288*e7be843bSPierre Pronchery=item B<SSL_POLL_EVENT_IC>
289*e7be843bSPierre Pronchery
290*e7be843bSPierre ProncheryThis event, which is only raised by a QUIC listener SSL object, is raised when
291*e7be843bSPierre Proncheryone or more incoming QUIC connections are available to be accepted using
292*e7be843bSPierre ProncheryL<SSL_accept_connection(3)>.
293*e7be843bSPierre Pronchery
294*e7be843bSPierre Pronchery=item B<SSL_POLL_EVENT_ISB>
295*e7be843bSPierre Pronchery
296*e7be843bSPierre ProncheryThis event, which is only raised by a QUIC connection SSL object, is raised when
297*e7be843bSPierre Proncheryone or more incoming bidirectional streams are available to be accepted using
298*e7be843bSPierre ProncheryL<SSL_accept_stream(3)>.
299*e7be843bSPierre Pronchery
300*e7be843bSPierre Pronchery=item B<SSL_POLL_EVENT_ISU>
301*e7be843bSPierre Pronchery
302*e7be843bSPierre ProncheryThis event, which is only raised by a QUIC connection SSL object, is raised when
303*e7be843bSPierre Proncheryone or more incoming unidirectional streams are available to be accepted using
304*e7be843bSPierre ProncheryL<SSL_accept_stream(3)>.
305*e7be843bSPierre Pronchery
306*e7be843bSPierre Pronchery=item B<SSL_POLL_EVENT_OSB>
307*e7be843bSPierre Pronchery
308*e7be843bSPierre ProncheryThis event, which is only raised by a QUIC connection SSL object, is raised when
309*e7be843bSPierre ProncheryQUIC stream creation flow control currently permits at least one additional
310*e7be843bSPierre Proncherybidirectional stream to be locally created.
311*e7be843bSPierre Pronchery
312*e7be843bSPierre Pronchery=item B<SSL_POLL_EVENT_OSU>
313*e7be843bSPierre Pronchery
314*e7be843bSPierre ProncheryThis event, which is only raised by a QUIC connection SSL object, is raised when
315*e7be843bSPierre ProncheryQUIC stream creation flow control currently permits at least one additional
316*e7be843bSPierre Proncheryunidirectional stream to be locally created.
317*e7be843bSPierre Pronchery
318*e7be843bSPierre Pronchery=back
319*e7be843bSPierre Pronchery
320*e7be843bSPierre Pronchery=head1 LIMITATIONS
321*e7be843bSPierre Pronchery
322*e7be843bSPierre ProncherySSL_poll() as presently implemented has the following limitation:
323*e7be843bSPierre Pronchery
324*e7be843bSPierre Pronchery=over 4
325*e7be843bSPierre Pronchery
326*e7be843bSPierre Pronchery=item
327*e7be843bSPierre Pronchery
328*e7be843bSPierre ProncheryOnly B<BIO_POLL_DESCRIPTOR> structures with type
329*e7be843bSPierre ProncheryB<BIO_POLL_DESCRIPTOR_TYPE_SSL>, referencing QUIC listener, connection or
330*e7be843bSPierre Proncherystream SSL objects, are supported.
331*e7be843bSPierre Pronchery
332*e7be843bSPierre Pronchery=back
333*e7be843bSPierre Pronchery
334*e7be843bSPierre ProncheryThis limitation may be revised in a future release of OpenSSL.
335*e7be843bSPierre Pronchery
336*e7be843bSPierre Pronchery=head1 RETURN VALUES
337*e7be843bSPierre Pronchery
338*e7be843bSPierre ProncherySSL_poll() returns 1 on success and 0 on failure.
339*e7be843bSPierre Pronchery
340*e7be843bSPierre ProncheryUnless the I<items> pointer itself is invalid, SSL_poll() will always initialise
341*e7be843bSPierre Proncherythe I<revents> fields of all items in the input array upon returning, even if it
342*e7be843bSPierre Proncheryreturns failure.
343*e7be843bSPierre Pronchery
344*e7be843bSPierre ProncheryIf I<result_count> is non-NULL, it is always written with the number of items in
345*e7be843bSPierre Proncherythe array with nonzero I<revents> fields, even if the SSL_poll() call returns
346*e7be843bSPierre Proncheryfailure.
347*e7be843bSPierre Pronchery
348*e7be843bSPierre ProncheryIt is possible for I<result_count> to be written as 0 even if the SSL_poll()
349*e7be843bSPierre Proncherycall returns success, namely if no events were output but the polling process
350*e7be843bSPierre Proncherywas successful (e.g. in nonblocking usage) or timed out.
351*e7be843bSPierre Pronchery
352*e7be843bSPierre ProncheryIt is possible for I<result_count> to be written as a nonzero value if the
353*e7be843bSPierre ProncherySSL_poll() call returns failure, for example due to B<SSL_POLL_EVENT_F> events,
354*e7be843bSPierre Proncheryor because some events were detected and output before encountering a failure
355*e7be843bSPierre Proncherycondition while processing a subsequent entry in the I<items> array.
356*e7be843bSPierre Pronchery
357*e7be843bSPierre ProncheryIf at least one B<SSL_POLL_EVENT_F> event is output, SSL_poll() is guaranteed
358*e7be843bSPierre Proncheryto return 0 and guaranteed to place at least one ERR on the error stack
359*e7be843bSPierre Proncherydescribing the first B<SSL_POLL_EVENT_F> output. Detailed information on any
360*e7be843bSPierre Proncheryadditional B<SSL_POLL_EVENT_F> events is not available. SSL_poll() may or may
361*e7be843bSPierre Proncherynot return more than one B<SSL_POLL_EVENT_F> event at once.
362*e7be843bSPierre Pronchery
363*e7be843bSPierre Pronchery"Normal" events representing exceptional I/O conditions which do not
364*e7be843bSPierre Proncheryconstitute a failure of the SSL_poll() mechanism itself are not considered
365*e7be843bSPierre Proncheryerrors by SSL_poll() and are instead represented using their own event type; see
366*e7be843bSPierre ProncheryL</EVENT TYPES> for details.
367*e7be843bSPierre Pronchery
368*e7be843bSPierre ProncheryThe caller can establish the meaning of the SSL_poll() return and output values
369*e7be843bSPierre Proncheryas follows:
370*e7be843bSPierre Pronchery
371*e7be843bSPierre Pronchery=over 4
372*e7be843bSPierre Pronchery
373*e7be843bSPierre Pronchery=item
374*e7be843bSPierre Pronchery
375*e7be843bSPierre ProncheryIf SSL_poll() returns 1 and I<result_count> is zero, the operation timed out
376*e7be843bSPierre Proncherybefore any resource was ready.
377*e7be843bSPierre Pronchery
378*e7be843bSPierre Pronchery=item
379*e7be843bSPierre Pronchery
380*e7be843bSPierre ProncheryIf SSL_poll() returns 1 and I<result_count> is nonzero, that many events were
381*e7be843bSPierre Proncheryoutput.
382*e7be843bSPierre Pronchery
383*e7be843bSPierre Pronchery=item
384*e7be843bSPierre Pronchery
385*e7be843bSPierre ProncheryIf SSL_poll() returns 0 and I<result_count> is zero, the caller has made a basic
386*e7be843bSPierre Proncheryusage error; check the ERR stack for details.
387*e7be843bSPierre Pronchery
388*e7be843bSPierre Pronchery=item
389*e7be843bSPierre Pronchery
390*e7be843bSPierre ProncheryIf SSL_poll() returns 0 and I<result_count> is nonzero, inspect the I<items>
391*e7be843bSPierre Proncheryarray for B<SSL_POLL_ITEM> structures with the B<SSL_POLL_EVENT_F> event type
392*e7be843bSPierre Proncheryraised in I<revents>. The entries added to the ERR stack (of which there is
393*e7be843bSPierre Proncheryguaranteed to be at least one) reflect the cause of the failure of the first
394*e7be843bSPierre Proncheryitem in I<items> with B<SSL_POLL_EVENT_F> raised. Note that there may be events
395*e7be843bSPierre Proncheryother than I<SSL_POLL_EVENT_F> output for items which come before the first
396*e7be843bSPierre Proncheryitem with B<SSL_POLL_EVENT_F> raised, and additional B<SSL_POLL_EVENT_F>
397*e7be843bSPierre Proncheryevents may or may not have been output, both of which which will be reflected in
398*e7be843bSPierre ProncheryI<result_count>.
399*e7be843bSPierre Pronchery
400*e7be843bSPierre Pronchery=back
401*e7be843bSPierre Pronchery
402*e7be843bSPierre Pronchery=head1 SEE ALSO
403*e7be843bSPierre Pronchery
404*e7be843bSPierre ProncheryL<BIO_get_rpoll_descriptor(3)>, L<BIO_get_wpoll_descriptor(3)>,
405*e7be843bSPierre ProncheryL<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)>
406*e7be843bSPierre Pronchery
407*e7be843bSPierre Pronchery=head1 HISTORY
408*e7be843bSPierre Pronchery
409*e7be843bSPierre ProncherySSL_poll() was added in OpenSSL 3.3.
410*e7be843bSPierre Pronchery
411*e7be843bSPierre ProncheryBefore 3.5, SSL_poll() did not support blocking operation and
412*e7be843bSPierre Proncherywould fail if called with a NULL I<timeout> parameter or a I<timeout> parameter
413*e7be843bSPierre Proncherypointing to a B<struct timeval> which was not zero.
414*e7be843bSPierre Pronchery
415*e7be843bSPierre ProncheryBefore 3.5, the B<SSL_POLL_EVENT_EL> and B<SSL_POLL_EVENT_IC>
416*e7be843bSPierre Proncheryevent types were not present.
417*e7be843bSPierre Pronchery
418*e7be843bSPierre Pronchery=head1 COPYRIGHT
419*e7be843bSPierre Pronchery
420*e7be843bSPierre ProncheryCopyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved.
421*e7be843bSPierre Pronchery
422*e7be843bSPierre ProncheryLicensed under the Apache License 2.0 (the "License").  You may not use
423*e7be843bSPierre Proncherythis file except in compliance with the License.  You can obtain a copy
424*e7be843bSPierre Proncheryin the file LICENSE in the source distribution or at
425*e7be843bSPierre ProncheryL<https://www.openssl.org/source/license.html>.
426*e7be843bSPierre Pronchery
427*e7be843bSPierre Pronchery=cut
428