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