From 82b7f378b6907ab315a6e50322d2a0a8794a0aa9 Mon Sep 17 00:00:00 2001
From: bentley <>
Date: Sun, 12 Oct 2014 09:33:04 +0000
Subject: Convert libssl manpages from pod to mdoc(7).

libcrypto has not been started yet.

ok schwarze@ miod@
---
 src/lib/libssl/doc/SSL_write.3 | 172 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 172 insertions(+)
 create mode 100644 src/lib/libssl/doc/SSL_write.3

(limited to 'src/lib/libssl/doc/SSL_write.3')

diff --git a/src/lib/libssl/doc/SSL_write.3 b/src/lib/libssl/doc/SSL_write.3
new file mode 100644
index 0000000000..19dfffae1b
--- /dev/null
+++ b/src/lib/libssl/doc/SSL_write.3
@@ -0,0 +1,172 @@
+.Dd $Mdocdate: October 12 2014 $
+.Dt SSL_WRITE 3
+.Os
+.Sh NAME
+.Nm SSL_write
+.Nd write bytes to a TLS/SSL connection
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft int
+.Fn SSL_write "SSL *ssl" "const void *buf" "int num"
+.Sh DESCRIPTION
+.Fn SSL_write
+writes
+.Fa num
+bytes from the buffer
+.Fa buf
+into the specified
+.Fa ssl
+connection.
+.Sh NOTES
+If necessary,
+.Fn SSL_write
+will negotiate a TLS/SSL session, if not already explicitly performed by
+.Xr SSL_connect 3
+or
+.Xr SSL_accept 3 .
+If the peer requests a re-negotiation,
+it will be performed transparently during the
+.Fn SSL_write
+operation.
+The behaviour of
+.Fn SSL_write
+depends on the underlying
+.Vt BIO .
+.Pp
+For the transparent negotiation to succeed, the
+.Fa ssl
+must have been initialized to client or server mode.
+This is being done by calling
+.Xr SSL_set_connect_state 3
+or
+.Xr SSL_set_accept_state 3
+before the first call to an
+.Xr SSL_read 3
+or
+.Fn SSL_write
+function.
+.Pp
+If the underlying
+.Vt BIO
+is
+.Em blocking ,
+.Fn SSL_write
+will only return once the write operation has been finished or an error
+occurred, except when a renegotiation take place, in which case a
+.Dv SSL_ERROR_WANT_READ
+may occur.
+This behaviour can be controlled with the
+.Dv SSL_MODE_AUTO_RETRY
+flag of the
+.Xr SSL_CTX_set_mode 3
+call.
+.Pp
+If the underlying
+.Vt BIO
+is
+.Em non-blocking ,
+.Fn SSL_write
+will also return when the underlying
+.Vt BIO
+could not satisfy the needs of
+.Fn SSL_write
+to continue the operation.
+In this case a call to
+.Xr SSL_get_error 3
+with the return value of
+.Fn SSL_write
+will yield
+.Dv SSL_ERROR_WANT_READ
+or
+.Dv SSL_ERROR_WANT_WRITE .
+As at any time a re-negotiation is possible, a call to
+.Fn SSL_write
+can also cause read operations!
+The calling process then must repeat the call after taking appropriate action
+to satisfy the needs of
+.Fn SSL_write .
+The action depends on the underlying
+.Vt BIO .
+When using a non-blocking socket, nothing is to be done, but
+.Xr select 2
+can be used to check for the required condition.
+When using a buffering
+.Vt BIO ,
+like a
+.Vt BIO
+pair, data must be written into or retrieved out of the BIO before being able
+to continue.
+.Pp
+.Fn SSL_write
+will only return with success, when the complete contents of
+.Fa buf
+of length
+.Fa num
+have been written.
+This default behaviour can be changed with the
+.Dv SSL_MODE_ENABLE_PARTIAL_WRITE
+option of
+.Xr SSL_CTX_set_mode 3 .
+When this flag is set,
+.Fn SSL_write
+will also return with success when a partial write has been successfully
+completed.
+In this case the
+.Fn SSL_write
+operation is considered completed.
+The bytes are sent and a new
+.Fn SSL_write
+operation with a new buffer (with the already sent bytes removed) must be
+started.
+A partial write is performed with the size of a message block, which is 16kB
+for SSLv3/TLSv1.
+.Sh WARNING
+When an
+.Fn SSL_write
+operation has to be repeated because of
+.Dv SSL_ERROR_WANT_READ
+or
+.Dv SSL_ERROR_WANT_WRITE ,
+it must be repeated with the same arguments.
+.Pp
+When calling
+.Fn SSL_write
+with
+.Fa num Ns
+=0 bytes to be sent the behaviour is undefined.
+.Sh RETURN VALUES
+The following return values can occur:
+.Bl -tag -width Ds
+.It >0
+The write operation was successful.
+The return value is the number of bytes actually written to the TLS/SSL
+connection.
+.It 0
+The write operation was not successful.
+Probably the underlying connection was closed.
+Call
+.Xr SSL_get_error 3
+with the return value to find out whether an error occurred or the connection
+was shut down cleanly
+.Pq Dv SSL_ERROR_ZERO_RETURN .
+.Pp
+SSLv2 (deprecated) does not support a shutdown alert protocol, so it can only
+be detected whether the underlying connection was closed.
+It cannot be checked why the closure happened.
+.It <0
+The write operation was not successful, because either an error occurred or
+action must be taken by the calling process.
+Call
+.Xr SSL_get_error 3
+with the return value to find out the reason.
+.El
+.Sh SEE ALSO
+.Xr bio 3 ,
+.Xr ssl 3 ,
+.Xr SSL_accept 3 ,
+.Xr SSL_connect 3 ,
+.Xr SSL_CTX_new 3 ,
+.Xr SSL_CTX_set_mode 3 ,
+.Xr SSL_get_error 3 ,
+.Xr SSL_read 3 ,
+.Xr SSL_set_connect_state 3
-- 
cgit v1.2.3-55-g6feb