Debian Codegraph @

upstream/debian-unstable/man3/SSL_get_rpoll_descriptor.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_GET_RPOLL_DESCRIPTOR 3SSL"
58 .TH SSL_GET_RPOLL_DESCRIPTOR 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_get_rpoll_descriptor, SSL_get_wpoll_descriptor, SSL_net_read_desired,
65 SSL_net_write_desired \- obtain information which can be used to determine when
66 network I/O can be performed
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/ssl.h>
71 \&
72 \& int SSL_get_rpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc);
73 \& int SSL_get_wpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc);
74 \& int SSL_net_read_desired(SSL *s);
75 \& int SSL_net_write_desired(SSL *s);
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 The functions \fBSSL_get_rpoll_descriptor()\fR and \fBSSL_get_wpoll_descriptor()\fR can be
80 used to determine when an SSL object which represents a QUIC connection can
81 perform useful network I/O, so that an application using a QUIC connection SSL
82 object in nonblocking mode can determine when it should call \fBSSL_handle_events()\fR.
83 .PP
84 On success, these functions output poll descriptors. For more information on
85 poll descriptors, see \fBBIO_get_rpoll_descriptor\fR\|(3).
86 .PP
87 The functions \fBSSL_net_read_desired()\fR and \fBSSL_net_write_desired()\fR return 1 or 0
88 depending on whether the SSL object is currently interested in receiving data
89 from the network and/or writing data to the network respectively.
90 If an SSL object is not interested in reading data from the network at the
91 current time, \fBSSL_net_read_desired()\fR will return 0; likewise, if an SSL object is
92 not interested in writing data to the network at the current time,
93 \&\fBSSL_net_write_desired()\fR will return 0.
94 .PP
95 The intention is that an application using QUIC in nonblocking mode can use
96 these calls, in conjunction with \fBSSL_get_event_timeout\fR\|(3) to wait for network
97 I/O conditions which allow the SSL object to perform useful work. When such a
98 condition arises, \fBSSL_handle_events\fR\|(3) should be called.
99 .PP
100 In particular, the expected usage is as follows:
101 .IP \(bu 4
102 \&\fBSSL_handle_events()\fR should be called whenever the timeout returned by
103 \&\fBSSL_get_event_timeout\fR\|(3) (if any) expires
104 .IP \(bu 4
105 If the last call to \fBSSL_net_read_desired()\fR returned 1, \fBSSL_handle_events()\fR should be called
106 whenever the poll descriptor output by \fBSSL_get_rpoll_descriptor()\fR becomes
107 readable.
108 .IP \(bu 4
109 If the last call to \fBSSL_net_write_desired()\fR returned 1, \fBSSL_handle_events()\fR should be called
110 whenever the poll descriptor output by \fBSSL_get_wpoll_descriptor()\fR becomes
111 writable.
112 .PP
113 The return values of the \fBSSL_net_read_desired()\fR and \fBSSL_net_write_desired()\fR functions
114 may change in response to any call to the SSL object other than
115 \&\fBSSL_net_read_desired()\fR, \fBSSL_net_write_desired()\fR, \fBSSL_get_rpoll_descriptor()\fR,
116 \&\fBSSL_get_wpoll_descriptor()\fR and \fBSSL_get_event_timeout()\fR.
117 .PP
118 On non-QUIC SSL objects, calls to \fBSSL_get_rpoll_descriptor()\fR and
119 \&\fBSSL_get_wpoll_descriptor()\fR function the same as calls to
120 \&\fBBIO_get_rpoll_descriptor()\fR and \fBBIO_get_wpoll_descriptor()\fR on the respective read
121 and write BIOs configured on the SSL object.
122 .PP
123 On non-QUIC SSL objects, calls to \fBSSL_net_read_desired()\fR and
124 \&\fBSSL_net_write_desired()\fR function identically to calls to \fBSSL_want_read()\fR and
125 \&\fBSSL_want_write()\fR respectively.
126 .SH "RETURN VALUES"
127 .IX Header "RETURN VALUES"
128 These functions return 1 on success and 0 on failure.
129 .SH "SEE ALSO"
130 .IX Header "SEE ALSO"
131 \&\fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3), \fBssl\fR\|(7)
132 .SH HISTORY
133 .IX Header "HISTORY"
134 The \fBSSL_get_rpoll_descriptor()\fR, \fBSSL_get_wpoll_descriptor()\fR, \fBSSL_net_read_desired()\fR
135 and \fBSSL_net_write_desired()\fR functions were added in OpenSSL 3.2.
136 .SH COPYRIGHT
137 .IX Header "COPYRIGHT"
138 Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved.
139 .PP
140 Licensed under the Apache License 2.0 (the "License"). You may not use
141 this file except in compliance with the License. You can obtain a copy
142 in the file LICENSE in the source distribution or at
143 <https://www.openssl.org/source/license.html>.