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