Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libssl / man / SSL_get_error.3
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
e056f0e0
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
e056f0e0 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
e056f0e0 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
e056f0e0 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
e056f0e0
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
e056f0e0 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
e056f0e0
JR
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
984263bc
MD
35'br\}
36.el\{\
e056f0e0
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
984263bc 41'br\}
e056f0e0 42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
e056f0e0 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
e056f0e0
JR
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
e056f0e0
JR
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 54..
e056f0e0
JR
55. nr % 0
56. rr F
984263bc 57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 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"
e3261593 127.TH SSL_get_error 3 "2012-01-04" "1.0.0f" "OpenSSL"
e257b235
PA
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>
e257b235 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.