Convert libssl manpages from pod to mdoc(7).

libcrypto has not been started yet.

ok schwarze@ miod@

1 files changed, 94 insertions, 0 deletions

diff --git a/src/lib/libssl/doc/SSL_get_session.3 b/src/lib/libssl/doc/SSL_get_session.3
new file mode 100644
index 0000000000..fe9a6d48ef
--- /dev/null
+++ b/src/lib/libssl/doc/SSL_get_session.3
@@ -0,0 +1,94 @@
+.Dd $Mdocdate: October 12 2014 $
+.Dt SSL_GET_SESSION 3
+.Os
+.Sh NAME
+.Nm SSL_get_session ,
+.Nm SSL_get0_session ,
+.Nm SSL_get1_session
+.Nd retrieve TLS/SSL session data
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft SSL_SESSION *
+SSL_get_session "const SSL *ssl"
+.Ft SSL_SESSION *
+SSL_get0_session "const SSL *ssl"
+.Ft SSL_SESSION *
+SSL_get1_session "SSL *ssl"
+.Sh DESCRIPTION
+.Fn SSL_get_session
+returns a pointer to the
+.Vt SSL_SESSION
+actually used in
+.Fa ssl .
+The reference count of the
+.Vt SSL_SESSION
+is not incremented, so that the pointer can become invalid by other operations.
+.Pp
+.Fn SSL_get0_session
+is the same as
+.Fn SSL_get_session .
+.Pp
+.Fn SSL_get1_session
+is the same as
+.Fn SSL_get_session ,
+but the reference count of the
+.Vt SSL_SESSION
+is incremented by one.
+.Sh NOTES
+The
+Fa ssl
+session contains all information required to re-establish the connection
+without a new handshake.
+.Pp
+.Fn SSL_get0_session
+returns a pointer to the actual session.
+As the reference counter is not incremented,
+the pointer is only valid while the connection is in use.
+If
+.Xr SSL_clear 3
+or
+.Xr SSL_free 3
+is called, the session may be removed completely (if considered bad),
+and the pointer obtained will become invalid.
+Even if the session is valid,
+it can be removed at any time due to timeout during
+.Xr SSL_CTX_flush_sessions 3 .
+.Pp
+If the data is to be kept,
+.Fn SSL_get1_session
+will increment the reference count, so that the session will not be implicitly
+removed by other operations but stays in memory.
+In order to remove the session
+.Xr SSL_SESSION_free 3
+must be explicitly called once to decrement the reference count again.
+.Pp
+.Vt SSL_SESSION
+objects keep internal link information about the session cache list when being
+inserted into one
+.Vt SSL_CTX
+object's session cache.
+One
+.Vt SSL_SESSION
+object, regardless of its reference count, must therefore only be used with one
+.Vt SSL_CTX
+object (and the
+.Vt SSL
+objects created from this
+.Vt SSL_CTX
+object).
+.Sh RETURN VALUES
+The following return values can occur:
+.Bl -tag -width Ds
+.It Dv NULL
+There is no session available in
+.Fa ssl .
+.It Pointer to an Vt SSL
+The return value points to the data of an
+.Vt SSL
+session.
+.El
+.Sh SEE ALSO
+.Xr ssl 3 ,
+.Xr SSL_clear 3 ,
+.Xr SSL_free 3 ,
+.Xr SSL_SESSION_free 3