diff options
Diffstat (limited to 'upstream/archlinux/man3/SSL_poll.3ssl')
| -rw-r--r-- | upstream/archlinux/man3/SSL_poll.3ssl | 393 |
1 files changed, 393 insertions, 0 deletions
diff --git a/upstream/archlinux/man3/SSL_poll.3ssl b/upstream/archlinux/man3/SSL_poll.3ssl new file mode 100644 index 00000000..d322d70b --- /dev/null +++ b/upstream/archlinux/man3/SSL_poll.3ssl @@ -0,0 +1,393 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "SSL_POLL 3ssl" +.TH SSL_POLL 3ssl 2024-04-28 3.3.0 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +SSL_poll, +SSL_POLL_EVENT_NONE, +SSL_POLL_EVENT_F, +SSL_POLL_EVENT_EC, +SSL_POLL_EVENT_ECD, +SSL_POLL_EVENT_ER, +SSL_POLL_EVENT_EW, +SSL_POLL_EVENT_R, +SSL_POLL_EVENT_W, +SSL_POLL_EVENT_ISB, +SSL_POLL_EVENT_ISU, +SSL_POLL_EVENT_OSB, +SSL_POLL_EVENT_OSU, +SSL_POLL_EVENT_RW, +SSL_POLL_EVENT_RE, +SSL_POLL_EVENT_WE, +SSL_POLL_EVENT_RWE, +SSL_POLL_EVENT_E, +SSL_POLL_EVENT_IS, +SSL_POLL_EVENT_ISE, +SSL_POLL_EVENT_I, +SSL_POLL_EVENT_OS, +SSL_POLL_EVENT_OSE, +SSL_POLL_FLAG_NO_HANDLE_EVENTS +\&\- determine or await readiness conditions for one or more pollable objects +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/ssl.h> +\& +\& #define SSL_POLL_EVENT_NONE 0 +\& +\& #define SSL_POLL_EVENT_F /* F (Failure) */ +\& #define SSL_POLL_EVENT_EC /* EC (Exception on Conn) */ +\& #define SSL_POLL_EVENT_ECD /* ECD (Exception on Conn Drained) */ +\& #define SSL_POLL_EVENT_ER /* ER (Exception on Read) */ +\& #define SSL_POLL_EVENT_EW /* EW (Exception on Write) */ +\& #define SSL_POLL_EVENT_R /* R (Readable) */ +\& #define SSL_POLL_EVENT_W /* W (Writable) */ +\& #define SSL_POLL_EVENT_ISB /* ISB (Incoming Stream: Bidi) */ +\& #define SSL_POLL_EVENT_ISU /* ISU (Incoming Stream: Uni) */ +\& #define SSL_POLL_EVENT_OSB /* OSB (Outgoing Stream: Bidi) */ +\& #define SSL_POLL_EVENT_OSU /* OSU (Outgoing Stream: Uni) */ +\& +\& #define SSL_POLL_EVENT_RW /* R | W */ +\& #define SSL_POLL_EVENT_RE /* R | ER */ +\& #define SSL_POLL_EVENT_WE /* W | EW */ +\& #define SSL_POLL_EVENT_RWE /* RE | WE */ +\& #define SSL_POLL_EVENT_E /* EC | ER | EW */ +\& #define SSL_POLL_EVENT_IS /* ISB | ISU */ +\& #define SSL_POLL_EVENT_ISE /* IS | EC */ +\& #define SSL_POLL_EVENT_I /* IS */ +\& #define SSL_POLL_EVENT_OS /* OSB | OSU */ +\& #define SSL_POLL_EVENT_OSE /* OS | EC */ +\& +\& typedef struct ssl_poll_item_st { +\& BIO_POLL_DESCRIPTOR desc; +\& uint64_t events, revents; +\& } SSL_POLL_ITEM; +\& +\& #define SSL_POLL_FLAG_NO_HANDLE_EVENTS +\& +\& int SSL_poll(SSL_POLL_ITEM *items, +\& size_t num_items, +\& size_t stride, +\& const struct timeval *timeout, +\& uint64_t flags, +\& size_t *result_count); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_poll()\fR allows the readiness conditions of the resources represented by one +or more BIO_POLL_DESCRIPTOR structures to be determined. In particular, it can +be used to query for readiness conditions on QUIC connection SSL objects and +QUIC stream SSL objects in a single call. +.PP +A call to \fBSSL_poll()\fR specifies an array of \fBSSL_POLL_ITEM\fR structures, each of +which designates a resource which is being polled for readiness, and a set of +event flags which indicate the specific readiness events which the caller is +interested in in relation to the specified resource. +.PP +The fields of \fBSSL_POLL_ITEM\fR are as follows: +.IP \fIdesc\fR 4 +.IX Item "desc" +The resource being polled for readiness, as represented by a +\&\fBBIO_POLL_DESCRIPTOR\fR. Currently, this must be a poll descriptor of type +\&\fBBIO_POLL_DESCRIPTOR_TYPE_SSL\fR, representing a SSL object pointer, and the SSL +object must be a QUIC connection SSL object or QUIC stream SSL object. +.Sp +If a \fBSSL_POLL_ITEM\fR has a poll descriptor type of +\&\fBBIO_POLL_DESCRIPTOR_TYPE_NONE\fR, or the SSL object pointer is NULL, the +\&\fBSSL_POLL_ITEM\fR array entry is ignored and \fIrevents\fR will be set to 0 on +return. +.IP \fIevents\fR 4 +.IX Item "events" +This is the set of zero or more events which the caller is interested in +learning about in relation to the resource described by \fIdesc\fR. It is a +collection of zero or more \fBSSL_POLL_EVENT\fR flags. See "EVENT TYPES" for a +description of each of the event types. +.IP \fIrevents\fR 4 +.IX Item "revents" +After \fBSSL_poll()\fR returns, this is the set of zero or more events which are +actually applicable to the resource described by \fIdesc\fR. As for \fIevents\fR, +it is a collection of zero or more \fBSSL_POLL_EVENT\fR flags. +.Sp +\&\fIrevents\fR need not be a subset of the events specified in \fIevents\fR, as some +event types are defined as always being enabled (non-maskable). See "EVENT +TYPES" for more information. +.PP +To use \fBSSL_poll()\fR, call it with an array of \fBSSL_POLL_ITEM\fR structures. The +array need remain allocated only for the duration of the call. \fInum_items\fR must +be set to the number of entries in the array, and \fIstride\fR must be set to +\&\f(CWsizeof(SSL_POLL_ITEM)\fR. +.PP +The present implementation of \fBSSL_poll()\fR is a subset of the functionality which +will eventually be available. Only a nonblocking mode of operation is available +at this time, where \fBSSL_poll()\fR always returns immediately. As such, \fItimeout\fR +must point to a valid \fBstruct timeval\fR and that structure must be set to zero. +In future, other inputs to the \fItimeout\fR argument will result in a blocking +mode of operation, which is not currently supported. For more information, see +"LIMITATIONS". +.PP +The following flags are currently defined for the \fIflags\fR argument: +.IP \fBSSL_POLL_FLAG_NO_HANDLE_EVENTS\fR 4 +.IX Item "SSL_POLL_FLAG_NO_HANDLE_EVENTS" +This flag indicates that internal state machine processing should not be +performed in an attempt to generate new readiness events. Only existing +readiness events will be reported. +.PP +The \fIresult_count\fR argument is optional. If it is non-NULL, it is used to +output the number of entries in the array which have nonzero \fIrevents\fR fields +when the call to \fBSSL_poll()\fR returns; see "RETURN VALUES" for details. +.SH "EVENT TYPES" +.IX Header "EVENT TYPES" +The \fBSSL_poll()\fR interface reports zero or more event types on a given resource, +represented by a bit mask. +.PP +All of the event types are level triggered and represent a readiness or +permanent exception condition; as such, after an event has been reported by +\&\fBSSL_poll()\fR for a resource, it will continue to be reported in future \fBSSL_poll()\fR +calls until the condition ceases to be in effect. A caller must mask the given +event type bit in future \fBSSL_poll()\fR calls if it does not wish to receive +repeated notifications and has not caused the underlying readiness condition +(for example, consuming all available data using \fBSSL_read_ex\fR\|(3) after +\&\fBSSL_POLL_EVENT_R\fR is reported) to be deasserted. +.PP +Some event types do not make sense on a given kind of resource. In this case, +specifying that event type in \fIevents\fR is a no-op and will be ignored, and the +given event will never be reported in \fIrevents\fR. +.PP +Failure of the polling mechanism itself is considered distinct from an exception +condition on a resource which was successfully polled. See \fBSSL_POLL_EVENT_F\fR +and "RETURN VALUES" for details. +.PP +In general, an application should always listen for the event types +corresponding to exception conditions if it is listening to the corresponding +non-exception event types (e.g. \fBSSL_POLL_EVENT_EC\fR and \fBSSL_POLL_EVENT_ER\fR +for \fBSSL_POLL_EVENT_R\fR), as not doing so is unlikely to be a sound design. +.PP +Some event types are non-maskable and may be reported in \fIrevents\fR regardless +of whether they were requested in \fIevents\fR. +.PP +The following event types are supported: +.IP \fBSSL_POLL_EVENT_F\fR 4 +.IX Item "SSL_POLL_EVENT_F" +Polling failure. This event is raised when a resource could not be polled. It is +distinct from an exception condition reported on a resource which was +successfully polled and represents a failure of the polling process itself in +relation to a resource. This may mean that \fBSSL_poll()\fR does not support the kind +of resource specified. +.Sp +Where this event is raised on at least one item in \fIitems\fR, \fBSSL_poll()\fR will +return 0 and the ERR stack will contain information pertaining to the first item +in \fIitems\fR with \fBSSL_POLL_EVENT_F\fR set. See "RETURN VALUES" for more +information. +.Sp +This event type may be raised even if it was not requested in \fIevents\fR; +specifying this event type in \fIevents\fR does nothing. +.IP \fBSSL_POLL_EVENT_EC\fR 4 +.IX Item "SSL_POLL_EVENT_EC" +Error at connection level. This event is raised when a connection has failed. +In particular, it is raised when a connection begins terminating. +.Sp +This event is never raised on objects which are not connections. +.IP \fBSSL_POLL_EVENT_DCD\fR 4 +.IX Item "SSL_POLL_EVENT_DCD" +Error at connection level (drained). This event is raised when a connection has +finished terminating, and has reached the terminated state. This event will +generally occur after an interval of time passes after the \fBSSL_POLL_EVENT_EC\fR +event is raised on a connection. +.Sp +This event is never raised on objects which are not connections. +.IP \fBSSL_POLL_EVENT_ER\fR 4 +.IX Item "SSL_POLL_EVENT_ER" +Error in read direction. For QUIC, this is raised only in the event that a +stream has a read part and that read part has been reset by the peer (for +example, using a \fBRESET_STREAM\fR frame). +.IP \fBSSL_POLL_EVENT_EW\fR 4 +.IX Item "SSL_POLL_EVENT_EW" +Error in write direction. For QUIC, this is raised only in the event that a +stream has a write part and that write part has been reset by the peer using a +\&\fBSTOP_SENDING\fR frame. +.IP \fBSSL_POLL_EVENT_R\fR 4 +.IX Item "SSL_POLL_EVENT_R" +Readable. This event is raised when a QUIC stream SSL object (or a QUIC +connection SSL object with a default stream attached) has application data +waiting to be read using \fBSSL_read_ex\fR\|(3), or a FIN event as represented by +\&\fBSSL_ERROR_ZERO_RETURN\fR waiting to be read. +.Sp +It is not raised in the event of the receiving part of the QUIC stream being +reset by the peer; see \fBSSL_POLL_EVENT_ER\fR. +.IP \fBSSL_POLL_EVENT_W\fR 4 +.IX Item "SSL_POLL_EVENT_W" +Writable. This event is raised when a QUIC stream SSL object (or a QUIC +connection SSL object with a default stream attached) could accept more +application data using \fBSSL_write_ex\fR\|(3). +.Sp +This event is never raised by a receive-only stream. +.Sp +This event is never raised by a stream which has had its send part concluded +normally (as with \fBSSL_stream_conclude\fR\|(3)) or locally reset (as with +\&\fBSSL_stream_reset\fR\|(3)). +.Sp +This event does not guarantee that a subsequent call to \fBSSL_write_ex\fR\|(3) will +succeed. +.IP \fBSSL_POLL_EVENT_ISB\fR 4 +.IX Item "SSL_POLL_EVENT_ISB" +This event, which is only raised by a QUIC connection SSL object, is raised when +one or more incoming bidirectional streams are available to be accepted using +\&\fBSSL_accept_stream\fR\|(3). +.IP \fBSSL_POLL_EVENT_ISU\fR 4 +.IX Item "SSL_POLL_EVENT_ISU" +This event, which is only raised by a QUIC connection SSL object, is raised when +one or more incoming unidirectional streams are available to be accepted using +\&\fBSSL_accept_stream\fR\|(3). +.IP \fBSSL_POLL_EVENT_OSB\fR 4 +.IX Item "SSL_POLL_EVENT_OSB" +This event, which is only raised by a QUIC connection SSL object, is raised when +QUIC stream creation flow control currently permits at least one additional +bidirectional stream to be locally created. +.IP \fBSSL_POLL_EVENT_OSU\fR 4 +.IX Item "SSL_POLL_EVENT_OSU" +This event, which is only raised by a QUIC connection SSL object, is raised when +QUIC stream creation flow control currently permits at least one additional +unidirectional stream to be locally created. +.SH LIMITATIONS +.IX Header "LIMITATIONS" +\&\fBSSL_poll()\fR as presently implemented has the following limitations: +.IP \(bu 4 +The implementation of \fBSSL_poll()\fR only supports nonblocking operation and +therefore requires the \fItimeout\fR argument be used to specify a zero timeout. +Calls to \fBSSL_poll()\fR which specify another value, or which pass \fItimeout\fR as +NULL, will fail. This does not allow waiting, but does allow multiple QUIC SSL +objects to be queried for their readiness state in a single call. +.Sp +Future releases will remove this limitation and support blocking \fBSSL_poll()\fR. +.IP \(bu 4 +Only \fBBIO_POLL_DESCRIPTOR\fR structures with type +\&\fBBIO_POLL_DESCRIPTOR_TYPE_SSL\fR, referencing QUIC connection SSL objects or QUIC +stream SSL objects, are supported. +.PP +These limitations will be revised in a future release of OpenSSL. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_poll()\fR returns 1 on success and 0 on failure. +.PP +Unless the \fIitems\fR pointer itself is invalid, \fBSSL_poll()\fR will always initialise +the \fIrevents\fR fields of all items in the input array upon returning, even if it +returns failure. +.PP +If \fIresult_count\fR is non-NULL, it is always written with the number of items in +the array with nonzero \fIrevents\fR fields, even if the \fBSSL_poll()\fR call returns +failure. +.PP +It is possible for \fIresult_count\fR to be written as 0 even if the \fBSSL_poll()\fR +call returns success, namely if no events were output but the polling process +was successful (e.g. in nonblocking usage) or timed out. +.PP +It is possible for \fIresult_count\fR to be written as a nonzero value if the +\&\fBSSL_poll()\fR call returns failure, for example due to \fBSSL_POLL_EVENT_F\fR events, +or because some events were detected and output before encountering a failure +condition while processing a subsequent entry in the \fIitems\fR array. +.PP +If at least one \fBSSL_POLL_EVENT_F\fR event is output, \fBSSL_poll()\fR is guaranteed +to return 0 and guaranteed to place at least one ERR on the error stack +describing the first \fBSSL_POLL_EVENT_F\fR output. Detailed information on any +additional \fBSSL_POLL_EVENT_F\fR events is not available. \fBSSL_poll()\fR may or may +not return more than one \fBSSL_POLL_EVENT_F\fR event at once. +.PP +"Normal" events representing exceptional I/O conditions which do not +constitute a failure of the \fBSSL_poll()\fR mechanism itself are not considered +errors by \fBSSL_poll()\fR and are instead represented using their own event type; see +"EVENT TYPES" for details. +.PP +The caller can establish the meaning of the \fBSSL_poll()\fR return and output values +as follows: +.IP \(bu 4 +If \fBSSL_poll()\fR returns 1 and \fIresult_count\fR is zero, the operation timed out +before any resource was ready. +.IP \(bu 4 +If \fBSSL_poll()\fR returns 1 and \fIresult_count\fR is nonzero, that many events were +output. +.IP \(bu 4 +If \fBSSL_poll()\fR returns 0 and \fIresult_count\fR is zero, the caller has made a basic +usage error; check the ERR stack for details. +.IP \(bu 4 +If \fBSSL_poll()\fR returns 0 and \fIresult_count\fR is nonzero, inspect the \fIitems\fR +array for \fBSSL_POLL_ITEM\fR structures with the \fBSSL_POLL_EVENT_F\fR event type +raised in \fIrevents\fR. The entries added to the ERR stack (of which there is +guaranteed to be at least one) reflect the cause of the failure of the first +item in \fIitems\fR with \fBSSL_POLL_EVENT_F\fR raised. Note that there may be events +other than \fISSL_POLL_EVENT_F\fR output for items which come before the first +item with \fBSSL_POLL_EVENT_F\fR raised, and additional \fBSSL_POLL_EVENT_F\fR +events may or may not have been output, both of which which will be reflected in +\&\fIresult_count\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBBIO_get_rpoll_descriptor\fR\|(3), \fBBIO_get_wpoll_descriptor\fR\|(3), +\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +\&\fBSSL_poll()\fR was added in OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. |