secure/lib/libssl/man/SSL_read.3

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  34 '''
  35 '''
  36 '''     Set up \*(-- to give an unbreakable dash;
  37 '''     string Tr holds user defined translation string.
  38 '''     Bell System Logo is used as a dummy character.
  39 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  42 .ds -- \(*W-
  43 .ds PI pi
  44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  46 .ds L" ""
  47 .ds R" ""
  48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  50 '''   such as .IP and .SH, which do another additional levels of
  51 '''   double-quote interpretation
  52 .ds M" """
  53 .ds S" """
  54 .ds N" """""
  55 .ds T" """""
  56 .ds L' '
  57 .ds R' '
  58 .ds M' '
  59 .ds S' '
  60 .ds N' '
  61 .ds T' '
  62 'br\}
  63 .el\{\
  64 .ds -- \(em\|
  65 .tr \*(Tr
  66 .ds L" ``
  67 .ds R" ''
  68 .ds M" ``
  69 .ds S" ''
  70 .ds N" ``
  71 .ds T" ''
  72 .ds L' `
  73 .ds R' '
  74 .ds M' `
  75 .ds S' '
  76 .ds N' `
  77 .ds T' '
  78 .ds PI \(*p
  79 'br\}
  80 .\"     If the F register is turned on, we'll generate
  81 .\"     index entries out stderr for the following things:
  82 .\"             TH      Title
  83 .\"             SH      Header
  84 .\"             Sh      Subsection
  85 .\"             Ip      Item
  86 .\"             X<>     Xref  (embedded
  87 .\"     Of course, you have to process the output yourself
  88 .\"     in some meaninful fashion.
  89 .if \nF \{
  90 .de IX
  91 .tm Index:\\$1\t\\n%\t"\\$2"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH SSL_read 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 101 .de CQ          \" put $1 in typewriter font
 102 .ft CW
 103 'if n "\c
 104 'if t \\&\\$1\c
 105 'if n \\&\\$1\c
 106 'if n \&"
 107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 108 '.ft R
 109 ..
 110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 111 .       \" AM - accent mark definitions
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 163 .ds ae a\h'-(\w'a'u*4/10)'e
 164 .ds Ae A\h'-(\w'A'u*4/10)'E
 165 .ds oe o\h'-(\w'o'u*4/10)'e
 166 .ds Oe O\h'-(\w'O'u*4/10)'E
 167 .       \" corrections for vroff
 168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 173 .       ds : e
 174 .       ds 8 ss
 175 .       ds v \h'-1'\o'\(aa\(ga'
 176 .       ds _ \h'-1'^
 177 .       ds . \h'-1'.
 178 .       ds 3 3
 179 .       ds o a
 180 .       ds d- d\h'-1'\(ga
 181 .       ds D- D\h'-1'\(hy
 182 .       ds th \o'bp'
 183 .       ds Th \o'LP'
 184 .       ds ae ae
 185 .       ds Ae AE
 186 .       ds oe oe
 187 .       ds Oe OE
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 SSL_read \- read bytes from a TLS/SSL connection.
 192 .SH "SYNOPSIS"
 193 .PP
 194 .Vb 1
 195 \& #include <openssl/ssl.h>
 196 .Ve
 197 .Vb 1
 198 \& int SSL_read(SSL *ssl, void *buf, int num);
 199 .Ve
 200 .SH "DESCRIPTION"
 201 \fISSL_read()\fR tries to read \fBnum\fR bytes from the specified \fBssl\fR into the
 202 buffer \fBbuf\fR.
 203 .SH "NOTES"
 204 If necessary, \fISSL_read()\fR will negotiate a TLS/SSL session, if
 205 not already explicitly performed by SSL_connect(3) or
 206 SSL_accept(3). If the
 207 peer requests a re-negotiation, it will be performed transparently during
 208 the \fISSL_read()\fR operation. The behaviour of \fISSL_read()\fR depends on the
 209 underlying BIO.
 210 .PP
 211 For the transparent negotiation to succeed, the \fBssl\fR must have been
 212 initialized to client or server mode. This is being done by calling
 213 SSL_set_connect_state(3) or \fISSL_set_accept_state()\fR
 214 before the first call to an \fISSL_read()\fR or SSL_write(3)
 215 function.
 216 .PP
 217 \fISSL_read()\fR works based on the SSL/TLS records. The data are received in
 218 records (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a
 219 record has been completely received, it can be processed (decryption and
 220 check of integrity). Therefore data that was not retrieved at the last
 221 call of \fISSL_read()\fR can still be buffered inside the SSL layer and will be
 222 retrieved on the next call to \fISSL_read()\fR. If \fBnum\fR is higher than the
 223 number of bytes buffered, \fISSL_read()\fR will return with the bytes buffered.
 224 If no more bytes are in the buffer, \fISSL_read()\fR will trigger the processing
 225 of the next record. Only when the record has been received and processed
 226 completely, \fISSL_read()\fR will return reporting success. At most the contents
 227 of the record will be returned. As the size of an SSL/TLS record may exceed
 228 the maximum packet size of the underlying transport (e.g. TCP), it may
 229 be necessary to read several packets from the transport layer before the
 230 record is complete and \fISSL_read()\fR can succeed.
 231 .PP
 232 If the underlying BIO is \fBblocking\fR, \fISSL_read()\fR will only return, once the
 233 read operation has been finished or an error occurred, except when a
 234 renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
 235 This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
 236 SSL_CTX_set_mode(3) call.
 237 .PP
 238 If the underlying BIO is \fBnon-blocking\fR, \fISSL_read()\fR will also return
 239 when the underlying BIO could not satisfy the needs of \fISSL_read()\fR
 240 to continue the operation. In this case a call to
 241 SSL_get_error(3) with the
 242 return value of \fISSL_read()\fR will yield \fBSSL_ERROR_WANT_READ\fR or
 243 \fBSSL_ERROR_WANT_WRITE\fR. As at any time a re-negotiation is possible, a
 244 call to \fISSL_read()\fR can also cause write operations! The calling process
 245 then must repeat the call after taking appropriate action to satisfy the
 246 needs of \fISSL_read()\fR. The action depends on the underlying BIO. When using a
 247 non-blocking socket, nothing is to be done, but \fIselect()\fR can be used to check
 248 for the required condition. When using a buffering BIO, like a BIO pair, data
 249 must be written into or retrieved out of the BIO before being able to continue.
 250 .SH "WARNING"
 251 When an \fISSL_read()\fR operation has to be repeated because of
 252 \fBSSL_ERROR_WANT_READ\fR or \fBSSL_ERROR_WANT_WRITE\fR, it must be repeated
 253 with the same arguments.
 254 .SH "RETURN VALUES"
 255 The following return values can occur:
 256 .Ip ">0" 4
 257 The read operation was successful; the return value is the number of
 258 bytes actually read from the \s-1TLS/SSL\s0 connection.
 259 .Ip "0" 4
 260 The read operation was not successful. The reason may either be a clean
 261 shutdown due to a \*(L"close notify\*(R" alert sent by the peer (in which case
 262 the \s-1SSL_RECEIVED_SHUTDOWN\s0 flag in the ssl shutdown state is set
 263 (see SSL_shutdown(3),
 264 SSL_set_shutdown(3)). It is also possible, that
 265 the peer simply shut down the underlying transport and the shutdown is
 266 incomplete. Call \fISSL_get_error()\fR with the return value \fBret\fR to find out,
 267 whether an error occurred or the connection was shut down cleanly
 268 (\s-1SSL_ERROR_ZERO_RETURN\s0).
 269 .Sp
 270 SSLv2 (deprecated) does not support a shutdown alert protocol, so it can
 271 only be detected, whether the underlying connection was closed. It cannot
 272 be checked, whether the closure was initiated by the peer or by something
 273 else.
 274 .Ip "<0" 4
 275 The read operation was not successful, because either an error occurred
 276 or action must be taken by the calling process. Call \fISSL_get_error()\fR with the
 277 return value \fBret\fR to find out the reason.
 278 .SH "SEE ALSO"
 279 SSL_get_error(3), SSL_write(3),
 280 SSL_CTX_set_mode(3), SSL_CTX_new(3),
 281 SSL_connect(3), SSL_accept(3)
 282 SSL_set_connect_state(3),
 283 SSL_shutdown(3), SSL_set_shutdown(3),
 284 ssl(3), bio(3)
 285
 286 .rn }` ''
 287 .IX Title "SSL_read 3"
 288 .IX Name "SSL_read - read bytes from a TLS/SSL connection."
 289
 290 .IX Header "NAME"
 291
 292 .IX Header "SYNOPSIS"
 293
 294 .IX Header "DESCRIPTION"
 295
 296 .IX Header "NOTES"
 297
 298 .IX Header "WARNING"
 299
 300 .IX Header "RETURN VALUES"
 301
 302 .IX Item ">0"
 303
 304 .IX Item "0"
 305
 306 .IX Item "<0"
 307
 308 .IX Header "SEE ALSO"
 309