diff options
Diffstat (limited to 'secure/lib/libcrypto/man/SSL_get_error.3')
| -rw-r--r-- | secure/lib/libcrypto/man/SSL_get_error.3 | 103 |
1 files changed, 55 insertions, 48 deletions
diff --git a/secure/lib/libcrypto/man/SSL_get_error.3 b/secure/lib/libcrypto/man/SSL_get_error.3 index 5a2d201580040..aa56b83544a4e 100644 --- a/secure/lib/libcrypto/man/SSL_get_error.3 +++ b/secure/lib/libcrypto/man/SSL_get_error.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) +.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== @@ -54,16 +54,20 @@ .\" Avoid warning from groff about undefined register 'F'. .de IX .. -.if !\nF .nr F 0 -.if \nF>0 \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" .. -. if !\nF==2 \{\ -. nr % 0 -. nr F 2 +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} . \} .\} +.rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. @@ -129,7 +133,7 @@ .\" ======================================================================== .\" .IX Title "SSL_GET_ERROR 3" -.TH SSL_GET_ERROR 3 "2018-11-20" "1.1.1a" "OpenSSL" +.TH SSL_GET_ERROR 3 "2019-02-26" "1.1.1b" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -145,18 +149,18 @@ SSL_get_error \- obtain result code for TLS/SSL I/O operation .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" -\&\fISSL_get_error()\fR returns a result code (suitable for the C \*(L"switch\*(R" -statement) for a preceding call to \fISSL_connect()\fR, \fISSL_accept()\fR, \fISSL_do_handshake()\fR, -\&\fISSL_read_ex()\fR, \fISSL_read()\fR, \fISSL_peek_ex()\fR, \fISSL_peek()\fR, \fISSL_write_ex()\fR or -\&\fISSL_write()\fR on \fBssl\fR. The value returned by that \s-1TLS/SSL I/O\s0 function must be -passed to \fISSL_get_error()\fR in parameter \fBret\fR. +\&\fBSSL_get_error()\fR returns a result code (suitable for the C \*(L"switch\*(R" +statement) for a preceding call to \fBSSL_connect()\fR, \fBSSL_accept()\fR, \fBSSL_do_handshake()\fR, +\&\fBSSL_read_ex()\fR, \fBSSL_read()\fR, \fBSSL_peek_ex()\fR, \fBSSL_peek()\fR, \fBSSL_write_ex()\fR or +\&\fBSSL_write()\fR on \fBssl\fR. The value returned by that \s-1TLS/SSL I/O\s0 function must be +passed to \fBSSL_get_error()\fR in parameter \fBret\fR. .PP -In addition to \fBssl\fR and \fBret\fR, \fISSL_get_error()\fR inspects the -current thread's OpenSSL error queue. Thus, \fISSL_get_error()\fR must be +In addition to \fBssl\fR and \fBret\fR, \fBSSL_get_error()\fR inspects the +current thread's OpenSSL error queue. Thus, \fBSSL_get_error()\fR must be used in the same thread that performed the \s-1TLS/SSL I/O\s0 operation, and no other OpenSSL function calls should appear in between. The current thread's error queue must be empty before the \s-1TLS/SSL I/O\s0 operation is -attempted, or \fISSL_get_error()\fR will not work reliably. +attempted, or \fBSSL_get_error()\fR will not work reliably. .SH "RETURN VALUES" .IX Header "RETURN VALUES" The following return values can currently occur: @@ -182,10 +186,10 @@ operation. If at a later time the underlying \fB\s-1BIO\s0\fR has data available for reading the same function can be called again. .Sp -\&\fISSL_read()\fR and \fISSL_read_ex()\fR can also set \fB\s-1SSL_ERROR_WANT_READ\s0\fR when there is +\&\fBSSL_read()\fR and \fBSSL_read_ex()\fR can also set \fB\s-1SSL_ERROR_WANT_READ\s0\fR when there is still unprocessed data available at either the \fB\s-1SSL\s0\fR or the \fB\s-1BIO\s0\fR layer, even for a blocking \fB\s-1BIO\s0\fR. -See \fISSL_read\fR\|(3) for more information. +See \fBSSL_read\fR\|(3) for more information. .Sp \&\fB\s-1SSL_ERROR_WANT_WRITE\s0\fR is returned when the last operation was a write to a non-blocking \fB\s-1BIO\s0\fR and it was unable to sent all data to the \fB\s-1BIO\s0\fR. @@ -197,85 +201,88 @@ There is no fixed upper limit for the number of iterations that may be necessary until progress becomes visible at application protocol level. .Sp -It is safe to call \fISSL_read()\fR or \fISSL_read_ex()\fR when more data is available -even when the call that set this error was an \fISSL_write()\fR or \fISSL_write_ex()\fR. -However if the call was an \fISSL_write()\fR or \fISSL_write_ex()\fR, it should be called +It is safe to call \fBSSL_read()\fR or \fBSSL_read_ex()\fR when more data is available +even when the call that set this error was an \fBSSL_write()\fR or \fBSSL_write_ex()\fR. +However if the call was an \fBSSL_write()\fR or \fBSSL_write_ex()\fR, it should be called again to continue sending the application data. .Sp -For socket \fB\s-1BIO\s0\fRs (e.g. when \fISSL_set_fd()\fR was used), \fIselect()\fR or -\&\fIpoll()\fR on the underlying socket can be used to find out when the +For socket \fB\s-1BIO\s0\fRs (e.g. when \fBSSL_set_fd()\fR was used), \fBselect()\fR or +\&\fBpoll()\fR on the underlying socket can be used to find out when the \&\s-1TLS/SSL I/O\s0 function should be retried. .Sp Caveat: Any \s-1TLS/SSL I/O\s0 function can lead to either of \&\fB\s-1SSL_ERROR_WANT_READ\s0\fR and \fB\s-1SSL_ERROR_WANT_WRITE\s0\fR. In particular, -\&\fISSL_read_ex()\fR, \fISSL_read()\fR, \fISSL_peek_ex()\fR, or \fISSL_peek()\fR may want to write data -and \fISSL_write()\fR or \fISSL_write_ex()\fR may want to read data. +\&\fBSSL_read_ex()\fR, \fBSSL_read()\fR, \fBSSL_peek_ex()\fR, or \fBSSL_peek()\fR may want to write data +and \fBSSL_write()\fR or \fBSSL_write_ex()\fR may want to read data. This is mainly because \&\s-1TLS/SSL\s0 handshakes may occur at any time during the protocol (initiated by -either the client or the server); \fISSL_read_ex()\fR, \fISSL_read()\fR, \fISSL_peek_ex()\fR, -\&\fISSL_peek()\fR, \fISSL_write_ex()\fR, and \fISSL_write()\fR will handle any pending handshakes. +either the client or the server); \fBSSL_read_ex()\fR, \fBSSL_read()\fR, \fBSSL_peek_ex()\fR, +\&\fBSSL_peek()\fR, \fBSSL_write_ex()\fR, and \fBSSL_write()\fR will handle any pending handshakes. .IP "\s-1SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT\s0" 4 .IX Item "SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT" The operation did not complete; the same \s-1TLS/SSL I/O\s0 function should be called again later. The underlying \s-1BIO\s0 was not connected yet to the peer -and the call would block in \fIconnect()\fR/\fIaccept()\fR. The \s-1SSL\s0 function should be +and the call would block in \fBconnect()\fR/\fBaccept()\fR. The \s-1SSL\s0 function should be called again when the connection is established. These messages can only -appear with a \fIBIO_s_connect()\fR or \fIBIO_s_accept()\fR \s-1BIO,\s0 respectively. +appear with a \fBBIO_s_connect()\fR or \fBBIO_s_accept()\fR \s-1BIO,\s0 respectively. In order to find out, when the connection has been successfully established, -on many platforms \fIselect()\fR or \fIpoll()\fR for writing on the socket file descriptor +on many platforms \fBselect()\fR or \fBpoll()\fR for writing on the socket file descriptor can be used. .IP "\s-1SSL_ERROR_WANT_X509_LOOKUP\s0" 4 .IX Item "SSL_ERROR_WANT_X509_LOOKUP" The operation did not complete because an application callback set by -\&\fISSL_CTX_set_client_cert_cb()\fR has asked to be called again. +\&\fBSSL_CTX_set_client_cert_cb()\fR has asked to be called again. The \s-1TLS/SSL I/O\s0 function should be called again later. Details depend on the application. .IP "\s-1SSL_ERROR_WANT_ASYNC\s0" 4 .IX Item "SSL_ERROR_WANT_ASYNC" The operation did not complete because an asynchronous engine is still processing data. This will only occur if the mode has been set to \s-1SSL_MODE_ASYNC\s0 -using \fISSL_CTX_set_mode\fR\|(3) or \fISSL_set_mode\fR\|(3) and an asynchronous capable +using \fBSSL_CTX_set_mode\fR\|(3) or \fBSSL_set_mode\fR\|(3) and an asynchronous capable engine is being used. An application can determine whether the engine has -completed its processing using \fIselect()\fR or \fIpoll()\fR on the asynchronous wait file +completed its processing using \fBselect()\fR or \fBpoll()\fR on the asynchronous wait file descriptor. This file descriptor is available by calling -\&\fISSL_get_all_async_fds\fR\|(3) or \fISSL_get_changed_async_fds\fR\|(3). The \s-1TLS/SSL I/O\s0 +\&\fBSSL_get_all_async_fds\fR\|(3) or \fBSSL_get_changed_async_fds\fR\|(3). The \s-1TLS/SSL I/O\s0 function should be called again later. The function \fBmust\fR be called from the same thread that the original call was made from. .IP "\s-1SSL_ERROR_WANT_ASYNC_JOB\s0" 4 .IX Item "SSL_ERROR_WANT_ASYNC_JOB" The asynchronous job could not be started because there were no async jobs -available in the pool (see \fIASYNC_init_thread\fR\|(3)). This will only occur if the -mode has been set to \s-1SSL_MODE_ASYNC\s0 using \fISSL_CTX_set_mode\fR\|(3) or -\&\fISSL_set_mode\fR\|(3) and a maximum limit has been set on the async job pool -through a call to \fIASYNC_init_thread\fR\|(3). The application should retry the +available in the pool (see \fBASYNC_init_thread\fR\|(3)). This will only occur if the +mode has been set to \s-1SSL_MODE_ASYNC\s0 using \fBSSL_CTX_set_mode\fR\|(3) or +\&\fBSSL_set_mode\fR\|(3) and a maximum limit has been set on the async job pool +through a call to \fBASYNC_init_thread\fR\|(3). The application should retry the operation after a currently executing asynchronous operation for the current thread has completed. .IP "\s-1SSL_ERROR_WANT_CLIENT_HELLO_CB\s0" 4 .IX Item "SSL_ERROR_WANT_CLIENT_HELLO_CB" The operation did not complete because an application callback set by -\&\fISSL_CTX_set_client_hello_cb()\fR has asked to be called again. +\&\fBSSL_CTX_set_client_hello_cb()\fR has asked to be called again. The \s-1TLS/SSL I/O\s0 function should be called again later. Details depend on the application. .IP "\s-1SSL_ERROR_SYSCALL\s0" 4 .IX Item "SSL_ERROR_SYSCALL" -Some non-recoverable I/O error occurred. -The OpenSSL error queue may contain more information on the error. -For socket I/O on Unix systems, consult \fBerrno\fR for details. +Some non-recoverable, fatal I/O error occurred. The OpenSSL error queue may +contain more information on the error. For socket I/O on Unix systems, consult +\&\fBerrno\fR for details. If this error occurs then no further I/O operations should +be performed on the connection and \fBSSL_shutdown()\fR must not be called. .Sp This value can also be returned for other errors, check the error queue for details. .IP "\s-1SSL_ERROR_SSL\s0" 4 .IX Item "SSL_ERROR_SSL" -A failure in the \s-1SSL\s0 library occurred, usually a protocol error. The -OpenSSL error queue contains more information on the error. +A non-recoverable, fatal error in the \s-1SSL\s0 library occurred, usually a protocol +error. The OpenSSL error queue contains more information on the error. If this +error occurs then no further I/O operations should be performed on the +connection and \fBSSL_shutdown()\fR must not be called. .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\fIssl\fR\|(7) +\&\fBssl\fR\|(7) .SH "HISTORY" .IX Header "HISTORY" -\&\s-1SSL_ERROR_WANT_ASYNC\s0 was added in OpenSSL 1.1.0. -\&\s-1SSL_ERROR_WANT_CLIENT_HELLO_CB\s0 was added in OpenSSL 1.1.1. +The \s-1SSL_ERROR_WANT_ASYNC\s0 error code was added in OpenSSL 1.1.0. +The \s-1SSL_ERROR_WANT_CLIENT_HELLO_CB\s0 error code was added in OpenSSL 1.1.1. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. |