Update documentation on how to close a connection

=item SSL_ERROR_ZERO_RETURN

The TLS/SSL connection has been closed.

If the protocol version is SSL 3.0 or higher, this result code is returned only

if a closure alert has occurred in the protocol, i.e. if the connection has been

closed cleanly.

Note that in this case B<SSL_ERROR_ZERO_RETURN> does not necessarily

The TLS/SSL peer has closed the connection for writing by sending the

"close notify" alert.

No more data can be read.

Note that B<SSL_ERROR_ZERO_RETURN> does not necessarily

indicate that the underlying transport has been closed.

=item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE

SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step

behaviour.

=over 4

SSL_shutdown() only closes the write direction.

It is not possible to call SSL_write() after calling SSL_shutdown().

The read direction is closed by the peer.

=head2 First to close the connection

=item When the application is the first party to send the "close notify"

When the application is the first party to send the "close notify"

alert, SSL_shutdown() will only send the alert and then set the

SSL_SENT_SHUTDOWN flag (so that the session is considered good and will

be kept in cache). SSL_shutdown() will then return with 0. If a unidirectional

shutdown is enough (the underlying connection shall be closed anyway), this

first call to SSL_shutdown() is sufficient. In order to complete the

bidirectional shutdown handshake, SSL_shutdown() must be called again.

The second call will make SSL_shutdown() wait for the peer's "close notify"

shutdown alert. On success, the second call to SSL_shutdown() will return

with 1.

=item If the peer already sent the "close notify" alert B<and> it was

be kept in the cache).

SSL_shutdown() will then return with 0.

If a unidirectional shutdown is enough (the underlying connection shall be

closed anyway), this first call to SSL_shutdown() is sufficient.

In order to complete the bidirectional shutdown handshake, the peer needs

to send back a "close notify" alert.

The SSL_RECEIVED_SHUTDOWN flag will be set after receiving and processing

it.

SSL_shutdown() will return 1 when it has been received.

The peer is still allowed to send data after receiving the "close notify"

event.

If the peer did send data it needs to be processed by calling SSL_read()

before calling SSL_shutdown() a second time.

SSL_read() will indicate the end of the peer data by returning <= 0

and SSL_get_error() returning SSL_ERROR_ZERO_RETURN.

It is recommended to call SSL_read() between SSL_shutdown() calls.

=head2 Peer closes the connection

If the peer already sent the "close notify" alert B<and> it was

already processed implicitly inside another function

(L<SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set.

SSL_read() will return <= 0 in that case, and SSL_get_error() will return

SSL_ERROR_ZERO_RETURN.

SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN

flag and will immediately return with 1.

Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the

SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call.

=back

=head1 NOTES

It is therefore recommended, to check the return value of SSL_shutdown()

and call SSL_shutdown() again, if the bidirectional shutdown is not yet

complete (return value of the first call is 0).

It is recommended to do a bidirectional shutdown by checking the return value

of SSL_shutdown() and call it again until it returns 1 or a fatal error.

The behaviour of SSL_shutdown() additionally depends on the underlying BIO.

If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the

handshake step has been finished or an error occurred.

=item Z<>0

The shutdown is not yet finished. Call SSL_shutdown() for a second time,

if a bidirectional shutdown shall be performed.

The shutdown is not yet finished: the "close notify" was send but the peer

did not send it back yet.

Call SSL_shutdown() again to do a bidirectional shutdown.

The output of L<SSL_get_error(3)> may be misleading, as an

erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred.

=item E<lt>0

The shutdown was not successful because a fatal error occurred either

at the protocol level or a connection failure occurred. It can also occur if

action is need to continue the operation for non-blocking BIOs.

Call L<SSL_get_error(3)> with the return value B<ret>

to find out the reason.

The shutdown was not successful.

Call L<SSL_get_error(3)> with the return value B<ret> to find out the reason.

It can occur if an action is needed to continue the operation for non-blocking

BIOs.

It can also occur when not all data was read using SSL_read().

=back