Debian Codegraph @

upstream/debian-unstable/man3/SSL_poll.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_POLL 3SSL"
58 .TH SSL_POLL 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_poll,
65 SSL_POLL_EVENT_NONE,
66 SSL_POLL_EVENT_F,
67 SSL_POLL_EVENT_EL,
68 SSL_POLL_EVENT_EC,
69 SSL_POLL_EVENT_ECD,
70 SSL_POLL_EVENT_ER,
71 SSL_POLL_EVENT_EW,
72 SSL_POLL_EVENT_R,
73 SSL_POLL_EVENT_W,
74 SSL_POLL_EVENT_IC,
75 SSL_POLL_EVENT_ISB,
76 SSL_POLL_EVENT_ISU,
77 SSL_POLL_EVENT_OSB,
78 SSL_POLL_EVENT_OSU,
79 SSL_POLL_EVENT_RW,
80 SSL_POLL_EVENT_RE,
81 SSL_POLL_EVENT_WE,
82 SSL_POLL_EVENT_RWE,
83 SSL_POLL_EVENT_E,
84 SSL_POLL_EVENT_IS,
85 SSL_POLL_EVENT_ISE,
86 SSL_POLL_EVENT_I,
87 SSL_POLL_EVENT_OS,
88 SSL_POLL_EVENT_OSE,
89 SSL_POLL_FLAG_NO_HANDLE_EVENTS
90 \&\- determine or await readiness conditions for one or more pollable objects
91 .SH SYNOPSIS
92 .IX Header "SYNOPSIS"
93 .Vb 1
94 \& #include <openssl/ssl.h>
95 \&
96 \& #define SSL_POLL_EVENT_NONE 0
97 \&
98 \& #define SSL_POLL_EVENT_F /* F (Failure) */
99 \& #define SSL_POLL_EVENT_EL /* EL (Exception on Listener) */
100 \& #define SSL_POLL_EVENT_EC /* EC (Exception on Conn) */
101 \& #define SSL_POLL_EVENT_ECD /* ECD (Exception on Conn Drained) */
102 \& #define SSL_POLL_EVENT_ER /* ER (Exception on Read) */
103 \& #define SSL_POLL_EVENT_EW /* EW (Exception on Write) */
104 \& #define SSL_POLL_EVENT_R /* R (Readable) */
105 \& #define SSL_POLL_EVENT_W /* W (Writable) */
106 \& #define SSL_POLL_EVENT_IC /* IC (Incoming Connection) */
107 \& #define SSL_POLL_EVENT_ISB /* ISB (Incoming Stream: Bidi) */
108 \& #define SSL_POLL_EVENT_ISU /* ISU (Incoming Stream: Uni) */
109 \& #define SSL_POLL_EVENT_OSB /* OSB (Outgoing Stream: Bidi) */
110 \& #define SSL_POLL_EVENT_OSU /* OSU (Outgoing Stream: Uni) */
111 \&
112 \& #define SSL_POLL_EVENT_RW /* R | W */
113 \& #define SSL_POLL_EVENT_RE /* R | ER */
114 \& #define SSL_POLL_EVENT_WE /* W | EW */
115 \& #define SSL_POLL_EVENT_RWE /* RE | WE */
116 \& #define SSL_POLL_EVENT_E /* EL | EC | ER | EW */
117 \& #define SSL_POLL_EVENT_IS /* ISB | ISU */
118 \& #define SSL_POLL_EVENT_ISE /* IS | EC */
119 \& #define SSL_POLL_EVENT_I /* IS */
120 \& #define SSL_POLL_EVENT_OS /* OSB | OSU */
121 \& #define SSL_POLL_EVENT_OSE /* OS | EC */
122 \&
123 \& typedef struct ssl_poll_item_st {
124 \& BIO_POLL_DESCRIPTOR desc;
125 \& uint64_t events, revents;
126 \& } SSL_POLL_ITEM;
127 \&
128 \& #define SSL_POLL_FLAG_NO_HANDLE_EVENTS
129 \&
130 \& int SSL_poll(SSL_POLL_ITEM *items,
131 \& size_t num_items,
132 \& size_t stride,
133 \& const struct timeval *timeout,
134 \& uint64_t flags,
135 \& size_t *result_count);
136 .Ve
137 .SH DESCRIPTION
138 .IX Header "DESCRIPTION"
139 \&\fBSSL_poll()\fR allows the readiness conditions of the resources represented by one
140 or more BIO_POLL_DESCRIPTOR structures to be determined. In particular, it can
141 be used to query for readiness conditions on QUIC connection SSL objects and
142 QUIC stream SSL objects in a single call. It can also be used to block until at
143 least one of the given resources is ready.
144 .PP
145 A call to \fBSSL_poll()\fR specifies an array of \fBSSL_POLL_ITEM\fR structures, each of
146 which designates a resource which is being polled for readiness, and a set of
147 event flags which indicate the specific readiness events which the caller is
148 interested in in relation to the specified resource.
149 .PP
150 The fields of \fBSSL_POLL_ITEM\fR are as follows:
151 .IP \fIdesc\fR 4
152 .IX Item "desc"
153 The resource being polled for readiness, as represented by a
154 \&\fBBIO_POLL_DESCRIPTOR\fR. Currently, this must be a poll descriptor of type
155 \&\fBBIO_POLL_DESCRIPTOR_TYPE_SSL\fR, representing an SSL object pointer, and the SSL
156 object must be a QUIC connection SSL object or QUIC stream SSL object.
157 .Sp
158 If a \fBSSL_POLL_ITEM\fR has a poll descriptor type of
159 \&\fBBIO_POLL_DESCRIPTOR_TYPE_NONE\fR, or the SSL object pointer is NULL, the
160 \&\fBSSL_POLL_ITEM\fR array entry is ignored and \fIrevents\fR will be set to 0 on
161 return.
162 .IP \fIevents\fR 4
163 .IX Item "events"
164 This is the set of zero or more events which the caller is interested in
165 learning about in relation to the resource described by \fIdesc\fR. It is a
166 collection of zero or more \fBSSL_POLL_EVENT\fR flags. See "EVENT TYPES" for a
167 description of each of the event types.
168 .IP \fIrevents\fR 4
169 .IX Item "revents"
170 After \fBSSL_poll()\fR returns, this is the set of zero or more events which are
171 actually applicable to the resource described by \fIdesc\fR. As for \fIevents\fR,
172 it is a collection of zero or more \fBSSL_POLL_EVENT\fR flags.
173 .Sp
174 \&\fIrevents\fR need not be a subset of the events specified in \fIevents\fR, as some
175 event types are defined as always being enabled (non-maskable). See "EVENT
176 TYPES" for more information.
177 .PP
178 To use \fBSSL_poll()\fR, call it with an array of \fBSSL_POLL_ITEM\fR structures. The
179 array need remain allocated only for the duration of the call. \fInum_items\fR must
180 be set to the number of entries in the array, and \fIstride\fR must be set to
181 \&\f(CWsizeof(SSL_POLL_ITEM)\fR.
182 .PP
183 The \fItimeout\fR argument specifies the timeout to use, and, implicitly, whether
184 to use \fBSSL_poll()\fR in blocking or nonblocking mode:
185 .IP \(bu 4
186 If \fItimeout\fR is NULL, the function blocks indefinitely until at least one
187 resource is ready.
188 .IP \(bu 4
189 If \fItimeout\fR is non-NULL, and it points to a \fBstruct timeval\fR which is set to
190 zero, the function operates in nonblocking mode and returns immediately with
191 readiness information.
192 .IP \(bu 4
193 If \fItimeout\fR is non-NULL, and it points to a \fBstruct timeval\fR which is set to
194 a value other than zero, the function blocks for the specified interval or until
195 at least one of the specified resources is ready, whichever comes first.
196 .PP
197 The present implementation of \fBSSL_poll()\fR is a subset of the functionality which
198 will eventually be available. For more information, see "LIMITATIONS".
199 .PP
200 The following flags are currently defined for the \fIflags\fR argument:
201 .IP \fBSSL_POLL_FLAG_NO_HANDLE_EVENTS\fR 4
202 .IX Item "SSL_POLL_FLAG_NO_HANDLE_EVENTS"
203 This flag indicates that internal state machine processing should not be
204 performed in an attempt to generate new readiness events. Only existing
205 readiness events will be reported.
206 .Sp
207 If this flag is used in nonblocking mode (with a timeout of zero), no internal
208 state machine processing is performed.
209 .Sp
210 If this flag is used in blocking mode (for example, with \fItimeout\fR set to
211 NULL), event processing does not occur unless the function blocks.
212 .PP
213 The \fIresult_count\fR argument is optional. If it is non-NULL, it is used to
214 output the number of entries in the array which have nonzero \fIrevents\fR fields
215 when the call to \fBSSL_poll()\fR returns; see "RETURN VALUES" for details.
216 .SH "EVENT TYPES"
217 .IX Header "EVENT TYPES"
218 The \fBSSL_poll()\fR interface reports zero or more event types on a given resource,
219 represented by a bit mask.
220 .PP
221 All of the event types are level triggered and represent a readiness or
222 permanent exception condition; as such, after an event has been reported by
223 \&\fBSSL_poll()\fR for a resource, it will continue to be reported in future \fBSSL_poll()\fR
224 calls until the condition ceases to be in effect. A caller must mask the given
225 event type bit in future \fBSSL_poll()\fR calls if it does not wish to receive
226 repeated notifications and has not caused the underlying readiness condition
227 (for example, consuming all available data using \fBSSL_read_ex\fR\|(3) after
228 \&\fBSSL_POLL_EVENT_R\fR is reported) to be deasserted.
229 .PP
230 Some event types do not make sense on a given kind of resource. In this case,
231 specifying that event type in \fIevents\fR is a no-op and will be ignored, and the
232 given event will never be reported in \fIrevents\fR.
233 .PP
234 Failure of the polling mechanism itself is considered distinct from an exception
235 condition on a resource which was successfully polled. See \fBSSL_POLL_EVENT_F\fR
236 and "RETURN VALUES" for details.
237 .PP
238 In general, an application should always listen for the event types
239 corresponding to exception conditions if it is listening to the corresponding
240 non-exception event types (e.g. \fBSSL_POLL_EVENT_EC\fR and \fBSSL_POLL_EVENT_ER\fR
241 for \fBSSL_POLL_EVENT_R\fR), as not doing so is unlikely to be a sound design.
242 .PP
243 Some event types are non-maskable and may be reported in \fIrevents\fR regardless
244 of whether they were requested in \fIevents\fR.
245 .PP
246 The following event types are supported:
247 .IP \fBSSL_POLL_EVENT_F\fR 4
248 .IX Item "SSL_POLL_EVENT_F"
249 Polling failure. This event is raised when a resource could not be polled. It is
250 distinct from an exception condition reported on a resource which was
251 successfully polled and represents a failure of the polling process itself in
252 relation to a resource. This may mean that \fBSSL_poll()\fR does not support the kind
253 of resource specified.
254 .Sp
255 Where this event is raised on at least one item in \fIitems\fR, \fBSSL_poll()\fR will
256 return 0 and the ERR stack will contain information pertaining to the first item
257 in \fIitems\fR with \fBSSL_POLL_EVENT_F\fR set. See "RETURN VALUES" for more
258 information.
259 .Sp
260 This event type may be raised even if it was not requested in \fIevents\fR;
261 specifying this event type in \fIevents\fR does nothing.
262 .IP \fBSSL_POLL_EVENT_EL\fR 4
263 .IX Item "SSL_POLL_EVENT_EL"
264 Error at listener level. This event is raised when a listener has failed, for
265 example if a network BIO has encountered a permanent error.
266 .Sp
267 This event is never raised on objects which are not listeners, but its
268 occurrence will cause \fBSSL_POLL_EVENT_EC\fR to be raised on all dependent
269 connections.
270 .IP \fBSSL_POLL_EVENT_EC\fR 4
271 .IX Item "SSL_POLL_EVENT_EC"
272 Error at connection level. This event is raised when a connection has failed.
273 In particular, it is raised when a connection begins terminating.
274 .Sp
275 This event is never raised on objects which are not connections.
276 .IP \fBSSL_POLL_EVENT_ECD\fR 4
277 .IX Item "SSL_POLL_EVENT_ECD"
278 Error at connection level (drained). This event is raised when a connection has
279 finished terminating, and has reached the terminated state. This event will
280 generally occur after an interval of time passes after the \fBSSL_POLL_EVENT_EC\fR
281 event is raised on a connection.
282 .Sp
283 This event is never raised on objects which are not connections.
284 .IP \fBSSL_POLL_EVENT_ER\fR 4
285 .IX Item "SSL_POLL_EVENT_ER"
286 Error in read direction. For QUIC, this is raised only in the event that a
287 stream has a read part and that read part has been reset by the peer (for
288 example, using a \fBRESET_STREAM\fR frame).
289 .IP \fBSSL_POLL_EVENT_EW\fR 4
290 .IX Item "SSL_POLL_EVENT_EW"
291 Error in write direction. For QUIC, this is raised only in the event that a
292 stream has a write part and that write part has been reset by the peer using a
293 \&\fBSTOP_SENDING\fR frame.
294 .IP \fBSSL_POLL_EVENT_R\fR 4
295 .IX Item "SSL_POLL_EVENT_R"
296 Readable. This event is raised when a QUIC stream SSL object (or a QUIC
297 connection SSL object with a default stream attached) has application data
298 waiting to be read using \fBSSL_read_ex\fR\|(3), or a FIN event as represented by
299 \&\fBSSL_ERROR_ZERO_RETURN\fR waiting to be read.
300 .Sp
301 It is not raised in the event of the receiving part of the QUIC stream being
302 reset by the peer; see \fBSSL_POLL_EVENT_ER\fR.
303 .IP \fBSSL_POLL_EVENT_W\fR 4
304 .IX Item "SSL_POLL_EVENT_W"
305 Writable. This event is raised when a QUIC stream SSL object (or a QUIC
306 connection SSL object with a default stream attached) could accept more
307 application data using \fBSSL_write_ex\fR\|(3).
308 .Sp
309 This event is never raised by a receive-only stream.
310 .Sp
311 This event is never raised by a stream which has had its send part concluded
312 normally (as with \fBSSL_stream_conclude\fR\|(3)) or locally reset (as with
313 \&\fBSSL_stream_reset\fR\|(3)).
314 .Sp
315 This event does not guarantee that a subsequent call to \fBSSL_write_ex\fR\|(3) will
316 succeed.
317 .IP \fBSSL_POLL_EVENT_IC\fR 4
318 .IX Item "SSL_POLL_EVENT_IC"
319 This event, which is only raised by a QUIC listener SSL object, is raised when
320 one or more incoming QUIC connections are available to be accepted using
321 \&\fBSSL_accept_connection\fR\|(3).
322 .IP \fBSSL_POLL_EVENT_ISB\fR 4
323 .IX Item "SSL_POLL_EVENT_ISB"
324 This event, which is only raised by a QUIC connection SSL object, is raised when
325 one or more incoming bidirectional streams are available to be accepted using
326 \&\fBSSL_accept_stream\fR\|(3).
327 .IP \fBSSL_POLL_EVENT_ISU\fR 4
328 .IX Item "SSL_POLL_EVENT_ISU"
329 This event, which is only raised by a QUIC connection SSL object, is raised when
330 one or more incoming unidirectional streams are available to be accepted using
331 \&\fBSSL_accept_stream\fR\|(3).
332 .IP \fBSSL_POLL_EVENT_OSB\fR 4
333 .IX Item "SSL_POLL_EVENT_OSB"
334 This event, which is only raised by a QUIC connection SSL object, is raised when
335 QUIC stream creation flow control currently permits at least one additional
336 bidirectional stream to be locally created.
337 .IP \fBSSL_POLL_EVENT_OSU\fR 4
338 .IX Item "SSL_POLL_EVENT_OSU"
339 This event, which is only raised by a QUIC connection SSL object, is raised when
340 QUIC stream creation flow control currently permits at least one additional
341 unidirectional stream to be locally created.
342 .SH LIMITATIONS
343 .IX Header "LIMITATIONS"
344 \&\fBSSL_poll()\fR as presently implemented has the following limitation:
345 .IP \(bu 4
346 Only \fBBIO_POLL_DESCRIPTOR\fR structures with type
347 \&\fBBIO_POLL_DESCRIPTOR_TYPE_SSL\fR, referencing QUIC listener, connection or
348 stream SSL objects, are supported.
349 .PP
350 This limitation may be revised in a future release of OpenSSL.
351 .SH "RETURN VALUES"
352 .IX Header "RETURN VALUES"
353 \&\fBSSL_poll()\fR returns 1 on success and 0 on failure.
354 .PP
355 Unless the \fIitems\fR pointer itself is invalid, \fBSSL_poll()\fR will always initialise
356 the \fIrevents\fR fields of all items in the input array upon returning, even if it
357 returns failure.
358 .PP
359 If \fIresult_count\fR is non-NULL, it is always written with the number of items in
360 the array with nonzero \fIrevents\fR fields, even if the \fBSSL_poll()\fR call returns
361 failure.
362 .PP
363 It is possible for \fIresult_count\fR to be written as 0 even if the \fBSSL_poll()\fR
364 call returns success, namely if no events were output but the polling process
365 was successful (e.g. in nonblocking usage) or timed out.
366 .PP
367 It is possible for \fIresult_count\fR to be written as a nonzero value if the
368 \&\fBSSL_poll()\fR call returns failure, for example due to \fBSSL_POLL_EVENT_F\fR events,
369 or because some events were detected and output before encountering a failure
370 condition while processing a subsequent entry in the \fIitems\fR array.
371 .PP
372 If at least one \fBSSL_POLL_EVENT_F\fR event is output, \fBSSL_poll()\fR is guaranteed
373 to return 0 and guaranteed to place at least one ERR on the error stack
374 describing the first \fBSSL_POLL_EVENT_F\fR output. Detailed information on any
375 additional \fBSSL_POLL_EVENT_F\fR events is not available. \fBSSL_poll()\fR may or may
376 not return more than one \fBSSL_POLL_EVENT_F\fR event at once.
377 .PP
378 "Normal" events representing exceptional I/O conditions which do not
379 constitute a failure of the \fBSSL_poll()\fR mechanism itself are not considered
380 errors by \fBSSL_poll()\fR and are instead represented using their own event type; see
381 "EVENT TYPES" for details.
382 .PP
383 The caller can establish the meaning of the \fBSSL_poll()\fR return and output values
384 as follows:
385 .IP \(bu 4
386 If \fBSSL_poll()\fR returns 1 and \fIresult_count\fR is zero, the operation timed out
387 before any resource was ready.
388 .IP \(bu 4
389 If \fBSSL_poll()\fR returns 1 and \fIresult_count\fR is nonzero, that many events were
390 output.
391 .IP \(bu 4
392 If \fBSSL_poll()\fR returns 0 and \fIresult_count\fR is zero, the caller has made a basic
393 usage error; check the ERR stack for details.
394 .IP \(bu 4
395 If \fBSSL_poll()\fR returns 0 and \fIresult_count\fR is nonzero, inspect the \fIitems\fR
396 array for \fBSSL_POLL_ITEM\fR structures with the \fBSSL_POLL_EVENT_F\fR event type
397 raised in \fIrevents\fR. The entries added to the ERR stack (of which there is
398 guaranteed to be at least one) reflect the cause of the failure of the first
399 item in \fIitems\fR with \fBSSL_POLL_EVENT_F\fR raised. Note that there may be events
400 other than \fISSL_POLL_EVENT_F\fR output for items which come before the first
401 item with \fBSSL_POLL_EVENT_F\fR raised, and additional \fBSSL_POLL_EVENT_F\fR
402 events may or may not have been output, both of which which will be reflected in
403 \&\fIresult_count\fR.
404 .SH "SEE ALSO"
405 .IX Header "SEE ALSO"
406 \&\fBBIO_get_rpoll_descriptor\fR\|(3), \fBBIO_get_wpoll_descriptor\fR\|(3),
407 \&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3)
408 .SH HISTORY
409 .IX Header "HISTORY"
410 \&\fBSSL_poll()\fR was added in OpenSSL 3.3.
411 .PP
412 Before 3.5, \fBSSL_poll()\fR did not support blocking operation and
413 would fail if called with a NULL \fItimeout\fR parameter or a \fItimeout\fR parameter
414 pointing to a \fBstruct timeval\fR which was not zero.
415 .PP
416 Before 3.5, the \fBSSL_POLL_EVENT_EL\fR and \fBSSL_POLL_EVENT_IC\fR
417 event types were not present.
418 .SH COPYRIGHT
419 .IX Header "COPYRIGHT"
420 Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved.
421 .PP
422 Licensed under the Apache License 2.0 (the "License"). You may not use
423 this file except in compliance with the License. You can obtain a copy
424 in the file LICENSE in the source distribution or at
425 <https://www.openssl.org/source/license.html>.