Add docs for new atomic apis

Documents CRYPTO_atomic_load_ptr(), CRYPTO_atomic_store_ptr() and
CRYPTO_atomic_cmp_exch_ptr()

Reviewed-by: Paul Dale <paul.dale@oracle.com>
Reviewed-by: Nikola Pajkovsky <nikolap@openssl.org>
MergeDate: Tue Apr 14 08:29:33 2026
(Merged from https://github.com/openssl/openssl/pull/30670)

diff --git a/CHANGES.md b/CHANGES.md
index ca6646958619aa1d7aa672ed8b798c58bb06e35d..2b55f6ebdff99783030b581ac65f855d56f5fbb1 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -42,6 +42,11 @@ OpenSSL Releases
 
    *Shane Lontis*
 
+ * The API functions `CRYPTO_atomic_load_ptr`, `CRYPTO_atomic_store_ptr`, and
+   `CRYPTO_atomic_cmp_exch_ptr` have been added to libcrypto.
+
+   *Neil Horman*
+
  * The `openssl pkeyutl` command now uses memory-mapped I/O when reading
    raw input from a file for oneshot sign/verify operations (such as Ed25519,
    Ed448, and ML-DSA) on platforms that support it (Unix-like). The

diff --git a/NEWS.md b/NEWS.md
index 4829d57c47f6405a2f80cc820f04ce187aa88a04..7abd5c5f651d23808fbf34b00977125342090fc4 100644 (file)
--- a/NEWS.md
+++ b/NEWS.md
@@ -27,7 +27,8 @@ OpenSSL 4.0
 
 ### Major changes between OpenSSL 4.0 and OpenSSL 4.1 [under development]
 
-  * none
+  * API calls `CRYPTO_atomic_load_ptr`, `CRYPTO_atomic_store_ptr`, and
+    `CRYPTO_atomic_cmp_exch_ptr` have been added.
 
 ### Major changes between OpenSSL 3.6 and OpenSSL 4.0 [under development]
 

diff --git a/doc/man3/CRYPTO_THREAD_run_once.pod b/doc/man3/CRYPTO_THREAD_run_once.pod
index 51671646f7836965df7755b2788170950e71559d..161105471a7133b59958a10075b45431689d1c01 100644 (file)
--- a/doc/man3/CRYPTO_THREAD_run_once.pod
+++ b/doc/man3/CRYPTO_THREAD_run_once.pod
@@ -7,7 +7,8 @@ CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock,
 CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free,
 CRYPTO_atomic_add, CRYPTO_atomic_add64, CRYPTO_atomic_and, CRYPTO_atomic_or,
 CRYPTO_atomic_load, CRYPTO_atomic_store, CRYPTO_atomic_load_int,
-CRYPTO_atomic_store_int,
+CRYPTO_atomic_store_int, CRYPTO_atomic_load_ptr, CRYPTO_atomic_store_ptr,
+CRYPTO_atomic_cmp_exch_ptr,
 OSSL_set_max_threads, OSSL_get_max_threads,
 OSSL_get_thread_support_flags, OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL,
 OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN - OpenSSL thread support
@@ -36,6 +37,9 @@ OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN - OpenSSL thread support
  int CRYPTO_atomic_store(uint64_t *dst, uint64_t val, CRYPTO_RWLOCK *lock);
  int CRYPTO_atomic_load_int(int *val, int *ret, CRYPTO_RWLOCK *lock);
  int CRYPTO_atomic_store_int(int *dst, int val, CRYPTO_RWLOCK *lock);
+ int CRYPTO_atomic_load_ptr(void **ptr, void **ret, CRYPTO_RWLOCK *lock);
+ int CRYPTO_atomic_store_ptr(void **dst, void **val, CRYPTO_RWLOCK *lock);
+ int CRYPTO_atomic_cmp_exch_ptr(void **ptr, void **expect, void *desire, CRYPTO_RWLOCK *lock);
 
  int OSSL_set_max_threads(OSSL_LIB_CTX *ctx, uint64_t max_threads);
  uint64_t OSSL_get_max_threads(OSSL_LIB_CTX *ctx);
@@ -155,6 +159,34 @@ operates on an I<int> value instead of a I<uint64_t> value.
 
 =item *
 
+int CRYPTO_atomic_load_ptr(void **ptr, void **ret, CRYPTO_RWLOCK *lock);
+
+CRYPTO_atomic_load_ptr() atomically loads the void * contents of I<*ptr> to the contents of I<*ret>.
+I<lock> will be used to emulate atomic operations on platforms that do not support
+atomic operations.
+
+=item *
+
+int CRYPTO_atomic_store_ptr(void **dst, void **val, CRYPTO_RWLOCK *lock);
+
+CRYPTO_atomic_store_ptr() atomically stores the contents of I<*val> to the location pointed
+to by I<*p>.
+I<lock> will be used to emulate atomic operations on platforms that do not support
+atomic operations.
+
+=item *
+
+int CRYPTO_atomic_cmp_exch_ptr(void **ptr, void **expect, void *desire, CRYPTO_RWLOCK *lock);
+
+CRYPTO_atomic_cmp_exch_ptr() atomically performs a read-modify-write operation.  If the contents of
+I<*ptr> matches the contents of I<*expect> then the value of I<desire> is stored in I<*ptr> and the
+function returns 1.  If I<*ptr> does not match the contents of I<*expect>, then the contents of
+I<*ptr> are atomically loaded to the contents of I<*expect> and the function returns 0.
+I<lock> will be used to emulate atomic operations on platforms that do not support
+atomic operations.
+
+=item *
+
 OSSL_set_max_threads() sets the maximum number of threads to be used by the
 thread pool. If the argument is 0, thread pooling is disabled. OpenSSL will
 not create any threads and existing threads in the thread pool will be torn
@@ -282,6 +314,9 @@ were added in OpenSSL 3.4.
 
 CRYPTO_atomic_store_int() was added in OpenSSL 4.0.
 
+CRYPTO_atomic_load_ptr(), CRYPTO_atomic_store_ptr(), CRYPTO_atomic_cmp_exch_ptr()
+were added in OpenSSL 4.1
+
 =head1 COPYRIGHT
 
 Copyright 2000-2026 The OpenSSL Project Authors. All Rights Reserved.