Debian Codegraph @

upstream/debian-unstable/man3/SSL_pending.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_PENDING 3SSL"
58 .TH SSL_PENDING 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_pending, SSL_has_pending \- check for readable bytes buffered in an
65 SSL object
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 1
69 \& #include <openssl/ssl.h>
70 \&
71 \& int SSL_pending(const SSL *ssl);
72 \& int SSL_has_pending(const SSL *s);
73 .Ve
74 .SH DESCRIPTION
75 .IX Header "DESCRIPTION"
76 Data is received in whole blocks known as records from the peer. A whole record
77 is processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is
78 read by the application via a call to \fBSSL_read_ex\fR\|(3) or \fBSSL_read\fR\|(3).
79 .PP
80 \&\fBSSL_pending()\fR returns the number of bytes which have been processed, buffered
81 and are available inside \fBssl\fR for immediate read.
82 .PP
83 If the \fBSSL\fR object's \fIread_ahead\fR flag is set (see
84 \&\fBSSL_CTX_set_read_ahead\fR\|(3)), additional protocol bytes (beyond the current
85 record) may have been read containing more TLS/SSL records. This also applies to
86 DTLS and pipelining (see \fBSSL_CTX_set_split_send_fragment\fR\|(3)). These
87 additional bytes will be buffered by OpenSSL but will remain unprocessed until
88 they are needed. As these bytes are still in an unprocessed state \fBSSL_pending()\fR
89 will ignore them. Therefore, it is possible for no more bytes to be readable from
90 the underlying BIO (because OpenSSL has already read them) and for \fBSSL_pending()\fR
91 to return 0, even though readable application data bytes are available (because
92 the data is in unprocessed buffered records).
93 .PP
94 \&\fBSSL_has_pending()\fR returns 1 if \fBs\fR has buffered data (whether processed or
95 unprocessed) and 0 otherwise. Note that it is possible for \fBSSL_has_pending()\fR to
96 return 1, and then a subsequent call to \fBSSL_read_ex()\fR or \fBSSL_read()\fR to return no
97 data because the unprocessed buffered data when processed yielded no application
98 data (for example this can happen during renegotiation). It is also possible in
99 this scenario for \fBSSL_has_pending()\fR to continue to return 1 even after an
100 \&\fBSSL_read_ex()\fR or \fBSSL_read()\fR call because the buffered and unprocessed data is
101 not yet processable (e.g. because OpenSSL has only received a partial record so
102 far).
103 .SH "RETURN VALUES"
104 .IX Header "RETURN VALUES"
105 \&\fBSSL_pending()\fR returns the number of buffered and processed application data
106 bytes that are pending and are available for immediate read. \fBSSL_has_pending()\fR
107 returns 1 if there is buffered record data in the SSL object and 0 otherwise.
108 .SH "SEE ALSO"
109 .IX Header "SEE ALSO"
110 \&\fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3), \fBSSL_CTX_set_read_ahead\fR\|(3),
111 \&\fBSSL_CTX_set_split_send_fragment\fR\|(3), \fBssl\fR\|(7)
112 .SH HISTORY
113 .IX Header "HISTORY"
114 The \fBSSL_has_pending()\fR function was added in OpenSSL 1.1.0.
115 .SH COPYRIGHT
116 .IX Header "COPYRIGHT"
117 Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
118 .PP
119 Licensed under the Apache License 2.0 (the "License"). You may not use
120 this file except in compliance with the License. You can obtain a copy
121 in the file LICENSE in the source distribution or at
122 <https://www.openssl.org/source/license.html>.