secure/lib/libssl/man/SSL_get_error.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_get_error 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_get_error \- obtain result code for TLS/SSL I/O operation
 192 .SH "SYNOPSIS"
 193 .PP
 194 .Vb 1
 195 \& #include <openssl/ssl.h>
 196 .Ve
 197 .Vb 1
 198 \& int SSL_get_error(SSL *ssl, int ret);
 199 .Ve
 200 .SH "DESCRIPTION"
 201 \fISSL_get_error()\fR returns a result code (suitable for the C \*(L"switch\*(R"
 202 statement) for a preceding call to \fISSL_connect()\fR, \fISSL_accept()\fR, \fISSL_do_handshake()\fR,
 203 \fISSL_read()\fR, \fISSL_peek()\fR, or \fISSL_write()\fR on \fBssl\fR.  The value returned by
 204 that TLS/SSL I/O function must be passed to \fISSL_get_error()\fR in parameter
 205 \fBret\fR.
 206 .PP
 207 In addition to \fBssl\fR and \fBret\fR, \fISSL_get_error()\fR inspects the
 208 current thread's OpenSSL error queue.  Thus, \fISSL_get_error()\fR must be
 209 used in the same thread that performed the TLS/SSL I/O operation, and no
 210 other OpenSSL function calls should appear in between.  The current
 211 thread's error queue must be empty before the TLS/SSL I/O operation is
 212 attempted, or \fISSL_get_error()\fR will not work reliably.
 213 .SH "RETURN VALUES"
 214 The following return values can currently occur:
 215 .Ip "\s-1SSL_ERROR_NONE\s0" 4
 216 The \s-1TLS/SSL\s0 I/O operation completed.  This result code is returned
 217 if and only if \fBret > 0\fR.
 218 .Ip "\s-1SSL_ERROR_ZERO_RETURN\s0" 4
 219 The \s-1TLS/SSL\s0 connection has been closed.  If the protocol version is \s-1SSL\s0 3.0
 220 or \s-1TLS\s0 1.0, this result code is returned only if a closure
 221 alert has occurred in the protocol, i.e. if the connection has been
 222 closed cleanly. Note that in this case \fB\s-1SSL_ERROR_ZERO_RETURN\s0\fR
 223 does not necessarily indicate that the underlying transport
 224 has been closed.
 225 .Ip "\s-1SSL_ERROR_WANT_READ\s0, \s-1SSL_ERROR_WANT_WRITE\s0" 4
 226 The operation did not complete; the same \s-1TLS/SSL\s0 I/O function should be
 227 called again later.  If, by then, the underlying \fB\s-1BIO\s0\fR has data
 228 available for reading (if the result code is \fB\s-1SSL_ERROR_WANT_READ\s0\fR)
 229 or allows writing data (\fB\s-1SSL_ERROR_WANT_WRITE\s0\fR), then some \s-1TLS/SSL\s0
 230 protocol progress will take place, i.e. at least part of an \s-1TLS/SSL\s0
 231 record will be read or written.  Note that the retry may again lead to
 232 a \fB\s-1SSL_ERROR_WANT_READ\s0\fR or \fB\s-1SSL_ERROR_WANT_WRITE\s0\fR condition.
 233 There is no fixed upper limit for the number of iterations that
 234 may be necessary until progress becomes visible at application
 235 protocol level.
 236 .Sp
 237 For socket \fB\s-1BIO\s0\fRs (e.g. when \fISSL_set_fd()\fR was used), \fIselect()\fR or
 238 \fIpoll()\fR on the underlying socket can be used to find out when the
 239 \s-1TLS/SSL\s0 I/O function should be retried.
 240 .Sp
 241 Caveat: Any \s-1TLS/SSL\s0 I/O function can lead to either of
 242 \fB\s-1SSL_ERROR_WANT_READ\s0\fR and \fB\s-1SSL_ERROR_WANT_WRITE\s0\fR.  In particular,
 243 \fISSL_read()\fR or \fISSL_peek()\fR may want to write data and \fISSL_write()\fR may want
 244 to read data.  This is mainly because \s-1TLS/SSL\s0 handshakes may occur at any
 245 time during the protocol (initiated by either the client or the server);
 246 \fISSL_read()\fR, \fISSL_peek()\fR, and \fISSL_write()\fR will handle any pending handshakes.
 247 .Ip "\s-1SSL_ERROR_WANT_CONNECT\s0, \s-1SSL_ERROR_WANT_ACCEPT\s0" 4
 248 The operation did not complete; the same \s-1TLS/SSL\s0 I/O function should be
 249 called again later. The underlying \s-1BIO\s0 was not connected yet to the peer
 250 and the call would block in \fIconnect()\fR/\fIaccept()\fR. The \s-1SSL\s0 function should be
 251 called again when the connection is established. These messages can only
 252 appear with a \fIBIO_s_connect()\fR or \fIBIO_s_accept()\fR \s-1BIO\s0, respectively.
 253 In order to find out, when the connection has been successfully established,
 254 on many platforms \fIselect()\fR or \fIpoll()\fR for writing on the socket file descriptor
 255 can be used.
 256 .Ip "\s-1SSL_ERROR_WANT_X509_LOOKUP\s0" 4
 257 The operation did not complete because an application callback set by
 258 \fISSL_CTX_set_client_cert_cb()\fR has asked to be called again.
 259 The \s-1TLS/SSL\s0 I/O function should be called again later.
 260 Details depend on the application.
 261 .Ip "\s-1SSL_ERROR_SYSCALL\s0" 4
 262 Some I/O error occurred.  The OpenSSL error queue may contain more
 263 information on the error.  If the error queue is empty
 264 (i.e. \fIERR_get_error()\fR returns 0), \fBret\fR can be used to find out more
 265 about the error: If \fBret == 0\fR, an \s-1EOF\s0 was observed that violates
 266 the protocol.  If \fBret == \-1\fR, the underlying \fB\s-1BIO\s0\fR reported an
 267 I/O error (for socket I/O on Unix systems, consult \fBerrno\fR for details).
 268 .Ip "\s-1SSL_ERROR_SSL\s0" 4
 269 A failure in the \s-1SSL\s0 library occurred, usually a protocol error.  The
 270 OpenSSL error queue contains more information on the error.
 271 .SH "SEE ALSO"
 272 ssl(3), err(3)
 273 .SH "HISTORY"
 274 \fISSL_get_error()\fR was added in SSLeay 0.8.
 275
 276 .rn }` ''
 277 .IX Title "SSL_get_error 3"
 278 .IX Name "SSL_get_error - obtain result code for TLS/SSL I/O operation"
 279
 280 .IX Header "NAME"
 281
 282 .IX Header "SYNOPSIS"
 283
 284 .IX Header "DESCRIPTION"
 285
 286 .IX Header "RETURN VALUES"
 287
 288 .IX Item "\s-1SSL_ERROR_NONE\s0"
 289
 290 .IX Item "\s-1SSL_ERROR_ZERO_RETURN\s0"
 291
 292 .IX Item "\s-1SSL_ERROR_WANT_READ\s0, \s-1SSL_ERROR_WANT_WRITE\s0"
 293
 294 .IX Item "\s-1SSL_ERROR_WANT_CONNECT\s0, \s-1SSL_ERROR_WANT_ACCEPT\s0"
 295
 296 .IX Item "\s-1SSL_ERROR_WANT_X509_LOOKUP\s0"
 297
 298 .IX Item "\s-1SSL_ERROR_SYSCALL\s0"
 299
 300 .IX Item "\s-1SSL_ERROR_SSL\s0"
 301
 302 .IX Header "SEE ALSO"
 303
 304 .IX Header "HISTORY"
 305