In crypto.h rev. 1.43 and ssl.h rev. 1.153 2018/03/17 16:20:01, beck@

provided OPENSSL_init_crypto(3) and OPENSSL_init_ssl(3).
Write the documentation from scratch
because the text OpenSSL provides is full of bloat.

1 files changed, 77 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/OPENSSL_init_crypto.3 b/src/lib/libcrypto/man/OPENSSL_init_crypto.3
new file mode 100644
index 0000000000..27c60561fe
--- /dev/null
+++ b/src/lib/libcrypto/man/OPENSSL_init_crypto.3
@@ -0,0 +1,77 @@
+.\" $OpenBSD: OPENSSL_init_crypto.3,v 1.1 2018/03/17 18:52:42 schwarze Exp $
+.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: March 17 2018 $
+.Dt OPENSSL_INIT_CRYPTO 3
+.Os
+.Sh NAME
+.Nm OPENSSL_init_crypto
+.Nd initialise the crypto library
+.Sh SYNOPSIS
+.In openssl/crypto.h
+.Ft int
+.Fo OPENSSL_init_crypto
+.Fa "uint64_t options"
+.Fa "const void *dummy"
+.Fc
+.Sh DESCRIPTION
+If
+.Fn OPENSSL_init_crypto
+is called before any other crypto or ssl functions, the crypto
+library is initialised by allocating various internal resources.
+Unless the
+.Dv OPENSSL_INIT_NO_LOAD_CONFIG
+bit is set in the
+.Fa options
+argument, the default
+.Xr openssl.cnf 5
+configuration file is also loaded as documented in
+.Xr OPENSSL_config 3 .
+.Pp
+The other
+.Fa options
+flags defined by OpenSSL are all ignored by LibreSSL.
+The
+.Fa dummy
+argument has no effect.
+.Pp
+Calling this function is almost never useful because it is internally
+called with an
+.Fa options
+argument of 0 by those functions in the crypto and ssl libraries
+that require it.
+It is safest to assume that any function may do so.
+.Pp
+If this function is called more than once, none of the calls except
+the first one have any effect.
+.Sh RETURN VALUES
+.Fn OPENSSL_init_crypto
+is intended to return 1 on success or 0 on error.
+.Sh SEE ALSO
+.Xr CONF_modules_load_file 3 ,
+.Xr OPENSSL_init_ssl 3 ,
+.Xr openssl.cnf 5
+.Sh HISTORY
+.Fn OPENSSL_init_crypto
+first appeared in OpenSSL 1.1.0.
+.Sh BUGS
+.Fn OPENSSL_init_crypto
+silently ignores almost all kinds of errors.
+In particular, if memory allocation fails, initialisation is likely
+to remain incomplete, the library may be in an inconsistent internal
+state, but the return value will usually indicate success anyway.
+There is no way for the application program to find out whether
+library initialisation is actually complete, nor to get back to a
+consistent state if it isn't.