secure/lib/libcrypto/man/SSL_read.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_READ 3"
 132 .TH SSL_READ 3 "2018-09-11" "1.1.1" "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_read_ex, SSL_read, SSL_peek_ex, SSL_peek \&\- read bytes from a TLS/SSL connection
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& int SSL_read_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes);
 145 \& int SSL_read(SSL *ssl, void *buf, int num);
 146 \&
 147 \& int SSL_peek_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes);
 148 \& int SSL_peek(SSL *ssl, void *buf, int num);
 149 .Ve
 150 .SH "DESCRIPTION"
 151 .IX Header "DESCRIPTION"
 152 \&\fISSL_read_ex()\fR and \fISSL_read()\fR try to read \fBnum\fR bytes from the specified \fBssl\fR
 153 into the buffer \fBbuf\fR. On success \fISSL_read_ex()\fR will store the number of bytes
 154 actually read in \fB*readbytes\fR.
 155 .PP
 156 \&\fISSL_peek_ex()\fR and \fISSL_peek()\fR are identical to \fISSL_read_ex()\fR and \fISSL_read()\fR
 157 respectively except no bytes are actually removed from the underlying \s-1BIO\s0 during
 158 the read, so that a subsequent call to \fISSL_read_ex()\fR or \fISSL_read()\fR will yield
 159 at least the same bytes.
 160 .SH "NOTES"
 161 .IX Header "NOTES"
 162 In the paragraphs below a \*(L"read function\*(R" is defined as one of \fISSL_read_ex()\fR,
 163 \&\fISSL_read()\fR, \fISSL_peek_ex()\fR or \fISSL_peek()\fR.
 164 .PP
 165 If necessary, a read function will negotiate a \s-1TLS/SSL\s0 session, if not already
 166 explicitly performed by \fISSL_connect\fR\|(3) or \fISSL_accept\fR\|(3). If the
 167 peer requests a re-negotiation, it will be performed transparently during
 168 the read function operation. The behaviour of the read functions depends on the
 169 underlying \s-1BIO.\s0
 170 .PP
 171 For the transparent negotiation to succeed, the \fBssl\fR must have been
 172 initialized to client or server mode. This is being done by calling
 173 \&\fISSL_set_connect_state\fR\|(3) or \fISSL_set_accept_state()\fR before the first
 174 invocation of a read function.
 175 .PP
 176 The read functions work based on the \s-1SSL/TLS\s0 records. The data are received in
 177 records (with a maximum record size of 16kB). Only when a record has been
 178 completely received, can it be processed (decryption and check of integrity).
 179 Therefore data that was not retrieved at the last read call can still be
 180 buffered inside the \s-1SSL\s0 layer and will be retrieved on the next read
 181 call. If \fBnum\fR is higher than the number of bytes buffered then the read
 182 functions will return with the bytes buffered. If no more bytes are in the
 183 buffer, the read functions will trigger the processing of the next record.
 184 Only when the record has been received and processed completely will the read
 185 functions return reporting success. At most the contents of one record will
 186 be returned. As the size of an \s-1SSL/TLS\s0 record may exceed the maximum packet size
 187 of the underlying transport (e.g. \s-1TCP\s0), it may be necessary to read several
 188 packets from the transport layer before the record is complete and the read call
 189 can succeed.
 190 .PP
 191 If \fB\s-1SSL_MODE_AUTO_RETRY\s0\fR has been switched off and a non-application data
 192 record has been processed, the read function can return and set the error to
 193 \&\fB\s-1SSL_ERROR_WANT_READ\s0\fR.
 194 In this case there might still be unprocessed data available in the \fB\s-1BIO\s0\fR.
 195 If read ahead was set using \fISSL_CTX_set_read_ahead\fR\|(3), there might also still
 196 be unprocessed data available in the \fB\s-1SSL\s0\fR.
 197 This behaviour can be controlled using the \fISSL_CTX_set_mode\fR\|(3) call.
 198 .PP
 199 If the underlying \s-1BIO\s0 is \fBblocking\fR, a read function will only return once the
 200 read operation has been finished or an error occurred, except when a
 201 non-application data record has been processed and \fB\s-1SSL_MODE_AUTO_RETRY\s0\fR is
 202 not set.
 203 Note that if \fB\s-1SSL_MODE_AUTO_RETRY\s0\fR is set and only non-application data is
 204 available the call will hang.
 205 .PP
 206 If the underlying \s-1BIO\s0 is \fBnon-blocking\fR, a read function will also return when
 207 the underlying \s-1BIO\s0 could not satisfy the needs of the function to continue the
 208 operation.
 209 In this case a call to \fISSL_get_error\fR\|(3) with the
 210 return value of the read function will yield \fB\s-1SSL_ERROR_WANT_READ\s0\fR or
 211 \&\fB\s-1SSL_ERROR_WANT_WRITE\s0\fR.
 212 As at any time it's possible that non-application data needs to be sent,
 213 a read function can also cause write operations.
 214 The calling process then must repeat the call after taking appropriate action
 215 to satisfy the needs of the read function.
 216 The action depends on the underlying \s-1BIO.\s0
 217 When using a non-blocking socket, nothing is to be done, but \fIselect()\fR can be
 218 used to check for the required condition.
 219 When using a buffering \s-1BIO,\s0 like a \s-1BIO\s0 pair, data must be written into or
 220 retrieved out of the \s-1BIO\s0 before being able to continue.
 221 .PP
 222 \&\fISSL_pending\fR\|(3) can be used to find out whether there
 223 are buffered bytes available for immediate retrieval.
 224 In this case the read function can be called without blocking or actually
 225 receiving new data from the underlying socket.
 226 .SH "RETURN VALUES"
 227 .IX Header "RETURN VALUES"
 228 \&\fISSL_read_ex()\fR and \fISSL_peek_ex()\fR will return 1 for success or 0 for failure.
 229 Success means that 1 or more application data bytes have been read from the \s-1SSL\s0
 230 connection.
 231 Failure means that no bytes could be read from the \s-1SSL\s0 connection.
 232 Failures can be retryable (e.g. we are waiting for more bytes to
 233 be delivered by the network) or non-retryable (e.g. a fatal network error).
 234 In the event of a failure call \fISSL_get_error\fR\|(3) to find out the reason which
 235 indicates whether the call is retryable or not.
 236 .PP
 237 For \fISSL_read()\fR and \fISSL_peek()\fR the following return values can occur:
 238 .IP "> 0" 4
 239 .IX Item "> 0"
 240 The read operation was successful.
 241 The return value is the number of bytes actually read from the \s-1TLS/SSL\s0
 242 connection.
 243 .IP "<= 0" 4
 244 .IX Item "<= 0"
 245 The read operation was not successful, because either the connection was closed,
 246 an error occurred or action must be taken by the calling process.
 247 Call \fISSL_get_error\fR\|(3) with the return value \fBret\fR to find out the reason.
 248 .Sp
 249 Old documentation indicated a difference between 0 and \-1, and that \-1 was
 250 retryable.
 251 You should instead call \fISSL_get_error()\fR to find out if it's retryable.
 252 .SH "HISTORY"
 253 .IX Header "HISTORY"
 254 \&\fISSL_read_ex()\fR and \fISSL_peek_ex()\fR were added in OpenSSL 1.1.1.
 255 .SH "SEE ALSO"
 256 .IX Header "SEE ALSO"
 257 \&\fISSL_get_error\fR\|(3), \fISSL_write_ex\fR\|(3),
 258 \&\fISSL_CTX_set_mode\fR\|(3), \fISSL_CTX_new\fR\|(3),
 259 \&\fISSL_connect\fR\|(3), \fISSL_accept\fR\|(3)
 260 \&\fISSL_set_connect_state\fR\|(3),
 261 \&\fISSL_pending\fR\|(3),
 262 \&\fISSL_shutdown\fR\|(3), \fISSL_set_shutdown\fR\|(3),
 263 \&\fIssl\fR\|(7), \fIbio\fR\|(7)
 264 .SH "COPYRIGHT"
 265 .IX Header "COPYRIGHT"
 266 Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
 267 .PP
 268 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 269 this file except in compliance with the License.  You can obtain a copy
 270 in the file \s-1LICENSE\s0 in the source distribution or at
 271 <https://www.openssl.org/source/license.html>.