Update copyright year

[thirdparty/openssl.git] / doc / man3 / CRYPTO_THREAD_run_once.pod

diff --git a/doc/man3/CRYPTO_THREAD_run_once.pod b/doc/man3/CRYPTO_THREAD_run_once.pod
index dd0d21a9de37a48f7aa2fa0ef12134fddb17be33..a51679b97edde47c264b37f4b97719f9b84e7d7e 100644 (file)
--- a/doc/man3/CRYPTO_THREAD_run_once.pod
+++ b/doc/man3/CRYPTO_THREAD_run_once.pod
@@ -5,7 +5,7 @@
 CRYPTO_THREAD_run_once,
 CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock,
 CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free,
-CRYPTO_atomic_add - OpenSSL thread support
+CRYPTO_atomic_add, CRYPTO_atomic_or, CRYPTO_atomic_load - OpenSSL thread support
 
 =head1 SYNOPSIS
 
@@ -21,6 +21,9 @@ CRYPTO_atomic_add - OpenSSL thread support
  void CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock);
 
  int CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock);
+ int CRYPTO_atomic_or(uint64_t *val, uint64_t op, uint64_t *ret,
+                      CRYPTO_RWLOCK *lock);
+ int CRYPTO_atomic_load(uint64_t *val, uint64_t *ret, CRYPTO_RWLOCK *lock);
 
 =head1 DESCRIPTION
 
@@ -38,10 +41,10 @@ The following multi-threading function are provided:
 =item *
 
 CRYPTO_THREAD_run_once() can be used to perform one-time initialization.
-The B<once> argument must be a pointer to a static object of type
+The I<once> argument must be a pointer to a static object of type
 B<CRYPTO_ONCE> that was statically initialized to the value
 B<CRYPTO_ONCE_STATIC_INIT>.
-The B<init> argument is a pointer to a function that performs the desired
+The I<init> argument is a pointer to a function that performs the desired
 exactly once initialization.
 In particular, this can be used to allocate locks in a thread-safe manner,
 which can then be used with the locking functions below.
@@ -53,27 +56,47 @@ lock.
 
 =item *
 
-CRYPTO_THREAD_read_lock() locks the provided B<lock> for reading.
+CRYPTO_THREAD_read_lock() locks the provided I<lock> for reading.
 
 =item *
 
-CRYPTO_THREAD_write_lock() locks the provided B<lock> for writing.
+CRYPTO_THREAD_write_lock() locks the provided I<lock> for writing.
 
 =item *
 
-CRYPTO_THREAD_unlock() unlocks the previously locked B<lock>.
+CRYPTO_THREAD_unlock() unlocks the previously locked I<lock>.
 
 =item *
 
-CRYPTO_THREAD_lock_free() frees the provided B<lock>.
+CRYPTO_THREAD_lock_free() frees the provided I<lock>.
 
 =item *
 
-CRYPTO_atomic_add() atomically adds B<amount> to B<val> and returns the
-result of the operation in B<ret>. B<lock> will be locked, unless atomic
+CRYPTO_atomic_add() atomically adds I<amount> to I<*val> and returns the
+result of the operation in I<*ret>. I<lock> will be locked, unless atomic
 operations are supported on the specific platform. Because of this, if a
 variable is modified by CRYPTO_atomic_add() then CRYPTO_atomic_add() must
-be the only way that the variable is modified.
+be the only way that the variable is modified. If atomic operations are not
+supported and I<lock> is NULL, then the function will fail.
+
+=item *
+
+CRYPTO_atomic_or() performs an atomic bitwise or of I<op> and I<*val> and stores
+the result back in I<*val>. It also returns the result of the operation in
+I<*ret>. I<lock> will be locked, unless atomic operations are supported on the
+specific platform. Because of this, if a variable is modified by
+CRYPTO_atomic_or() or read by CRYPTO_atomic_load() then CRYPTO_atomic_or() must
+be the only way that the variable is modified. If atomic operations are not
+supported and I<lock> is NULL, then the function will fail.
+
+=item *
+
+CRYPTO_atomic_load() atomically loads the contents of I<*val> into I<*ret>.
+I<lock> will be locked, unless atomic operations are supported on the specific
+platform. Because of this, if a variable is modified by CRYPTO_atomic_or() or
+read by CRYPTO_atomic_load() then CRYPTO_atomic_load() must be the only way that
+the variable is read. If atomic operations are not supported and I<lock> is
+NULL, then the function will fail.
 
 =back
 
@@ -90,12 +113,13 @@ The other functions return 1 on success, or 0 on error.
 =head1 NOTES
 
 On Windows platforms the CRYPTO_THREAD_* types and functions in the
-openssl/crypto.h header are dependent on some of the types customarily
-made available by including windows.h. The application developer is
-likely to require control over when the latter is included, commonly as
-one of the first included headers. Therefore, it is defined as an
-application developer's responsibility to include windows.h prior to
-crypto.h where use of CRYPTO_THREAD_* types and functions is required.
+F<< <openssl/crypto.h> >> header are dependent on some of the types
+customarily made available by including F<< <windows.h> >>. The application
+developer is likely to require control over when the latter is included,
+commonly as one of the first included headers. Therefore, it is defined as an
+application developer's responsibility to include F<< <windows.h> >> prior to
+F<< <openssl/crypto.h> >> where use of CRYPTO_THREAD_* types and functions is
+required.
 
 =head1 EXAMPLES
 
@@ -155,11 +179,11 @@ repeatedly load/unload shared libraries that allocate locks.
 
 =head1 SEE ALSO
 
-L<crypto(7)>
+L<crypto(7)>, L<openssl-threads(7)>.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy