In ssl.h rev. 1.136 2018/02/14 17:08:44, jsing@ provided

SSL_CTX_up_ref(3).  Merge the related documentation from OpenSSL,
but tweak the wording to be less confusing and simplify the RETURN
VALUES section.

1 files changed, 32 insertions, 15 deletions

diff --git a/lib/libssl/man/SSL_CTX_new.3 b/lib/libssl/man/SSL_CTX_new.3
index 0c846ceadec..64f8ea713c7 100644
--- a/lib/libssl/man/SSL_CTX_new.3
+++ b/lib/libssl/man/SSL_CTX_new.3
@@ -1,5 +1,6 @@
-.\"	$OpenBSD: SSL_CTX_new.3,v 1.3 2017/08/19 23:45:10 schwarze Exp $
-.\"	OpenSSL 21cd6e00 Aug 17 15:21:33 2015 -0400
+.\" $OpenBSD: SSL_CTX_new.3,v 1.4 2018/02/14 18:09:13 schwarze Exp $
+.\" full merge up to: OpenSSL 21cd6e00 Oct 21 14:40:15 2015 +0100
+.\" selective merge up to: OpenSSL eb43101f Dec 9 18:07:09 2016 +0100
 .\"
 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
 .\" Copyright (c) 2000, 2005, 2012, 2013, 2015, 2016 The OpenSSL Project.
@@ -49,11 +50,12 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 19 2017 $
+.Dd $Mdocdate: February 14 2018 $
 .Dt SSL_CTX_NEW 3
 .Os
 .Sh NAME
 .Nm SSL_CTX_new ,
+.Nm SSL_CTX_up_ref ,
 .Nm TLS_method ,
 .Nm TLS_server_method ,
 .Nm TLS_client_method ,
@@ -77,6 +79,8 @@
 .In openssl/ssl.h
 .Ft SSL_CTX *
 .Fn SSL_CTX_new "const SSL_METHOD *method"
+.Ft int
+.Fn SSL_CTX_up_ref "SSL_CTX *ctx"
 .Ft const SSL_METHOD *
 .Fn TLS_method void
 .Ft const SSL_METHOD *
@@ -122,6 +126,23 @@ It initializes the list of ciphers, the session cache setting, the
 callbacks, the keys and certificates, and the options to its default
 values.
 .Pp
+An
+.Vt SSL_CTX
+object is reference counted.
+Creating a new
+.Vt SSL_CTX
+object sets its reference count to 1.
+Calling
+.Fn SSL_CTX_up_ref
+on it increments the reference count by 1.
+Calling
+.Xr SSL_CTX_free 3
+on it decrements the reference count by 1.
+When the reference count drops to zero,
+any memory or resources allocated to the
+.Vt SSL_CTX
+object are freed.
+.Pp
 The
 .Vt SSL_CTX
 object uses
@@ -202,18 +223,14 @@ In clients, when a protocol version is disabled without disabling
 all previous protocol versions, the effect is to also disable all
 subsequent protocol versions.
 .Sh RETURN VALUES
-The following return values can occur:
-.Bl -tag -width Ds
-.It Dv NULL
-The creation of a new
-.Vt SSL_CTX
-object failed.
-Check the error stack to find out the reason.
-.It Pointer to an SSL_CTX object
-The return value points to an allocated
-.Vt SSL_CTX
-object.
-.El
+.Fn SSL_CTX_new
+returns a pointer to the newly allocated object or
+.Dv NULL
+on failure.
+Check the error stack to find out the reason for failure.
+.Pp
+.Fn SSL_CTX_up_ref
+returns 1 for success or 0 for failure.
 .Sh SEE ALSO
 .Xr ssl 3 ,
 .Xr SSL_accept 3 ,