From: Matt Caswell <matt@openssl.org>
Date: Wed, 29 May 2019 15:04:17 +0000 (+0100)
Subject: Document OPENSSL_thread_stop_ex()
X-Git-Tag: openssl-3.0.0-alpha1~1901
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=ff6da65e0d81bae4af3fc3337a95b03595cf5878;p=oweals%2Fopenssl.git

Document OPENSSL_thread_stop_ex()

This new function works in the same way as OPENSSL_thread_stop() but
for a specified OPENSSL_CTX.

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9040)
---

diff --git a/doc/man3/OPENSSL_CTX.pod b/doc/man3/OPENSSL_CTX.pod
index 5348367135..1893c923a3 100644
--- a/doc/man3/OPENSSL_CTX.pod
+++ b/doc/man3/OPENSSL_CTX.pod
@@ -21,6 +21,10 @@ the internal default context with functions that take a C<OPENSSL_CTX>
 argument.
 
 OPENSSL_CTX_new() creates a new OpenSSL library context.
+When a non default library context is in use care should be taken with
+multi-threaded applications to properly clean up thread local resources before
+the OPENSSL_CTX is freed.
+See L<OPENSSL_thread_stop_ex(3)> for more information.
 
 OPENSSL_CTX_free() frees the given C<ctx>.
 
diff --git a/doc/man3/OPENSSL_init_crypto.pod b/doc/man3/OPENSSL_init_crypto.pod
index a83256144a..e20fc8c998 100644
--- a/doc/man3/OPENSSL_init_crypto.pod
+++ b/doc/man3/OPENSSL_init_crypto.pod
@@ -5,7 +5,7 @@
 OPENSSL_INIT_new, OPENSSL_INIT_set_config_filename,
 OPENSSL_INIT_set_config_appname, OPENSSL_INIT_set_config_file_flags,
 OPENSSL_INIT_free, OPENSSL_init_crypto, OPENSSL_cleanup, OPENSSL_atexit,
-OPENSSL_thread_stop - OpenSSL initialisation
+OPENSSL_thread_stop_ex, OPENSSL_thread_stop - OpenSSL initialisation
 and deinitialisation functions
 
 =head1 SYNOPSIS
@@ -15,6 +15,7 @@ and deinitialisation functions
  void OPENSSL_cleanup(void);
  int OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings);
  int OPENSSL_atexit(void (*handler)(void));
+ void OPENSSL_thread_stop_ex(OPENSSL_CTX *ctx);
  void OPENSSL_thread_stop(void);
 
  OPENSSL_INIT_SETTINGS *OPENSSL_INIT_new(void);
@@ -202,11 +203,25 @@ called after deinitialisation of resources local to a thread, but before other
 process wide resources are freed. In the event that multiple stop handlers are
 registered, no guarantees are made about the order of execution.
 
-The OPENSSL_thread_stop() function deallocates resources associated
-with the current thread. Typically this function will be called automatically by
-the library when the thread exits. This should only be called directly if
-resources should be freed at an earlier time, or under the circumstances
-described in the NOTES section below.
+The OPENSSL_thread_stop_ex() function deallocates resources associated
+with the current thread for the given OPENSSL_CTX B<ctx>. The B<ctx> parameter
+can be NULL in which case the default OPENSSL_CTX is used.
+
+Typically, this function will be called automatically by the library when
+the thread exits as long as the OPENSSL_CTX has not been freed before the thread
+exits. If OPENSSL_CTX_free() is called OPENSSL_thread_stop_ex will be called
+automatically for the current thread (but not any other threads that may have
+used this OPENSSL_CTX).
+
+OPENSSL_thread_stop_ex should be called on all threads that will exit after the
+OPENSSL_CTX is freed.
+Typically this is not necessary for the default OPENSSL_CTX (because all
+resources are cleaned up on library exit) except if thread local resources
+should be freed before library exit, or under the circumstances described in
+the NOTES section below.
+
+OPENSSL_thread_stop() is the same as OPENSSL_thread_stop_ex() except that the
+default OPENSSL_CTX is always used.
 
 The B<OPENSSL_INIT_LOAD_CONFIG> flag will load a configuration file, as with
 L<CONF_modules_load_file(3)> with NULL filename and application name and the