diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man7/openssl-threads.7')
| -rw-r--r-- | secure/lib/libcrypto/man/man7/openssl-threads.7 | 134 |
1 files changed, 29 insertions, 105 deletions
diff --git a/secure/lib/libcrypto/man/man7/openssl-threads.7 b/secure/lib/libcrypto/man/man7/openssl-threads.7 index c699373765e3..7b07a4378103 100644 --- a/secure/lib/libcrypto/man/man7/openssl-threads.7 +++ b/secure/lib/libcrypto/man/man7/openssl-threads.7 @@ -1,4 +1,5 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== @@ -15,29 +16,12 @@ .ft R .fi .. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. \*(C+ will -.\" give a nicer C++. Capital omega is used to do unbreakable dashes and -.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, -.\" nothing in troff, for use with C<>. -.tr \(*W- -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' . ds C` . ds C' 'br\} @@ -68,85 +52,25 @@ . \} .\} .rr rF -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "OPENSSL-THREADS 7ossl" -.TH OPENSSL-THREADS 7ossl "2023-09-19" "3.0.11" "OpenSSL" +.TH OPENSSL-THREADS 7ossl 2025-07-01 3.5.1 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh -.SH "NAME" +.SH NAME openssl\-threads \- Overview of thread safety in OpenSSL -.SH "DESCRIPTION" +.SH DESCRIPTION .IX Header "DESCRIPTION" In this man page, we use the term \fBthread-safe\fR to indicate that an object or function can be used by multiple threads at the same time. .PP OpenSSL can be built with or without threads support. The most important use of this support is so that OpenSSL itself can use a single consistent -\&\s-1API,\s0 as shown in \*(L"\s-1EXAMPLES\*(R"\s0 in \fBCRYPTO_THREAD_run_once\fR\|(3). -Multi-platform applications can also use this \s-1API.\s0 +API, as shown in "EXAMPLES" in \fBCRYPTO_THREAD_run_once\fR\|(3). +Multi-platform applications can also use this API. .PP In particular, being configured for threads support does not imply that all OpenSSL objects are thread-safe. @@ -154,18 +78,18 @@ To emphasize: \fImost objects are not safe for simultaneous use\fR. Exceptions to this should be documented on the specific manual pages, and some general high-level guidance is given here. .PP -One major use of the OpenSSL thread \s-1API\s0 is to implement reference counting. +One major use of the OpenSSL thread API is to implement reference counting. Many objects within OpenSSL are reference-counted, so resources are not released, until the last reference is removed. References are often increased automatically (such as when an \fBX509\fR certificate object is added into an \fBX509_STORE\fR trust store). -There is often an \fB\f(BIobject\fB_up_ref\fR() function that can be used to increase +There is often an \fR\f(BIobject\fR\fB_up_ref\fR() function that can be used to increase the reference count. -Failure to match \fB\f(BIobject\fB_up_ref\fR() calls with the right number of -\&\fB\f(BIobject\fB_free\fR() calls is a common source of memory leaks when a program +Failure to match \fB\fR\f(BIobject\fR\fB_up_ref\fR() calls with the right number of +\&\fB\fR\f(BIobject\fR\fB_free\fR() calls is a common source of memory leaks when a program exits. .PP -Many objects have set and get \s-1API\s0's to set attributes in the object. +Many objects have set and get API's to set attributes in the object. A \f(CW\*(C`set0\*(C'\fR passes ownership from the caller to the object and a \&\f(CW\*(C`get0\*(C'\fR returns a pointer but the attribute ownership remains with the object and a reference to it is returned. @@ -182,38 +106,38 @@ Set methods, or modifying shared objects, are generally not thread-safe as discussed below. .PP Objects are thread-safe -as long as the \s-1API\s0's being invoked don't modify the object; in this -case the parameter is usually marked in the \s-1API\s0 as \f(CW\*(C`const\*(C'\fR. +as long as the API's being invoked don't modify the object; in this +case the parameter is usually marked in the API as \f(CW\*(C`const\*(C'\fR. Not all parameters are marked this way. Note that a \f(CW\*(C`const\*(C'\fR declaration does not mean immutable; for example \&\fBX509_cmp\fR\|(3) takes pointers to \f(CW\*(C`const\*(C'\fR objects, but the implementation uses a C cast to remove that so it can lock objects, generate and cache -a \s-1DER\s0 encoding, and so on. +a DER encoding, and so on. .PP Another instance of thread-safety is when updates to an object's internal state, such as cached values, are done with locks. -One example of this is the reference counting \s-1API\s0's described above. +One example of this is the reference counting API's described above. .PP In all cases, however, it is generally not safe for one thread to mutate an object, such as setting elements of a private or public key, while another thread is using that object, such as verifying a signature. .PP -The same \s-1API\s0's can usually be used simultaneously on different objects +The same API's can usually be used simultaneously on different objects without interference. For example, two threads can calculate a signature using two different -\&\fB\s-1EVP_PKEY_CTX\s0\fR objects. +\&\fBEVP_PKEY_CTX\fR objects. .PP For implicit global state or singletons, thread-safety depends on the facility. -The \fBCRYPTO_secure_malloc\fR\|(3) and related \s-1API\s0's have their own lock, +The \fBCRYPTO_secure_malloc\fR\|(3) and related API's have their own lock, while \fBCRYPTO_malloc\fR\|(3) assumes the underlying platform allocation will do any necessary locking. -Some \s-1API\s0's, such as \fBNCONF_load\fR\|(3) and related, or \fBOBJ_create\fR\|(3) -do no locking at all; this can be considered a bug. +Some API's, such as \fBNCONF_load\fR\|(3) and related do no locking at all; +this can be considered a bug. .PP -A separate, although related, issue is modifying \*(L"factory\*(R" objects +A separate, although related, issue is modifying "factory" objects when other objects have been created from that. -For example, an \fB\s-1SSL_CTX\s0\fR object created by \fBSSL_CTX_new\fR\|(3) is used -to create per-connection \fB\s-1SSL\s0\fR objects by calling \fBSSL_new\fR\|(3). +For example, an \fBSSL_CTX\fR object created by \fBSSL_CTX_new\fR\|(3) is used +to create per-connection \fBSSL\fR objects by calling \fBSSL_new\fR\|(3). In this specific case, and probably for factory methods in general, it is not safe to modify the factory object after it has been used to create other objects. @@ -221,14 +145,14 @@ other objects. .IX Header "SEE ALSO" \&\fBCRYPTO_THREAD_run_once\fR\|(3), local system threads documentation. -.SH "BUGS" +.SH BUGS .IX Header "BUGS" This page is admittedly very incomplete. -.SH "COPYRIGHT" +.SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use +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 -in the file \s-1LICENSE\s0 in the source distribution or at +in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>. |