Debian Codegraph @

upstream/debian-unstable/man3/CRYPTO_THREAD_run_once.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "CRYPTO_THREAD_RUN_ONCE 3SSL"
58 .TH CRYPTO_THREAD_RUN_ONCE 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 CRYPTO_THREAD_run_once,
65 CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock,
66 CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free,
67 CRYPTO_atomic_add, CRYPTO_atomic_add64, CRYPTO_atomic_and, CRYPTO_atomic_or,
68 CRYPTO_atomic_load, CRYPTO_atomic_store, CRYPTO_atomic_load_int,
69 OSSL_set_max_threads, OSSL_get_max_threads,
70 OSSL_get_thread_support_flags, OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL,
71 OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN \- OpenSSL thread support
72 .SH SYNOPSIS
73 .IX Header "SYNOPSIS"
74 .Vb 1
75 \& #include <openssl/crypto.h>
76 \&
77 \& CRYPTO_ONCE CRYPTO_ONCE_STATIC_INIT;
78 \& int CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void));
79 \&
80 \& CRYPTO_RWLOCK *CRYPTO_THREAD_lock_new(void);
81 \& int CRYPTO_THREAD_read_lock(CRYPTO_RWLOCK *lock);
82 \& int CRYPTO_THREAD_write_lock(CRYPTO_RWLOCK *lock);
83 \& int CRYPTO_THREAD_unlock(CRYPTO_RWLOCK *lock);
84 \& void CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock);
85 \&
86 \& int CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock);
87 \& int CRYPTO_atomic_add64(uint64_t *val, uint64_t op, uint64_t *ret,
88 \& CRYPTO_RWLOCK *lock);
89 \& int CRYPTO_atomic_and(uint64_t *val, uint64_t op, uint64_t *ret,
90 \& CRYPTO_RWLOCK *lock);
91 \& int CRYPTO_atomic_or(uint64_t *val, uint64_t op, uint64_t *ret,
92 \& CRYPTO_RWLOCK *lock);
93 \& int CRYPTO_atomic_load(uint64_t *val, uint64_t *ret, CRYPTO_RWLOCK *lock);
94 \& int CRYPTO_atomic_store(uint64_t *dst, uint64_t val, CRYPTO_RWLOCK *lock);
95 \& int CRYPTO_atomic_load_int(int *val, int *ret, CRYPTO_RWLOCK *lock);
96 \&
97 \& int OSSL_set_max_threads(OSSL_LIB_CTX *ctx, uint64_t max_threads);
98 \& uint64_t OSSL_get_max_threads(OSSL_LIB_CTX *ctx);
99 \& uint32_t OSSL_get_thread_support_flags(void);
100 \&
101 \& #define OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL
102 \& #define OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN
103 .Ve
104 .SH DESCRIPTION
105 .IX Header "DESCRIPTION"
106 OpenSSL can be safely used in multi-threaded applications provided that
107 support for the underlying OS threading API is built-in. Currently, OpenSSL
108 supports the pthread and Windows APIs. OpenSSL can also be built without
109 any multi-threading support, for example on platforms that don't provide
110 any threading support or that provide a threading API that is not yet
111 supported by OpenSSL.
112 .PP
113 The following multi-threading function are provided:
114 .IP \(bu 2
115 \&\fBCRYPTO_THREAD_run_once()\fR can be used to perform one-time initialization.
116 The \fIonce\fR argument must be a pointer to a static object of type
117 \&\fBCRYPTO_ONCE\fR that was statically initialized to the value
118 \&\fBCRYPTO_ONCE_STATIC_INIT\fR.
119 The \fIinit\fR argument is a pointer to a function that performs the desired
120 exactly once initialization.
121 In particular, this can be used to allocate locks in a thread-safe manner,
122 which can then be used with the locking functions below.
123 .IP \(bu 2
124 \&\fBCRYPTO_THREAD_lock_new()\fR allocates, initializes and returns a new read/write
125 lock.
126 .IP \(bu 2
127 \&\fBCRYPTO_THREAD_read_lock()\fR locks the provided \fIlock\fR for reading.
128 .IP \(bu 2
129 \&\fBCRYPTO_THREAD_write_lock()\fR locks the provided \fIlock\fR for writing.
130 .IP \(bu 2
131 \&\fBCRYPTO_THREAD_unlock()\fR unlocks the previously locked \fIlock\fR.
132 .IP \(bu 2
133 \&\fBCRYPTO_THREAD_lock_free()\fR frees the provided \fIlock\fR.
134 If the argument is NULL, nothing is done.
135 .IP \(bu 2
136 \&\fBCRYPTO_atomic_add()\fR atomically adds \fIamount\fR to \fI*val\fR and returns the
137 result of the operation in \fI*ret\fR. \fIlock\fR will be locked, unless atomic
138 operations are supported on the specific platform. Because of this, if a
139 variable is modified by \fBCRYPTO_atomic_add()\fR then \fBCRYPTO_atomic_add()\fR must
140 be the only way that the variable is modified. If atomic operations are not
141 supported and \fIlock\fR is NULL, then the function will fail.
142 .IP \(bu 2
143 \&\fBCRYPTO_atomic_add64()\fR atomically adds \fIop\fR to \fI*val\fR and returns the
144 result of the operation in \fI*ret\fR. \fIlock\fR will be locked, unless atomic
145 operations are supported on the specific platform. Because of this, if a
146 variable is modified by \fBCRYPTO_atomic_add64()\fR then \fBCRYPTO_atomic_add64()\fR must
147 be the only way that the variable is modified. If atomic operations are not
148 supported and \fIlock\fR is NULL, then the function will fail.
149 .IP \(bu 2
150 \&\fBCRYPTO_atomic_and()\fR performs an atomic bitwise and of \fIop\fR and \fI*val\fR and stores
151 the result back in \fI*val\fR. It also returns the result of the operation in
152 \&\fI*ret\fR. \fIlock\fR will be locked, unless atomic operations are supported on the
153 specific platform. Because of this, if a variable is modified by
154 \&\fBCRYPTO_atomic_and()\fR or read by \fBCRYPTO_atomic_load()\fR then \fBCRYPTO_atomic_and()\fR must
155 be the only way that the variable is modified. If atomic operations are not
156 supported and \fIlock\fR is NULL, then the function will fail.
157 .IP \(bu 2
158 \&\fBCRYPTO_atomic_or()\fR performs an atomic bitwise or of \fIop\fR and \fI*val\fR and stores
159 the result back in \fI*val\fR. It also returns the result of the operation in
160 \&\fI*ret\fR. \fIlock\fR will be locked, unless atomic operations are supported on the
161 specific platform. Because of this, if a variable is modified by
162 \&\fBCRYPTO_atomic_or()\fR or read by \fBCRYPTO_atomic_load()\fR then \fBCRYPTO_atomic_or()\fR must
163 be the only way that the variable is modified. If atomic operations are not
164 supported and \fIlock\fR is NULL, then the function will fail.
165 .IP \(bu 2
166 \&\fBCRYPTO_atomic_load()\fR atomically loads the contents of \fI*val\fR into \fI*ret\fR.
167 \&\fIlock\fR will be locked, unless atomic operations are supported on the specific
168 platform. Because of this, if a variable is modified by \fBCRYPTO_atomic_or()\fR or
169 read by \fBCRYPTO_atomic_load()\fR then \fBCRYPTO_atomic_load()\fR must be the only way that
170 the variable is read. If atomic operations are not supported and \fIlock\fR is
171 NULL, then the function will fail.
172 .IP \(bu 2
173 \&\fBCRYPTO_atomic_store()\fR atomically stores the contents of \fIval\fR into \fI*dst\fR.
174 \&\fIlock\fR will be locked, unless atomic operations are supported on the specific
175 platform.
176 .IP \(bu 2
177 \&\fBCRYPTO_atomic_load_int()\fR works identically to \fBCRYPTO_atomic_load()\fR but operates
178 on an \fIint\fR value instead of a \fIuint64_t\fR value.
179 .IP \(bu 2
180 \&\fBOSSL_set_max_threads()\fR sets the maximum number of threads to be used by the
181 thread pool. If the argument is 0, thread pooling is disabled. OpenSSL will
182 not create any threads and existing threads in the thread pool will be torn
183 down. The maximum thread count is a limit, not a target. Threads will not be
184 spawned unless (and until) there is demand. Thread polling is disabled by
185 default. To enable threading you must call \fBOSSL_set_max_threads()\fR explicitly.
186 Under no circumstances is this done for you.
187 .IP \(bu 2
188 \&\fBOSSL_get_thread_support_flags()\fR determines what thread pool functionality
189 OpenSSL is compiled with and is able to support in the current run time
190 environment. \fBOSSL_THREAD_SUPPORT_FLAG_THREAD_POOL\fR indicates that the base
191 thread pool functionality is available, and
192 \&\fBOSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN\fR indicates that the default thread pool
193 model is available. The default thread pool model is currently the only model
194 available, therefore both of these flags must be set for thread pool
195 functionality to be used.
196 .SH "RETURN VALUES"
197 .IX Header "RETURN VALUES"
198 \&\fBCRYPTO_THREAD_run_once()\fR returns 1 on success, or 0 on error.
199 .PP
200 \&\fBCRYPTO_THREAD_lock_new()\fR returns the allocated lock, or NULL on error.
201 .PP
202 \&\fBCRYPTO_THREAD_lock_free()\fR returns no value.
203 .PP
204 \&\fBOSSL_set_max_threads()\fR returns 1 on success and 0 on failure. Returns failure
205 if OpenSSL-managed thread pooling is not supported (for example, if it is not
206 supported on the current platform, or because OpenSSL is not built with the
207 necessary support).
208 .PP
209 \&\fBOSSL_get_max_threads()\fR returns the maximum number of threads currently allowed
210 to be used by the thread pool. If thread pooling is disabled or not available,
211 returns 0.
212 .PP
213 \&\fBOSSL_get_thread_support_flags()\fR returns zero or more \fBOSSL_THREAD_SUPPORT_FLAG\fR
214 values.
215 .PP
216 The other functions return 1 on success, or 0 on error.
217 .SH NOTES
218 .IX Header "NOTES"
219 On Windows platforms the CRYPTO_THREAD_* types and functions in the
220 \&\fI<openssl/crypto.h>\fR header are dependent on some of the types
221 customarily made available by including \fI<windows.h>\fR. The application
222 developer is likely to require control over when the latter is included,
223 commonly as one of the first included headers. Therefore, it is defined as an
224 application developer's responsibility to include \fI<windows.h>\fR prior to
225 \&\fI<openssl/crypto.h>\fR where use of CRYPTO_THREAD_* types and functions is
226 required.
227 .SH EXAMPLES
228 .IX Header "EXAMPLES"
229 You can find out if OpenSSL was configured with thread support:
230 .PP
231 .Vb 6
232 \& #include <openssl/opensslconf.h>
233 \& #if defined(OPENSSL_THREADS)
234 \& /* thread support enabled */
235 \& #else
236 \& /* no thread support */
237 \& #endif
238 .Ve
239 .PP
240 This example safely initializes and uses a lock.
241 .PP
242 .Vb 4
243 \& #ifdef _WIN32
244 \& # include <windows.h>
245 \& #endif
246 \& #include <openssl/crypto.h>
247 \&
248 \& static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT;
249 \& static CRYPTO_RWLOCK *lock;
250 \&
251 \& static void myinit(void)
252 \& {
253 \& lock = CRYPTO_THREAD_lock_new();
254 \& }
255 \&
256 \& static int mylock(void)
257 \& {
258 \& if (!CRYPTO_THREAD_run_once(&once, void init) || lock == NULL)
259 \& return 0;
260 \& return CRYPTO_THREAD_write_lock(lock);
261 \& }
262 \&
263 \& static int myunlock(void)
264 \& {
265 \& return CRYPTO_THREAD_unlock(lock);
266 \& }
267 \&
268 \& int serialized(void)
269 \& {
270 \& int ret = 0;
271 \&
272 \& if (!mylock()) {
273 \& /* Do not unlock unless the lock was successfully acquired. */
274 \& return 0;
275 \& }
276 \&
277 \& /* Your code here, do not return without releasing the lock! */
278 \& ret = ... ;
279 \& myunlock();
280 \& return ret;
281 \& }
282 .Ve
283 .PP
284 Finalization of locks is an advanced topic, not covered in this example.
285 This can only be done at process exit or when a dynamically loaded library is
286 no longer in use and is unloaded.
287 The simplest solution is to just "leak" the lock in applications and not
288 repeatedly load/unload shared libraries that allocate locks.
289 .SH "SEE ALSO"
290 .IX Header "SEE ALSO"
291 \&\fBcrypto\fR\|(7), \fBopenssl\-threads\fR\|(7).
292 .SH HISTORY
293 .IX Header "HISTORY"
294 \&\fBCRYPTO_atomic_load_int()\fR, \fBOSSL_set_max_threads()\fR, \fBOSSL_get_max_threads()\fR,
295 \&\fBOSSL_get_thread_support_flags()\fR were added in OpenSSL 3.2.
296 .PP
297 \&\fBCRYPTO_atomic_store()\fR, \fBCRYPTO_atomic_add64()\fR, \fBCRYPTO_atomic_and()\fR
298 were added in OpenSSL 3.4.
299 .SH COPYRIGHT
300 .IX Header "COPYRIGHT"
301 Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved.
302 .PP
303 Licensed under the Apache License 2.0 (the "License"). You may not use
304 this file except in compliance with the License. You can obtain a copy
305 in the file LICENSE in the source distribution or at
306 <https://www.openssl.org/source/license.html>.