secure/lib/libcrypto/man/SSL_pending.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_PENDING 3"
 132 .TH SSL_PENDING 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 SSL_pending, SSL_has_pending \- check for readable bytes buffered in an SSL object
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& int SSL_pending(const SSL *ssl);
 145 \& int SSL_has_pending(const SSL *s);
 146 .Ve
 147 .SH "DESCRIPTION"
 148 .IX Header "DESCRIPTION"
 149 Data is received in whole blocks known as records from the peer. A whole record
 150 is processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is
 151 read by the application via a call to \fISSL_read_ex\fR\|(3) or \fISSL_read\fR\|(3).
 152 .PP
 153 \&\fISSL_pending()\fR returns the number of bytes which have been processed, buffered
 154 and are available inside \fBssl\fR for immediate read.
 155 .PP
 156 If the \fB\s-1SSL\s0\fR object's \fIread_ahead\fR flag is set (see
 157 \&\fISSL_CTX_set_read_ahead\fR\|(3)), additional protocol bytes (beyond the current
 158 record) may have been read containing more \s-1TLS/SSL\s0 records. This also applies to
 159 \&\s-1DTLS\s0 and pipelining (see \fISSL_CTX_set_split_send_fragment\fR\|(3)). These
 160 additional bytes will be buffered by OpenSSL but will remain unprocessed until
 161 they are needed. As these bytes are still in an unprocessed state \fISSL_pending()\fR
 162 will ignore them. Therefore it is possible for no more bytes to be readable from
 163 the underlying \s-1BIO\s0 (because OpenSSL has already read them) and for \fISSL_pending()\fR
 164 to return 0, even though readable application data bytes are available (because
 165 the data is in unprocessed buffered records).
 166 .PP
 167 \&\fISSL_has_pending()\fR returns 1 if \fBs\fR has buffered data (whether processed or
 168 unprocessed) and 0 otherwise. Note that it is possible for \fISSL_has_pending()\fR to
 169 return 1, and then a subsequent call to \fISSL_read_ex()\fR or \fISSL_read()\fR to return no
 170 data because the unprocessed buffered data when processed yielded no application
 171 data (for example this can happen during renegotiation). It is also possible in
 172 this scenario for \fISSL_has_pending()\fR to continue to return 1 even after an
 173 \&\fISSL_read_ex()\fR or \fISSL_read()\fR call because the buffered and unprocessed data is
 174 not yet processable (e.g. because OpenSSL has only received a partial record so
 175 far).
 176 .SH "RETURN VALUES"
 177 .IX Header "RETURN VALUES"
 178 \&\fISSL_pending()\fR returns the number of buffered and processed application data
 179 bytes that are pending and are available for immediate read. \fISSL_has_pending()\fR
 180 returns 1 if there is buffered record data in the \s-1SSL\s0 object and 0 otherwise.
 181 .SH "SEE ALSO"
 182 .IX Header "SEE ALSO"
 183 \&\fISSL_read_ex\fR\|(3), \fISSL_read\fR\|(3), \fISSL_CTX_set_read_ahead\fR\|(3),
 184 \&\fISSL_CTX_set_split_send_fragment\fR\|(3), \fIssl\fR\|(7)
 185 .SH "HISTORY"
 186 .IX Header "HISTORY"
 187 The \fISSL_has_pending()\fR function was added in OpenSSL 1.1.0.
 188 .SH "COPYRIGHT"
 189 .IX Header "COPYRIGHT"
 190 Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
 191 .PP
 192 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 193 this file except in compliance with the License.  You can obtain a copy
 194 in the file \s-1LICENSE\s0 in the source distribution or at
 195 <https://www.openssl.org/source/license.html>.