1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
.\" -*- 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_GET_RPOLL_DESCRIPTOR 3SSL"
.TH SSL_GET_RPOLL_DESCRIPTOR 3SSL 2024-04-04 3.2.2-dev 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_get_rpoll_descriptor, SSL_get_wpoll_descriptor, SSL_net_read_desired,
SSL_net_write_desired \- obtain information which can be used to determine when
network I/O can be performed
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/ssl.h>
\&
\& int SSL_get_rpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc);
\& int SSL_get_wpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc);
\& int SSL_net_read_desired(SSL *s);
\& int SSL_net_write_desired(SSL *s);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The functions \fBSSL_get_rpoll_descriptor()\fR and \fBSSL_get_wpoll_descriptor()\fR can be
used to determine when an SSL object which represents a QUIC connection can
perform useful network I/O, so that an application using a QUIC connection SSL
object in nonblocking mode can determine when it should call \fBSSL_handle_events()\fR.
.PP
On success, these functions output poll descriptors. For more information on
poll descriptors, see \fBBIO_get_rpoll_descriptor\fR\|(3).
.PP
The functions \fBSSL_net_read_desired()\fR and \fBSSL_net_write_desired()\fR return 1 or 0
depending on whether the SSL object is currently interested in receiving data
from the network and/or writing data to the network respectively.
If an SSL object is not interested in reading data from the network at the
current time, \fBSSL_net_read_desired()\fR will return 0; likewise, if an SSL object is
not interested in writing data to the network at the current time,
\&\fBSSL_net_write_desired()\fR will return 0.
.PP
The intention is that an application using QUIC in nonblocking mode can use
these calls, in conjunction with \fBSSL_get_event_timeout\fR\|(3) to wait for network
I/O conditions which allow the SSL object to perform useful work. When such a
condition arises, \fBSSL_handle_events\fR\|(3) should be called.
.PP
In particular, the expected usage is as follows:
.IP \(bu 4
\&\fBSSL_handle_events()\fR should be called whenever the timeout returned by
\&\fBSSL_get_event_timeout\fR\|(3) (if any) expires
.IP \(bu 4
If the last call to \fBSSL_net_read_desired()\fR returned 1, \fBSSL_handle_events()\fR should be called
whenever the poll descriptor output by \fBSSL_get_rpoll_descriptor()\fR becomes
readable.
.IP \(bu 4
If the last call to \fBSSL_net_write_desired()\fR returned 1, \fBSSL_handle_events()\fR should be called
whenever the poll descriptor output by \fBSSL_get_wpoll_descriptor()\fR becomes
writable.
.PP
The return values of the \fBSSL_net_read_desired()\fR and \fBSSL_net_write_desired()\fR functions
may change in response to any call to the SSL object other than
\&\fBSSL_net_read_desired()\fR, \fBSSL_net_write_desired()\fR, \fBSSL_get_rpoll_descriptor()\fR,
\&\fBSSL_get_wpoll_descriptor()\fR and \fBSSL_get_event_timeout()\fR.
.PP
On non-QUIC SSL objects, calls to \fBSSL_get_rpoll_descriptor()\fR and
\&\fBSSL_get_wpoll_descriptor()\fR function the same as calls to
\&\fBBIO_get_rpoll_descriptor()\fR and \fBBIO_get_wpoll_descriptor()\fR on the respective read
and write BIOs configured on the SSL object.
.PP
On non-QUIC SSL objects, calls to \fBSSL_net_read_desired()\fR and
\&\fBSSL_net_write_desired()\fR function identically to calls to \fBSSL_want_read()\fR and
\&\fBSSL_want_write()\fR respectively.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
These functions return 1 on success and 0 on failure.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3), \fBssl\fR\|(7)
.SH HISTORY
.IX Header "HISTORY"
The \fBSSL_get_rpoll_descriptor()\fR, \fBSSL_get_wpoll_descriptor()\fR, \fBSSL_net_read_desired()\fR
and \fBSSL_net_write_desired()\fR functions were added in OpenSSL 3.2.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2022\-2023 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>.
|
