secure/lib/libcrypto/man/man3/SSL_read.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   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 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_READ 3"
 136 .TH SSL_READ 3 "2022-05-03" "1.1.1o" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SSL_read_ex, SSL_read, SSL_peek_ex, SSL_peek \&\- read bytes from a TLS/SSL connection
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& int SSL_read_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes);
 149 \& int SSL_read(SSL *ssl, void *buf, int num);
 150 \&
 151 \& int SSL_peek_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes);
 152 \& int SSL_peek(SSL *ssl, void *buf, int num);
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 \&\fBSSL_read_ex()\fR and \fBSSL_read()\fR try to read \fBnum\fR bytes from the specified \fBssl\fR
 157 into the buffer \fBbuf\fR. On success \fBSSL_read_ex()\fR will store the number of bytes
 158 actually read in \fB*readbytes\fR.
 159 .PP
 160 \&\fBSSL_peek_ex()\fR and \fBSSL_peek()\fR are identical to \fBSSL_read_ex()\fR and \fBSSL_read()\fR
 161 respectively except no bytes are actually removed from the underlying \s-1BIO\s0 during
 162 the read, so that a subsequent call to \fBSSL_read_ex()\fR or \fBSSL_read()\fR will yield
 163 at least the same bytes.
 164 .SH "NOTES"
 165 .IX Header "NOTES"
 166 In the paragraphs below a \*(L"read function\*(R" is defined as one of \fBSSL_read_ex()\fR,
 167 \&\fBSSL_read()\fR, \fBSSL_peek_ex()\fR or \fBSSL_peek()\fR.
 168 .PP
 169 If necessary, a read function will negotiate a \s-1TLS/SSL\s0 session, if not already
 170 explicitly performed by \fBSSL_connect\fR\|(3) or \fBSSL_accept\fR\|(3). If the
 171 peer requests a re-negotiation, it will be performed transparently during
 172 the read function operation. The behaviour of the read functions depends on the
 173 underlying \s-1BIO.\s0
 174 .PP
 175 For the transparent negotiation to succeed, the \fBssl\fR must have been
 176 initialized to client or server mode. This is being done by calling
 177 \&\fBSSL_set_connect_state\fR\|(3) or \fBSSL_set_accept_state()\fR before the first
 178 invocation of a read function.
 179 .PP
 180 The read functions work based on the \s-1SSL/TLS\s0 records. The data are received in
 181 records (with a maximum record size of 16kB). Only when a record has been
 182 completely received, can it be processed (decryption and check of integrity).
 183 Therefore, data that was not retrieved at the last read call can still be
 184 buffered inside the \s-1SSL\s0 layer and will be retrieved on the next read
 185 call. If \fBnum\fR is higher than the number of bytes buffered then the read
 186 functions will return with the bytes buffered. If no more bytes are in the
 187 buffer, the read functions will trigger the processing of the next record.
 188 Only when the record has been received and processed completely will the read
 189 functions return reporting success. At most the contents of one record will
 190 be returned. As the size of an \s-1SSL/TLS\s0 record may exceed the maximum packet size
 191 of the underlying transport (e.g. \s-1TCP\s0), it may be necessary to read several
 192 packets from the transport layer before the record is complete and the read call
 193 can succeed.
 194 .PP
 195 If \fB\s-1SSL_MODE_AUTO_RETRY\s0\fR has been switched off and a non-application data
 196 record has been processed, the read function can return and set the error to
 197 \&\fB\s-1SSL_ERROR_WANT_READ\s0\fR.
 198 In this case there might still be unprocessed data available in the \fB\s-1BIO\s0\fR.
 199 If read ahead was set using \fBSSL_CTX_set_read_ahead\fR\|(3), there might also still
 200 be unprocessed data available in the \fB\s-1SSL\s0\fR.
 201 This behaviour can be controlled using the \fBSSL_CTX_set_mode\fR\|(3) call.
 202 .PP
 203 If the underlying \s-1BIO\s0 is \fBblocking\fR, a read function will only return once the
 204 read operation has been finished or an error occurred, except when a
 205 non-application data record has been processed and \fB\s-1SSL_MODE_AUTO_RETRY\s0\fR is
 206 not set.
 207 Note that if \fB\s-1SSL_MODE_AUTO_RETRY\s0\fR is set and only non-application data is
 208 available the call will hang.
 209 .PP
 210 If the underlying \s-1BIO\s0 is \fBnonblocking\fR, a read function will also return when
 211 the underlying \s-1BIO\s0 could not satisfy the needs of the function to continue the
 212 operation.
 213 In this case a call to \fBSSL_get_error\fR\|(3) with the
 214 return value of the read function will yield \fB\s-1SSL_ERROR_WANT_READ\s0\fR or
 215 \&\fB\s-1SSL_ERROR_WANT_WRITE\s0\fR.
 216 As at any time it's possible that non-application data needs to be sent,
 217 a read function can also cause write operations.
 218 The calling process then must repeat the call after taking appropriate action
 219 to satisfy the needs of the read function.
 220 The action depends on the underlying \s-1BIO.\s0
 221 When using a nonblocking socket, nothing is to be done, but \fBselect()\fR can be
 222 used to check for the required condition.
 223 When using a buffering \s-1BIO,\s0 like a \s-1BIO\s0 pair, data must be written into or
 224 retrieved out of the \s-1BIO\s0 before being able to continue.
 225 .PP
 226 \&\fBSSL_pending\fR\|(3) can be used to find out whether there
 227 are buffered bytes available for immediate retrieval.
 228 In this case the read function can be called without blocking or actually
 229 receiving new data from the underlying socket.
 230 .SH "RETURN VALUES"
 231 .IX Header "RETURN VALUES"
 232 \&\fBSSL_read_ex()\fR and \fBSSL_peek_ex()\fR will return 1 for success or 0 for failure.
 233 Success means that 1 or more application data bytes have been read from the \s-1SSL\s0
 234 connection.
 235 Failure means that no bytes could be read from the \s-1SSL\s0 connection.
 236 Failures can be retryable (e.g. we are waiting for more bytes to
 237 be delivered by the network) or non-retryable (e.g. a fatal network error).
 238 In the event of a failure call \fBSSL_get_error\fR\|(3) to find out the reason which
 239 indicates whether the call is retryable or not.
 240 .PP
 241 For \fBSSL_read()\fR and \fBSSL_peek()\fR the following return values can occur:
 242 .IP "> 0" 4
 243 .IX Item "> 0"
 244 The read operation was successful.
 245 The return value is the number of bytes actually read from the \s-1TLS/SSL\s0
 246 connection.
 247 .IP "<= 0" 4
 248 .IX Item "<= 0"
 249 The read operation was not successful, because either the connection was closed,
 250 an error occurred or action must be taken by the calling process.
 251 Call \fBSSL_get_error\fR\|(3) with the return value \fBret\fR to find out the reason.
 252 .Sp
 253 Old documentation indicated a difference between 0 and \-1, and that \-1 was
 254 retryable.
 255 You should instead call \fBSSL_get_error()\fR to find out if it's retryable.
 256 .SH "SEE ALSO"
 257 .IX Header "SEE ALSO"
 258 \&\fBSSL_get_error\fR\|(3), \fBSSL_write_ex\fR\|(3),
 259 \&\fBSSL_CTX_set_mode\fR\|(3), \fBSSL_CTX_new\fR\|(3),
 260 \&\fBSSL_connect\fR\|(3), \fBSSL_accept\fR\|(3)
 261 \&\fBSSL_set_connect_state\fR\|(3),
 262 \&\fBSSL_pending\fR\|(3),
 263 \&\fBSSL_shutdown\fR\|(3), \fBSSL_set_shutdown\fR\|(3),
 264 \&\fBssl\fR\|(7), \fBbio\fR\|(7)
 265 .SH "HISTORY"
 266 .IX Header "HISTORY"
 267 The \fBSSL_read_ex()\fR and \fBSSL_peek_ex()\fR functions were added in OpenSSL 1.1.1.
 268 .SH "COPYRIGHT"
 269 .IX Header "COPYRIGHT"
 270 Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
 271 .PP
 272 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 273 this file except in compliance with the License.  You can obtain a copy
 274 in the file \s-1LICENSE\s0 in the source distribution or at
 275 <https://www.openssl.org/source/license.html>.