| blob | e8d8017224a5799fcf320be96424b0c9217788e4 |
1 .\" $NetBSD: SSL_get_error.3,v 1.14 2015/06/12 17:01:14 christos Exp $
2 .\"
3 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
4 .\"
5 .\" Standard preamble:
6 .\" ========================================================================
7 .de Sp \" Vertical space (when we can't use .PP)
8 .if t .sp .5v
9 .if n .sp
10 ..
11 .de Vb \" Begin verbatim text
12 .ft CW
13 .nf
14 .ne \\$1
15 ..
16 .de Ve \" End verbatim text
17 .ft R
18 .fi
19 ..
20 .\" Set up some character translations and predefined strings. \*(-- will
21 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
22 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
23 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
24 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
25 .\" nothing in troff, for use with C<>.
26 .tr \(*W-
27 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
28 .ie n \{\
29 . ds -- \(*W-
30 . ds PI pi
31 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
32 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
33 . ds L" ""
34 . ds R" ""
35 . ds C` ""
36 . ds C' ""
37 'br\}
38 .el\{\
39 . ds -- \|\(em\|
40 . ds PI \(*p
41 . ds L" ``
42 . ds R" ''
43 . ds C`
44 . ds C'
45 'br\}
46 .\"
47 .\" Escape single quotes in literal strings from groff's Unicode transform.
48 .ie \n(.g .ds Aq \(aq
49 .el .ds Aq '
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .\"
56 .\" Avoid warning from groff about undefined register 'F'.
57 .de IX
58 ..
59 .nr rF 0
60 .if \n(.g .if rF .nr rF 1
61 .if (\n(rF:(\n(.g==0)) \{
62 . if \nF \{
63 . de IX
64 . tm Index:\\$1\t\\n%\t"\\$2"
65 ..
66 . if !\nF==2 \{
67 . nr % 0
68 . nr F 2
69 . \}
70 . \}
71 .\}
72 .rr rF
73 .\"
74 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
75 .\" Fear. Run. Save yourself. No user-serviceable parts.
76 . \" fudge factors for nroff and troff
77 .if n \{\
78 . ds #H 0
79 . ds #V .8m
80 . ds #F .3m
81 . ds #[ \f1
82 . ds #] \fP
83 .\}
84 .if t \{\
85 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
86 . ds #V .6m
87 . ds #F 0
88 . ds #[ \&
89 . ds #] \&
90 .\}
91 . \" simple accents for nroff and troff
92 .if n \{\
93 . ds ' \&
94 . ds ` \&
95 . ds ^ \&
96 . ds , \&
97 . ds ~ ~
98 . ds /
99 .\}
100 .if t \{\
101 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
102 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
103 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
104 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
105 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
106 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
107 .\}
108 . \" troff and (daisy-wheel) nroff accents
109 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
110 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
111 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
112 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
113 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
114 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
115 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
116 .ds ae a\h'-(\w'a'u*4/10)'e
117 .ds Ae A\h'-(\w'A'u*4/10)'E
118 . \" corrections for vroff
119 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
120 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
121 . \" for low resolution devices (crt and lpr)
122 .if \n(.H>23 .if \n(.V>19 \
123 \{\
124 . ds : e
125 . ds 8 ss
126 . ds o a
127 . ds d- d\h'-1'\(ga
128 . ds D- D\h'-1'\(hy
129 . ds th \o'bp'
130 . ds Th \o'LP'
131 . ds ae ae
132 . ds Ae AE
133 .\}
134 .rm #[ #] #H #V #F C
135 .\" ========================================================================
136 .\"
137 .IX Title "SSL_get_error 3"
138 .TH SSL_get_error 3 "2009-07-19" "1.0.1n" "OpenSSL"
139 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
140 .\" way too many mistakes in technical documents.
141 .if n .ad l
142 .nh
143 .SH "NAME"
144 SSL_get_error \- obtain result code for TLS/SSL I/O operation
145 .SH "LIBRARY"
146 libcrypto, -lcrypto
147 .SH "SYNOPSIS"
148 .IX Header "SYNOPSIS"
149 .Vb 1
150 \& #include <openssl/ssl.h>
151 \&
152 \& int SSL_get_error(const SSL *ssl, int ret);
153 .Ve
154 .SH "DESCRIPTION"
155 .IX Header "DESCRIPTION"
156 \&\fISSL_get_error()\fR returns a result code (suitable for the C \*(L"switch\*(R"
157 statement) for a preceding call to \fISSL_connect()\fR, \fISSL_accept()\fR, \fISSL_do_handshake()\fR,
158 \&\fISSL_read()\fR, \fISSL_peek()\fR, or \fISSL_write()\fR on \fBssl\fR. The value returned by
159 that \s-1TLS/SSL I/O\s0 function must be passed to \fISSL_get_error()\fR in parameter
160 \&\fBret\fR.
161 .PP
162 In addition to \fBssl\fR and \fBret\fR, \fISSL_get_error()\fR inspects the
163 current thread's OpenSSL error queue. Thus, \fISSL_get_error()\fR must be
164 used in the same thread that performed the \s-1TLS/SSL I/O\s0 operation, and no
165 other OpenSSL function calls should appear in between. The current
166 thread's error queue must be empty before the \s-1TLS/SSL I/O\s0 operation is
167 attempted, or \fISSL_get_error()\fR will not work reliably.
168 .SH "RETURN VALUES"
169 .IX Header "RETURN VALUES"
170 The following return values can currently occur:
171 .IP "\s-1SSL_ERROR_NONE\s0" 4
172 .IX Item "SSL_ERROR_NONE"
173 The \s-1TLS/SSL I/O\s0 operation completed. This result code is returned
174 if and only if \fBret > 0\fR.
175 .IP "\s-1SSL_ERROR_ZERO_RETURN\s0" 4
176 .IX Item "SSL_ERROR_ZERO_RETURN"
177 The \s-1TLS/SSL\s0 connection has been closed. If the protocol version is \s-1SSL 3.0\s0
178 or \s-1TLS 1.0,\s0 this result code is returned only if a closure
179 alert has occurred in the protocol, i.e. if the connection has been
180 closed cleanly. Note that in this case \fB\s-1SSL_ERROR_ZERO_RETURN\s0\fR
181 does not necessarily indicate that the underlying transport
182 has been closed.
183 .IP "\s-1SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE\s0" 4
184 .IX Item "SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE"
185 The operation did not complete; the same \s-1TLS/SSL I/O\s0 function should be
186 called again later. If, by then, the underlying \fB\s-1BIO\s0\fR has data
187 available for reading (if the result code is \fB\s-1SSL_ERROR_WANT_READ\s0\fR)
188 or allows writing data (\fB\s-1SSL_ERROR_WANT_WRITE\s0\fR), then some \s-1TLS/SSL\s0
189 protocol progress will take place, i.e. at least part of an \s-1TLS/SSL\s0
190 record will be read or written. Note that the retry may again lead to
191 a \fB\s-1SSL_ERROR_WANT_READ\s0\fR or \fB\s-1SSL_ERROR_WANT_WRITE\s0\fR condition.
192 There is no fixed upper limit for the number of iterations that
193 may be necessary until progress becomes visible at application
194 protocol level.
195 .Sp
196 For socket \fB\s-1BIO\s0\fRs (e.g. when \fISSL_set_fd()\fR was used), \fIselect()\fR or
197 \&\fIpoll()\fR on the underlying socket can be used to find out when the
198 \&\s-1TLS/SSL I/O\s0 function should be retried.
199 .Sp
200 Caveat: Any \s-1TLS/SSL I/O\s0 function can lead to either of
201 \&\fB\s-1SSL_ERROR_WANT_READ\s0\fR and \fB\s-1SSL_ERROR_WANT_WRITE\s0\fR. In particular,
202 \&\fISSL_read()\fR or \fISSL_peek()\fR may want to write data and \fISSL_write()\fR may want
203 to read data. This is mainly because \s-1TLS/SSL\s0 handshakes may occur at any
204 time during the protocol (initiated by either the client or the server);
205 \&\fISSL_read()\fR, \fISSL_peek()\fR, and \fISSL_write()\fR will handle any pending handshakes.
206 .IP "\s-1SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT\s0" 4
207 .IX Item "SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT"
208 The operation did not complete; the same \s-1TLS/SSL I/O\s0 function should be
209 called again later. The underlying \s-1BIO\s0 was not connected yet to the peer
210 and the call would block in \fIconnect()\fR/\fIaccept()\fR. The \s-1SSL\s0 function should be
211 called again when the connection is established. These messages can only
212 appear with a \fIBIO_s_connect()\fR or \fIBIO_s_accept()\fR \s-1BIO,\s0 respectively.
213 In order to find out, when the connection has been successfully established,
214 on many platforms \fIselect()\fR or \fIpoll()\fR for writing on the socket file descriptor
215 can be used.
216 .IP "\s-1SSL_ERROR_WANT_X509_LOOKUP\s0" 4
217 .IX Item "SSL_ERROR_WANT_X509_LOOKUP"
218 The operation did not complete because an application callback set by
219 \&\fISSL_CTX_set_client_cert_cb()\fR has asked to be called again.
220 The \s-1TLS/SSL I/O\s0 function should be called again later.
221 Details depend on the application.
222 .IP "\s-1SSL_ERROR_SYSCALL\s0" 4
223 .IX Item "SSL_ERROR_SYSCALL"
224 Some I/O error occurred. The OpenSSL error queue may contain more
225 information on the error. If the error queue is empty
226 (i.e. \fIERR_get_error()\fR returns 0), \fBret\fR can be used to find out more
227 about the error: If \fBret == 0\fR, an \s-1EOF\s0 was observed that violates
228 the protocol. If \fBret == \-1\fR, the underlying \fB\s-1BIO\s0\fR reported an
229 I/O error (for socket I/O on Unix systems, consult \fBerrno\fR for details).
230 .IP "\s-1SSL_ERROR_SSL\s0" 4
231 .IX Item "SSL_ERROR_SSL"
232 A failure in the \s-1SSL\s0 library occurred, usually a protocol error. The
233 OpenSSL error queue contains more information on the error.
234 .SH "SEE ALSO"
235 .IX Header "SEE ALSO"
236 \&\fIssl\fR\|(3), \fIopenssl_err\fR\|(3)
237 .SH "HISTORY"
238 .IX Header "HISTORY"
239 \&\fISSL_get_error()\fR was added in SSLeay 0.8.