diff options
Diffstat (limited to 'upstream/debian-unstable/man7')
308 files changed, 12427 insertions, 5085 deletions
diff --git a/upstream/debian-unstable/man7/EVP_ASYM_CIPHER-RSA.7ssl b/upstream/debian-unstable/man7/EVP_ASYM_CIPHER-RSA.7ssl index f4f61970..98bdc390 100644 --- a/upstream/debian-unstable/man7/EVP_ASYM_CIPHER-RSA.7ssl +++ b/upstream/debian-unstable/man7/EVP_ASYM_CIPHER-RSA.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_ASYM_CIPHER-RSA 7SSL" -.TH EVP_ASYM_CIPHER-RSA 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_ASYM_CIPHER-RSA 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_ASYM_CIPHER-SM2.7ssl b/upstream/debian-unstable/man7/EVP_ASYM_CIPHER-SM2.7ssl index 55b899c4..95e67f21 100644 --- a/upstream/debian-unstable/man7/EVP_ASYM_CIPHER-SM2.7ssl +++ b/upstream/debian-unstable/man7/EVP_ASYM_CIPHER-SM2.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_ASYM_CIPHER-SM2 7SSL" -.TH EVP_ASYM_CIPHER-SM2 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_ASYM_CIPHER-SM2 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_CIPHER-AES.7ssl b/upstream/debian-unstable/man7/EVP_CIPHER-AES.7ssl index 454b41d2..b1d7dadc 100644 --- a/upstream/debian-unstable/man7/EVP_CIPHER-AES.7ssl +++ b/upstream/debian-unstable/man7/EVP_CIPHER-AES.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_CIPHER-AES 7SSL" -.TH EVP_CIPHER-AES 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_CIPHER-AES 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -101,6 +101,8 @@ FIPS provider: .PD 0 .IP """AES\-128\-SIV"", ""AES\-192\-SIV"" and ""AES\-256\-SIV""" 4 .IX Item """AES-128-SIV"", ""AES-192-SIV"" and ""AES-256-SIV""" +.IP """AES\-128\-GCM\-SIV"", ""AES\-192\-GCM\-SIV"" and ""AES\-256\-GCM\-SIV""" 4 +.IX Item """AES-128-GCM-SIV"", ""AES-192-GCM-SIV"" and ""AES-256-GCM-SIV""" .PD .SS Parameters .IX Subsection "Parameters" @@ -121,9 +123,12 @@ stealing (CTS) is used to fill the block. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +The GCM-SIV mode ciphers were added in OpenSSL version 3.2. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2021\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2021\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_CIPHER-ARIA.7ssl b/upstream/debian-unstable/man7/EVP_CIPHER-ARIA.7ssl index 7a32631a..89f9aadf 100644 --- a/upstream/debian-unstable/man7/EVP_CIPHER-ARIA.7ssl +++ b/upstream/debian-unstable/man7/EVP_CIPHER-ARIA.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_CIPHER-ARIA 7SSL" -.TH EVP_CIPHER-ARIA 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_CIPHER-ARIA 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_CIPHER-BLOWFISH.7ssl b/upstream/debian-unstable/man7/EVP_CIPHER-BLOWFISH.7ssl index e68594d3..6872a6ef 100644 --- a/upstream/debian-unstable/man7/EVP_CIPHER-BLOWFISH.7ssl +++ b/upstream/debian-unstable/man7/EVP_CIPHER-BLOWFISH.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_CIPHER-BLOWFISH 7SSL" -.TH EVP_CIPHER-BLOWFISH 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_CIPHER-BLOWFISH 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_CIPHER-CAMELLIA.7ssl b/upstream/debian-unstable/man7/EVP_CIPHER-CAMELLIA.7ssl index 87704f50..dd5831d7 100644 --- a/upstream/debian-unstable/man7/EVP_CIPHER-CAMELLIA.7ssl +++ b/upstream/debian-unstable/man7/EVP_CIPHER-CAMELLIA.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_CIPHER-CAMELLIA 7SSL" -.TH EVP_CIPHER-CAMELLIA 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_CIPHER-CAMELLIA 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_CIPHER-CAST.7ssl b/upstream/debian-unstable/man7/EVP_CIPHER-CAST.7ssl index 251dda7c..b02e95ab 100644 --- a/upstream/debian-unstable/man7/EVP_CIPHER-CAST.7ssl +++ b/upstream/debian-unstable/man7/EVP_CIPHER-CAST.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_CIPHER-CAST 7SSL" -.TH EVP_CIPHER-CAST 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_CIPHER-CAST 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_CIPHER-CHACHA.7ssl b/upstream/debian-unstable/man7/EVP_CIPHER-CHACHA.7ssl index e27e487f..d7a1a3b7 100644 --- a/upstream/debian-unstable/man7/EVP_CIPHER-CHACHA.7ssl +++ b/upstream/debian-unstable/man7/EVP_CIPHER-CHACHA.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_CIPHER-CHACHA 7SSL" -.TH EVP_CIPHER-CHACHA 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_CIPHER-CHACHA 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_CIPHER-DES.7ssl b/upstream/debian-unstable/man7/EVP_CIPHER-DES.7ssl index 2e7eb299..d2c9d880 100644 --- a/upstream/debian-unstable/man7/EVP_CIPHER-DES.7ssl +++ b/upstream/debian-unstable/man7/EVP_CIPHER-DES.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_CIPHER-DES 7SSL" -.TH EVP_CIPHER-DES 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_CIPHER-DES 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_CIPHER-IDEA.7ssl b/upstream/debian-unstable/man7/EVP_CIPHER-IDEA.7ssl index ec659582..0f464d8b 100644 --- a/upstream/debian-unstable/man7/EVP_CIPHER-IDEA.7ssl +++ b/upstream/debian-unstable/man7/EVP_CIPHER-IDEA.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_CIPHER-IDEA 7SSL" -.TH EVP_CIPHER-IDEA 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_CIPHER-IDEA 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_CIPHER-NULL.7ssl b/upstream/debian-unstable/man7/EVP_CIPHER-NULL.7ssl index 8b68ccc2..c2a4c3d6 100644 --- a/upstream/debian-unstable/man7/EVP_CIPHER-NULL.7ssl +++ b/upstream/debian-unstable/man7/EVP_CIPHER-NULL.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_CIPHER-NULL 7SSL" -.TH EVP_CIPHER-NULL 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_CIPHER-NULL 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_CIPHER-RC2.7ssl b/upstream/debian-unstable/man7/EVP_CIPHER-RC2.7ssl index 2cfaee54..b5490ef2 100644 --- a/upstream/debian-unstable/man7/EVP_CIPHER-RC2.7ssl +++ b/upstream/debian-unstable/man7/EVP_CIPHER-RC2.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_CIPHER-RC2 7SSL" -.TH EVP_CIPHER-RC2 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_CIPHER-RC2 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_CIPHER-RC4.7ssl b/upstream/debian-unstable/man7/EVP_CIPHER-RC4.7ssl index 18c1e7eb..427ef8d3 100644 --- a/upstream/debian-unstable/man7/EVP_CIPHER-RC4.7ssl +++ b/upstream/debian-unstable/man7/EVP_CIPHER-RC4.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_CIPHER-RC4 7SSL" -.TH EVP_CIPHER-RC4 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_CIPHER-RC4 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_CIPHER-RC5.7ssl b/upstream/debian-unstable/man7/EVP_CIPHER-RC5.7ssl index ea7e836d..2b4f81b8 100644 --- a/upstream/debian-unstable/man7/EVP_CIPHER-RC5.7ssl +++ b/upstream/debian-unstable/man7/EVP_CIPHER-RC5.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_CIPHER-RC5 7SSL" -.TH EVP_CIPHER-RC5 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_CIPHER-RC5 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_CIPHER-SEED.7ssl b/upstream/debian-unstable/man7/EVP_CIPHER-SEED.7ssl index ea63c19f..b6612e31 100644 --- a/upstream/debian-unstable/man7/EVP_CIPHER-SEED.7ssl +++ b/upstream/debian-unstable/man7/EVP_CIPHER-SEED.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_CIPHER-SEED 7SSL" -.TH EVP_CIPHER-SEED 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_CIPHER-SEED 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_CIPHER-SM4.7ssl b/upstream/debian-unstable/man7/EVP_CIPHER-SM4.7ssl index 612e0329..692fbe71 100644 --- a/upstream/debian-unstable/man7/EVP_CIPHER-SM4.7ssl +++ b/upstream/debian-unstable/man7/EVP_CIPHER-SM4.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_CIPHER-SM4 7SSL" -.TH EVP_CIPHER-SM4 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_CIPHER-SM4 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -79,11 +79,25 @@ The following algorithms are available in the default provider: .IX Item """SM4-OFB"" or ""SM4-OFB128""" .IP """SM4\-CFB"" or ""SM4\-CFB128""" 4 .IX Item """SM4-CFB"" or ""SM4-CFB128""" +.IP """SM4\-GCM""" 4 +.IX Item """SM4-GCM""" +.IP """SM4\-CCM""" 4 +.IX Item """SM4-CCM""" +.IP """SM4\-XTS""" 4 +.IX Item """SM4-XTS""" .PD .SS Parameters .IX Subsection "Parameters" This implementation supports the parameters described in "PARAMETERS" in \fBEVP_EncryptInit\fR\|(3). +.SH NOTES +.IX Header "NOTES" +The SM4\-XTS implementation allows streaming to be performed, but each +\&\fBEVP_EncryptUpdate\fR\|(3) or \fBEVP_DecryptUpdate\fR\|(3) call requires each input +to be a multiple of the blocksize. Only the final \fBEVP_EncryptUpdate()\fR or +\&\fBEVP_DecryptUpdate()\fR call can optionally have an input that is not a multiple +of the blocksize but is larger than one block. In that case ciphertext +stealing (CTS) is used to fill the block. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBprovider\-cipher\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) diff --git a/upstream/debian-unstable/man7/EVP_KDF-ARGON2.7ssl b/upstream/debian-unstable/man7/EVP_KDF-ARGON2.7ssl new file mode 100644 index 00000000..de02c0f0 --- /dev/null +++ b/upstream/debian-unstable/man7/EVP_KDF-ARGON2.7ssl @@ -0,0 +1,234 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-ARGON2 7SSL" +.TH EVP_KDF-ARGON2 7SSL 2024-04-04 3.2.2-dev 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 +EVP_KDF\-ARGON2 \- The Argon2 EVP KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing the \fBargon2\fR password-based KDF through the \fBEVP_KDF\fR +API. +.PP +The EVP_KDF\-ARGON2 algorithm implements the Argon2 password-based key +derivation function, as described in IETF RFC 9106. It is memory-hard in +the sense that it deliberately requires a significant amount of RAM for efficient +computation. The intention of this is to render brute forcing of passwords on +systems that lack large amounts of main memory (such as GPUs or ASICs) +computationally infeasible. +.PP +Argon2d (Argon2i) uses data-dependent (data-independent) memory access and +primary seek to address trade-off (side-channel) attacks. +.PP +Argon2id is a hybrid construction which, in the first two slices of the first +pass, generates reference addresses data-independently as in Argon2i, whereas +in later slices and next passes it generates them data-dependently as in +Argon2d. +.PP +Sbox-hardened version Argon2ds is not supported. +.PP +For more information, please refer to RFC 9106. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """pass"" (\fBOSSL_KDF_PARAM_PASSWORD\fR) <octet string>" 4 +.IX Item """pass"" (OSSL_KDF_PARAM_PASSWORD) <octet string>" +.PD 0 +.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) <octet string>" 4 +.IX Item """salt"" (OSSL_KDF_PARAM_SALT) <octet string>" +.IP """secret"" (\fBOSSL_KDF_PARAM_SECRET\fR) <octet string>" 4 +.IX Item """secret"" (OSSL_KDF_PARAM_SECRET) <octet string>" +.IP """iter"" (\fBOSSL_KDF_PARAM_ITER\fR) <unsigned integer>" 4 +.IX Item """iter"" (OSSL_KDF_PARAM_ITER) <unsigned integer>" +.IP """size"" (\fBOSSL_KDF_PARAM_SIZE\fR) <unsigned integer>" 4 +.IX Item """size"" (OSSL_KDF_PARAM_SIZE) <unsigned integer>" +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.Sp +Note that RFC 9106 recommends 128 bits salt for most applications, or 64 bits +salt in the case of space constraints. At least 128 bits output length is +recommended. +.Sp +Note that secret (or pepper) is an optional secret data used along the +password. +.IP """threads"" (\fBOSSL_KDF_PARAM_THREADS\fR) <unsigned integer>" 4 +.IX Item """threads"" (OSSL_KDF_PARAM_THREADS) <unsigned integer>" +The number of threads, bounded above by the number of lanes. +.Sp +This can only be used with built-in thread support. Threading must be +explicitly enabled. See EXAMPLES section for more information. +.IP """ad"" (\fBOSSL_KDF_PARAM_ARGON2_AD\fR) <octet string>" 4 +.IX Item """ad"" (OSSL_KDF_PARAM_ARGON2_AD) <octet string>" +Optional associated data, may be used to "tag" a group of keys, or tie them +to a particular public key, without having to modify salt. +.IP """lanes"" (\fBOSSL_KDF_PARAM_ARGON2_LANES\fR) <unsigned integer>" 4 +.IX Item """lanes"" (OSSL_KDF_PARAM_ARGON2_LANES) <unsigned integer>" +Argon2 splits the requested memory size into lanes, each of which is designed +to be processed in parallel. For example, on a system with p cores, it's +recommended to use p lanes. +.Sp +The number of lanes is used to derive the key. It is possible to specify +more lanes than the number of available computational threads. This is +especially encouraged if multi-threading is disabled. +.IP """memcost"" (\fBOSSL_KDF_PARAM_ARGON2_MEMCOST\fR) <unsigned integer>" 4 +.IX Item """memcost"" (OSSL_KDF_PARAM_ARGON2_MEMCOST) <unsigned integer>" +Memory cost parameter (the number of 1k memory blocks used). +.IP """version"" (\fBOSSL_KDF_PARAM_ARGON2_VERSION\fR) <unsigned integer>" 4 +.IX Item """version"" (OSSL_KDF_PARAM_ARGON2_VERSION) <unsigned integer>" +Argon2 version. Supported values: 0x10, 0x13 (default). +.IP """early_clean"" (\fBOSSL_KDF_PARAM_EARLY_CLEAN\fR) <unsigned integer>" 4 +.IX Item """early_clean"" (OSSL_KDF_PARAM_EARLY_CLEAN) <unsigned integer>" +If set (nonzero), password and secret stored in Argon2 context are zeroed +early during initial hash computation, as soon as they are not needed. +Otherwise, they are zeroed along the rest of Argon2 context data on clear, +free, reset. +.Sp +This can be useful if, for example, multiple keys with different ad value +are to be generated from a single password and secret. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example uses Argon2d with password "1234567890", salt "saltsalt", +using 2 lanes, 2 threads, and memory cost of 65536: +.PP +.Vb 5 +\& #include <string.h> /* strlen */ +\& #include <openssl/core_names.h> /* OSSL_KDF_* */ +\& #include <openssl/params.h> /* OSSL_PARAM_* */ +\& #include <openssl/thread.h> /* OSSL_set_max_threads */ +\& #include <openssl/kdf.h> /* EVP_KDF_* */ +\& +\& int main(void) +\& { +\& int retval = 1; +\& +\& EVP_KDF *kdf = NULL; +\& EVP_KDF_CTX *kctx = NULL; +\& OSSL_PARAM params[6], *p = params; +\& +\& /* argon2 params, please refer to RFC9106 for recommended defaults */ +\& uint32_t lanes = 2, threads = 2, memcost = 65536; +\& char pwd[] = "1234567890", salt[] = "saltsalt"; +\& +\& /* derive result */ +\& size_t outlen = 128; +\& unsigned char result[outlen]; +\& +\& /* required if threads > 1 */ +\& if (OSSL_set_max_threads(NULL, threads) != 1) +\& goto fail; +\& +\& p = params; +\& *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_THREADS, &threads); +\& *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_LANES, +\& &lanes); +\& *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_MEMCOST, +\& &memcost); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& salt, +\& strlen((const char *)salt)); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD, +\& pwd, +\& strlen((const char *)pwd)); +\& *p++ = OSSL_PARAM_construct_end(); +\& +\& if ((kdf = EVP_KDF_fetch(NULL, "ARGON2D", NULL)) == NULL) +\& goto fail; +\& if ((kctx = EVP_KDF_CTX_new(kdf)) == NULL) +\& goto fail; +\& if (EVP_KDF_derive(kctx, &result[0], outlen, params) != 1) +\& goto fail; +\& +\& printf("Output = %s\en", OPENSSL_buf2hexstr(result, outlen)); +\& retval = 0; +\& +\& fail: +\& EVP_KDF_free(kdf); +\& EVP_KDF_CTX_free(kctx); +\& OSSL_set_max_threads(NULL, 0); +\& +\& return retval; +\& } +.Ve +.SH NOTES +.IX Header "NOTES" +"ARGON2I", "ARGON2D", and "ARGON2ID" are the names for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 9106 Argon2, see <https://www.rfc\-editor.org/rfc/rfc9106.txt>. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added to OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/EVP_KDF-HKDF.7ssl b/upstream/debian-unstable/man7/EVP_KDF-HKDF.7ssl index 4bad27db..22dec65a 100644 --- a/upstream/debian-unstable/man7/EVP_KDF-HKDF.7ssl +++ b/upstream/debian-unstable/man7/EVP_KDF-HKDF.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KDF-HKDF 7SSL" -.TH EVP_KDF-HKDF 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KDF-HKDF 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -192,7 +192,7 @@ RFC 5869 This functionality was added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2016\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_KDF-HMAC-DRBG.7ssl b/upstream/debian-unstable/man7/EVP_KDF-HMAC-DRBG.7ssl new file mode 100644 index 00000000..d67e60d4 --- /dev/null +++ b/upstream/debian-unstable/man7/EVP_KDF-HMAC-DRBG.7ssl @@ -0,0 +1,117 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-HMAC-DRBG 7SSL" +.TH EVP_KDF-HMAC-DRBG 7SSL 2024-04-04 3.2.2-dev 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 +EVP_KDF\-HMAC\-DRBG +\&\- The HMAC DRBG DETERMINISTIC EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for a deterministic HMAC DRBG using the \fBEVP_KDF\fR API. This is similar +to \fBEVP_RAND\-HMAC\-DRBG\fR\|(7), but uses fixed values for its entropy and nonce +values. This is used to generate deterministic nonce value required by ECDSA +and DSA (as defined in RFC 6979). +.SS Identity +.IX Subsection "Identity" +"HMAC-DRBG-KDF" is the name for this implementation; it can be used +with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """digest"" (\fBOSSL_DRBG_PARAM_DIGEST\fR) <UTF8 string>" 4 +.IX Item """digest"" (OSSL_DRBG_PARAM_DIGEST) <UTF8 string>" +.PD 0 +.IP """properties"" (\fBOSSL_DRBG_PARAM_PROPERTIES\fR) <UTF8 string>" 4 +.IX Item """properties"" (OSSL_DRBG_PARAM_PROPERTIES) <UTF8 string>" +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.IP """entropy"" (\fBOSSL_KDF_PARAM_HMACDRBG_ENTROPY\fR) <octet string>" 4 +.IX Item """entropy"" (OSSL_KDF_PARAM_HMACDRBG_ENTROPY) <octet string>" +Sets the entropy bytes supplied to the HMAC-DRBG. +.IP """nonce"" (\fBOSSL_KDF_PARAM_HMACDRBG_NONCE\fR) <octet string>" 4 +.IX Item """nonce"" (OSSL_KDF_PARAM_HMACDRBG_NONCE) <octet string>" +Sets the nonce bytes supplied to the HMAC-DRBG. +.SH NOTES +.IX Header "NOTES" +A context for KDF HMAC DRBG can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "HMAC\-DRBG\-KDF", NULL); +\& EVP_KDF_CTX *kdf_ctx = EVP_KDF_CTX_new(kdf, NULL); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 6979 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The EVP_KDF\-HMAC\-DRBG functionality was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/EVP_KDF-KB.7ssl b/upstream/debian-unstable/man7/EVP_KDF-KB.7ssl index ebd0f956..a5ce67d3 100644 --- a/upstream/debian-unstable/man7/EVP_KDF-KB.7ssl +++ b/upstream/debian-unstable/man7/EVP_KDF-KB.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KDF-KB 7SSL" -.TH EVP_KDF-KB 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KDF-KB 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_KDF-KRB5KDF.7ssl b/upstream/debian-unstable/man7/EVP_KDF-KRB5KDF.7ssl index 3c98451d..e0427c56 100644 --- a/upstream/debian-unstable/man7/EVP_KDF-KRB5KDF.7ssl +++ b/upstream/debian-unstable/man7/EVP_KDF-KRB5KDF.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KDF-KRB5KDF 7SSL" -.TH EVP_KDF-KRB5KDF 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KDF-KRB5KDF 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -154,7 +154,7 @@ RFC 3961 This functionality was added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2016\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_KDF-PBKDF1.7ssl b/upstream/debian-unstable/man7/EVP_KDF-PBKDF1.7ssl index ad301467..dbe61913 100644 --- a/upstream/debian-unstable/man7/EVP_KDF-PBKDF1.7ssl +++ b/upstream/debian-unstable/man7/EVP_KDF-PBKDF1.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KDF-PBKDF1 7SSL" -.TH EVP_KDF-PBKDF1 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KDF-PBKDF1 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -105,6 +105,8 @@ of candidate passwords. .PP No assumption is made regarding the given password; it is simply treated as a byte sequence. +.PP +The legacy provider needs to be available in order to access this algorithm. .SH "CONFORMING TO" .IX Header "CONFORMING TO" RFC 8018 @@ -115,13 +117,14 @@ RFC 8018 \&\fBEVP_KDF_CTX_free\fR\|(3), \&\fBEVP_KDF_CTX_set_params\fR\|(3), \&\fBEVP_KDF_derive\fR\|(3), -"PARAMETERS" in \fBEVP_KDF\fR\|(3) +"PARAMETERS" in \fBEVP_KDF\fR\|(3), +\&\fBOSSL_PROVIDER\-legacy\fR\|(7) .SH HISTORY .IX Header "HISTORY" This functionality was added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2021\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_KDF-PBKDF2.7ssl b/upstream/debian-unstable/man7/EVP_KDF-PBKDF2.7ssl index ce546afe..1301aeca 100644 --- a/upstream/debian-unstable/man7/EVP_KDF-PBKDF2.7ssl +++ b/upstream/debian-unstable/man7/EVP_KDF-PBKDF2.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KDF-PBKDF2 7SSL" -.TH EVP_KDF-PBKDF2 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KDF-PBKDF2 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -144,7 +144,7 @@ SP800\-132 This functionality was added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2018\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2018\-2020 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_KDF-PKCS12KDF.7ssl b/upstream/debian-unstable/man7/EVP_KDF-PKCS12KDF.7ssl index d79511af..ee938674 100644 --- a/upstream/debian-unstable/man7/EVP_KDF-PKCS12KDF.7ssl +++ b/upstream/debian-unstable/man7/EVP_KDF-PKCS12KDF.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KDF-PKCS12KDF 7SSL" -.TH EVP_KDF-PKCS12KDF 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KDF-PKCS12KDF 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_KDF-PVKKDF.7ssl b/upstream/debian-unstable/man7/EVP_KDF-PVKKDF.7ssl new file mode 100644 index 00000000..13de1a58 --- /dev/null +++ b/upstream/debian-unstable/man7/EVP_KDF-PVKKDF.7ssl @@ -0,0 +1,118 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-PVKKDF 7SSL" +.TH EVP_KDF-PVKKDF 7SSL 2024-04-04 3.2.2-dev 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 +EVP_KDF\-PVKKDF \- The PVK EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing the \fBPVK KDF\fR PIN-based KDF through the \fBEVP_KDF\fR +API. +.PP +The EVP_KDF\-PVKKDF algorithm implements a PVK PIN-based key +derivation function; it derives a key from a password using a salt. +.SS Identity +.IX Subsection "Identity" +"PVKKDF" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """pass"" (\fBOSSL_KDF_PARAM_PASSWORD\fR) <octet string>" 4 +.IX Item """pass"" (OSSL_KDF_PARAM_PASSWORD) <octet string>" +.PD 0 +.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) <octet string>" 4 +.IX Item """salt"" (OSSL_KDF_PARAM_SALT) <octet string>" +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) <UTF8 string>" 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +.IP """digest"" (\fBOSSL_KDF_PARAM_DIGEST\fR) <UTF8 string>" 4 +.IX Item """digest"" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>" +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.SH NOTES +.IX Header "NOTES" +A typical application of this algorithm is to derive keying material for an +encryption algorithm from a password in the "pass" and a salt in "salt". +.PP +No assumption is made regarding the given password; it is simply treated as a +byte sequence. +.PP +The legacy provider needs to be available in order to access this algorithm. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3), +\&\fBOSSL_PROVIDER\-legacy\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/EVP_KDF-SCRYPT.7ssl b/upstream/debian-unstable/man7/EVP_KDF-SCRYPT.7ssl index c19cea39..8195942f 100644 --- a/upstream/debian-unstable/man7/EVP_KDF-SCRYPT.7ssl +++ b/upstream/debian-unstable/man7/EVP_KDF-SCRYPT.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KDF-SCRYPT 7SSL" -.TH EVP_KDF-SCRYPT 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KDF-SCRYPT 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -191,7 +191,7 @@ RFC 7914 This functionality was added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2017\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_KDF-SS.7ssl b/upstream/debian-unstable/man7/EVP_KDF-SS.7ssl index 4505eeaf..b8cd475e 100644 --- a/upstream/debian-unstable/man7/EVP_KDF-SS.7ssl +++ b/upstream/debian-unstable/man7/EVP_KDF-SS.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KDF-SS 7SSL" -.TH EVP_KDF-SS 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KDF-SS 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_KDF-SSHKDF.7ssl b/upstream/debian-unstable/man7/EVP_KDF-SSHKDF.7ssl index 7ff3f699..217ba17b 100644 --- a/upstream/debian-unstable/man7/EVP_KDF-SSHKDF.7ssl +++ b/upstream/debian-unstable/man7/EVP_KDF-SSHKDF.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KDF-SSHKDF 7SSL" -.TH EVP_KDF-SSHKDF 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KDF-SSHKDF 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_KDF-TLS13_KDF.7ssl b/upstream/debian-unstable/man7/EVP_KDF-TLS13_KDF.7ssl index 7472712e..3aaa0d88 100644 --- a/upstream/debian-unstable/man7/EVP_KDF-TLS13_KDF.7ssl +++ b/upstream/debian-unstable/man7/EVP_KDF-TLS13_KDF.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KDF-TLS13_KDF 7SSL" -.TH EVP_KDF-TLS13_KDF 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KDF-TLS13_KDF 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -166,7 +166,7 @@ RFC 8446 This functionality was added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2021\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_KDF-TLS1_PRF.7ssl b/upstream/debian-unstable/man7/EVP_KDF-TLS1_PRF.7ssl index 9275b6dc..b0972317 100644 --- a/upstream/debian-unstable/man7/EVP_KDF-TLS1_PRF.7ssl +++ b/upstream/debian-unstable/man7/EVP_KDF-TLS1_PRF.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KDF-TLS1_PRF 7SSL" -.TH EVP_KDF-TLS1_PRF 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KDF-TLS1_PRF 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -153,7 +153,7 @@ RFC 2246, RFC 5246 and NIST SP 800\-135 r1 This functionality was added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2018\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_KDF-X942-ASN1.7ssl b/upstream/debian-unstable/man7/EVP_KDF-X942-ASN1.7ssl index eb2753f9..05dcfbcb 100644 --- a/upstream/debian-unstable/man7/EVP_KDF-X942-ASN1.7ssl +++ b/upstream/debian-unstable/man7/EVP_KDF-X942-ASN1.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KDF-X942-ASN1 7SSL" -.TH EVP_KDF-X942-ASN1 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KDF-X942-ASN1 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -183,7 +183,7 @@ RFC 2631 This functionality was added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2019\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_KDF-X942-CONCAT.7ssl b/upstream/debian-unstable/man7/EVP_KDF-X942-CONCAT.7ssl index 790b738f..a62a1c1f 100644 --- a/upstream/debian-unstable/man7/EVP_KDF-X942-CONCAT.7ssl +++ b/upstream/debian-unstable/man7/EVP_KDF-X942-CONCAT.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KDF-X942-CONCAT 7SSL" -.TH EVP_KDF-X942-CONCAT 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KDF-X942-CONCAT 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -80,7 +80,7 @@ See \fBEVP_KDF\-X963\fR\|(7) for a list of supported parameters and examples. This functionality was added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_KDF-X963.7ssl b/upstream/debian-unstable/man7/EVP_KDF-X963.7ssl index b394e4a2..9ac5116d 100644 --- a/upstream/debian-unstable/man7/EVP_KDF-X963.7ssl +++ b/upstream/debian-unstable/man7/EVP_KDF-X963.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KDF-X963 7SSL" -.TH EVP_KDF-X963 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KDF-X963 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -147,7 +147,7 @@ value "label": This functionality was added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2019\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_KEM-EC.7ssl b/upstream/debian-unstable/man7/EVP_KEM-EC.7ssl new file mode 100644 index 00000000..72eb48ef --- /dev/null +++ b/upstream/debian-unstable/man7/EVP_KEM-EC.7ssl @@ -0,0 +1,124 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "EVP_KEM-EC 7SSL" +.TH EVP_KEM-EC 7SSL 2024-04-04 3.2.2-dev 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 +EVP_KEM\-EC +\&\- EVP_KEM EC keytype and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBEC\fR keytype and its parameters are described in \fBEVP_PKEY\-EC\fR\|(7). +See \fBEVP_PKEY_encapsulate\fR\|(3) and \fBEVP_PKEY_decapsulate\fR\|(3) for more info. +.SS "EC KEM parameters" +.IX Subsection "EC KEM parameters" +.IP """operation"" (\fBOSSL_KEM_PARAM_OPERATION\fR)<UTF8 string>" 4 +.IX Item """operation"" (OSSL_KEM_PARAM_OPERATION)<UTF8 string>" +The OpenSSL EC Key Encapsulation Mechanisms only supports the +following operation: +.RS 4 +.IP """DHKEM"" (\fBOSSL_KEM_PARAM_OPERATION_DHKEM\fR)" 4 +.IX Item """DHKEM"" (OSSL_KEM_PARAM_OPERATION_DHKEM)" +The encapsulate function generates an ephemeral keypair. It produces keymaterial +by doing an ECDH key exchange using the ephemeral private key and a supplied +recipient public key. A HKDF operation using the keymaterial and a kem context +then produces a shared secret. The shared secret and the ephemeral public key +are returned. +The decapsulate function uses the recipient private key and the +ephemeral public key to produce the same keymaterial, which can then be used to +produce the same shared secret. +See <https://www.rfc\-editor.org/rfc/rfc9180.html#name\-dh\-based\-kem\-dhkem> +.RE +.RS 4 +.Sp +This can be set using either \fBEVP_PKEY_CTX_set_kem_op()\fR or +\&\fBEVP_PKEY_CTX_set_params()\fR. +.RE +.IP """ikme"" (\fBOSSL_KEM_PARAM_IKME\fR) <octet string>" 4 +.IX Item """ikme"" (OSSL_KEM_PARAM_IKME) <octet string>" +Used to specify the key material used for generation of the ephemeral key. +This value should not be reused for other purposes. +It can only be used for the curves "P\-256", "P\-384" and "P\-521" and should +have a length of at least the size of the encoded private key +(i.e. 32, 48 and 66 for the listed curves). +If this value is not set, then a random ikm is used. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP RFC9180 4 +.IX Item "RFC9180" +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set_kem_op\fR\|(3), +\&\fBEVP_PKEY_encapsulate\fR\|(3), +\&\fBEVP_PKEY_decapsulate\fR\|(3) +\&\fBEVP_KEYMGMT\fR\|(3), +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/EVP_KEM-RSA.7ssl b/upstream/debian-unstable/man7/EVP_KEM-RSA.7ssl index b2d06a60..46bea425 100644 --- a/upstream/debian-unstable/man7/EVP_KEM-RSA.7ssl +++ b/upstream/debian-unstable/man7/EVP_KEM-RSA.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KEM-RSA 7SSL" -.TH EVP_KEM-RSA 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KEM-RSA 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -103,7 +103,7 @@ Section 7.2.1.3 RSASVE Recovery Operation (RSASVE.RECOVER). This functionality was added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_KEM-X25519.7ssl b/upstream/debian-unstable/man7/EVP_KEM-X25519.7ssl new file mode 100644 index 00000000..bcadb6a3 --- /dev/null +++ b/upstream/debian-unstable/man7/EVP_KEM-X25519.7ssl @@ -0,0 +1,123 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "EVP_KEM-X25519 7SSL" +.TH EVP_KEM-X25519 7SSL 2024-04-04 3.2.2-dev 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 +EVP_KEM\-X25519, EVP_KEM\-X448 +\&\- EVP_KEM X25519 and EVP_KEM X448 keytype and algorithm support +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBX25519\fR and <X448> keytype and its parameters are described in +\&\fBEVP_PKEY\-X25519\fR\|(7). +See \fBEVP_PKEY_encapsulate\fR\|(3) and \fBEVP_PKEY_decapsulate\fR\|(3) for more info. +.SS "X25519 and X448 KEM parameters" +.IX Subsection "X25519 and X448 KEM parameters" +.IP """operation"" (\fBOSSL_KEM_PARAM_OPERATION\fR)<UTF8 string>" 4 +.IX Item """operation"" (OSSL_KEM_PARAM_OPERATION)<UTF8 string>" +The OpenSSL X25519 and X448 Key Encapsulation Mechanisms only support the +following operation: +.RS 4 +.IP """DHKEM"" (\fBOSSL_KEM_PARAM_OPERATION_DHKEM\fR)" 4 +.IX Item """DHKEM"" (OSSL_KEM_PARAM_OPERATION_DHKEM)" +The encapsulate function generates an ephemeral keypair. It produces keymaterial +by doing an X25519 or X448 key exchange using the ephemeral private key and a +supplied recipient public key. A HKDF operation using the keymaterial and a kem +context then produces a shared secret. The shared secret and the ephemeral +public key are returned. +The decapsulate function uses the recipient private key and the +ephemeral public key to produce the same keymaterial, which can then be used to +produce the same shared secret. +See <https://www.rfc\-editor.org/rfc/rfc9180.html#name\-dh\-based\-kem\-dhkem> +.RE +.RS 4 +.Sp +This can be set using either \fBEVP_PKEY_CTX_set_kem_op()\fR or +\&\fBEVP_PKEY_CTX_set_params()\fR. +.RE +.IP """ikme"" (\fBOSSL_KEM_PARAM_IKME\fR) <octet string>" 4 +.IX Item """ikme"" (OSSL_KEM_PARAM_IKME) <octet string>" +Used to specify the key material used for generation of the ephemeral key. +This value should not be reused for other purposes. +It should have a length of at least 32 for X25519, and 56 for X448. +If this value is not set, then a random ikm is used. +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +.IP RFC9180 4 +.IX Item "RFC9180" +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_set_kem_op\fR\|(3), +\&\fBEVP_PKEY_encapsulate\fR\|(3), +\&\fBEVP_PKEY_decapsulate\fR\|(3) +\&\fBEVP_KEYMGMT\fR\|(3), +\&\fBEVP_PKEY\fR\|(3), +\&\fBprovider\-keymgmt\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.2. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/EVP_KEYEXCH-DH.7ssl b/upstream/debian-unstable/man7/EVP_KEYEXCH-DH.7ssl index 8c221d8b..9dd6c96b 100644 --- a/upstream/debian-unstable/man7/EVP_KEYEXCH-DH.7ssl +++ b/upstream/debian-unstable/man7/EVP_KEYEXCH-DH.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KEYEXCH-DH 7SSL" -.TH EVP_KEYEXCH-DH 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KEYEXCH-DH 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_KEYEXCH-ECDH.7ssl b/upstream/debian-unstable/man7/EVP_KEYEXCH-ECDH.7ssl index f397031a..45ff44b6 100644 --- a/upstream/debian-unstable/man7/EVP_KEYEXCH-ECDH.7ssl +++ b/upstream/debian-unstable/man7/EVP_KEYEXCH-ECDH.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KEYEXCH-ECDH 7SSL" -.TH EVP_KEYEXCH-ECDH 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KEYEXCH-ECDH 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_KEYEXCH-X25519.7ssl b/upstream/debian-unstable/man7/EVP_KEYEXCH-X25519.7ssl index c978872a..6e76a354 100644 --- a/upstream/debian-unstable/man7/EVP_KEYEXCH-X25519.7ssl +++ b/upstream/debian-unstable/man7/EVP_KEYEXCH-X25519.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_KEYEXCH-X25519 7SSL" -.TH EVP_KEYEXCH-X25519 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_KEYEXCH-X25519 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_MAC-BLAKE2.7ssl b/upstream/debian-unstable/man7/EVP_MAC-BLAKE2.7ssl index 8fdc3866..bd16bda2 100644 --- a/upstream/debian-unstable/man7/EVP_MAC-BLAKE2.7ssl +++ b/upstream/debian-unstable/man7/EVP_MAC-BLAKE2.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MAC-BLAKE2 7SSL" -.TH EVP_MAC-BLAKE2 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MAC-BLAKE2 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -123,7 +123,7 @@ It is 64 for EVP_MAC_BLAKE2S and 128 for EVP_MAC_BLAKE2B. The macros and functions described here were added to OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2018\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_MAC-CMAC.7ssl b/upstream/debian-unstable/man7/EVP_MAC-CMAC.7ssl index 67d6c091..49ea42e8 100644 --- a/upstream/debian-unstable/man7/EVP_MAC-CMAC.7ssl +++ b/upstream/debian-unstable/man7/EVP_MAC-CMAC.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MAC-CMAC 7SSL" -.TH EVP_MAC-CMAC 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MAC-CMAC 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -110,7 +110,7 @@ Gets the MAC block size. The "block-size" parameter can also be retrieved with "PARAMETERS" in \fBEVP_MAC\fR\|(3), \fBOSSL_PARAM\fR\|(3) .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2018\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2018\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_MAC-GMAC.7ssl b/upstream/debian-unstable/man7/EVP_MAC-GMAC.7ssl index 3a2b7385..d003ee60 100644 --- a/upstream/debian-unstable/man7/EVP_MAC-GMAC.7ssl +++ b/upstream/debian-unstable/man7/EVP_MAC-GMAC.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MAC-GMAC 7SSL" -.TH EVP_MAC-GMAC 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MAC-GMAC 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_MAC-HMAC.7ssl b/upstream/debian-unstable/man7/EVP_MAC-HMAC.7ssl index 202b24da..caebdf03 100644 --- a/upstream/debian-unstable/man7/EVP_MAC-HMAC.7ssl +++ b/upstream/debian-unstable/man7/EVP_MAC-HMAC.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MAC-HMAC 7SSL" -.TH EVP_MAC-HMAC 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MAC-HMAC 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -119,7 +119,7 @@ Gets the MAC block size. The "block-size" parameter can also be retrieved with "PARAMETERS" in \fBEVP_MAC\fR\|(3), \fBOSSL_PARAM\fR\|(3), \fBHMAC\fR\|(3) .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2018\-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2018\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_MAC-KMAC.7ssl b/upstream/debian-unstable/man7/EVP_MAC-KMAC.7ssl index 2c61b7f3..0fb1f08b 100644 --- a/upstream/debian-unstable/man7/EVP_MAC-KMAC.7ssl +++ b/upstream/debian-unstable/man7/EVP_MAC-KMAC.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MAC-KMAC 7SSL" -.TH EVP_MAC-KMAC 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MAC-KMAC 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -187,7 +187,7 @@ set before it instead. "PARAMETERS" in \fBEVP_MAC\fR\|(3), \fBOSSL_PARAM\fR\|(3) .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2018\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2018\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_MAC-Poly1305.7ssl b/upstream/debian-unstable/man7/EVP_MAC-Poly1305.7ssl index fd091f8c..d73e897c 100644 --- a/upstream/debian-unstable/man7/EVP_MAC-Poly1305.7ssl +++ b/upstream/debian-unstable/man7/EVP_MAC-Poly1305.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MAC-POLY1305 7SSL" -.TH EVP_MAC-POLY1305 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MAC-POLY1305 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_MAC-Siphash.7ssl b/upstream/debian-unstable/man7/EVP_MAC-Siphash.7ssl index 9683867a..78039244 100644 --- a/upstream/debian-unstable/man7/EVP_MAC-Siphash.7ssl +++ b/upstream/debian-unstable/man7/EVP_MAC-Siphash.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MAC-SIPHASH 7SSL" -.TH EVP_MAC-SIPHASH 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MAC-SIPHASH 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_MD-BLAKE2.7ssl b/upstream/debian-unstable/man7/EVP_MD-BLAKE2.7ssl index 91452964..0c825434 100644 --- a/upstream/debian-unstable/man7/EVP_MD-BLAKE2.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-BLAKE2.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-BLAKE2 7SSL" -.TH EVP_MD-BLAKE2 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-BLAKE2 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -79,12 +79,30 @@ Known names are "BLAKE2B\-512" and "BLAKE2b512". .IX Subsection "Gettable Parameters" This implementation supports the common gettable parameters described in \fBEVP_MD\-common\fR\|(7). +.SS "Settable Context Parameters" +.IX Subsection "Settable Context Parameters" +The BLAKE2B\-512 implementation supports the following \fBOSSL_PARAM\fR\|(3) entries +which are settable for an \fBEVP_MD_CTX\fR with \fBEVP_DigestInit_ex2\fR\|(3) or +\&\fBEVP_MD_CTX_set_params\fR\|(3): +.IP """size"" (\fBOSSL_DIGEST_PARAM_SIZE\fR) <unsigned integer>" 4 +.IX Item """size"" (OSSL_DIGEST_PARAM_SIZE) <unsigned integer>" +Sets a different digest length for the \fBEVP_DigestFinal\fR\|(3) output. +The value of the "size" parameter must not exceed the default digest length +(64 for BLAKE2B\-512). The parameter must be set with the +\&\fBEVP_DigestInit_ex2\fR\|(3) call to have an immediate effect. When set with +\&\fBEVP_MD_CTX_set_params\fR\|(3) it will have an effect only if the \fBEVP_MD_CTX\fR +context is reinitialized. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.PP +The variable size support was added in OpenSSL 3.2 for BLAKE2B\-512. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_MD-KECCAK.7ssl b/upstream/debian-unstable/man7/EVP_MD-KECCAK.7ssl new file mode 100644 index 00000000..de8530fe --- /dev/null +++ b/upstream/debian-unstable/man7/EVP_MD-KECCAK.7ssl @@ -0,0 +1,96 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "EVP_MD-KECCAK 7SSL" +.TH EVP_MD-KECCAK 7SSL 2024-04-04 3.2.2-dev 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 +EVP_MD\-KECCAK \- The KECCAK EVP_MD implementations +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing KECCAK digests through the \fBEVP_MD\fR API. +.SS Identities +.IX Subsection "Identities" +This implementation is available in the default provider and +includes the following varieties: +.IP """KECCAK\-224""" 4 +.IX Item """KECCAK-224""" +.PD 0 +.IP """KECCAK\-256""" 4 +.IX Item """KECCAK-256""" +.IP """KECCAK\-384""" 4 +.IX Item """KECCAK-384""" +.IP """KECCAK\-512""" 4 +.IX Item """KECCAK-512""" +.PD +.SS "Gettable Parameters" +.IX Subsection "Gettable Parameters" +This implementation supports the common gettable parameters described +in \fBEVP_MD\-common\fR\|(7). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/EVP_MD-MD2.7ssl b/upstream/debian-unstable/man7/EVP_MD-MD2.7ssl index ec772c07..3c10b380 100644 --- a/upstream/debian-unstable/man7/EVP_MD-MD2.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-MD2.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-MD2 7SSL" -.TH EVP_MD-MD2 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-MD2 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_MD-MD4.7ssl b/upstream/debian-unstable/man7/EVP_MD-MD4.7ssl index 506dcf15..658ec45e 100644 --- a/upstream/debian-unstable/man7/EVP_MD-MD4.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-MD4.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-MD4 7SSL" -.TH EVP_MD-MD4 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-MD4 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_MD-MD5-SHA1.7ssl b/upstream/debian-unstable/man7/EVP_MD-MD5-SHA1.7ssl index 32d9e2c6..e08aa3c1 100644 --- a/upstream/debian-unstable/man7/EVP_MD-MD5-SHA1.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-MD5-SHA1.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-MD5-SHA1 7SSL" -.TH EVP_MD-MD5-SHA1 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-MD5-SHA1 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_MD-MD5.7ssl b/upstream/debian-unstable/man7/EVP_MD-MD5.7ssl index 328e8d6c..85d3ffed 100644 --- a/upstream/debian-unstable/man7/EVP_MD-MD5.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-MD5.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-MD5 7SSL" -.TH EVP_MD-MD5 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-MD5 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_MD-MDC2.7ssl b/upstream/debian-unstable/man7/EVP_MD-MDC2.7ssl index 5f398945..56c68424 100644 --- a/upstream/debian-unstable/man7/EVP_MD-MDC2.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-MDC2.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-MDC2 7SSL" -.TH EVP_MD-MDC2 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-MDC2 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_MD-NULL.7ssl b/upstream/debian-unstable/man7/EVP_MD-NULL.7ssl index e2f747c5..245a18c3 100644 --- a/upstream/debian-unstable/man7/EVP_MD-NULL.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-NULL.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-NULL 7SSL" -.TH EVP_MD-NULL 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-NULL 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_MD-RIPEMD160.7ssl b/upstream/debian-unstable/man7/EVP_MD-RIPEMD160.7ssl index bc9f8bdc..77165173 100644 --- a/upstream/debian-unstable/man7/EVP_MD-RIPEMD160.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-RIPEMD160.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-RIPEMD160 7SSL" -.TH EVP_MD-RIPEMD160 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-RIPEMD160 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -82,7 +82,7 @@ in \fBEVP_MD\-common\fR\|(7). This digest was added to the default provider in OpenSSL 3.0.7. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_MD-SHA1.7ssl b/upstream/debian-unstable/man7/EVP_MD-SHA1.7ssl index db3ae2cf..bf86997a 100644 --- a/upstream/debian-unstable/man7/EVP_MD-SHA1.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-SHA1.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-SHA1 7SSL" -.TH EVP_MD-SHA1 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-SHA1 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_MD-SHA2.7ssl b/upstream/debian-unstable/man7/EVP_MD-SHA2.7ssl index bfcb5e01..b3d6cf2f 100644 --- a/upstream/debian-unstable/man7/EVP_MD-SHA2.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-SHA2.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-SHA2 7SSL" -.TH EVP_MD-SHA2 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-SHA2 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -89,6 +89,9 @@ Known names are "SHA2\-512", "SHA\-512" and "SHA512". .IP \(bu 4 Available with the default provider: .RS 4 +.IP SHA2\-256/192 4 +.IX Item "SHA2-256/192" +Known names are "SHA2\-256/192", "SHA\-256/192" and "SHA256\-192". .IP SHA2\-512/224 4 .IX Item "SHA2-512/224" Known names are "SHA2\-512/224", "SHA\-512/224" and "SHA512\-224". @@ -107,7 +110,7 @@ in \fBEVP_MD\-common\fR\|(7). \&\fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_MD-SHA3.7ssl b/upstream/debian-unstable/man7/EVP_MD-SHA3.7ssl index a991b251..8f74961b 100644 --- a/upstream/debian-unstable/man7/EVP_MD-SHA3.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-SHA3.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-SHA3 7SSL" -.TH EVP_MD-SHA3 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-SHA3 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_MD-SHAKE.7ssl b/upstream/debian-unstable/man7/EVP_MD-SHAKE.7ssl index ddc09653..e7ded890 100644 --- a/upstream/debian-unstable/man7/EVP_MD-SHAKE.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-SHAKE.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-SHAKE 7SSL" -.TH EVP_MD-SHAKE 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-SHAKE 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -118,7 +118,7 @@ maximum security strength of 256 bits, the xoflen should be set to at least 64. \&\fBEVP_MD_CTX_set_params\fR\|(3), \fBprovider\-digest\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7) .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_MD-SM3.7ssl b/upstream/debian-unstable/man7/EVP_MD-SM3.7ssl index a83aceb5..6486fa88 100644 --- a/upstream/debian-unstable/man7/EVP_MD-SM3.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-SM3.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-SM3 7SSL" -.TH EVP_MD-SM3 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-SM3 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_MD-WHIRLPOOL.7ssl b/upstream/debian-unstable/man7/EVP_MD-WHIRLPOOL.7ssl index a6d7e183..dab2301f 100644 --- a/upstream/debian-unstable/man7/EVP_MD-WHIRLPOOL.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-WHIRLPOOL.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-WHIRLPOOL 7SSL" -.TH EVP_MD-WHIRLPOOL 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-WHIRLPOOL 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_MD-common.7ssl b/upstream/debian-unstable/man7/EVP_MD-common.7ssl index 9bccd5cf..0937fd53 100644 --- a/upstream/debian-unstable/man7/EVP_MD-common.7ssl +++ b/upstream/debian-unstable/man7/EVP_MD-common.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_MD-COMMON 7SSL" -.TH EVP_MD-COMMON 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_MD-COMMON 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_PKEY-DH.7ssl b/upstream/debian-unstable/man7/EVP_PKEY-DH.7ssl index 3bd6c8a2..d9936d82 100644 --- a/upstream/debian-unstable/man7/EVP_PKEY-DH.7ssl +++ b/upstream/debian-unstable/man7/EVP_PKEY-DH.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_PKEY-DH 7SSL" -.TH EVP_PKEY-DH 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_PKEY-DH 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -359,7 +359,7 @@ The following sections of FIPS186\-4: \&\fBOSSL_PROVIDER\-FIPS\fR\|(7) .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_PKEY-DSA.7ssl b/upstream/debian-unstable/man7/EVP_PKEY-DSA.7ssl index dd3370e4..ab1c9011 100644 --- a/upstream/debian-unstable/man7/EVP_PKEY-DSA.7ssl +++ b/upstream/debian-unstable/man7/EVP_PKEY-DSA.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_PKEY-DSA 7SSL" -.TH EVP_PKEY-DSA 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_PKEY-DSA 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -167,7 +167,7 @@ The following sections of FIPS186\-4: \&\fBOSSL_PROVIDER\-FIPS\fR\|(7) .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_PKEY-EC.7ssl b/upstream/debian-unstable/man7/EVP_PKEY-EC.7ssl index d55f603f..047d90dd 100644 --- a/upstream/debian-unstable/man7/EVP_PKEY-EC.7ssl +++ b/upstream/debian-unstable/man7/EVP_PKEY-EC.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_PKEY-EC 7SSL" -.TH EVP_PKEY-EC 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_PKEY-EC 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -188,6 +188,13 @@ Used for getting the EC public key Y component. .IX Item """default-digest"" (OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 string>" Getter that returns the default digest name. (Currently returns "SHA256" as of OpenSSL 3.0). +.IP """dhkem-ikm"" (\fBOSSL_PKEY_PARAM_DHKEM_IKM\fR) <octet string>" 4 +.IX Item """dhkem-ikm"" (OSSL_PKEY_PARAM_DHKEM_IKM) <octet string>" +DHKEM requires the generation of a keypair using an input key material (seed). +Use this to specify the key material used for generation of the private key. +This value should not be reused for other purposes. It can only be used +for the curves "P\-256", "P\-384" and "P\-521" and should have a length of at least +the size of the encoded private key (i.e. 32, 48 and 66 for the listed curves). .PP The following Gettable types are also available for the built-in EC algorithm: .IP """basis-type"" (\fBOSSL_PKEY_PARAM_EC_CHAR2_TYPE\fR) <UTF8 string>" 4 diff --git a/upstream/debian-unstable/man7/EVP_PKEY-FFC.7ssl b/upstream/debian-unstable/man7/EVP_PKEY-FFC.7ssl index 51420563..ec06768d 100644 --- a/upstream/debian-unstable/man7/EVP_PKEY-FFC.7ssl +++ b/upstream/debian-unstable/man7/EVP_PKEY-FFC.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_PKEY-FFC 7SSL" -.TH EVP_PKEY-FFC 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_PKEY-FFC 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -235,7 +235,7 @@ The following sections of FIPS186\-4: \&\fBOSSL_PROVIDER\-FIPS\fR\|(7), .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_PKEY-HMAC.7ssl b/upstream/debian-unstable/man7/EVP_PKEY-HMAC.7ssl index 76bd748e..00d96eb6 100644 --- a/upstream/debian-unstable/man7/EVP_PKEY-HMAC.7ssl +++ b/upstream/debian-unstable/man7/EVP_PKEY-HMAC.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_PKEY-HMAC 7SSL" -.TH EVP_PKEY-HMAC 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_PKEY-HMAC 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_PKEY-RSA.7ssl b/upstream/debian-unstable/man7/EVP_PKEY-RSA.7ssl index 62441c25..fd452c60 100644 --- a/upstream/debian-unstable/man7/EVP_PKEY-RSA.7ssl +++ b/upstream/debian-unstable/man7/EVP_PKEY-RSA.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_PKEY-RSA 7SSL" -.TH EVP_PKEY-RSA 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_PKEY-RSA 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_PKEY-SM2.7ssl b/upstream/debian-unstable/man7/EVP_PKEY-SM2.7ssl index 2a6ce0da..e472806a 100644 --- a/upstream/debian-unstable/man7/EVP_PKEY-SM2.7ssl +++ b/upstream/debian-unstable/man7/EVP_PKEY-SM2.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_PKEY-SM2 7SSL" -.TH EVP_PKEY-SM2 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_PKEY-SM2 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_PKEY-X25519.7ssl b/upstream/debian-unstable/man7/EVP_PKEY-X25519.7ssl index 66f423b3..28980f20 100644 --- a/upstream/debian-unstable/man7/EVP_PKEY-X25519.7ssl +++ b/upstream/debian-unstable/man7/EVP_PKEY-X25519.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_PKEY-X25519 7SSL" -.TH EVP_PKEY-X25519 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_PKEY-X25519 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -70,8 +70,18 @@ The \fBX25519\fR, \fBX448\fR, \fBED25519\fR and \fBED448\fR keytypes are implemented in OpenSSL's default and FIPS providers. These implementations support the associated key, containing the public key \fIpub\fR and the private key \fIpriv\fR. +.SS "Keygen Parameters" +.IX Subsection "Keygen Parameters" +.IP """dhkem-ikm"" (\fBOSSL_PKEY_PARAM_DHKEM_IKM\fR) <octet string>" 4 +.IX Item """dhkem-ikm"" (OSSL_PKEY_PARAM_DHKEM_IKM) <octet string>" +DHKEM requires the generation of a keypair using an input key material (seed). +Use this to specify the key material used for generation of the private key. +This value should not be reused for other purposes. +It should have a length of at least 32 for X25519, and 56 for X448. +.Sp +This is only supported by X25519 and X448. .PP -No additional parameters can be set during key generation. +Use \fBEVP_PKEY_CTX_set_params()\fR after calling \fBEVP_PKEY_keygen_init()\fR. .SS "Common X25519, X448, ED25519 and ED448 parameters" .IX Subsection "Common X25519, X448, ED25519 and ED448 parameters" In addition to the common parameters that all keytypes should support (see diff --git a/upstream/debian-unstable/man7/EVP_RAND-CTR-DRBG.7ssl b/upstream/debian-unstable/man7/EVP_RAND-CTR-DRBG.7ssl index 28c2242c..508ef8fb 100644 --- a/upstream/debian-unstable/man7/EVP_RAND-CTR-DRBG.7ssl +++ b/upstream/debian-unstable/man7/EVP_RAND-CTR-DRBG.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_RAND-CTR-DRBG 7SSL" -.TH EVP_RAND-CTR-DRBG 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_RAND-CTR-DRBG 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -115,7 +115,7 @@ A context for CTR DRBG can be obtained by calling: .PP .Vb 2 \& EVP_RAND *rand = EVP_RAND_fetch(NULL, "CTR\-DRBG", NULL); -\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL); .Ve .SH EXAMPLES .IX Header "EXAMPLES" diff --git a/upstream/debian-unstable/man7/EVP_RAND-HASH-DRBG.7ssl b/upstream/debian-unstable/man7/EVP_RAND-HASH-DRBG.7ssl index cf44f703..420a8bab 100644 --- a/upstream/debian-unstable/man7/EVP_RAND-HASH-DRBG.7ssl +++ b/upstream/debian-unstable/man7/EVP_RAND-HASH-DRBG.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_RAND-HASH-DRBG 7SSL" -.TH EVP_RAND-HASH-DRBG 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_RAND-HASH-DRBG 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -126,7 +126,7 @@ A context for HASH DRBG can be obtained by calling: .PP .Vb 2 \& EVP_RAND *rand = EVP_RAND_fetch(NULL, "HASH\-DRBG", NULL); -\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL); .Ve .SH EXAMPLES .IX Header "EXAMPLES" diff --git a/upstream/debian-unstable/man7/EVP_RAND-HMAC-DRBG.7ssl b/upstream/debian-unstable/man7/EVP_RAND-HMAC-DRBG.7ssl index 99ceafc8..62dadc64 100644 --- a/upstream/debian-unstable/man7/EVP_RAND-HMAC-DRBG.7ssl +++ b/upstream/debian-unstable/man7/EVP_RAND-HMAC-DRBG.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_RAND-HMAC-DRBG 7SSL" -.TH EVP_RAND-HMAC-DRBG 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_RAND-HMAC-DRBG 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -127,7 +127,7 @@ A context for HMAC DRBG can be obtained by calling: .PP .Vb 2 \& EVP_RAND *rand = EVP_RAND_fetch(NULL, "HMAC\-DRBG", NULL); -\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL); .Ve .SH EXAMPLES .IX Header "EXAMPLES" diff --git a/upstream/debian-unstable/man7/EVP_RAND-SEED-SRC.7ssl b/upstream/debian-unstable/man7/EVP_RAND-SEED-SRC.7ssl index 88718037..22430aa8 100644 --- a/upstream/debian-unstable/man7/EVP_RAND-SEED-SRC.7ssl +++ b/upstream/debian-unstable/man7/EVP_RAND-SEED-SRC.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_RAND-SEED-SRC 7SSL" -.TH EVP_RAND-SEED-SRC 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_RAND-SEED-SRC 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -92,7 +92,7 @@ A context for the seed source can be obtained by calling: .PP .Vb 2 \& EVP_RAND *rand = EVP_RAND_fetch(NULL, "SEED\-SRC", NULL); -\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL); .Ve .SH EXAMPLES .IX Header "EXAMPLES" diff --git a/upstream/debian-unstable/man7/EVP_RAND-TEST-RAND.7ssl b/upstream/debian-unstable/man7/EVP_RAND-TEST-RAND.7ssl index 010c3c41..17a72a6c 100644 --- a/upstream/debian-unstable/man7/EVP_RAND-TEST-RAND.7ssl +++ b/upstream/debian-unstable/man7/EVP_RAND-TEST-RAND.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_RAND-TEST-RAND 7SSL" -.TH EVP_RAND-TEST-RAND 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_RAND-TEST-RAND 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -123,7 +123,7 @@ A context for a test generator can be obtained by calling: .PP .Vb 2 \& EVP_RAND *rand = EVP_RAND_fetch(NULL, "TEST\-RAND", NULL); -\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand); +\& EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL); .Ve .SH EXAMPLES .IX Header "EXAMPLES" diff --git a/upstream/debian-unstable/man7/EVP_RAND.7ssl b/upstream/debian-unstable/man7/EVP_RAND.7ssl index 70bdbfbe..20c5c299 100644 --- a/upstream/debian-unstable/man7/EVP_RAND.7ssl +++ b/upstream/debian-unstable/man7/EVP_RAND.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_RAND 7SSL" -.TH EVP_RAND 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_RAND 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_SIGNATURE-DSA.7ssl b/upstream/debian-unstable/man7/EVP_SIGNATURE-DSA.7ssl index 0fe9eaba..eaf4809b 100644 --- a/upstream/debian-unstable/man7/EVP_SIGNATURE-DSA.7ssl +++ b/upstream/debian-unstable/man7/EVP_SIGNATURE-DSA.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_SIGNATURE-DSA 7SSL" -.TH EVP_SIGNATURE-DSA 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_SIGNATURE-DSA 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -77,6 +77,8 @@ and before calling \fBEVP_PKEY_sign()\fR or \fBEVP_PKEY_verify()\fR. .PD 0 .IP """properties"" (\fBOSSL_SIGNATURE_PARAM_PROPERTIES\fR) <UTF8 string>" 4 .IX Item """properties"" (OSSL_SIGNATURE_PARAM_PROPERTIES) <UTF8 string>" +.IP """nonce-type"" (\fBOSSL_SIGNATURE_PARAM_NONCE_TYPE\fR) <unsigned integer>" 4 +.IX Item """nonce-type"" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) <unsigned integer>" .PD The settable parameters are described in \fBprovider\-signature\fR\|(7). .PP @@ -87,6 +89,8 @@ The following signature parameters can be retrieved using .PD 0 .IP """digest"" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) <UTF8 string>" 4 .IX Item """digest"" (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>" +.IP """nonce-type"" (\fBOSSL_SIGNATURE_PARAM_NONCE_TYPE\fR) <unsigned integer>" 4 +.IX Item """nonce-type"" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) <unsigned integer>" .PD The gettable parameters are described in \fBprovider\-signature\fR\|(7). .SH "SEE ALSO" @@ -97,7 +101,7 @@ The gettable parameters are described in \fBprovider\-signature\fR\|(7). \&\fBprovider\-signature\fR\|(7), .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_SIGNATURE-ECDSA.7ssl b/upstream/debian-unstable/man7/EVP_SIGNATURE-ECDSA.7ssl index 1dff8533..30e1f722 100644 --- a/upstream/debian-unstable/man7/EVP_SIGNATURE-ECDSA.7ssl +++ b/upstream/debian-unstable/man7/EVP_SIGNATURE-ECDSA.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_SIGNATURE-ECDSA 7SSL" -.TH EVP_SIGNATURE-ECDSA 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_SIGNATURE-ECDSA 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -76,6 +76,8 @@ and before calling \fBEVP_PKEY_sign()\fR or \fBEVP_PKEY_verify()\fR. .PD 0 .IP """properties"" (\fBOSSL_SIGNATURE_PARAM_PROPERTIES\fR) <UTF8 string>" 4 .IX Item """properties"" (OSSL_SIGNATURE_PARAM_PROPERTIES) <UTF8 string>" +.IP """nonce-type"" (\fBOSSL_SIGNATURE_PARAM_NONCE_TYPE\fR) <unsigned integer>" 4 +.IX Item """nonce-type"" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) <unsigned integer>" .PD These parameters are described in \fBprovider\-signature\fR\|(7). .PP @@ -86,6 +88,8 @@ The following signature parameters can be retrieved using .PD 0 .IP """digest"" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) <UTF8 string>" 4 .IX Item """digest"" (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 string>" +.IP """nonce-type"" (\fBOSSL_SIGNATURE_PARAM_NONCE_TYPE\fR) <unsigned integer>" 4 +.IX Item """nonce-type"" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) <unsigned integer>" .PD The parameters are described in \fBprovider\-signature\fR\|(7). .SH "SEE ALSO" @@ -96,7 +100,7 @@ The parameters are described in \fBprovider\-signature\fR\|(7). \&\fBprovider\-signature\fR\|(7), .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_SIGNATURE-ED25519.7ssl b/upstream/debian-unstable/man7/EVP_SIGNATURE-ED25519.7ssl index 0fcdcfe1..27df8aca 100644 --- a/upstream/debian-unstable/man7/EVP_SIGNATURE-ED25519.7ssl +++ b/upstream/debian-unstable/man7/EVP_SIGNATURE-ED25519.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_SIGNATURE-ED25519 7SSL" -.TH EVP_SIGNATURE-ED25519 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_SIGNATURE-ED25519 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -68,29 +68,81 @@ Ed448 \&\- EVP_PKEY Ed25519 and Ed448 support .SH DESCRIPTION .IX Header "DESCRIPTION" -The \fBEd25519\fR and \fBEd448\fR EVP_PKEY implementation supports key generation, -one-shot digest sign and digest verify using PureEdDSA and \fBEd25519\fR or \fBEd448\fR -(see RFC8032). It has associated private and public key formats compatible with -RFC 8410. +The \fBEd25519\fR and \fBEd448\fR EVP_PKEY implementation supports key +generation, one-shot digest-sign and digest-verify using the EdDSA +signature scheme described in RFC 8032. It has associated private and +public key formats compatible with RFC 8410. +.SS "EdDSA Instances" +.IX Subsection "EdDSA Instances" +RFC 8032 describes five EdDSA instances: Ed25519, Ed25519ctx, +Ed25519ph, Ed448, Ed448ph. +.PP +The instances Ed25519, Ed25519ctx, Ed448 are referred to as \fBPureEdDSA\fR +schemes. For these three instances, the sign and verify procedures +require access to the complete message (not a digest of the message). +.PP +The instances Ed25519ph, Ed448ph are referred to as \fBHashEdDSA\fR +schemes. For these two instances, the sign and verify procedures do +not require access to the complete message; they operate on a hash of +the message. For Ed25519ph, the hash function is SHA512. For +Ed448ph, the hash function is SHAKE256 with an output length of 512 +bits. +.PP +The instances Ed25519ctx, Ed25519ph, Ed448, Ed448ph accept an optional +\&\fBcontext-string\fR as input to sign and verify operations (and for +Ed25519ctx, the context-string must be nonempty). For the Ed25519 +instance, a nonempty context-string is not permitted. .SS "ED25519 and ED448 Signature Parameters" .IX Subsection "ED25519 and ED448 Signature Parameters" -No additional parameters can be set during one-shot signing or verification. -In particular, because PureEdDSA is used, a digest must \fBNOT\fR be specified when -signing or verifying. +Two parameters can be set during signing or verification: the EdDSA +\&\fBinstance name\fR and the \fBcontext-string value\fR. They can be set by +passing an OSSL_PARAM array to \fBEVP_DigestSignInit_ex()\fR. +.IP \(bu 4 +"instance" (\fBOSSL_SIGNATURE_PARAM_INSTANCE\fR) <utf8 string> +.Sp +One of the five strings "Ed25519", "Ed25519ctx", "Ed25519ph", "Ed448", "Ed448ph". +.Sp +"Ed25519", "Ed25519ctx", "Ed25519ph" are valid only for an Ed25519 EVP_PKEY. +.Sp +"Ed448", "Ed448ph" are valid only for an Ed448 EVP_PKEY. +.IP \(bu 4 +"context-string" (\fBOSSL_SIGNATURE_PARAM_CONTEXT_STRING\fR) <octet string> +.Sp +A string of octets with length at most 255. +.PP +Both of these parameters are optional. +.PP +If the instance name is not specified, then the default "Ed25519" or +"Ed448" is used. +.PP +If a context-string is not specified, then an empty context-string is +used. +.PP +Note that a message digest name must \fBNOT\fR be specified when signing +or verifying. +.PP See \fBEVP_PKEY\-X25519\fR\|(7) for information related to \fBX25519\fR and \fBX448\fR keys. .PP The following signature parameters can be retrieved using \&\fBEVP_PKEY_CTX_get_params()\fR. -.IP """algorithm-id"" (\fBOSSL_SIGNATURE_PARAM_ALGORITHM_ID\fR) <octet string>" 4 -.IX Item """algorithm-id"" (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <octet string>" +.IP \(bu 4 +"algorithm-id" (\fBOSSL_SIGNATURE_PARAM_ALGORITHM_ID\fR) <octet string> +.IP \(bu 4 +"instance" (\fBOSSL_SIGNATURE_PARAM_INSTANCE\fR) <utf8 string> +.IP \(bu 4 +"context-string" (\fBOSSL_SIGNATURE_PARAM_CONTEXT_STRING\fR) <octet string> +.PP The parameters are described in \fBprovider\-signature\fR\|(7). .SH NOTES .IX Header "NOTES" -The PureEdDSA algorithm does not support the streaming mechanism -of other signature algorithms using, for example, \fBEVP_DigestUpdate()\fR. +The PureEdDSA instances do not support the streaming mechanism of +other signature algorithms using, for example, \fBEVP_DigestUpdate()\fR. The message to sign or verify must be passed using the one-shot \&\fBEVP_DigestSign()\fR and \fBEVP_DigestVerify()\fR functions. .PP +The HashEdDSA instances do not yet support the streaming mechanisms +(so the one-shot functions must be used with HashEdDSA as well). +.PP When calling \fBEVP_DigestSignInit()\fR or \fBEVP_DigestVerifyInit()\fR, the digest \fItype\fR parameter \fBMUST\fR be set to NULL. .PP @@ -114,7 +166,7 @@ Valid algorithm names are \fBed25519\fR, \fBed448\fR and \fBeddsa\fR. If \fBedds specified, then both Ed25519 and Ed448 are benchmarked. .SH EXAMPLES .IX Header "EXAMPLES" -To sign a message using a ED25519 or ED448 key: +To sign a message using an ED25519 EVP_PKEY structure: .PP .Vb 5 \& void do_sign(EVP_PKEY *ed_key, unsigned char *msg, size_t msg_len) @@ -123,8 +175,16 @@ To sign a message using a ED25519 or ED448 key: \& unsigned char *sig = NULL; \& EVP_MD_CTX *md_ctx = EVP_MD_CTX_new(); \& -\& EVP_DigestSignInit(md_ctx, NULL, NULL, NULL, ed_key); -\& /* Calculate the requires size for the signature by passing a NULL buffer */ +\& const OSSL_PARAM params[] = { +\& OSSL_PARAM_utf8_string ("instance", "Ed25519ctx", 10), +\& OSSL_PARAM_octet_string("context\-string", (unsigned char *)"A protocol defined context string", 33), +\& OSSL_PARAM_END +\& }; +\& +\& /* The input "params" is not needed if default options are acceptable. +\& Use NULL in place of "params" in that case. */ +\& EVP_DigestSignInit_ex(md_ctx, NULL, NULL, NULL, NULL, ed_key, params); +\& /* Calculate the required size for the signature by passing a NULL buffer. */ \& EVP_DigestSign(md_ctx, NULL, &sig_len, msg, msg_len); \& sig = OPENSSL_zalloc(sig_len); \& @@ -142,7 +202,7 @@ To sign a message using a ED25519 or ED448 key: \&\fBEVP_DigestVerifyInit\fR\|(3), .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2017\-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2017\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/EVP_SIGNATURE-HMAC.7ssl b/upstream/debian-unstable/man7/EVP_SIGNATURE-HMAC.7ssl index 70108b29..0e620ddd 100644 --- a/upstream/debian-unstable/man7/EVP_SIGNATURE-HMAC.7ssl +++ b/upstream/debian-unstable/man7/EVP_SIGNATURE-HMAC.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_SIGNATURE-HMAC 7SSL" -.TH EVP_SIGNATURE-HMAC 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_SIGNATURE-HMAC 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/EVP_SIGNATURE-RSA.7ssl b/upstream/debian-unstable/man7/EVP_SIGNATURE-RSA.7ssl index 942d0dc7..c480ddcd 100644 --- a/upstream/debian-unstable/man7/EVP_SIGNATURE-RSA.7ssl +++ b/upstream/debian-unstable/man7/EVP_SIGNATURE-RSA.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP_SIGNATURE-RSA 7SSL" -.TH EVP_SIGNATURE-RSA 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP_SIGNATURE-RSA 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -149,7 +149,7 @@ These parameters are as described above. \&\fBprovider\-signature\fR\|(7), .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/OSSL_PROVIDER-FIPS.7ssl b/upstream/debian-unstable/man7/OSSL_PROVIDER-FIPS.7ssl index a281e513..4d4b65ad 100644 --- a/upstream/debian-unstable/man7/OSSL_PROVIDER-FIPS.7ssl +++ b/upstream/debian-unstable/man7/OSSL_PROVIDER-FIPS.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OSSL_PROVIDER-FIPS 7SSL" -.TH OSSL_PROVIDER-FIPS 7SSL 2024-02-03 3.1.5 OpenSSL +.TH OSSL_PROVIDER-FIPS 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -118,15 +118,18 @@ The OpenSSL FIPS provider supports these operations and algorithms: .IX Item "SHA3, see EVP_MD-SHA3" .IP "KECCAK-KMAC, see \fBEVP_MD\-KECCAK\-KMAC\fR\|(7)" 4 .IX Item "KECCAK-KMAC, see EVP_MD-KECCAK-KMAC" +.IP "SHAKE, see \fBEVP_MD\-SHAKE\fR\|(7)" 4 +.IX Item "SHAKE, see EVP_MD-SHAKE" .PD .SS "Symmetric Ciphers" .IX Subsection "Symmetric Ciphers" .IP "AES, see \fBEVP_CIPHER\-AES\fR\|(7)" 4 .IX Item "AES, see EVP_CIPHER-AES" .PD 0 -.IP "DES\-EDE3 (TripleDES), see \fBEVP_CIPHER\-DES\fR\|(7)" 4 -.IX Item "DES-EDE3 (TripleDES), see EVP_CIPHER-DES" +.IP "3DES, see \fBEVP_CIPHER\-DES\fR\|(7)" 4 +.IX Item "3DES, see EVP_CIPHER-DES" .PD +This is an unapproved algorithm. .SS "Message Authentication Code (MAC)" .IX Subsection "Message Authentication Code (MAC)" .IP "CMAC, see \fBEVP_MAC\-CMAC\fR\|(7)" 4 @@ -174,16 +177,28 @@ The OpenSSL FIPS provider supports these operations and algorithms: .IX Item "X25519, see EVP_KEYEXCH-X25519" .IP "X448, see \fBEVP_KEYEXCH\-X448\fR\|(7)" 4 .IX Item "X448, see EVP_KEYEXCH-X448" +.IP TLS1\-PRF 4 +.IX Item "TLS1-PRF" +.IP HKDF 4 +.IX Item "HKDF" .PD .SS "Asymmetric Signature" .IX Subsection "Asymmetric Signature" .IP "RSA, see \fBEVP_SIGNATURE\-RSA\fR\|(7)" 4 .IX Item "RSA, see EVP_SIGNATURE-RSA" .PD 0 -.IP "X25519, see \fBEVP_SIGNATURE\-ED25519\fR\|(7)" 4 -.IX Item "X25519, see EVP_SIGNATURE-ED25519" -.IP "X448, see \fBEVP_SIGNATURE\-ED448\fR\|(7)" 4 -.IX Item "X448, see EVP_SIGNATURE-ED448" +.IP "DSA, see \fBEVP_SIGNATURE\-DSA\fR\|(7)" 4 +.IX Item "DSA, see EVP_SIGNATURE-DSA" +.IP "ED25519, see \fBEVP_SIGNATURE\-ED25519\fR\|(7)" 4 +.IX Item "ED25519, see EVP_SIGNATURE-ED25519" +.PD +This is an unapproved algorithm. +.IP "ED448, see \fBEVP_SIGNATURE\-ED448\fR\|(7)" 4 +.IX Item "ED448, see EVP_SIGNATURE-ED448" +This is an unapproved algorithm. +.IP "ECDSA, see \fBEVP_SIGNATURE\-ECDSA\fR\|(7)" 4 +.IX Item "ECDSA, see EVP_SIGNATURE-ECDSA" +.PD 0 .IP "HMAC, see \fBEVP_SIGNATURE\-HMAC\fR\|(7)" 4 .IX Item "HMAC, see EVP_SIGNATURE-HMAC" .IP "CMAC, see \fBEVP_SIGNATURE\-CMAC\fR\|(7)" 4 @@ -210,12 +225,30 @@ The OpenSSL FIPS provider supports these operations and algorithms: .IX Item "DSA, see EVP_KEYMGMT-DSA" .IP "RSA, see \fBEVP_KEYMGMT\-RSA\fR\|(7)" 4 .IX Item "RSA, see EVP_KEYMGMT-RSA" +.IP RSA-PSS 4 +.IX Item "RSA-PSS" .IP "EC, see \fBEVP_KEYMGMT\-EC\fR\|(7)" 4 .IX Item "EC, see EVP_KEYMGMT-EC" .IP "X25519, see \fBEVP_KEYMGMT\-X25519\fR\|(7)" 4 .IX Item "X25519, see EVP_KEYMGMT-X25519" .IP "X448, see \fBEVP_KEYMGMT\-X448\fR\|(7)" 4 .IX Item "X448, see EVP_KEYMGMT-X448" +.IP "ED25519, see \fBEVP_KEYMGMT\-ED25519\fR\|(7)" 4 +.IX Item "ED25519, see EVP_KEYMGMT-ED25519" +.PD +This is an unapproved algorithm. +.IP "ED448, see \fBEVP_KEYMGMT\-ED448\fR\|(7)" 4 +.IX Item "ED448, see EVP_KEYMGMT-ED448" +This is an unapproved algorithm. +.IP TLS1\-PRF 4 +.IX Item "TLS1-PRF" +.PD 0 +.IP HKDF 4 +.IX Item "HKDF" +.IP "HMAC, see \fBEVP_KEYMGMT\-HMAC\fR\|(7)" 4 +.IX Item "HMAC, see EVP_KEYMGMT-HMAC" +.IP "CMAC, see \fBEVP_KEYMGMT\-CMAC\fR\|(7)" 4 +.IX Item "CMAC, see EVP_KEYMGMT-CMAC" .PD .SS "Random Number Generation" .IX Subsection "Random Number Generation" diff --git a/upstream/debian-unstable/man7/OSSL_PROVIDER-base.7ssl b/upstream/debian-unstable/man7/OSSL_PROVIDER-base.7ssl index b2f9e16b..88546469 100644 --- a/upstream/debian-unstable/man7/OSSL_PROVIDER-base.7ssl +++ b/upstream/debian-unstable/man7/OSSL_PROVIDER-base.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OSSL_PROVIDER-BASE 7SSL" -.TH OSSL_PROVIDER-BASE 7SSL 2024-02-03 3.1.5 OpenSSL +.TH OSSL_PROVIDER-BASE 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -104,25 +104,86 @@ currently permitted. .SH "OPERATIONS AND ALGORITHMS" .IX Header "OPERATIONS AND ALGORITHMS" The OpenSSL base provider supports these operations and algorithms: +.SS "Random Number Generation" +.IX Subsection "Random Number Generation" +.IP "SEED-SRC, see \fBEVP_RAND\-SEED\-SRC\fR\|(7)" 4 +.IX Item "SEED-SRC, see EVP_RAND-SEED-SRC" +.PP +In addition to this provider, the "SEED-SRC" algorithm is also available in the +default provider. .SS "Asymmetric Key Encoder" .IX Subsection "Asymmetric Key Encoder" -In addition to "provider=base", some of these encoders define the -property "fips=yes", to allow them to be used together with the FIPS -provider. -.IP "RSA, see \fBOSSL_ENCODER\-RSA\fR\|(7)" 4 -.IX Item "RSA, see OSSL_ENCODER-RSA" +.IP RSA 4 +.IX Item "RSA" +.PD 0 +.IP RSA-PSS 4 +.IX Item "RSA-PSS" +.IP DH 4 +.IX Item "DH" +.IP DHX 4 +.IX Item "DHX" +.IP DSA 4 +.IX Item "DSA" +.IP EC 4 +.IX Item "EC" +.IP ED25519 4 +.IX Item "ED25519" +.IP ED448 4 +.IX Item "ED448" +.IP X25519 4 +.IX Item "X25519" +.IP X448 4 +.IX Item "X448" +.IP SM2 4 +.IX Item "SM2" +.PD +.PP +In addition to this provider, all of these encoding algorithms are also +available in the default provider. Some of these algorithms may be used in +combination with the FIPS provider. +.SS "Asymmetric Key Decoder" +.IX Subsection "Asymmetric Key Decoder" +.IP RSA 4 +.IX Item "RSA" .PD 0 -.IP "DH, see \fBOSSL_ENCODER\-DH\fR\|(7)" 4 -.IX Item "DH, see OSSL_ENCODER-DH" -.IP "DSA, see \fBOSSL_ENCODER\-DSA\fR\|(7)" 4 -.IX Item "DSA, see OSSL_ENCODER-DSA" -.IP "EC, see \fBOSSL_ENCODER\-EC\fR\|(7)" 4 -.IX Item "EC, see OSSL_ENCODER-EC" -.IP "X25519, see \fBOSSL_ENCODER\-X25519\fR\|(7)" 4 -.IX Item "X25519, see OSSL_ENCODER-X25519" -.IP "X448, see \fBOSSL_ENCODER\-X448\fR\|(7)" 4 -.IX Item "X448, see OSSL_ENCODER-X448" +.IP RSA-PSS 4 +.IX Item "RSA-PSS" +.IP DH 4 +.IX Item "DH" +.IP DHX 4 +.IX Item "DHX" +.IP DSA 4 +.IX Item "DSA" +.IP EC 4 +.IX Item "EC" +.IP ED25519 4 +.IX Item "ED25519" +.IP ED448 4 +.IX Item "ED448" +.IP X25519 4 +.IX Item "X25519" +.IP X448 4 +.IX Item "X448" +.IP SM2 4 +.IX Item "SM2" +.IP DER 4 +.IX Item "DER" .PD +.PP +In addition to this provider, all of these decoding algorithms are also +available in the default provider. Some of these algorithms may be used in +combination with the FIPS provider. +.SS Stores +.IX Subsection "Stores" +.IP file 4 +.IX Item "file" +.PD 0 +.IP org.openssl.winstore 4 +.IX Item "org.openssl.winstore" +.PD +.PP +In addition to this provider, all of these store algorithms are also +available in the default provider. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBOSSL_PROVIDER\-default\fR\|(7), \fBopenssl\-core.h\fR\|(7), @@ -132,7 +193,7 @@ provider. This functionality was added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/OSSL_PROVIDER-default.7ssl b/upstream/debian-unstable/man7/OSSL_PROVIDER-default.7ssl index e535e445..b6325d94 100644 --- a/upstream/debian-unstable/man7/OSSL_PROVIDER-default.7ssl +++ b/upstream/debian-unstable/man7/OSSL_PROVIDER-default.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OSSL_PROVIDER-DEFAULT 7SSL" -.TH OSSL_PROVIDER-DEFAULT 7SSL 2024-02-03 3.1.5 OpenSSL +.TH OSSL_PROVIDER-DEFAULT 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -107,6 +107,8 @@ The OpenSSL default provider supports these operations and algorithms: .IX Item "SHA2, see EVP_MD-SHA2" .IP "SHA3, see \fBEVP_MD\-SHA3\fR\|(7)" 4 .IX Item "SHA3, see EVP_MD-SHA3" +.IP "KECCAK, see \fBEVP_MD\-KECCAK\fR\|(7)" 4 +.IX Item "KECCAK, see EVP_MD-KECCAK" .IP "KECCAK-KMAC, see \fBEVP_MD\-KECCAK\-KMAC\fR\|(7)" 4 .IX Item "KECCAK-KMAC, see EVP_MD-KECCAK-KMAC" .IP "SHAKE, see \fBEVP_MD\-SHAKE\fR\|(7)" 4 @@ -135,8 +137,6 @@ The OpenSSL default provider supports these operations and algorithms: .IX Item "CAMELLIA, see EVP_CIPHER-CAMELLIA" .IP "3DES, see \fBEVP_CIPHER\-DES\fR\|(7)" 4 .IX Item "3DES, see EVP_CIPHER-DES" -.IP "SEED, see \fBEVP_CIPHER\-SEED\fR\|(7)" 4 -.IX Item "SEED, see EVP_CIPHER-SEED" .IP "SM4, see \fBEVP_CIPHER\-SM4\fR\|(7)" 4 .IX Item "SM4, see EVP_CIPHER-SM4" .IP "ChaCha20, see \fBEVP_CIPHER\-CHACHA\fR\|(7)" 4 @@ -169,6 +169,8 @@ The OpenSSL default provider supports these operations and algorithms: .IP "HKDF, see \fBEVP_KDF\-HKDF\fR\|(7)" 4 .IX Item "HKDF, see EVP_KDF-HKDF" .PD 0 +.IP "TLS13\-KDF, see \fBEVP_KDF\-TLS13_KDF\fR\|(7)" 4 +.IX Item "TLS13-KDF, see EVP_KDF-TLS13_KDF" .IP "SSKDF, see \fBEVP_KDF\-SS\fR\|(7)" 4 .IX Item "SSKDF, see EVP_KDF-SS" .IP "PBKDF2, see \fBEVP_KDF\-PBKDF2\fR\|(7)" 4 @@ -191,6 +193,10 @@ The OpenSSL default provider supports these operations and algorithms: .IX Item "SCRYPT, see EVP_KDF-SCRYPT" .IP "KRB5KDF, see \fBEVP_KDF\-KRB5KDF\fR\|(7)" 4 .IX Item "KRB5KDF, see EVP_KDF-KRB5KDF" +.IP "HMAC-DRBG, see \fBEVP_KDF\-HMAC\-DRBG\fR\|(7)" 4 +.IX Item "HMAC-DRBG, see EVP_KDF-HMAC-DRBG" +.IP "ARGON2, see \fBEVP_KDF\-ARGON2\fR\|(7)" 4 +.IX Item "ARGON2, see EVP_KDF-ARGON2" .PD .SS "Key Exchange" .IX Subsection "Key Exchange" @@ -203,6 +209,12 @@ The OpenSSL default provider supports these operations and algorithms: .IX Item "X25519, see EVP_KEYEXCH-X25519" .IP "X448, see \fBEVP_KEYEXCH\-X448\fR\|(7)" 4 .IX Item "X448, see EVP_KEYEXCH-X448" +.IP TLS1\-PRF 4 +.IX Item "TLS1-PRF" +.IP HKDF 4 +.IX Item "HKDF" +.IP SCRYPT 4 +.IX Item "SCRYPT" .PD .SS "Asymmetric Signature" .IX Subsection "Asymmetric Signature" @@ -211,6 +223,14 @@ The OpenSSL default provider supports these operations and algorithms: .PD 0 .IP "RSA, see \fBEVP_SIGNATURE\-RSA\fR\|(7)" 4 .IX Item "RSA, see EVP_SIGNATURE-RSA" +.IP "ED25519, see \fBEVP_SIGNATURE\-ED25519\fR\|(7)" 4 +.IX Item "ED25519, see EVP_SIGNATURE-ED25519" +.IP "ED448, see \fBEVP_SIGNATURE\-ED448\fR\|(7)" 4 +.IX Item "ED448, see EVP_SIGNATURE-ED448" +.IP "ECDSA, see \fBEVP_SIGNATURE\-ECDSA\fR\|(7)" 4 +.IX Item "ECDSA, see EVP_SIGNATURE-ECDSA" +.IP SM2 4 +.IX Item "SM2" .IP "HMAC, see \fBEVP_SIGNATURE\-HMAC\fR\|(7)" 4 .IX Item "HMAC, see EVP_SIGNATURE-HMAC" .IP "SIPHASH, see \fBEVP_SIGNATURE\-Siphash\fR\|(7)" 4 @@ -232,23 +252,53 @@ The OpenSSL default provider supports these operations and algorithms: .IX Subsection "Asymmetric Key Encapsulation" .IP "RSA, see \fBEVP_KEM\-RSA\fR\|(7)" 4 .IX Item "RSA, see EVP_KEM-RSA" +.PD 0 +.IP "X25519, see \fBEVP_KEM\-X25519\fR\|(7)" 4 +.IX Item "X25519, see EVP_KEM-X25519" +.IP "X448, see \fBEVP_KEM\-X448\fR\|(7)" 4 +.IX Item "X448, see EVP_KEM-X448" +.IP "EC, see \fBEVP_KEM\-EC\fR\|(7)" 4 +.IX Item "EC, see EVP_KEM-EC" +.PD .SS "Asymmetric Key Management" .IX Subsection "Asymmetric Key Management" -.PD 0 .IP "DH, see \fBEVP_KEYMGMT\-DH\fR\|(7)" 4 .IX Item "DH, see EVP_KEYMGMT-DH" +.PD 0 .IP "DHX, see \fBEVP_KEYMGMT\-DHX\fR\|(7)" 4 .IX Item "DHX, see EVP_KEYMGMT-DHX" .IP "DSA, see \fBEVP_KEYMGMT\-DSA\fR\|(7)" 4 .IX Item "DSA, see EVP_KEYMGMT-DSA" .IP "RSA, see \fBEVP_KEYMGMT\-RSA\fR\|(7)" 4 .IX Item "RSA, see EVP_KEYMGMT-RSA" +.IP RSA-PSS 4 +.IX Item "RSA-PSS" .IP "EC, see \fBEVP_KEYMGMT\-EC\fR\|(7)" 4 .IX Item "EC, see EVP_KEYMGMT-EC" .IP "X25519, see \fBEVP_KEYMGMT\-X25519\fR\|(7)" 4 .IX Item "X25519, see EVP_KEYMGMT-X25519" .IP "X448, see \fBEVP_KEYMGMT\-X448\fR\|(7)" 4 .IX Item "X448, see EVP_KEYMGMT-X448" +.IP "ED25519, see \fBEVP_KEYMGMT\-ED25519\fR\|(7)" 4 +.IX Item "ED25519, see EVP_KEYMGMT-ED25519" +.IP "ED448, see \fBEVP_KEYMGMT\-ED448\fR\|(7)" 4 +.IX Item "ED448, see EVP_KEYMGMT-ED448" +.IP TLS1\-PRF 4 +.IX Item "TLS1-PRF" +.IP HKDF 4 +.IX Item "HKDF" +.IP SCRYPT 4 +.IX Item "SCRYPT" +.IP "HMAC, see \fBEVP_KEYMGMT\-HMAC\fR\|(7)" 4 +.IX Item "HMAC, see EVP_KEYMGMT-HMAC" +.IP "SIPHASH, see \fBEVP_KEYMGMT\-Siphash\fR\|(7)" 4 +.IX Item "SIPHASH, see EVP_KEYMGMT-Siphash" +.IP "POLY1305, see \fBEVP_KEYMGMT\-Poly1305\fR\|(7)" 4 +.IX Item "POLY1305, see EVP_KEYMGMT-Poly1305" +.IP "CMAC, see \fBEVP_KEYMGMT\-CMAC\fR\|(7)" 4 +.IX Item "CMAC, see EVP_KEYMGMT-CMAC" +.IP "SM2, see \fBEVP_KEYMGMT\-SM2\fR\|(7)" 4 +.IX Item "SM2, see EVP_KEYMGMT-SM2" .PD .SS "Random Number Generation" .IX Subsection "Random Number Generation" @@ -264,25 +314,82 @@ The OpenSSL default provider supports these operations and algorithms: .IP "TEST-RAND, see \fBEVP_RAND\-TEST\-RAND\fR\|(7)" 4 .IX Item "TEST-RAND, see EVP_RAND-TEST-RAND" .PD +.PP +In addition to this provider, the "SEED-SRC" algorithm is also available in the +base provider. .SS "Asymmetric Key Encoder" .IX Subsection "Asymmetric Key Encoder" -The default provider also includes all of the encoding algorithms -present in the base provider. Some of these have the property "fips=yes", -to allow them to be used together with the FIPS provider. -.IP "RSA, see \fBOSSL_ENCODER\-RSA\fR\|(7)" 4 -.IX Item "RSA, see OSSL_ENCODER-RSA" +.IP RSA 4 +.IX Item "RSA" +.PD 0 +.IP RSA-PSS 4 +.IX Item "RSA-PSS" +.IP DH 4 +.IX Item "DH" +.IP DHX 4 +.IX Item "DHX" +.IP DSA 4 +.IX Item "DSA" +.IP EC 4 +.IX Item "EC" +.IP ED25519 4 +.IX Item "ED25519" +.IP ED448 4 +.IX Item "ED448" +.IP X25519 4 +.IX Item "X25519" +.IP X448 4 +.IX Item "X448" +.IP SM2 4 +.IX Item "SM2" +.PD +.PP +In addition to this provider, all of these encoding algorithms are also +available in the base provider. Some of these algorithms may be used in +combination with the FIPS provider. +.SS "Asymmetric Key Decoder" +.IX Subsection "Asymmetric Key Decoder" +.IP RSA 4 +.IX Item "RSA" +.PD 0 +.IP RSA-PSS 4 +.IX Item "RSA-PSS" +.IP DH 4 +.IX Item "DH" +.IP DHX 4 +.IX Item "DHX" +.IP DSA 4 +.IX Item "DSA" +.IP EC 4 +.IX Item "EC" +.IP ED25519 4 +.IX Item "ED25519" +.IP ED448 4 +.IX Item "ED448" +.IP X25519 4 +.IX Item "X25519" +.IP X448 4 +.IX Item "X448" +.IP SM2 4 +.IX Item "SM2" +.IP DER 4 +.IX Item "DER" +.PD +.PP +In addition to this provider, all of these decoding algorithms are also +available in the base provider. Some of these algorithms may be used in +combination with the FIPS provider. +.SS Stores +.IX Subsection "Stores" +.IP file 4 +.IX Item "file" .PD 0 -.IP "DH, see \fBOSSL_ENCODER\-DH\fR\|(7)" 4 -.IX Item "DH, see OSSL_ENCODER-DH" -.IP "DSA, see \fBOSSL_ENCODER\-DSA\fR\|(7)" 4 -.IX Item "DSA, see OSSL_ENCODER-DSA" -.IP "EC, see \fBOSSL_ENCODER\-EC\fR\|(7)" 4 -.IX Item "EC, see OSSL_ENCODER-EC" -.IP "X25519, see \fBOSSL_ENCODER\-X25519\fR\|(7)" 4 -.IX Item "X25519, see OSSL_ENCODER-X25519" -.IP "X448, see \fBOSSL_ENCODER\-X448\fR\|(7)" 4 -.IX Item "X448, see OSSL_ENCODER-X448" +.IP org.openssl.winstore 4 +.IX Item "org.openssl.winstore" .PD +.PP +In addition to this provider, all of these store algorithms are also +available in the base provider. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBopenssl\-core.h\fR\|(7), \fBopenssl\-core_dispatch.h\fR\|(7), \fBprovider\fR\|(7), diff --git a/upstream/debian-unstable/man7/OSSL_PROVIDER-legacy.7ssl b/upstream/debian-unstable/man7/OSSL_PROVIDER-legacy.7ssl index a5c91c1d..18e31736 100644 --- a/upstream/debian-unstable/man7/OSSL_PROVIDER-legacy.7ssl +++ b/upstream/debian-unstable/man7/OSSL_PROVIDER-legacy.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OSSL_PROVIDER-LEGACY 7SSL" -.TH OSSL_PROVIDER-LEGACY 7SSL 2024-02-03 3.1.5 OpenSSL +.TH OSSL_PROVIDER-LEGACY 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -91,9 +91,10 @@ The OpenSSL legacy provider supports these operations and algorithms: .IX Subsection "Hashing Algorithms / Message Digests" .IP "MD2, see \fBEVP_MD\-MD2\fR\|(7)" 4 .IX Item "MD2, see EVP_MD-MD2" -.PD 0 +Disabled by default. Use \fIenable\-md2\fR config option to enable. .IP "MD4, see \fBEVP_MD\-MD4\fR\|(7)" 4 .IX Item "MD4, see EVP_MD-MD4" +.PD 0 .IP "MDC2, see \fBEVP_MD\-MDC2\fR\|(7)" 4 .IX Item "MDC2, see EVP_MD-MDC2" .IP "WHIRLPOOL, see \fBEVP_MD\-WHIRLPOOL\fR\|(7)" 4 @@ -132,6 +133,8 @@ Disabled by default. Use \fIenable\-rc5\fR config option to enable. .PD 0 .IP PBKDF1 4 .IX Item "PBKDF1" +.IP PVKKDF 4 +.IX Item "PVKKDF" .PD .SH "SEE ALSO" .IX Header "SEE ALSO" @@ -144,7 +147,7 @@ Disabled by default. Use \fIenable\-rc5\fR config option to enable. This functionality was added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/OSSL_PROVIDER-null.7ssl b/upstream/debian-unstable/man7/OSSL_PROVIDER-null.7ssl index d36995bf..1f93b786 100644 --- a/upstream/debian-unstable/man7/OSSL_PROVIDER-null.7ssl +++ b/upstream/debian-unstable/man7/OSSL_PROVIDER-null.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OSSL_PROVIDER-NULL 7SSL" -.TH OSSL_PROVIDER-NULL 7SSL 2024-02-03 3.1.5 OpenSSL +.TH OSSL_PROVIDER-NULL 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -82,7 +82,7 @@ The OpenSSL null provider supports no operations and algorithms. This functionality was added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/PAM.7 b/upstream/debian-unstable/man7/PAM.7 index 00b313f8..fc81e1a5 100644 --- a/upstream/debian-unstable/man7/PAM.7 +++ b/upstream/debian-unstable/man7/PAM.7 @@ -2,12 +2,12 @@ .\" Title: pam .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/> -.\" Date: 09/15/2023 +.\" Date: 04/08/2024 .\" Manual: Linux-PAM Manual .\" Source: Linux-PAM .\" Language: English .\" -.TH "PAM" "7" "09/15/2023" "Linux\-PAM" "Linux\-PAM Manual" +.TH "PAM" "7" "04/08/2024" "Linux\-PAM" "Linux\-PAM Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/upstream/debian-unstable/man7/RAND.7ssl b/upstream/debian-unstable/man7/RAND.7ssl index 106a2194..fef833a1 100644 --- a/upstream/debian-unstable/man7/RAND.7ssl +++ b/upstream/debian-unstable/man7/RAND.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "RAND 7SSL" -.TH RAND 7SSL 2024-02-03 3.1.5 OpenSSL +.TH RAND 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/RSA-PSS.7ssl b/upstream/debian-unstable/man7/RSA-PSS.7ssl index 79bb68f1..4e041452 100644 --- a/upstream/debian-unstable/man7/RSA-PSS.7ssl +++ b/upstream/debian-unstable/man7/RSA-PSS.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "RSA-PSS 7SSL" -.TH RSA-PSS 7SSL 2024-02-03 3.1.5 OpenSSL +.TH RSA-PSS 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/X25519.7ssl b/upstream/debian-unstable/man7/X25519.7ssl index 687acc35..a66a9cf2 100644 --- a/upstream/debian-unstable/man7/X25519.7ssl +++ b/upstream/debian-unstable/man7/X25519.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "X25519 7SSL" -.TH X25519 7SSL 2024-02-03 3.1.5 OpenSSL +.TH X25519 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/address_families.7 b/upstream/debian-unstable/man7/address_families.7 index 4a75b723..06ceadd1 100644 --- a/upstream/debian-unstable/man7/address_families.7 +++ b/upstream/debian-unstable/man7/address_families.7 @@ -3,14 +3,14 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH address_families 7 2023-01-22 "Linux man-pages 6.05.01" +.TH address_families 7 2024-05-02 "Linux man-pages 6.8" .SH NAME address_families \- socket address families (domains) .SH SYNOPSIS .nf .BR "#include <sys/types.h>" " /* See NOTES */" .B #include <sys/socket.h> -.PP +.P .BI "int socket(int " domain ", int " type ", int " protocol ); .fi .SH DESCRIPTION @@ -24,7 +24,9 @@ These families are defined in .IR <sys/socket.h> . The formats currently understood by the Linux kernel include: .TP -.BR AF_UNIX ", " AF_LOCAL +.B AF_UNIX +.TQ +.B AF_LOCAL Local communication. For further information, see .BR unix (7). @@ -77,7 +79,7 @@ For further information, see the .UE . .TP .B AF_X25 -ITU-T X.25 / ISO-8208 protocol. +ITU-T X.25 / ISO/IEC\~8208 protocol. For further information, see .BR x25 (7). .TP diff --git a/upstream/debian-unstable/man7/aio.7 b/upstream/debian-unstable/man7/aio.7 index 64c0db16..cddb6152 100644 --- a/upstream/debian-unstable/man7/aio.7 +++ b/upstream/debian-unstable/man7/aio.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH AIO 7 2023-05-03 "Linux man-pages 6.05.01" +.TH AIO 7 2024-05-02 "Linux man-pages 6.8" .SH NAME aio \- POSIX asynchronous I/O overview .SH DESCRIPTION @@ -13,7 +13,7 @@ The application can elect to be notified of completion of the I/O operation in a variety of ways: by delivery of a signal, by instantiation of a thread, or no notification at all. -.PP +.P The POSIX AIO interface consists of the following functions: .TP .BR aio_read (3) @@ -49,14 +49,14 @@ file descriptor. .TP .BR lio_listio (3) Enqueue multiple I/O requests using a single function call. -.PP +.P The .I aiocb ("asynchronous I/O control block") structure defines parameters that control an I/O operation. An argument of this type is employed with all of the functions listed above. This structure has the following form: -.PP +.P .in +4n .EX #include <aiocb.h> @@ -81,7 +81,7 @@ struct aiocb { enum { LIO_READ, LIO_WRITE, LIO_NOP }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I aio_fildes @@ -117,13 +117,13 @@ are and .BR SIGEV_THREAD . See -.BR sigevent (7) +.BR sigevent (3type) for further details. .TP .I aio_lio_opcode The type of operation to be performed; used only for .BR lio_listio (3). -.PP +.P In addition to the standard functions listed above, the GNU C library provides the following extension to the POSIX AIO API: .TP @@ -151,11 +151,11 @@ The control block buffer and the buffer pointed to by .I aio_buf must not be changed while the I/O operation is in progress. These buffers must remain valid until the I/O operation completes. -.PP +.P Simultaneous asynchronous read or write operations using the same .I aiocb structure yield undefined results. -.PP +.P The current Linux POSIX AIO implementation is provided in user space by glibc. This has a number of limitations, most notably that maintaining multiple threads to perform I/O operations is expensive and scales poorly. @@ -186,18 +186,18 @@ of a signal. After all I/O requests have completed, the program retrieves their status using .BR aio_return (3). -.PP +.P The .B SIGQUIT signal (generated by typing control-\e) causes the program to request cancelation of each of the outstanding requests using .BR aio_cancel (3). -.PP +.P Here is an example of what we might see when running this program. In this example, the program queues two requests to standard input, and these are satisfied by two lines of input containing "abc" and "x". -.PP +.P .in +4n .EX $ \fB./a.out /dev/stdin /dev/stdin\fP @@ -438,7 +438,7 @@ main(int argc, char *argv[]) .BR aio_return (3), .BR aio_write (3), .BR lio_listio (3) -.PP +.P "Asynchronous I/O Support in Linux 2.5", Bhattacharya, Pratt, Pulavarty, and Morgan, Proceedings of the Linux Symposium, 2003, diff --git a/upstream/debian-unstable/man7/armscii-8.7 b/upstream/debian-unstable/man7/armscii-8.7 index 2ef36ab7..44197261 100644 --- a/upstream/debian-unstable/man7/armscii-8.7 +++ b/upstream/debian-unstable/man7/armscii-8.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ARMSCII-8 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ARMSCII-8 7 2024-05-02 "Linux man-pages 6.8" .SH NAME armscii-8 \- Armenian character set encoded in octal, decimal, and hexadecimal diff --git a/upstream/debian-unstable/man7/arp.7 b/upstream/debian-unstable/man7/arp.7 index a4ca6a60..c4be4d8a 100644 --- a/upstream/debian-unstable/man7/arp.7 +++ b/upstream/debian-unstable/man7/arp.7 @@ -6,7 +6,7 @@ .\" Modified June 1999 Andi Kleen .\" $Id: arp.7,v 1.10 2000/04/27 19:31:38 ak Exp $ .\" -.TH arp 7 2023-07-15 "Linux man-pages 6.05.01" +.TH arp 7 2024-05-02 "Linux man-pages 6.8" .SH NAME arp \- Linux ARP kernel module. .SH DESCRIPTION @@ -17,7 +17,7 @@ and IPv4 protocol addresses on directly connected networks. The user normally doesn't interact directly with this module except to configure it; instead it provides a service for other protocols in the kernel. -.PP +.P A user process can receive ARP packets by using .BR packet (7) sockets. @@ -30,7 +30,7 @@ The ARP table can also be controlled via on any .B AF_INET socket. -.PP +.P The ARP module maintains a cache of mappings between hardware addresses and protocol addresses. The cache has a limited size so old and less @@ -42,7 +42,7 @@ be directly manipulated by the use of ioctls and its behavior can be tuned by the .I /proc interfaces described below. -.PP +.P When there is no positive feedback for an existing mapping after some time (see the .I /proc @@ -65,7 +65,7 @@ If that fails too, it will broadcast a new ARP request to the network. Requests are sent only when there is data queued for sending. -.PP +.P Linux will automatically add a nonpermanent proxy arp entry when it receives a request for an address it forwards to and proxy arp is enabled on the receiving interface. @@ -77,7 +77,7 @@ sockets. They take a pointer to a .I struct arpreq as their argument. -.PP +.P .in +4n .EX struct arpreq { @@ -89,14 +89,14 @@ struct arpreq { }; .EE .in -.PP +.P .BR SIOCSARP ", " SIOCDARP " and " SIOCGARP respectively set, delete, and get an ARP mapping. Setting and deleting ARP maps are privileged operations and may be performed only by a process with the .B CAP_NET_ADMIN capability or an effective UID of 0. -.PP +.P .I arp_pa must be an .B AF_INET @@ -121,7 +121,7 @@ ATF_NETMASK:Use a netmask ATF_DONTPUB:Don't answer .TE .RE -.PP +.P If the .B ATF_NETMASK flag is set, then @@ -272,13 +272,13 @@ changed in Linux 2.0 to include the .I arp_dev member and the ioctl numbers changed at the same time. Support for the old ioctls was dropped in Linux 2.2. -.PP +.P Support for proxy arp entries for networks (netmask not equal 0xffffffff) was dropped in Linux 2.2. It is replaced by automatic proxy arp setup by the kernel for all reachable hosts on other interfaces (when forwarding and proxy arp is enabled for the interface). -.PP +.P The .I neigh/* interfaces did not exist before Linux 2.2. @@ -286,20 +286,20 @@ interfaces did not exist before Linux 2.2. Some timer settings are specified in jiffies, which is architecture- and kernel version-dependent; see .BR time (7). -.PP +.P There is no way to signal positive feedback from user space. This means connection-oriented protocols implemented in user space will generate excessive ARP traffic, because ndisc will regularly reprobe the MAC address. The same problem applies for some kernel protocols (e.g., NFS over UDP). -.PP +.P This man page mashes together functionality that is IPv4-specific with functionality that is shared between IPv4 and IPv6. .SH SEE ALSO .BR capabilities (7), .BR ip (7), .BR arpd (8) -.PP +.P RFC\ 826 for a description of ARP. RFC\ 2461 for a description of IPv6 neighbor discovery and the base algorithms used. diff --git a/upstream/debian-unstable/man7/ascii.7 b/upstream/debian-unstable/man7/ascii.7 index 13f55788..c1d1746d 100644 --- a/upstream/debian-unstable/man7/ascii.7 +++ b/upstream/debian-unstable/man7/ascii.7 @@ -13,20 +13,20 @@ .\" Modified 1999-08-08 by Michael Haardt (michael@moria.de) .\" Modified 2004-04-01 by aeb .\" -.TH ascii 7 2023-05-02 "Linux man-pages 6.05.01" +.TH ascii 7 2024-05-02 "Linux man-pages 6.8" .SH NAME ascii \- ASCII character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION ASCII is the American Standard Code for Information Interchange. It is a 7-bit code. -Many 8-bit codes (e.g., ISO 8859-1) contain ASCII as their lower half. -The international counterpart of ASCII is known as ISO 646-IRV. -.PP +Many 8-bit codes (e.g., ISO/IEC\~8859-1) contain ASCII as their lower half. +The international counterpart of ASCII is known as ISO/IEC\~646-IRV. +.P The following table contains the 128 ASCII characters. -.PP +.P C program \f(CW\[aq]\eX\[aq]\fP escapes are noted. -.PP +.P .EX .TS l l l l | l l l l. @@ -100,7 +100,7 @@ _ .EE .SS Tables For convenience, below are more compact tables in hex and decimal. -.PP +.P .EX 2 3 4 5 6 7 30 40 50 60 70 80 90 100 110 120 ------------- --------------------------------- @@ -124,17 +124,17 @@ F: / ? O _ o DEL .SH NOTES .SS History /etc/ascii (VII) appears in the UNIX Programmer's Manual. -.PP +.P On older terminals, the underscore code is displayed as a left arrow, called backarrow, the caret is displayed as an up-arrow and the vertical bar has a hole in the middle. -.PP +.P Uppercase and lowercase characters differ by just one bit and the ASCII character 2 differs from the double quote by just one bit, too. That made it much easier to encode characters mechanically or with a non-microcontroller-based electronic keyboard and that pairing was found on old teletypes. -.PP +.P The ASCII standard was published by the United States of America Standards Institute (USASI) in 1968. .\" diff --git a/upstream/debian-unstable/man7/attributes.7 b/upstream/debian-unstable/man7/attributes.7 index b32fe545..cf9fff7e 100644 --- a/upstream/debian-unstable/man7/attributes.7 +++ b/upstream/debian-unstable/man7/attributes.7 @@ -2,7 +2,7 @@ .\" Written by Alexandre Oliva <aoliva@redhat.com> .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH attributes 7 2023-03-18 "Linux man-pages 6.05.01" +.TH attributes 7 2024-05-02 "Linux man-pages 6.8" .SH NAME attributes \- POSIX safety concepts .SH DESCRIPTION @@ -13,7 +13,7 @@ the text of this man page is based on the material taken from the "POSIX Safety Concepts" section of the GNU C Library manual. Further details on the topics described here can be found in that manual. -.PP +.P Various function manual pages include a section ATTRIBUTES that describes the safety of calling the function in various contexts. This section annotates functions with the following safety markings: @@ -145,7 +145,7 @@ functions are not safe to call in a multithreaded programs. .\" keyword from safety notes. .\" As long as the keyword remains, however, .\" they are not to be regarded as a promise of future behavior. -.PP +.P Other keywords that appear in safety notes are defined in subsequent sections. .\" .\" @@ -470,7 +470,7 @@ in others, they are not even exposed to users. .\" In some cases, such as .\" .BR tmpname (3), .\" the variant is chosen not by calling an alternate entry point, -.\" but by passing a non-NULL pointer to the buffer in which the +.\" but by passing a non-null pointer to the buffer in which the .\" returned values are to be stored. .\" These variants are generally preferable in multi-threaded programs, .\" although some of them are not MT-Safe because of other internal buffers, diff --git a/upstream/debian-unstable/man7/bio.7ssl b/upstream/debian-unstable/man7/bio.7ssl index 9d974ab6..0ad46d91 100644 --- a/upstream/debian-unstable/man7/bio.7ssl +++ b/upstream/debian-unstable/man7/bio.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "BIO 7SSL" -.TH BIO 7SSL 2024-02-03 3.1.5 OpenSSL +.TH BIO 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -107,6 +107,24 @@ Normally the \fItype\fR argument is supplied by a function which returns a pointer to a BIO_METHOD. There is a naming convention for such functions: a source/sink BIO typically starts with \fIBIO_s_\fR and a filter BIO with \fIBIO_f_\fR. +.SS "TCP Fast Open" +.IX Subsection "TCP Fast Open" +TCP Fast Open (RFC7413), abbreviated "TFO", is supported by the BIO +interface since OpenSSL 3.2. TFO is supported in the following operating systems: +.IP \(bu 4 +Linux kernel 3.13 and later, where TFO is enabled by default. +.IP \(bu 4 +Linux kernel 4.11 and later, using TCP_FASTOPEN_CONNECT. +.IP \(bu 4 +FreeBSD 10.3 to 11.4, supports server TFO only. +.IP \(bu 4 +FreeBSD 12.0 and later, supports both client and server TFO. +.IP \(bu 4 +macOS 10.14 and later. +.PP +Each operating system has a slightly different API for TFO. Please +refer to the operating systems' API documentation when using +sockets directly. .SH EXAMPLES .IX Header "EXAMPLES" Create a memory BIO: @@ -121,7 +139,9 @@ Create a memory BIO: \&\fBBIO_f_cipher\fR\|(3), \fBBIO_f_md\fR\|(3), \&\fBBIO_f_null\fR\|(3), \fBBIO_f_ssl\fR\|(3), \&\fBBIO_f_readbuffer\fR\|(3), -\&\fBBIO_find_type\fR\|(3), \fBBIO_new\fR\|(3), +\&\fBBIO_find_type\fR\|(3), +\&\fBBIO_get_conn_mode\fR\|(3), +\&\fBBIO_new\fR\|(3), \&\fBBIO_new_bio_pair\fR\|(3), \&\fBBIO_push\fR\|(3), \fBBIO_read_ex\fR\|(3), \&\fBBIO_s_accept\fR\|(3), \fBBIO_s_bio\fR\|(3), @@ -129,10 +149,13 @@ Create a memory BIO: \&\fBBIO_s_file\fR\|(3), \fBBIO_s_mem\fR\|(3), \&\fBBIO_s_null\fR\|(3), \fBBIO_s_socket\fR\|(3), \&\fBBIO_set_callback\fR\|(3), +\&\fBBIO_set_conn_mode\fR\|(3), +\&\fBBIO_set_tfo\fR\|(3), +\&\fBBIO_set_tfo_accept\fR\|(3), \&\fBBIO_should_retry\fR\|(3) .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000\-2022 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/boot.7 b/upstream/debian-unstable/man7/boot.7 index f69e8c1c..ec053b1f 100644 --- a/upstream/debian-unstable/man7/boot.7 +++ b/upstream/debian-unstable/man7/boot.7 @@ -10,7 +10,7 @@ .\" .\" Modified 2004-11-03 patch from Martin Schulze <joey@infodrom.org> .\" -.TH boot 7 2023-07-08 "Linux man-pages 6.05.01" +.TH boot 7 2024-05-02 "Linux man-pages 6.8" .SH NAME boot \- System bootup process based on UNIX System V Release 4 .SH DESCRIPTION @@ -27,14 +27,14 @@ kernel root user-space process (\fIinit\fR and \fIinittab\fR) .IP (5) boot scripts -.PP +.P Each of these is described below in more detail. .SS Hardware After power-on or hard reset, control is given to a program stored in read-only memory (normally PROM); for historical reasons involving the personal computer, this program is often called "the \fBBIOS\fR". -.PP +.P This program normally performs a basic self-test of the machine and accesses nonvolatile memory to read further parameters. @@ -43,7 +43,7 @@ battery-backed CMOS memory, so most people refer to it as "the \fBCMOS\fR"; outside of the PC world, it is usually called "the \fBNVRAM\fR" (nonvolatile RAM). -.PP +.P The parameters stored in the NVRAM vary among systems, but as a minimum, they should specify which device can supply an OS loader, or at least which @@ -64,11 +64,11 @@ interactive use, in order to enable specification of an alternative kernel (maybe a backup in case the one last compiled isn't functioning) and to pass optional parameters to the kernel. -.PP +.P In a traditional PC, the OS loader is located in the initial 512-byte block of the boot device; this block is known as "the \fBMBR\fR" (Master Boot Record). -.PP +.P In most systems, the OS loader is very limited due to various constraints. Even on non-PC systems, @@ -76,12 +76,12 @@ there are some limitations on the size and complexity of this loader, but the size limitation of the PC MBR (512 bytes, including the partition table) makes it almost impossible to squeeze much functionality into it. -.PP +.P Therefore, most systems split the role of loading the OS between a primary OS loader and a secondary OS loader; this secondary OS loader may be located within a larger portion of persistent storage, such as a disk partition. -.PP +.P In Linux, the OS loader is often .BR grub (8) (an alternative is @@ -95,13 +95,13 @@ The kernel starts the virtual memory swapper (it is a kernel process, called "kswapd" in a modern Linux kernel), and mounts some filesystem at the root path, .IR / . -.PP +.P Some of the parameters that may be passed to the kernel relate to these activities (for example, the default root filesystem can be overridden); for further information on Linux kernel parameters, read .BR bootparam (7). -.PP +.P Only then does the kernel create the initial userland process, which is given the number 1 as its .B PID @@ -120,7 +120,7 @@ fundamentally different approach known as .BR systemd (1), for which the bootup process is detailed in its associated .BR bootup (7). -.PP +.P When .I /sbin/init starts, it reads @@ -137,12 +137,12 @@ is single-user mode, and run level .B 2 entails running most network services). -.PP +.P The administrator may change the current run level via .BR init (1), and query the current run level via .BR runlevel (8). -.PP +.P However, since it is not convenient to manage individual services by editing this file, .I /etc/inittab @@ -154,7 +154,7 @@ Note: The following description applies to an OS based on UNIX System V Release 4. However, a number of widely used systems (Slackware Linux, FreeBSD, OpenBSD) have a somewhat different scheme for boot scripts. -.PP +.P For each managed service (mail, nfs server, cron, etc.), there is a single startup script located in a specific directory .RI ( /etc/init.d @@ -174,7 +174,7 @@ of the form \fI/etc/rc[0\-6S].d\fR. In each of these directories, there are links (usually symbolic) to the scripts in the \fI/etc/init.d\fR directory. -.PP +.P A primary script (usually \fI/etc/rc\fR) is called from .BR inittab (5); this primary script calls each service's script via a link in the @@ -183,7 +183,7 @@ Each link whose name begins with \[aq]S\[aq] is called with the argument "start" (thereby starting the service). Each link whose name begins with \[aq]K\[aq] is called with the argument "stop" (thereby stopping the service). -.PP +.P To define the starting or stopping order within the same run level, the name of a link contains an \fBorder-number\fR. Also, for clarity, the name of a link usually @@ -195,7 +195,7 @@ service on run level 2. This happens after \fI/etc/rc2.d/S12syslog\fR is run but before \fI/etc/rc2.d/S90xfs\fR is run. -.PP +.P To manage these links is to manage the boot order and run levels; under many systems, there are tools to help with this task (e.g., @@ -209,7 +209,7 @@ inputs without editing an entire boot script, some separate configuration file is used, and is located in a specific directory where an associated boot script may find it (\fI/etc/sysconfig\fR on older Red Hat systems). -.PP +.P In older UNIX systems, such a file contained the actual command line options for a daemon, but in modern Linux systems (and also in HP-UX), it just contains shell variables. diff --git a/upstream/debian-unstable/man7/bootparam.7 b/upstream/debian-unstable/man7/bootparam.7 index 5514aca2..10bb5870 100644 --- a/upstream/debian-unstable/man7/bootparam.7 +++ b/upstream/debian-unstable/man7/bootparam.7 @@ -6,7 +6,7 @@ .\" (dated v1.0.1, 15/08/95). .\" Major update, aeb, 970114. .\" -.TH bootparam 7 2023-02-05 "Linux man-pages 6.05.01" +.TH bootparam 7 2024-05-02 "Linux man-pages 6.8" .SH NAME bootparam \- introduction to boot time parameters of the Linux kernel .SH DESCRIPTION @@ -16,7 +16,7 @@ In general, this is used to supply the kernel with information about hardware parameters that the kernel would not be able to determine on its own, or to avoid/override the values that the kernel would otherwise detect. -.PP +.P When the kernel is booted directly by the BIOS, you have no opportunity to specify any parameters. So, in order to take advantage of this possibility you have to @@ -25,13 +25,13 @@ use a boot loader that is able to pass parameters, such as GRUB. The kernel command line is parsed into a list of strings (boot arguments) separated by spaces. Most of the boot arguments have the form: -.PP +.P .in +4n .EX name[=value_1][,value_2]...[,value_10] .EE .in -.PP +.P where 'name' is a unique keyword that is used to identify what part of the kernel the associated values (if any) are to be given to. Note the limit of 10 is real, as the present code handles only 10 comma @@ -39,14 +39,14 @@ separated parameters per keyword. (However, you can reuse the same keyword with up to an additional 10 parameters in unusually complicated situations, assuming the setup function supports it.) -.PP +.P Most of the sorting is coded in the kernel source file .IR init/main.c . First, the kernel checks to see if the argument is any of the special arguments 'root=', \&'nfsroot=', 'nfsaddrs=', 'ro', 'rw', 'debug', or 'init'. The meaning of these special arguments is described below. -.PP +.P Then it walks a list of setup functions to see if the specified argument string (such as 'foo') has been associated with a setup function ('foo_setup()') for a particular @@ -57,13 +57,13 @@ if 'foo' was registered. If it was, then it would call the setup function associated with 'foo' (foo_setup()) and hand it the arguments 3, 4, 5, and 6 as given on the kernel command line. -.PP +.P Anything of the form 'foo=bar' that is not accepted as a setup function as described above is then interpreted as an environment variable to be set. A (useless?) example would be to use 'TERM=vt100' as a boot argument. -.PP +.P Any remaining arguments that were not picked up by the kernel and were not interpreted as environment variables are then passed onto PID 1, which is usually the @@ -376,12 +376,12 @@ the last process that used it has closed .IR /dev/initrd .) .SS Boot arguments for SCSI devices General notation for this section: -.PP +.P .I iobase -- the first I/O port that the SCSI host occupies. These are specified in hexadecimal notation, and usually lie in the range from 0x200 to 0x3ff. -.PP +.P .I irq -- the hardware interrupt that the card is configured to use. Valid values will be dependent on the card in question, but will @@ -389,7 +389,7 @@ usually be 5, 7, 9, 10, 11, 12, and 15. The other values are usually used for common peripherals like IDE hard disks, floppies, serial ports, and so on. -.PP +.P .I scsi\-id -- the ID that the host adapter uses to identify itself on the SCSI bus. @@ -397,7 +397,7 @@ Only some host adapters allow you to change this value, as most have it permanently specified internally. The usual default value is 7, but the Seagate and Future Domain TMC-950 boards use 6. -.PP +.P .I parity -- whether the SCSI host adapter expects the attached devices to supply a parity value with all information exchanges. @@ -553,33 +553,33 @@ geometry parameters of the second disk. Different drivers make use of different parameters, but they all at least share having an IRQ, an I/O port base value, and a name. In its most generic form, it looks something like this: -.PP +.P .in +4n .EX ether=irq,iobase[,param_1[,...param_8]],name .EE .in -.PP +.P The first nonnumeric argument is taken as the name. The param_n values (if applicable) usually have different meanings for each different card/driver. Typical param_n values are used to specify things like shared memory address, interface selection, DMA channel and the like. -.PP +.P The most common use of this parameter is to force probing for a second ethercard, as the default is to probe only for one. This can be accomplished with a simple: -.PP +.P .in +4n .EX ether=0,0,eth1 .EE .in -.PP +.P Note that the values of zero for the IRQ and I/O base in the above example tell the driver(s) to autoprobe. -.PP +.P The Ethernet-HowTo has extensive documentation on using multiple cards and on the card/driver-specific implementation of the param_n values where used. @@ -604,25 +604,25 @@ It is described in the Linux kernel source file in older kernel versions). It accepts a boot argument of the form: -.PP +.P .in +4n .EX sound=device1[,device2[,device3...[,device10]]] .EE .in -.PP +.P where each deviceN value is of the following format 0xTaaaId and the bytes are used as follows: -.PP +.P T \- device type: 1=FM, 2=SB, 3=PAS, 4=GUS, 5=MPU401, 6=SB16, 7=SB16-MPU401 -.PP +.P aaa \- I/O address in hex. -.PP +.P I \- interrupt line in hex (i.e., 10=a, 11=b, ...) -.PP +.P d \- DMA channel. -.PP +.P As you can see, it gets pretty messy, and you are better off to compile in your own personal values as recommended. Using a boot argument of @@ -659,6 +659,6 @@ lp=0. .SH SEE ALSO .BR klogd (8), .BR mount (8) -.PP +.P For up-to-date information, see the kernel source file .IR Documentation/admin\-guide/kernel\-parameters.txt . diff --git a/upstream/debian-unstable/man7/bootup.7 b/upstream/debian-unstable/man7/bootup.7 index 3c82f20d..643f7fc1 100644 --- a/upstream/debian-unstable/man7/bootup.7 +++ b/upstream/debian-unstable/man7/bootup.7 @@ -1,5 +1,5 @@ '\" t -.TH "BOOTUP" "7" "" "systemd 255" "bootup" +.TH "BOOTUP" "7" "" "systemd 256~rc3" "bootup" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -28,8 +28,7 @@ A number of different components are involved in the boot of a Linux system\&. I or \m[blue]\fBGRUB\fR\m[]\&\s-2\u[1]\d\s+2) stored on a persistent storage device\&. This boot loader will then invoke an OS kernel from disk (or the network)\&. On systems using EFI or other types of firmware, this firmware may also load the kernel directly\&. .PP -The kernel (optionally) mounts an in\-memory file system, often generated by -\fBdracut\fR(8), which looks for the root file system\&. Nowadays this is implemented as an "initramfs" \(em a compressed CPIO archive that the kernel extracts into a tmpfs\&. In the past normal file systems using an in\-memory block device (ramdisk) were used, and the name "initrd" is still used to describe both concepts\&. It\*(Aqs the boot loader or the firmware that loads both the kernel and initrd/initramfs images into memory, but the kernel which interprets it as a file system\&. +The kernel (optionally) mounts an in\-memory file system, which looks for the root file system\&. Nowadays this is implemented as an "initramfs" \(em a compressed CPIO archive that the kernel extracts into a tmpfs\&. In the past normal file systems using an in\-memory block device (ramdisk) were used, and the name "initrd" is still used to describe both concepts\&. It\*(Aqs the boot loader or the firmware that loads both the kernel and initrd/initramfs images into memory, but the kernel which interprets it as a file system\&. \fBsystemd\fR(1) may be used to manage services in the initrd, similarly to the real system\&. .PP @@ -301,21 +300,23 @@ System shutdown with systemd also consists of various target units with some min v final\&.target | - ___________________________/ \e_________________ - / | | \e - | | | | - v | | | -systemd\-reboot\&.service | | | - | v | | - | systemd\-poweroff\&.service | | - v | v | - \fIreboot\&.target\fR | systemd\-halt\&.service | - v | v - \fIpoweroff\&.target\fR | systemd\-kexec\&.service - v | - \fIhalt\&.target\fR | - v - \fIkexec\&.target\fR + ___________________________/ \e_________________________________ + / | | | \e + | | | | | + v | | | | +systemd\-reboot\&.service | | | | + | v | | | + | systemd\-poweroff\&.service | | | + v | v | | + \fIreboot\&.target\fR | systemd\-halt\&.service | | + v | v | + \fIpoweroff\&.target\fR | systemd\-kexec\&.service | + v | | + \fIhalt\&.target\fR | systemd\-soft\-reboot\&.service + v | + \fIkexec\&.target\fR | + v + \fIsoft\-reboot\&.target\fR .fi .if n \{\ .RE @@ -335,12 +336,7 @@ systemd\-shutdown binary), which will unmount any remaining file systems, kill any remaining processes and release any other remaining resources, in a simple and robust fashion, without taking any service or unit concept into account anymore\&. At that point, regular applications and resources are generally terminated and released already, the second phase hence operates only as safety net for everything that couldn\*(Aqt be stopped or released for some reason during the primary, unit\-based shutdown phase described above\&. .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBboot\fR(7), -\fBsystemd.special\fR(7), -\fBsystemd.target\fR(5), -\fBsystemd-halt.service\fR(8), -\fBdracut\fR(8) +\fBsystemd\fR(1), \fBboot\fR(7), \fBsystemd.special\fR(7), \fBsystemd.target\fR(5), \fBsystemd-halt.service\fR(8), \fBsystemd-soft-reboot.service\fR(8) .SH "NOTES" .IP " 1." 4 GRUB diff --git a/upstream/debian-unstable/man7/bpf-helpers.7 b/upstream/debian-unstable/man7/bpf-helpers.7 index 26ddf836..b4236f17 100644 --- a/upstream/debian-unstable/man7/bpf-helpers.7 +++ b/upstream/debian-unstable/man7/bpf-helpers.7 @@ -27,18 +27,18 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BPF-HELPERS" 7 "2023-04-11" "Linux v6.2" +.TH "BPF-HELPERS" 7 "2023-11-10" "Linux v6.8" .SH NAME BPF-HELPERS \- list of eBPF helper functions .\" Copyright (C) All BPF authors and contributors from 2014 to present. . .\" See git log include/uapi/linux/bpf.h in kernel tree for details. . -.\" +.\" . -.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" SPDX-License-Identifier: Linux-man-pages-copyleft . -.\" +.\" . .\" Please do not edit this file. It was generated from the documentation . @@ -156,27 +156,25 @@ Current \fIktime\fP\&. .B Description This helper is a \(dqprintk()\-like\(dq facility for debugging. It prints a message defined by format \fIfmt\fP (of size \fIfmt_size\fP) -to file \fI/sys/kernel/debug/tracing/trace\fP from DebugFS, if +to file \fI/sys/kernel/tracing/trace\fP from TraceFS, if available. It can take up to three additional \fBu64\fP arguments (as an eBPF helpers, the total number of arguments is limited to five). .sp Each time the helper is called, it appends a line to the trace. -Lines are discarded while \fI/sys/kernel/debug/tracing/trace\fP is -open, use \fI/sys/kernel/debug/tracing/trace_pipe\fP to avoid this. +Lines are discarded while \fI/sys/kernel/tracing/trace\fP is +open, use \fI/sys/kernel/tracing/trace_pipe\fP to avoid this. The format of the trace is customizable, and the exact output one will get depends on the options set in -\fI/sys/kernel/debug/tracing/trace_options\fP (see also the +\fI/sys/kernel/tracing/trace_options\fP (see also the \fIREADME\fP file under the same directory). However, it usually defaults to something like: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C -telnet\-470 [001] .N.. 419421.045894: 0x00000001: <fmt> -.ft P -.fi +.EX +telnet\-470 [001] .N.. 419421.045894: 0x00000001: <formatted msg> +.EE .UNINDENT .UNINDENT .sp @@ -204,7 +202,8 @@ are set. \fB0x00000001\fP is a fake value used by BPF for the instruction pointer register. .IP \(bu 2 -\fB<fmt>\fP is the message formatted with \fIfmt\fP\&. +\fB<formatted msg>\fP is the message formatted with +\fIfmt\fP\&. .UNINDENT .UNINDENT .UNINDENT @@ -404,7 +403,9 @@ performed again, if the helper is used in combination with direct packet access. .TP .B Return -0 on success, or a negative error in case of failure. +0 on success, or a negative error in case of failure. Positive +error indicates a potential drop or congestion in the target +device. The particular positive error codes are not defined. .UNINDENT .TP .B \fBu64 bpf_get_current_pid_tgid(void)\fP @@ -541,8 +542,7 @@ remote ends with IPv4 address other than 10.0.0.1: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX int ret; struct bpf_tunnel_key key = {}; @@ -554,8 +554,7 @@ if (key.remote_ipv4 != 0x0a000001) return TC_ACT_SHOT; // drop packet return TC_ACT_OK; // accept packet -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -600,20 +599,22 @@ sequence number should be added to tunnel header before sending the packet. This flag was added for GRE encapsulation, but might be used with other protocols as well in the future. +.TP +.B \fBBPF_F_NO_TUNNEL_KEY\fP +Add a flag to tunnel metadata indicating that no tunnel +key should be set in the resulting tunnel header. .UNINDENT .sp Here is a typical usage on the transmit path: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX struct bpf_tunnel_key key; populate key ... bpf_skb_set_tunnel_key(skb, &key, sizeof(key), 0); bpf_clone_redirect(skb, vxlan_dev_ifindex, 0); -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -827,11 +828,9 @@ user stacks (such as stacks for Java programs). To do so, use: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # sysctl kernel.perf_event_max_stack=<new value> -.ft P -.fi +.EE .UNINDENT .UNINDENT .TP @@ -1334,8 +1333,8 @@ The option value of length \fIoptlen\fP is pointed by \fIoptval\fP\&. .IP \(bu 2 \fBstruct bpf_sock_ops\fP for \fBBPF_PROG_TYPE_SOCK_OPS\fP\&. .IP \(bu 2 -\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP -and \fBBPF_CGROUP_INET6_CONNECT\fP\&. +\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP, +\fBBPF_CGROUP_INET6_CONNECT\fP and \fBBPF_CGROUP_UNIX_CONNECT\fP\&. .UNINDENT .sp This helper actually implements a subset of \fBsetsockopt()\fP\&. @@ -1417,6 +1416,11 @@ type; \fIlen\fP is the length of the inner MAC header. \fBBPF_F_ADJ_ROOM_ENCAP_L2_ETH\fP: Use with BPF_F_ADJ_ROOM_ENCAP_L2 flag to further specify the L2 type as Ethernet. +.IP \(bu 2 +\fBBPF_F_ADJ_ROOM_DECAP_L3_IPV4\fP, +\fBBPF_F_ADJ_ROOM_DECAP_L3_IPV6\fP: +Indicate the new IP header version after decapsulating the outer +IP header. Used when the inner and outer IP versions are different. .UNINDENT .sp A call to this helper is susceptible to change the underlying @@ -1572,11 +1576,9 @@ as follows. .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX normalized_counter = counter * t_enabled / t_running -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -1596,7 +1598,7 @@ value and do the calculation inside the eBPF program. .INDENT 7.0 .TP .B Description -For en eBPF program attached to a perf event, retrieve the +For an eBPF program attached to a perf event, retrieve the value of the event counter associated to \fIctx\fP and store it in the structure pointed by \fIbuf\fP and of size \fIbuf_size\fP\&. Enabled and running times are also stored in the structure (see @@ -1623,8 +1625,8 @@ The retrieved value is stored in the structure pointed by .IP \(bu 2 \fBstruct bpf_sock_ops\fP for \fBBPF_PROG_TYPE_SOCK_OPS\fP\&. .IP \(bu 2 -\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP -and \fBBPF_CGROUP_INET6_CONNECT\fP\&. +\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP, +\fBBPF_CGROUP_INET6_CONNECT\fP and \fBBPF_CGROUP_UNIX_CONNECT\fP\&. .UNINDENT .sp This helper actually implements a subset of \fBgetsockopt()\fP\&. @@ -1945,11 +1947,9 @@ user stacks (such as stacks for Java programs). To do so, use: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # sysctl kernel.perf_event_max_stack=<new value> -.ft P -.fi +.EE .UNINDENT .UNINDENT .TP @@ -2010,9 +2010,26 @@ following values: Do a direct table lookup vs full lookup using FIB rules. .TP +.B \fBBPF_FIB_LOOKUP_TBID\fP +Used with BPF_FIB_LOOKUP_DIRECT. +Use the routing table ID present in \fIparams\fP\->tbid +for the fib lookup. +.TP .B \fBBPF_FIB_LOOKUP_OUTPUT\fP Perform lookup from an egress perspective (default is ingress). +.TP +.B \fBBPF_FIB_LOOKUP_SKIP_NEIGH\fP +Skip the neighbour table lookup. \fIparams\fP\->dmac +and \fIparams\fP\->smac will not be set as output. A common +use case is to call \fBbpf_redirect_neigh\fP() after +doing \fBbpf_fib_lookup\fP(). +.TP +.B \fBBPF_FIB_LOOKUP_SRC\fP +Derive and set source IP addr in \fIparams\fP\->ipv{4,6}_src +for the nexthop. If the src addr cannot be derived, +\fBBPF_FIB_LKUP_RET_NO_SRC_ADDR\fP is returned. In this +case, \fIparams\fP\->dmac and \fIparams\fP\->smac are not set either. .UNINDENT .sp \fIctx\fP is either \fBstruct xdp_md\fP for XDP programs or @@ -3029,24 +3046,20 @@ get its length at runtime. See the following snippet: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX SEC(\(dqkprobe/sys_open\(dq) void bpf_sys_open(struct pt_regs *ctx) { char buf[PATHLEN]; // PATHLEN is defined to 256 - int res; - - res = bpf_probe_read_user_str(buf, sizeof(buf), - ctx\->di); + int res = bpf_probe_read_user_str(buf, sizeof(buf), + ctx\->di); // Consume buf, for example push it to // userspace via bpf_perf_event_output(); we // can use res (the string length) as event // size, after checking its boundaries. } -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -3253,9 +3266,6 @@ The \fIflags\fP argument must be zero. .sp \fB\-EOPNOTSUPP\fP if the operation is not supported, for example a call from outside of TC ingress. -.sp -\fB\-ESOCKTNOSUPPORT\fP if the socket type is not supported -(reuseport). .UNINDENT .TP .B \fBlong bpf_sk_assign(struct bpf_sk_lookup *\fP\fIctx\fP\fB, struct bpf_sock *\fP\fIsk\fP\fB, u64\fP \fIflags\fP\fB)\fP @@ -3605,6 +3615,8 @@ Dynamically cast a \fIsk\fP pointer to a \fIudp6_sock\fP pointer. .TP .B Description Return a user or a kernel stack in bpf program provided buffer. +Note: the user stack will only be populated if the \fItask\fP is +the current task; all other tasks will return \-EOPNOTSUPP. To achieve this, the helper needs \fItask\fP, which is a valid pointer to \fBstruct task_struct\fP\&. To store the stacktrace, the bpf program provides \fIbuf\fP with a nonnegative \fIsize\fP\&. @@ -3617,6 +3629,7 @@ the following flags: .TP .B \fBBPF_F_USER_STACK\fP Collect a user space stack instead of a kernel stack. +The \fItask\fP must be the current task. .TP .B \fBBPF_F_USER_BUILD_ID\fP Collect buildid+offset instead of ips for user stack, @@ -3632,11 +3645,9 @@ user stacks (such as stacks for Java programs). To do so, use: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # sysctl kernel.perf_event_max_stack=<new value> -.ft P -.fi +.EE .UNINDENT .UNINDENT .TP @@ -4334,6 +4345,17 @@ The map can contain timers that invoke callback_fn\-s from different programs. The same callback_fn can serve different timers from different maps if key/value layout matches across maps. Every bpf_timer_set_callback() can have different callback_fn. +.sp +\fIflags\fP can be one of: +.INDENT 7.0 +.TP +.B \fBBPF_F_TIMER_ABS\fP +Start the timer in absolute expire value instead of the +default relative one. +.TP +.B \fBBPF_F_TIMER_CPU_PIN\fP +Timer will be pinned to the CPU of the caller. +.UNINDENT .TP .B Return 0 on success. @@ -4360,10 +4382,14 @@ own timer which would have led to a deadlock otherwise. .TP .B Description Get address of the traced function (for tracing and kprobe programs). +.sp +When called for kprobe program attached as uprobe it returns +probe address for both entry and return uprobe. .TP .B Return -Address of the traced function. +Address of the traced function for kprobe. 0 for kprobes placed within the function (not at the entry). +Address of the probe for uprobe and return uprobe. .UNINDENT .TP .B \fBu64 bpf_get_attach_cookie(void *\fP\fIctx\fP\fB)\fP @@ -4817,12 +4843,28 @@ of \fIsrc\fP\(aqs data, \-EINVAL if \fIsrc\fP is an invalid dynptr or if .B Description Write \fIlen\fP bytes from \fIsrc\fP into \fIdst\fP, starting from \fIoffset\fP into \fIdst\fP\&. -\fIflags\fP is currently unused. +.sp +\fIflags\fP must be 0 except for skb\-type dynptrs. +.INDENT 7.0 +.TP +.B For skb\-type dynptrs: +.INDENT 7.0 +.IP \(bu 2 +All data slices of the dynptr are automatically +invalidated after \fBbpf_dynptr_write\fP(). This is +because writing may pull the skb and change the +underlying packet buffer. +.IP \(bu 2 +For \fIflags\fP, please see the flags accepted by +\fBbpf_skb_store_bytes\fP(). +.UNINDENT +.UNINDENT .TP .B Return 0 on success, \-E2BIG if \fIoffset\fP + \fIlen\fP exceeds the length of \fIdst\fP\(aqs data, \-EINVAL if \fIdst\fP is an invalid dynptr or if \fIdst\fP -is a read\-only dynptr or if \fIflags\fP is not 0. +is a read\-only dynptr or if \fIflags\fP is not correct. For skb\-type dynptrs, +other errors correspond to errors returned by \fBbpf_skb_store_bytes\fP(). .UNINDENT .TP .B \fBvoid *bpf_dynptr_data(const struct bpf_dynptr *\fP\fIptr\fP\fB, u32\fP \fIoffset\fP\fB, u32\fP \fIlen\fP\fB)\fP @@ -4833,6 +4875,9 @@ Get a pointer to the underlying dynptr data. .sp \fIlen\fP must be a statically known value. The returned data slice is invalidated whenever the dynptr is invalidated. +.sp +skb and xdp type dynptrs may not use bpf_dynptr_data. They should +instead use bpf_dynptr_slice and bpf_dynptr_slice_rdwr. .TP .B Return Pointer to the underlying dynptr data, NULL if the dynptr is @@ -5049,7 +5094,7 @@ eBPF programs can have an associated license, passed along with the bytecode instructions to the kernel when the programs are loaded. The format for that string is identical to the one in use for kernel modules (Dual licenses, such as \(dqDual BSD/GPL\(dq, may be used). Some helper functions are only accessible to -programs that are compatible with the GNU Privacy License (GPL). +programs that are compatible with the GNU General Public License (GNU GPL). .sp In order to use such helpers, the eBPF program must be loaded with the correct license string passed (via \fBattr\fP) to the \fBbpf\fP() system call, and this @@ -5058,11 +5103,9 @@ similar to the following: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX char ____license[] __attribute__((section(\(dqlicense\(dq), used)) = \(dqGPL\(dq; -.ft P -.fi +.EE .UNINDENT .UNINDENT .SH IMPLEMENTATION diff --git a/upstream/debian-unstable/man7/capabilities.7 b/upstream/debian-unstable/man7/capabilities.7 index c8766d2c..6fe74f47 100644 --- a/upstream/debian-unstable/man7/capabilities.7 +++ b/upstream/debian-unstable/man7/capabilities.7 @@ -25,7 +25,7 @@ .\" other capabilities where the permitted or inheritable bit is set. .\" 2011-09-07, mtk/Serge hallyn: Add CAP_SYSLOG .\" -.TH Capabilities 7 2023-05-03 "Linux man-pages 6.05.01" +.TH Capabilities 7 2024-05-02 "Linux man-pages 6.8" .SH NAME capabilities \- overview of Linux capabilities .SH DESCRIPTION @@ -40,7 +40,7 @@ Privileged processes bypass all kernel permission checks, while unprivileged processes are subject to full permission checking based on the process's credentials (usually: effective UID, effective GID, and supplementary group list). -.PP +.P Starting with Linux 2.2, Linux divides the privileges traditionally associated with superuser into distinct units, known as .IR capabilities , @@ -832,7 +832,7 @@ be changed and retrieved. .IP \[bu] The filesystem must support attaching capabilities to an executable file, so that a process gains those capabilities when the file is executed. -.PP +.P Before Linux 2.6.24, only the first two of these requirements are met; since Linux 2.6.24, all three requirements are met. .\" @@ -961,7 +961,7 @@ capabilities to increase during an .BR execve (2), this does not trigger the secure-execution mode described in .BR ld.so (8). -.PP +.P A child created via .BR fork (2) inherits copies of its parent's capability sets. @@ -970,13 +970,13 @@ For details on how affects capabilities, see .I Transformation of capabilities during execve() below. -.PP +.P Using .BR capset (2), a thread may manipulate its own capability sets; see .I Programmatically adjusting capability sets below. -.PP +.P Since Linux 3.2, the file .I /proc/sys/kernel/cap_last_cap .\" commit 73efc0394e148d0e15583e13712637831f926720 @@ -1002,7 +1002,7 @@ The file capability sets, in conjunction with the capability sets of the thread, determine the capabilities of a thread after an .BR execve (2). -.PP +.P The three file capability sets are: .TP .IR Permitted " (formerly known as " forced ): @@ -1084,7 +1084,7 @@ with version 2 capabilities; that is, on a modern Linux system, there may be some files with version 2 capabilities while others have version 3 capabilities. -.PP +.P Before Linux 4.14, the only kind of file capability extended attribute that could be attached to a file was a @@ -1095,7 +1095,7 @@ the version of the .I security.capability extended attribute that is attached to a file depends on the circumstances in which the attribute was created. -.PP +.P Starting with Linux 4.14, a .I security.capability extended attribute is automatically created as (or converted to) @@ -1115,13 +1115,13 @@ meaning that (a) the thread has the capability in its own user namespace; and (b) the UID and GID of the file inode have mappings in the writer's user namespace. -.PP +.P When a .B VFS_CAP_REVISION_3 .I security.capability extended attribute is created, the root user ID of the creating thread's user namespace is saved in the extended attribute. -.PP +.P By contrast, creating or modifying a .I security.capability extended attribute from a privileged @@ -1132,7 +1132,7 @@ namespace where the underlying filesystem was mounted automatically results in the creation of a version 2 .RB ( VFS_CAP_REVISION_2 ) attribute. -.PP +.P Note that the creation of a version 3 .I security.capability extended attribute is automatic. @@ -1161,7 +1161,7 @@ and in order for those tools to be used to create and retrieve version 3 .I security.capability attributes. -.PP +.P Note that a file can have either a version 2 or a version 3 .I security.capability extended attribute associated with it, but not both: @@ -1176,7 +1176,7 @@ During an .BR execve (2), the kernel calculates the new capabilities of the process using the following algorithm: -.PP +.P .in +4n .EX P'(ambient) = (file is privileged) ? 0 : P(ambient) @@ -1191,7 +1191,7 @@ P'(inheritable) = P(inheritable) [i.e., unchanged] P'(bounding) = P(bounding) [i.e., unchanged] .EE .in -.PP +.P where: .RS 4 .TP @@ -1206,7 +1206,7 @@ denotes the value of a thread capability set after the F() denotes a file capability set .RE -.PP +.P Note the following details relating to the above capability transformation rules: .IP \[bu] 3 @@ -1222,7 +1222,7 @@ That system-wide value was employed to calculate the new permitted set during .BR execve (2) in the same manner as shown above for .IR P(bounding) . -.PP +.P .IR Note : during the capability transitions described above, file capabilities may be ignored (treated as empty) for the same reasons @@ -1231,7 +1231,7 @@ that the set-user-ID and set-group-ID bits are ignored; see File capabilities are similarly ignored if the kernel was booted with the .I no_file_caps option. -.PP +.P .IR Note : according to the rules above, if a process with nonzero user IDs performs an @@ -1259,7 +1259,7 @@ so that the file permitted capabilities are automatically enabled in the process effective set when executing the file. The kernel recognizes a file which has the effective capability bit set as capability-dumb for the purpose of the check described here. -.PP +.P When executing a capability-dumb binary, the kernel checks if the process obtained all permitted capabilities that were specified in the file permitted set, @@ -1288,7 +1288,7 @@ In order to mirror traditional UNIX semantics, the kernel performs special treatment of file capabilities when a process with UID 0 (root) executes a program and when a set-user-ID-root program is executed. -.PP +.P After having performed any changes to the process effective ID that were triggered by the set-user-ID mode bit of the binary\[em]e.g., switching the effective user ID to 0 (root) because @@ -1306,12 +1306,12 @@ below.) If the effective user ID of the process is 0 (root) or the file effective bit is in fact enabled, then the file effective bit is notionally defined to be one (enabled). -.PP +.P These notional values for the file's capability sets are then used as described above to calculate the transformation of the process's capabilities during .BR execve (2). -.PP +.P Thus, when a process with nonzero UIDs .BR execve (2)s a set-user-ID-root program that does not have capabilities attached, @@ -1319,7 +1319,7 @@ or when a process whose real and effective UIDs are zero .BR execve (2)s a program, the calculation of the process's new permitted capabilities simplifies to: -.PP +.P .in +4n .EX P'(permitted) = P(inheritable) | P(bounding) @@ -1327,14 +1327,14 @@ P'(permitted) = P(inheritable) | P(bounding) P'(effective) = P'(permitted) .EE .in -.PP +.P Consequently, the process gains all capabilities in its permitted and effective capability sets, except those masked out by the capability bounding set. (In the calculation of P'(permitted), the P'(ambient) term can be simplified away because it is by definition a proper subset of P(inheritable).) -.PP +.P The special treatments of user ID 0 (root) described in this subsection can be disabled using the securebits mechanism described below. .\" @@ -1358,7 +1358,7 @@ the process gains just the capabilities granted by the program (i.e., not all capabilities, as would occur when executing a set-user-ID-root program that does not have any associated file capabilities). -.PP +.P Note that one can assign empty capability sets to a program file, and thus it is possible to create a set-user-ID-root program that changes the effective and saved set-user-ID of the process @@ -1390,29 +1390,29 @@ and thereby cannot have this capability preserved in its permitted set when it .BR execve (2)s a file that has the capability in its inheritable set. -.PP +.P Note that the bounding set masks the file permitted capabilities, but not the inheritable capabilities. If a thread maintains a capability in its inheritable set that is not in its bounding set, then it can still gain that capability in its permitted set by executing a file that has the capability in its inheritable set. -.PP +.P Depending on the kernel version, the capability bounding set is either a system-wide attribute, or a per-process attribute. -.PP +.P .B "Capability bounding set from Linux 2.6.25 onward" -.PP +.P From Linux 2.6.25, the .I "capability bounding set" is a per-thread attribute. (The system-wide capability bounding set described below no longer exists.) -.PP +.P The bounding set is inherited at .BR fork (2) from the thread's parent, and is preserved across an .BR execve (2). -.PP +.P A thread may remove capabilities from its capability bounding set using the .BR prctl (2) .B PR_CAPBSET_DROP @@ -1425,7 +1425,7 @@ A thread can determine if a capability is in its bounding set using the .BR prctl (2) .B PR_CAPBSET_READ operation. -.PP +.P Removing capabilities from the bounding set is supported only if file capabilities are compiled into the kernel. Before Linux 2.6.33, @@ -1445,14 +1445,14 @@ begins with a full bounding set minus .BR CAP_SETPCAP , because this capability has a different meaning when there are no file capabilities. -.PP +.P Removing a capability from the bounding set does not remove it from the thread's inheritable set. However it does prevent the capability from being added back into the thread's inheritable set in the future. -.PP +.P .B "Capability bounding set prior to Linux 2.6.25" -.PP +.P Before Linux 2.6.25, the capability bounding set is a system-wide attribute that affects all threads on the system. The bounding set is accessible via the file @@ -1460,14 +1460,14 @@ The bounding set is accessible via the file (Confusingly, this bit mask parameter is expressed as a signed decimal number in .IR /proc/sys/kernel/cap\-bound .) -.PP +.P Only the .B init process may set capabilities in the capability bounding set; other than that, the superuser (more precisely: a process with the .B CAP_SYS_MODULE capability) may only clear capabilities from this set. -.PP +.P On a standard system the capability bounding set always masks out the .B CAP_SETPCAP capability. @@ -1476,7 +1476,7 @@ To remove this restriction (dangerous!), modify the definition of in .I include/linux/capability.h and rebuild the kernel. -.PP +.P The system-wide capability bounding set feature was added to Linux 2.2.11. .\" @@ -1521,7 +1521,7 @@ and If the filesystem UID is changed from nonzero to 0, then any of these capabilities that are enabled in the permitted set are enabled in the effective set. -.PP +.P If a thread that has a 0 value for one or more of its user IDs wants to prevent its permitted capability set being cleared when it resets all of its user IDs to nonzero values, it can do so using the @@ -1625,7 +1625,7 @@ Setting this flag disallows raising ambient capabilities via the .BR prctl (2) .B PR_CAP_AMBIENT_RAISE operation. -.PP +.P Each of the above "base" flags has a companion "locked" flag. Setting any of the "locked" flags is irreversible, and has the effect of preventing further changes to the @@ -1636,7 +1636,7 @@ The locked flags are: .BR SECBIT_NOROOT_LOCKED , and .BR SECBIT_NO_CAP_AMBIENT_RAISE_LOCKED . -.PP +.P The .I securebits flags can be modified and retrieved using the @@ -1653,7 +1653,7 @@ Note that the constants are available only after including the .I <linux/securebits.h> header file. -.PP +.P The .I securebits flags are inherited by child processes. @@ -1662,12 +1662,12 @@ During an all of the flags are preserved, except .B SECBIT_KEEP_CAPS which is always cleared. -.PP +.P An application can use the following call to lock itself, and all of its descendants, into an environment where the only way of gaining capabilities is by executing a program with associated file capabilities: -.PP +.P .in +4n .EX prctl(PR_SET_SECUREBITS, @@ -1683,13 +1683,13 @@ prctl(PR_SET_SECUREBITS, .in .\" .\" -.SS Per-user-namespace """set-user-ID-root""" programs +.SS Per-user-namespace \[dq]set-user-ID-root\[dq] programs A set-user-ID program whose UID matches the UID that created a user namespace will confer capabilities in the process's permitted and effective sets when executed by any process inside that namespace or any descendant user namespace. -.PP +.P The rules about the transformation of the process's capabilities during the .BR execve (2) are exactly as described in @@ -1710,7 +1710,7 @@ it gains the associated capabilities (within its user namespace) as per the rules described in .I Transformation of capabilities during execve() above. -.PP +.P Because version 2 file capabilities confer capabilities to the executing process regardless of which user namespace it resides in, only privileged processes are permitted to associate capabilities with a file. @@ -1723,7 +1723,7 @@ For example, in user-namespaced containers, it can be desirable to be able to create a binary that confers capabilities only to processes executed inside that container, but not to processes that are executed outside the container. -.PP +.P Linux 4.14 added so-called namespaced file capabilities to support such use cases. Namespaced file capabilities are recorded as version 3 (i.e., @@ -1739,7 +1739,7 @@ When a version 3 extended attribute is created, the kernel records not just the capability masks in the extended attribute, but also the namespace root user ID. -.PP +.P As with a binary that has .B VFS_CAP_REVISION_2 file capabilities, a binary with @@ -1770,13 +1770,13 @@ you may find the .I \-u <username> option useful. Something like: -.PP +.P .in +4n .EX $ \fBsudo strace \-o trace.log \-u ceci ./myprivprog\fP .EE .in -.PP +.P From Linux 2.5.27 to Linux 2.6.26, .\" commit 5915eb53861c5776cfec33ca4fcc1fd20d66dd27 removed .\" CONFIG_SECURITY_CAPABILITIES @@ -1784,7 +1784,7 @@ capabilities were an optional kernel component, and could be enabled/disabled via the .B CONFIG_SECURITY_CAPABILITIES kernel configuration option. -.PP +.P The .IR /proc/ pid /task/TID/status file can be used to view the capability sets of a thread. @@ -1798,7 +1798,7 @@ Since Linux 3.8, all nonexistent capabilities (above .BR CAP_LAST_CAP ) are shown as disabled (0). -.PP +.P The .I libcap package provides a suite of routines for setting and @@ -1816,7 +1816,7 @@ It can be found at .br .UR https://git.kernel.org\:/pub\:/scm\:/libs\:/libcap\:/libcap.git\:/refs/ .UE . -.PP +.P Before Linux 2.6.24, and from Linux 2.6.24 to Linux 2.6.32 if file capabilities are not enabled, a thread with the .B CAP_SETPCAP @@ -1867,6 +1867,6 @@ created on the system. .BR netcap (8), \" from libcap-ng .BR pscap (8), \" from libcap-ng .BR setcap (8) -.PP +.P .I include/linux/capability.h in the Linux kernel source tree diff --git a/upstream/debian-unstable/man7/cgroup_namespaces.7 b/upstream/debian-unstable/man7/cgroup_namespaces.7 index c1162fe5..29ef09a9 100644 --- a/upstream/debian-unstable/man7/cgroup_namespaces.7 +++ b/upstream/debian-unstable/man7/cgroup_namespaces.7 @@ -3,20 +3,20 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH cgroup_namespaces 7 2023-03-30 "Linux man-pages 6.05.01" +.TH cgroup_namespaces 7 2024-05-02 "Linux man-pages 6.8" .SH NAME cgroup_namespaces \- overview of Linux cgroup namespaces .SH DESCRIPTION For an overview of namespaces, see .BR namespaces (7). -.PP +.P Cgroup namespaces virtualize the view of a process's cgroups (see .BR cgroups (7)) as seen via .IR /proc/ pid /cgroup and .IR /proc/ pid /mountinfo . -.PP +.P Each cgroup namespace has its own set of cgroup root directories. These root directories are the base points for the relative locations displayed in the corresponding records in the @@ -33,7 +33,7 @@ cgroups directories become the cgroup root directories of the new namespace. (This applies both for the cgroups version 1 hierarchies and the cgroups version 2 unified hierarchy.) -.PP +.P When reading the cgroup memberships of a "target" process from .IR /proc/ pid /cgroup , the pathname shown in the third field of each record will be @@ -44,16 +44,16 @@ the root directory of the reading process's cgroup namespace, then the pathname will show .I ../ entries for each ancestor level in the cgroup hierarchy. -.PP +.P The following shell session demonstrates the effect of creating a new cgroup namespace. -.PP +.P First, (as superuser) in a shell in the initial cgroup namespace, we create a child cgroup in the .I freezer hierarchy, and place a process in that cgroup that we will use as part of the demonstration below: -.PP +.P .in +4n .EX # \fBmkdir \-p /sys/fs/cgroup/freezer/sub2\fP @@ -62,11 +62,11 @@ use as part of the demonstration below: # \fBecho 20124 > /sys/fs/cgroup/freezer/sub2/cgroup.procs\fP .EE .in -.PP +.P We then create another child cgroup in the .I freezer hierarchy and put the shell into that cgroup: -.PP +.P .in +4n .EX # \fBmkdir \-p /sys/fs/cgroup/freezer/sub\fP @@ -77,17 +77,17 @@ hierarchy and put the shell into that cgroup: 7:freezer:/sub .EE .in -.PP +.P Next, we use .BR unshare (1) to create a process running a new shell in new cgroup and mount namespaces: -.PP +.P .in +4n .EX # \fBPS1="sh2# " unshare \-Cm bash\fP .EE .in -.PP +.P From the new shell started by .BR unshare (1), we then inspect the @@ -97,7 +97,7 @@ a process that is in the initial cgroup namespace .RI ( init , with PID 1), and the process in the sibling cgroup .RI ( sub2 ): -.PP +.P .in +4n .EX sh2# \fBcat /proc/self/cgroup | grep freezer\fP @@ -108,7 +108,7 @@ sh2# \fBcat /proc/20124/cgroup | grep freezer\fP 7:freezer:/../sub2 .EE .in -.PP +.P From the output of the first command, we see that the freezer cgroup membership of the new shell (which is in the same cgroup as the initial shell) @@ -122,18 +122,18 @@ and the root directory of the freezer cgroup hierarchy in the new cgroup namespace is also .IR /sub . Thus, the new shell's cgroup membership is displayed as \[aq]/\[aq].) -.PP +.P However, when we look in .I /proc/self/mountinfo we see the following anomaly: -.PP +.P .in +4n .EX sh2# \fBcat /proc/self/mountinfo | grep freezer\fP 155 145 0:32 /.. /sys/fs/cgroup/freezer ... .EE .in -.PP +.P The fourth field of this line .RI ( /.. ) should show the @@ -148,7 +148,7 @@ filesystem corresponding to the initial cgroup namespace To fix this problem, we must remount the freezer cgroup filesystem from the new shell (i.e., perform the mount from a process that is in the new cgroup namespace), after which we see the expected results: -.PP +.P .in +4n .EX sh2# \fBmount \-\-make\-rslave /\fP # Don\[aq]t propagate mount events @@ -166,7 +166,7 @@ Linux. Use of cgroup namespaces requires a kernel that is configured with the .B CONFIG_CGROUPS option. -.PP +.P The virtualization provided by cgroup namespaces serves a number of purposes: .IP \[bu] 3 It prevents information leaks whereby cgroup directory paths outside of diff --git a/upstream/debian-unstable/man7/cgroups.7 b/upstream/debian-unstable/man7/cgroups.7 index c070ca74..3ddb9cab 100644 --- a/upstream/debian-unstable/man7/cgroups.7 +++ b/upstream/debian-unstable/man7/cgroups.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH cgroups 7 2023-04-03 "Linux man-pages 6.05.01" +.TH cgroups 7 2024-05-02 "Linux man-pages 6.8" .SH NAME cgroups \- Linux control groups .SH DESCRIPTION @@ -22,7 +22,7 @@ A .I cgroup is a collection of processes that are bound to a set of limits or parameters defined via the cgroup filesystem. -.PP +.P A .I subsystem is a kernel component that modifies the behavior of @@ -34,7 +34,7 @@ and freezing and resuming execution of the processes in a cgroup. Subsystems are sometimes also known as .I resource controllers (or simply, controllers). -.PP +.P The cgroups for a controller are arranged in a .IR hierarchy . This hierarchy is defined by creating, removing, and @@ -60,7 +60,7 @@ source file (or .I Documentation/cgroup\-v2.txt in Linux 4.17 and earlier). -.PP +.P Because of the problems with the initial cgroups implementation (cgroups version 1), starting in Linux 3.10, work began on a new, @@ -74,7 +74,7 @@ The file .IR cgroup.sane_behavior , present in cgroups v1, is a relic of this mount option. The file always reports "0" and is only retained for backward compatibility. -.PP +.P Although cgroups v2 is intended as a replacement for cgroups v1, the older system continues to exist (and for compatibility reasons is unlikely to be removed). @@ -96,7 +96,7 @@ processes on the system. It is also possible to comount multiple (or even all) cgroups v1 controllers against the same cgroup filesystem, meaning that the comounted controllers manage the same hierarchical organization of processes. -.PP +.P For each mounted hierarchy, the directory tree mirrors the control group hierarchy. Each control group is represented by a directory, with each of its child @@ -123,7 +123,7 @@ In this view, a process can consist of multiple tasks and called such in the remainder of this man page). In cgroups v1, it is possible to independently manipulate the cgroup memberships of the threads in a process. -.PP +.P The cgroups v1 ability to split threads across different cgroups caused problems in some cases. For example, it made no sense for the @@ -142,7 +142,7 @@ The use of cgroups requires a kernel built with the option. In addition, each of the v1 controllers has an associated configuration option that must be set in order to employ that controller. -.PP +.P In order to use a v1 controller, it must be mounted against a cgroup filesystem. The usual place for such mounts is under a @@ -152,26 +152,26 @@ filesystem mounted at Thus, one might mount the .I cpu controller as follows: -.PP +.P .in +4n .EX mount \-t cgroup \-o cpu none /sys/fs/cgroup/cpu .EE .in -.PP +.P It is possible to comount multiple controllers against the same hierarchy. For example, here the .I cpu and .I cpuacct controllers are comounted against a single hierarchy: -.PP +.P .in +4n .EX mount \-t cgroup \-o cpu,cpuacct none /sys/fs/cgroup/cpu,cpuacct .EE .in -.PP +.P Comounting controllers has the effect that a process is in the same cgroup for all of the comounted controllers. Separately mounting controllers allows a process to @@ -180,19 +180,19 @@ be in cgroup for one controller while being in .I /foo2/foo3 for another. -.PP +.P It is possible to comount all v1 controllers against the same hierarchy: -.PP +.P .in +4n .EX mount \-t cgroup \-o all cgroup /sys/fs/cgroup .EE .in -.PP +.P (One can achieve the same result by omitting .IR "\-o all" , since it is the default if no controllers are explicitly specified.) -.PP +.P It is not possible to mount the same controller against multiple cgroup hierarchies. For example, it is not possible to mount both the @@ -206,7 +206,7 @@ It is possible to create multiple mount with exactly the same set of comounted controllers. However, in this case all that results is multiple mount points providing a view of the same hierarchy. -.PP +.P Note that on many systems, the v1 controllers are automatically mounted under .IR /sys/fs/cgroup ; in particular, @@ -217,13 +217,13 @@ automatically creates such mounts. A mounted cgroup filesystem can be unmounted using the .BR umount (8) command, as in the following example: -.PP +.P .in +4n .EX umount /sys/fs/cgroup/pids .EE .in -.PP +.P .IR "But note well" : a cgroup filesystem is unmounted only if it is not busy, that is, it has no child cgroups. @@ -409,41 +409,41 @@ in Linux 5.2 and earlier). A cgroup filesystem initially contains a single root cgroup, '/', which all processes belong to. A new cgroup is created by creating a directory in the cgroup filesystem: -.PP +.P .in +4n .EX mkdir /sys/fs/cgroup/cpu/cg1 .EE .in -.PP +.P This creates a new empty cgroup. -.PP +.P A process may be moved to this cgroup by writing its PID into the cgroup's .I cgroup.procs file: -.PP +.P .in +4n .EX echo $$ > /sys/fs/cgroup/cpu/cg1/cgroup.procs .EE .in -.PP +.P Only one PID at a time should be written to this file. -.PP +.P Writing the value 0 to a .I cgroup.procs file causes the writing process to be moved to the corresponding cgroup. -.PP +.P When writing a PID into the .IR cgroup.procs , all threads in the process are moved into the new cgroup at once. -.PP +.P Within a hierarchy, a process can be a member of exactly one cgroup. Writing a process's PID to a .I cgroup.procs file automatically removes it from the cgroup of which it was previously a member. -.PP +.P The .I cgroup.procs file can be read to obtain a list of the processes that are @@ -451,7 +451,7 @@ members of a cgroup. The returned list of PIDs is not guaranteed to be in order. Nor is it guaranteed to be free of duplicates. (For example, a PID may be recycled while reading from the list.) -.PP +.P In cgroups v1, an individual thread can be moved to another cgroup by writing its thread ID (i.e., the kernel thread ID returned by @@ -477,7 +477,7 @@ Two files can be used to determine whether the kernel provides notifications when a cgroup becomes empty. A cgroup is considered to be empty when it contains no child cgroups and no member processes. -.PP +.P A special file in the root directory of each cgroup hierarchy, .IR release_agent , can be used to register the pathname of a program that may be invoked when @@ -490,22 +490,22 @@ The .I release_agent program might remove the cgroup directory, or perhaps repopulate it with a process. -.PP +.P The default value of the .I release_agent file is empty, meaning that no release agent is invoked. -.PP +.P The content of the .I release_agent file can also be specified via a mount option when the cgroup filesystem is mounted: -.PP +.P .in +4n .EX mount \-o release_agent=pathname ... .EE .in -.PP +.P Whether or not the .I release_agent program is invoked when a particular cgroup becomes empty is determined @@ -526,13 +526,13 @@ in the parent cgroup. .SS Cgroup v1 named hierarchies In cgroups v1, it is possible to mount a cgroup hierarchy that has no attached controllers: -.PP +.P .in +4n .EX mount \-t cgroup \-o none,name=somename none /some/mount/point .EE .in -.PP +.P Multiple instances of such hierarchies can be mounted; each hierarchy must have a unique name. The only purpose of such hierarchies is to track processes. @@ -542,7 +542,7 @@ An example of this is the cgroup hierarchy that is used by .BR systemd (1) to track services and user sessions. -.PP +.P Since Linux 5.0, the .I cgroup_no_v1 kernel boot option (described below) can be used to disable cgroup v1 @@ -556,7 +556,7 @@ While (different) controllers may be simultaneously mounted under the v1 and v2 hierarchies, it is not possible to mount the same controller simultaneously under both the v1 and the v2 hierarchies. -.PP +.P The new behaviors in cgroups v2 are summarized here, and in some cases elaborated in the following subsections. .IP \[bu] 3 @@ -585,7 +585,7 @@ controller has been removed. An improved mechanism for notification of empty cgroups is provided by the .I cgroup.events file. -.PP +.P For more changes, see the .I Documentation/admin\-guide/cgroup\-v2.rst file in the kernel source @@ -593,7 +593,7 @@ file in the kernel source .I Documentation/cgroup\-v2.txt in Linux 4.17 and earlier). . -.PP +.P Some of the new behaviors listed above saw subsequent modification with the addition in Linux 4.14 of "thread mode" (described below). .\" @@ -609,13 +609,13 @@ all available controllers are mounted against a single hierarchy. The available controllers are automatically mounted, meaning that it is not necessary (or possible) to specify the controllers when mounting the cgroup v2 filesystem using a command such as the following: -.PP +.P .in +4n .EX mount \-t cgroup2 none /mnt/cgroup2 .EE .in -.PP +.P A cgroup v2 controller is available only if it is not currently in use via a mount against a cgroup v1 hierarchy. Or, to put things another way, it is not possible to employ @@ -638,7 +638,7 @@ to disable all v1 controllers. (This situation is correctly handled by .BR systemd (1), which falls back to operating without the specified controllers.) -.PP +.P Note that on many modern systems, .BR systemd (1) automatically mounts the @@ -726,7 +726,7 @@ controller. This is the same as the version 1 .I rdma controller. -.PP +.P There is no direct equivalent of the .I net_cls and @@ -736,7 +736,7 @@ Instead, support has been added to .BR iptables (8) to allow eBPF filters that hook on cgroup v2 pathnames to make decisions about network traffic on a per-cgroup basis. -.PP +.P The v2 .I devices controller provides no interface files; @@ -782,14 +782,14 @@ leads to an error when writing to the .I cgroup.subtree_control file. -.PP +.P Because the list of controllers in .I cgroup.subtree_control is a subset of those .IR cgroup.controllers , a controller that has been disabled in one cgroup in the hierarchy can never be re-enabled in the subtree below that cgroup. -.PP +.P A cgroup's .I cgroup.subtree_control file determines the set of controllers that are exercised in the @@ -805,14 +805,14 @@ then the corresponding controller-interface files (e.g., are automatically created in the children of that cgroup and can be used to exert resource control in the child cgroups. .\" -.SS Cgroups v2 """no internal processes""" rule +.SS Cgroups v2 \[dq]no internal processes\[dq] rule Cgroups v2 enforces a so-called "no internal processes" rule. Roughly speaking, this rule means that, with the exception of the root cgroup, processes may reside only in leaf nodes (cgroups that do not themselves contain child cgroups). This avoids the need to decide how to partition resources between processes which are members of cgroup A and processes in child cgroups of A. -.PP +.P For instance, if cgroup .I /cg1/cg2 exists, then a process may reside in @@ -836,7 +836,7 @@ the relationship between processes in and .IR /cg1 's other children. -.PP +.P The "no internal processes" rule is in fact more subtle than stated above. More precisely, the rule is that a (nonroot) cgroup can't both (1) have member processes, and @@ -849,7 +849,7 @@ possible for a cgroup to have both member processes and child cgroups, but before controllers can be enabled for that cgroup, the member processes must be moved out of the cgroup (e.g., perhaps into the child cgroups). -.PP +.P With the Linux 4.14 addition of "thread mode" (described below), the "no internal processes" rule has been relaxed in some cases. .\" @@ -859,7 +859,7 @@ Each nonroot cgroup in the v2 hierarchy contains a read-only file, whose contents are key-value pairs (delimited by newline characters, with the key and value separated by spaces) providing state information about the cgroup: -.PP +.P .in +4n .EX $ \fBcat mygrp/cgroup.events\fP @@ -867,7 +867,7 @@ populated 1 frozen 0 .EE .in -.PP +.P The following keys may appear in this file: .TP .I populated @@ -879,7 +879,7 @@ or otherwise 0. .\" commit 76f969e8948d82e78e1bc4beb6b9465908e7487 The value of this key is 1 if this cgroup is currently frozen, or 0 if it is not. -.PP +.P The .I cgroup.events file can be monitored, in order to receive notification when the value of @@ -915,7 +915,7 @@ meaning that the cgroup (and its descendants) contain no (nonzombie) member processes, or 1, meaning that the cgroup (or one of its descendants) contains member processes. -.PP +.P The cgroups v2 release-notification mechanism offers the following advantages over the cgroups v1 .I release_agent @@ -974,10 +974,10 @@ fails with the error .BR EAGAIN ). .IP Writing the string -.I """max""" +.I \[dq]max\[dq] to this file means that no limit is imposed. The default value in this file is -.I """max""" . +.IR \[dq]max\[dq] . .TP .IR cgroup.max.descendants " (since Linux 4.14)" .\" commit 1a926e0bbab83bae8207d05a533173425e0496d1 @@ -989,10 +989,10 @@ fails with the error .BR EAGAIN ). .IP Writing the string -.I """max""" +.I \[dq]max\[dq] to this file means that no limit is imposed. The default value in this file is -.IR """max""" . +.IR \[dq]max\[dq] . .\" .SH CGROUPS DELEGATION: DELEGATING A HIERARCHY TO A LESS PRIVILEGED USER In the context of cgroups, @@ -1004,7 +1004,7 @@ in the cgroup hierarchy but with less strict containment rules than v2 Cgroups v2 supports delegation with containment by explicit design. The focus of the discussion in this section is on delegation in cgroups v2, with some differences for cgroups v1 noted along the way. -.PP +.P Some terminology is required in order to describe delegation. A .I delegater @@ -1015,7 +1015,7 @@ is a nonprivileged user who will be granted the permissions needed to manage some subhierarchy under that parent cgroup, known as the .IR "delegated subtree" . -.PP +.P To perform delegation, the delegater makes certain directories and files writable by the delegatee, typically by changing the ownership of the objects to be the user ID @@ -1056,7 +1056,7 @@ file.) In cgroups v1, the corresponding file that should instead be delegated is the .I tasks file. -.PP +.P The delegater should .I not change the ownership of any of the controller interfaces files (e.g., @@ -1068,11 +1068,11 @@ Those files are used from the next level above the delegated subtree in order to distribute resources into the subtree, and the delegatee should not have permission to change the resources that are distributed into the delegated subtree. -.PP +.P See also the discussion of the .I /sys/kernel/cgroup/delegate file in NOTES for information about further delegatable files in cgroups v2. -.PP +.P After the aforementioned steps have been performed, the delegatee can create child cgroups within the delegated subtree (the cgroup subdirectories and the files they contain @@ -1095,7 +1095,7 @@ For example, if the cgroup v2 filesystem has already been mounted, we can remount it with the .I nsdelegate option as follows: -.PP +.P .in +4n .EX mount \-t cgroup2 \-o remount,nsdelegate \e @@ -1109,7 +1109,7 @@ mount \-t cgroup2 \-o remount,nsdelegate \e .\" .\" The effect of the latter option is to prevent systemd from employing .\" its "hybrid" cgroup mode, where it tries to make use of cgroups v2. -.PP +.P The effect of this mount option is to cause cgroup namespaces to automatically become delegation boundaries. More specifically, @@ -1133,7 +1133,7 @@ Processes inside the cgroup namespace can still move processes between cgroups .I within the subhierarchy under the namespace root. -.PP +.P The ability to define cgroup namespaces as delegation boundaries makes cgroup namespaces more useful. To understand why, suppose that we already have one cgroup hierarchy @@ -1163,17 +1163,17 @@ a process inside the child cgroup should not be allowed to modify them.) A process inside the inferior hierarchy could move processes into and out of the inferior hierarchy if the cgroups in the superior hierarchy were somehow visible. -.PP +.P Employing the .I nsdelegate mount option prevents both of these possibilities. -.PP +.P The .I nsdelegate mount option only has an effect when performed in the initial mount namespace; in other mount namespaces, the option is silently ignored. -.PP +.P .IR Note : On some systems, .BR systemd (1) @@ -1182,13 +1182,13 @@ In order to experiment with the .I nsdelegate operation, it may be useful to boot the kernel with the following command-line options: -.PP +.P .in +4n .EX cgroup_no_v1=all systemd.legacy_systemd_cgroup_controller .EE .in -.PP +.P These options cause the kernel to boot with the cgroups v1 controllers disabled (meaning that the controllers are available in the v2 hierarchy), and tells @@ -1237,7 +1237,7 @@ this requirement also applied in cgroups v2 (This was a historical requirement inherited from cgroups v1 that was later deemed unnecessary, since the other rules suffice for containment in cgroups v2.) -.PP +.P .IR Note : one consequence of these delegation containment rules is that the unprivileged delegatee can't place the first process into @@ -1255,7 +1255,7 @@ all of the threads of a process must be in the same cgroup. .IR "No internal processes" : a cgroup can't both have member processes and exercise controllers on child cgroups. -.PP +.P Both of these restrictions were added because the lack of these restrictions had caused problems in cgroups v1. @@ -1267,7 +1267,7 @@ controller: since threads share an address space, it made no sense to split threads across different .I memory cgroups.) -.PP +.P Notwithstanding the initial design decision in cgroups v2, there were use cases for certain controllers, notably the .I cpu @@ -1276,7 +1276,7 @@ for which thread-level granularity of control was meaningful and useful. To accommodate such use cases, Linux 4.14 added .I "thread mode" for cgroups v2. -.PP +.P Thread mode allows the following: .IP \[bu] 3 The creation of @@ -1293,7 +1293,7 @@ A relaxation of the "no internal processes rule", so that, within a threaded subtree, a cgroup can both contain member threads and exercise resource control over child cgroups. -.PP +.P With the addition of thread mode, each nonroot cgroup now contains a new file, .IR cgroup.type , @@ -1327,7 +1327,7 @@ The only thing that can be done with this cgroup (other than deleting it) is to convert it to a .I threaded cgroup by writing the string -.I """threaded""" +.I \[dq]threaded\[dq] to the .I cgroup.type file. @@ -1369,7 +1369,7 @@ There are two pathways that lead to the creation of a threaded subtree. The first pathway proceeds as follows: .IP (1) 5 We write the string -.I """threaded""" +.I \[dq]threaded\[dq] to the .I cgroup.type file of a cgroup @@ -1406,7 +1406,7 @@ will also have the type .RE .IP (2) We write the string -.I """threaded""" +.I \[dq]threaded\[dq] to each of the .I domain invalid cgroups under @@ -1418,10 +1418,10 @@ now have the type .I threaded and the threaded subtree is now fully usable. The requirement to write -.I """threaded""" +.I \[dq]threaded\[dq] to each of these cgroups is somewhat cumbersome, but allows for possible future extensions to the thread-mode model. -.PP +.P The second way of creating a threaded subtree is as follows: .IP (1) 5 In an existing cgroup, @@ -1441,7 +1441,7 @@ becomes .IR "domain threaded" . .IP \[bu] All of the descendant cgroups of -.I x +.I z that were not already of type .I threaded are converted to type @@ -1449,14 +1449,14 @@ are converted to type .RE .IP (2) As before, we make the threaded subtree usable by writing the string -.I """threaded""" +.I \[dq]threaded\[dq] to each of the .I domain invalid cgroups under -.IR y , +.IR z , in order to convert them to the type .IR threaded . -.PP +.P One of the consequences of the above pathways to creating a threaded subtree is that the threaded root cgroup can be a parent only to .I threaded @@ -1478,7 +1478,7 @@ in each subgroup whose type has been changed to .IR threaded ; upon doing so, the corresponding controller interface files appear in the children of that cgroup. -.PP +.P A process can be moved into a threaded subtree by writing its PID to the .I cgroup.procs file in one of the cgroups inside the tree. @@ -1492,7 +1492,7 @@ to the .I cgroup.threads files in different cgroups inside the subtree. The threads of a process must all reside in the same threaded subtree. -.PP +.P As with writing to .IR cgroup.procs , some containment rules apply when writing to the @@ -1517,7 +1517,7 @@ file in a different .I domain cgroup fails with the error .BR EOPNOTSUPP .) -.PP +.P The .I cgroup.threads file is present in each cgroup (including @@ -1526,7 +1526,7 @@ cgroups) and can be read in order to discover the set of threads that is present in the cgroup. The set of thread IDs obtained when reading this file is not guaranteed to be ordered or free of duplicates. -.PP +.P The .I cgroup.procs file in the threaded root shows the PIDs of all processes @@ -1534,7 +1534,7 @@ that are members of the threaded subtree. The .I cgroup.procs files in the other cgroups in the subtree are not readable. -.PP +.P Domain controllers can't be enabled in a threaded subtree; no controller-interface files appear inside the cgroups underneath the threaded root. @@ -1542,7 +1542,7 @@ From the point of view of a domain controller, threaded subtrees are invisible: a multithreaded process inside a threaded subtree appears to a domain controller as a process that resides in the threaded root cgroup. -.PP +.P Within a threaded subtree, the "no internal processes" rule does not apply: a cgroup can both contain member processes (or thread) and exercise controllers on child cgroups. @@ -1553,7 +1553,7 @@ A number of rules apply when writing to the file: .IP \[bu] 3 Only the string -.I """threaded""" +.I \[dq]threaded\[dq] may be written. In other words, the only explicit transition that is possible is to convert a .I domain @@ -1561,7 +1561,7 @@ cgroup to type .IR threaded . .IP \[bu] The effect of writing -.I """threaded""" +.I \[dq]threaded\[dq] depends on the current value in .IR cgroup.type , as follows: @@ -1590,7 +1590,7 @@ file if the parent's type is In other words, the cgroups of a threaded subtree must be converted to the .I threaded state in a top-down manner. -.PP +.P There are also some constraints that must be satisfied in order to create a threaded subtree rooted at the cgroup .IR x : @@ -1605,27 +1605,27 @@ No domain controllers may be enabled in .IR x 's .I cgroup.subtree_control file. -.PP +.P If any of the above constraints is violated, then an attempt to write -.I """threaded""" +.I \[dq]threaded\[dq] to a .I cgroup.type file fails with the error .BR ENOTSUP . .\" -.SS The """domain threaded""" cgroup type +.SS The \[dq]domain threaded\[dq] cgroup type According to the pathways described above, the type of a cgroup can change to .I domain threaded in either of the following cases: .IP \[bu] 3 The string -.I """threaded""" +.I \[dq]threaded\[dq] is written to a child cgroup. .IP \[bu] A threaded controller is enabled inside the cgroup and a process is made a member of the cgroup. -.PP +.P A .I domain threaded cgroup, @@ -1640,7 +1640,7 @@ are removed and either .I x no longer has threaded controllers enabled or no longer has member processes. -.PP +.P When a .I domain threaded cgroup @@ -1666,7 +1666,7 @@ and .I threaded cgroups. If the string -.I """threaded""" +.I \[dq]threaded\[dq] is written to the .I cgroup.type file of one of the children of the root cgroup, then @@ -1677,20 +1677,20 @@ The type of that cgroup becomes The type of any descendants of that cgroup that are not part of lower-level threaded subtrees changes to .IR "domain invalid" . -.PP +.P Note that in this case, there is no cgroup whose type becomes .IR "domain threaded" . (Notionally, the root cgroup can be considered as the threaded root for the cgroup whose type was changed to .IR threaded .) -.PP +.P The aim of this exceptional treatment for the root cgroup is to allow a threaded cgroup that employs the .I cpu controller to be placed as high as possible in the hierarchy, so as to minimize the (small) cost of traversing the cgroup hierarchy. .\" -.SS The cgroups v2 """cpu""" controller and realtime threads +.SS The cgroups v2 \[dq]cpu\[dq] controller and realtime threads As at Linux 4.19, the cgroups v2 .I cpu controller does not support control of realtime threads @@ -1708,12 +1708,12 @@ if all realtime threads are in the root cgroup. (If there are realtime threads in nonroot cgroups, then a .BR write (2) of the string -.I """+cpu""" +.I \[dq]+cpu\[dq] to the .I cgroup.subtree_control file fails with the error .BR EINVAL .) -.PP +.P On some systems, .BR systemd (1) places certain realtime threads in nonroot cgroups in the v2 hierarchy. @@ -1737,7 +1737,7 @@ A child process created via inherits its parent's cgroup memberships. A process's cgroup memberships are preserved across .BR execve (2). -.PP +.P The .BR clone3 (2) .B CLONE_INTO_CGROUP @@ -1909,6 +1909,6 @@ mount option. .BR namespaces (7), .BR sched (7), .BR user_namespaces (7) -.PP +.P The kernel source file .IR Documentation/admin\-guide/cgroup\-v2.rst . diff --git a/upstream/debian-unstable/man7/charsets.7 b/upstream/debian-unstable/man7/charsets.7 index 0692d8d8..d1e762b8 100644 --- a/upstream/debian-unstable/man7/charsets.7 +++ b/upstream/debian-unstable/man7/charsets.7 @@ -8,7 +8,7 @@ .\" .\" Changes also by David Starner <dstarner98@aasaa.ofe.org>. .\" -.TH charsets 7 2023-03-12 "Linux man-pages 6.05.01" +.TH charsets 7 2024-05-02 "Linux man-pages 6.8" .SH NAME charsets \- character set standards and internationalization .SH DESCRIPTION @@ -16,10 +16,10 @@ This manual page gives an overview on different character set standards and how they were used on Linux before Unicode became ubiquitous. Some of this information is still helpful for people working with legacy systems and documents. -.PP +.P Standards discussed include such as -ASCII, GB 2312, ISO 8859, JIS, KOI8-R, KS, and Unicode. -.PP +ASCII, GB 2312, ISO/IEC\~8859, JIS, KOI8-R, KS, and Unicode. +.P The primary emphasis is on character sets that were actually used by locale character sets, not the myriad others that could be found in data from other systems. @@ -27,9 +27,9 @@ from other systems. ASCII (American Standard Code For Information Interchange) is the original 7-bit character set, originally designed for American English. Also known as US-ASCII. -It is currently described by the ISO 646:1991 IRV +It is currently described by the ISO/IEC\~646:1991 IRV (International Reference Version) standard. -.PP +.P Various ASCII variants replacing the dollar sign with other currency symbols and replacing punctuation with non-English alphabetic characters to cover German, French, Spanish, and others in 7 bits @@ -37,30 +37,30 @@ emerged. All are deprecated; glibc does not support locales whose character sets are not true supersets of ASCII. -.PP +.P As Unicode, when using UTF-8, is ASCII-compatible, plain ASCII text still renders properly on modern UTF-8 using systems. -.SS ISO 8859 -ISO 8859 is a series of 15 8-bit character sets, all of which have ASCII +.SS ISO/IEC\~8859 +ISO/IEC\~8859 is a series of 15 8-bit character sets, all of which have ASCII in their low (7-bit) half, invisible control characters in positions 128 to 159, and 96 fixed-width graphics in positions 160\[en]255. -.PP -Of these, the most important is ISO 8859-1 +.P +Of these, the most important is ISO/IEC\~8859-1 ("Latin Alphabet No. 1" / Latin-1). It was widely adopted and supported by different systems, and is gradually being replaced with Unicode. -The ISO 8859-1 characters are also the first 256 characters of Unicode. -.PP -Console support for the other 8859 character sets is available under +The ISO/IEC\~8859-1 characters are also the first 256 characters of Unicode. +.P +Console support for the other ISO/IEC\~8859 character sets is available under Linux through user-mode utilities (such as .BR setfont (8)) that modify keyboard bindings and the EGA graphics table and employ the "user mapping" font table in the console driver. -.PP +.P Here are brief descriptions of each character set: .TP -8859-1 (Latin-1) +ISO/IEC\~8859-1 (Latin-1) Latin-1 covers many European languages such as Albanian, Basque, Danish, English, Faroese, Galician, Icelandic, Irish, Italian, Norwegian, Portuguese, Spanish, and Swedish. @@ -70,81 +70,81 @@ French œ, and „German“ quotation marks was considered tolerable. .TP -8859-2 (Latin-2) +ISO/IEC\~8859-2 (Latin-2) Latin-2 supports many Latin-written Central and East European languages such as Bosnian, Croatian, Czech, German, Hungarian, Polish, Slovak, and Slovene. Replacing Romanian ș/ț with ş/ţ was considered tolerable. .TP -8859-3 (Latin-3) +ISO/IEC\~8859-3 (Latin-3) Latin-3 was designed to cover of Esperanto, Maltese, and Turkish, but -8859-9 later superseded it for Turkish. +ISO/IEC\~8859-9 later superseded it for Turkish. .TP -8859-4 (Latin-4) +ISO/IEC\~8859-4 (Latin-4) Latin-4 introduced letters for North European languages such as -Estonian, Latvian, and Lithuanian, but was superseded by 8859-10 and -8859-13. +Estonian, Latvian, and Lithuanian, but was superseded by ISO/IEC\~8859-10 and +ISO/IEC\~8859-13. .TP -8859-5 +ISO/IEC\~8859-5 Cyrillic letters supporting Bulgarian, Byelorussian, Macedonian, Russian, Serbian, and (almost completely) Ukrainian. It was never widely used, see the discussion of KOI8-R/KOI8-U below. .TP -8859-6 +ISO/IEC\~8859-6 Was created for Arabic. -The 8859-6 glyph table is a fixed font of separate +The ISO/IEC\~8859-6 glyph table is a fixed font of separate letter forms, but a proper display engine should combine these using the proper initial, medial, and final forms. .TP -8859-7 +ISO/IEC\~8859-7 Was created for Modern Greek in 1987, updated in 2003. .TP -8859-8 +ISO/IEC\~8859-8 Supports Modern Hebrew without niqud (punctuation signs). Niqud and full-fledged Biblical Hebrew were outside the scope of this character set. .TP -8859-9 (Latin-5) +ISO/IEC\~8859-9 (Latin-5) This is a variant of Latin-1 that replaces Icelandic letters with Turkish ones. .TP -8859-10 (Latin-6) +ISO/IEC\~8859-10 (Latin-6) Latin-6 added the Inuit (Greenlandic) and Sami (Lappish) letters that were missing in Latin-4 to cover the entire Nordic area. .TP -8859-11 +ISO/IEC\~8859-11 Supports the Thai alphabet and is nearly identical to the TIS-620 standard. .TP -8859-12 +ISO/IEC\~8859-12 This character set does not exist. .TP -8859-13 (Latin-7) +ISO/IEC\~8859-13 (Latin-7) Supports the Baltic Rim languages; in particular, it includes Latvian characters not found in Latin-4. .TP -8859-14 (Latin-8) +ISO/IEC\~8859-14 (Latin-8) This is the Celtic character set, covering Old Irish, Manx, Gaelic, Welsh, Cornish, and Breton. .TP -8859-15 (Latin-9) +ISO/IEC\~8859-15 (Latin-9) Latin-9 is similar to the widely used Latin-1 but replaces some less common symbols with the Euro sign and French and Finnish letters that were missing in Latin-1. .TP -8859-16 (Latin-10) +ISO/IEC\~8859-16 (Latin-10) This character set covers many Southeast European languages, and most importantly supports Romanian more completely than Latin-2. .SS KOI8-R / KOI8-U KOI8-R is a non-ISO character set popular in Russia before Unicode. The lower half is ASCII; the upper is a Cyrillic character set somewhat better designed than -ISO 8859-5. +ISO/IEC\~8859-5. KOI8-U, based on KOI8-R, has better support for Ukrainian. -Neither of these sets are ISO-2022 compatible, -unlike the ISO 8859 series. -.PP +Neither of these sets are ISO/IEC\~2022 compatible, +unlike the ISO/IEC\~8859 series. +.P Console support for KOI8-R is available under Linux through user-mode utilities that modify keyboard bindings and the EGA graphics table, and employ the "user mapping" font table in the console driver. @@ -165,7 +165,7 @@ It is a superset of ASCII. Non-ASCII characters are expressed in two bytes. Bytes 0xa1\[en]0xfe are used as leading bytes for two-byte characters. Big5 and its extension were widely used in Taiwan and Hong Kong. -It is not ISO 2022 compliant. +It is not ISO/IEC\~2022 compliant. .\" Thanks to Tomohiro KUBOTA for the following sections about .\" national standards. .SS JIS X 0208 @@ -179,7 +179,7 @@ This means that JIS X 0208 itself is not used for expressing text data. JIS X 0208 is used as a component to construct encodings such as EUC-JP, Shift_JIS, -and ISO-2022-JP. +and ISO/IEC\~2022-JP. EUC-JP is the most important encoding for Linux and includes ASCII and JIS X 0208. In EUC-JP, JIS X 0208 @@ -190,19 +190,19 @@ KS X 1001 is a Korean national standard character set. Just as JIS X 0208, characters are mapped into a 94x94 two-byte matrix. KS X 1001 is used like JIS X 0208, as a component -to construct encodings such as EUC-KR, Johab, and ISO-2022-KR. +to construct encodings such as EUC-KR, Johab, and ISO/IEC\~2022-KR. EUC-KR is the most important encoding for Linux and includes ASCII and KS X 1001. KS C 5601 is an older name for KS X 1001. -.SS ISO 2022 and ISO 4873 -The ISO 2022 and 4873 standards describe a font-control model +.SS ISO/IEC\~2022 and ISO/IEC\~4873 +The ISO/IEC\~2022 and ISO/IEC\~4873 standards describe a font-control model based on VT100 practice. This model is (partially) supported by the Linux kernel and by .BR xterm (1). -Several ISO 2022-based character encodings have been defined, +Several ISO/IEC\~2022-based character encodings have been defined, especially for Japanese. -.PP +.P There are 4 graphic character sets, called G0, G1, G2, and G3, and one of them is the current character set for codes with high bit zero (initially G0), and one of them is the current @@ -212,7 +212,7 @@ essentially a 7-bit character set. It uses codes either 040\[en]0177 (041\[en]0176) or 0240\[en]0377 (0241\[en]0376). G0 always has size 94 and uses codes 041\[en]0176. -.PP +.P Switching between character sets is done using the shift functions \fB\[ha]N\fP (SO or LS1), \fB\[ha]O\fP (SI or LS0), ESC n (LS2), ESC o (LS3), ESC N (SS2), ESC O (SS3), ESC \[ti] (LS1R), ESC } (LS2R), ESC | (LS3R). @@ -223,32 +223,32 @@ for codes with high bit one. The function SS\fIn\fP makes character set G\fIn\fP (\fIn\fP=2 or 3) the current one for the next character only (regardless of the value of its high order bit). -.PP +.P A 94-character set is designated as G\fIn\fP character set by an escape sequence ESC ( xx (for G0), ESC ) xx (for G1), ESC * xx (for G2), ESC + xx (for G3), where xx is a symbol -or a pair of symbols found in the ISO 2375 International +or a pair of symbols found in the ISO/IEC\~2375 International Register of Coded Character Sets. -For example, ESC ( @ selects the ISO 646 character set as G0, +For example, ESC ( @ selects the ISO/IEC\~646 character set as G0, ESC ( A selects the UK standard character set (with pound instead of number sign), ESC ( B selects ASCII (with dollar instead of currency sign), ESC ( M selects a character set for African languages, ESC ( ! A selects the Cuban character set, and so on. -.PP +.P A 96-character set is designated as G\fIn\fP character set by an escape sequence ESC \- xx (for G1), ESC . xx (for G2) or ESC / xx (for G3). For example, ESC \- G selects the Hebrew alphabet as G1. -.PP +.P A multibyte character set is designated as G\fIn\fP character set by an escape sequence ESC $ xx or ESC $ ( xx (for G0), ESC $ ) xx (for G1), ESC $ * xx (for G2), ESC $ + xx (for G3). For example, ESC $ ( C selects the Korean character set for G0. The Japanese character set selected by ESC $ B has a more recent version selected by ESC & @ ESC $ B. -.PP -ISO 4873 stipulates a narrower use of character sets, where G0 +.P +ISO/IEC\~4873 stipulates a narrower use of character sets, where G0 is fixed (always ASCII), so that G1, G2, and G3 can be invoked only for codes with the high order bit set. In particular, \fB\[ha]N\fP and \fB\[ha]O\fP are not used anymore, ESC ( xx @@ -257,7 +257,7 @@ are equivalent to ESC \- xx, ESC . xx, ESC / xx, respectively. .SS TIS-620 TIS-620 is a Thai national standard character set and a superset of ASCII. -In the same fashion as the ISO 8859 series, Thai characters are mapped into +In the same fashion as the ISO/IEC\~8859 series, Thai characters are mapped into 0xa1\[en]0xfe. .SS Unicode Unicode (ISO/IEC 10646) is a standard which aims to unambiguously represent @@ -267,14 +267,14 @@ Since most computers don't include 20.1-bit integers, Unicode is usually encoded as 32-bit integers internally and either a series of 16-bit integers (UTF-16) (needing two 16-bit integers only when encoding certain rare characters) or a series of 8-bit bytes (UTF-8). -.PP +.P Linux represents Unicode using the 8-bit Unicode Transformation Format (UTF-8). UTF-8 is a variable length encoding of Unicode. It uses 1 byte to code 7 bits, 2 bytes for 11 bits, 3 bytes for 16 bits, 4 bytes for 21 bits, 5 bytes for 26 bits, 6 bytes for 31 bits. -.PP +.P Let 0,1,x stand for a zero, one, or arbitrary bit. A byte 0xxxxxxx stands for the Unicode 00000000 0xxxxxxx which codes the same symbol @@ -282,7 +282,7 @@ as the ASCII 0xxxxxxx. Thus, ASCII goes unchanged into UTF-8, and people using only ASCII do not notice any change: not in code, and not in file size. -.PP +.P A byte 110xxxxx is the start of a 2-byte code, and 110xxxxx 10yyyyyy is assembled into 00000xxx xxyyyyyy. A byte 1110xxxx is the start @@ -290,8 +290,8 @@ of a 3-byte code, and 1110xxxx 10yyyyyy 10zzzzzz is assembled into xxxxyyyy yyzzzzzz. (When UTF-8 is used to code the 31-bit ISO/IEC 10646 then this progression continues up to 6-byte codes.) -.PP -For most texts in ISO 8859 character sets, this means that the +.P +For most texts in ISO/IEC\~8859 character sets, this means that the characters outside of ASCII are now coded with two bytes. This tends to expand ordinary text files by only one or two percent. @@ -301,10 +301,10 @@ those languages is mostly outside of ASCII. For Japanese users this means that the 16-bit codes now in common use will take three bytes. While there are algorithmic conversions from some character sets -(especially ISO 8859-1) to Unicode, general conversion requires +(especially ISO/IEC\~8859-1) to Unicode, general conversion requires carrying around conversion tables, which can be quite large for 16-bit codes. -.PP +.P Note that UTF-8 is self-synchronizing: 10xxxxxx is a tail, any other byte is the head of a code. @@ -313,12 +313,12 @@ is as themselves. In particular, there are no embedded NULs (\[aq]\e0\[aq]) or \[aq]/\[aq]s that form part of some larger code. -.PP +.P Since ASCII, and, in particular, NUL and \[aq]/\[aq], are unchanged, the kernel does not notice that UTF-8 is being used. It does not care at all what the bytes it is handling stand for. -.PP +.P Rendering of Unicode data streams is typically handled through "subfont" tables which map a subset of Unicode to glyphs. Internally diff --git a/upstream/debian-unstable/man7/complex.7 b/upstream/debian-unstable/man7/complex.7 index 3685a8dd..b3a4ece7 100644 --- a/upstream/debian-unstable/man7/complex.7 +++ b/upstream/debian-unstable/man7/complex.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH complex 7 2023-07-18 "Linux man-pages 6.05.01" +.TH complex 7 2024-05-02 "Linux man-pages 6.8" .SH NAME complex \- basics of complex mathematics .SH LIBRARY @@ -15,7 +15,7 @@ Math library .SH DESCRIPTION Complex numbers are numbers of the form z = a+b*i, where a and b are real numbers and i = sqrt(\-1), so that i*i = \-1. -.PP +.P There are other ways to represent that number. The pair (a,b) of real numbers may be viewed as a point in the plane, given by X- and @@ -25,7 +25,7 @@ the pair of real numbers (r,phi), where r is the distance to the origin O, and phi the angle between the X-axis and the line Oz. Now z = r*exp(i*phi) = r*(cos(phi)+i*sin(phi)). -.PP +.P The basic operations are defined on z = a+b*i and w = c+d*i as: .TP .B addition: z+w = (a+c) + (b+d)*i @@ -33,13 +33,13 @@ The basic operations are defined on z = a+b*i and w = c+d*i as: .B multiplication: z*w = (a*c \- b*d) + (a*d + b*c)*i .TP .B division: z/w = ((a*c + b*d)/(c*c + d*d)) + ((b*c \- a*d)/(c*c + d*d))*i -.PP +.P Nearly all math function have a complex counterpart but there are some complex-only functions. .SH EXAMPLES Your C-compiler can work with complex numbers if it supports the C99 standard. The imaginary unit is represented by I. -.PP +.P .EX /* check that exp(i * pi) == \-1 */ #include <math.h> /* for atan */ diff --git a/upstream/debian-unstable/man7/cp1251.7 b/upstream/debian-unstable/man7/cp1251.7 index 6dd88c29..8e2ceba1 100644 --- a/upstream/debian-unstable/man7/cp1251.7 +++ b/upstream/debian-unstable/man7/cp1251.7 @@ -3,13 +3,13 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH cp1251 7 2022-12-15 "Linux man-pages 6.05.01" +.TH cp1251 7 2024-05-02 "Linux man-pages 6.8" .SH NAME cp1251 \- CP\ 1251 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The Windows Code Pages include several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). +character set (also known as ISO/IEC\~646-IRV). CP\ 1251 encodes the characters used in Cyrillic scripts. .SS CP\ 1251 characters diff --git a/upstream/debian-unstable/man7/cp1252.7 b/upstream/debian-unstable/man7/cp1252.7 index 2522b1d5..75a9e360 100644 --- a/upstream/debian-unstable/man7/cp1252.7 +++ b/upstream/debian-unstable/man7/cp1252.7 @@ -3,13 +3,13 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH cp1252 7 2022-12-15 "Linux man-pages 6.05.01" +.TH cp1252 7 2024-05-02 "Linux man-pages 6.8" .SH NAME cp1252 \- CP\ 1252 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The Windows Code Pages include several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). +character set (also known as ISO/IEC\~646-IRV). CP\ 1252 encodes the characters used in many West European languages. .SS CP\ 1252 characters diff --git a/upstream/debian-unstable/man7/cpuset.7 b/upstream/debian-unstable/man7/cpuset.7 index 800e4da3..239325d5 100644 --- a/upstream/debian-unstable/man7/cpuset.7 +++ b/upstream/debian-unstable/man7/cpuset.7 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-only .\" -.TH cpuset 7 2023-07-18 "Linux man-pages 6.05.01" +.TH cpuset 7 2024-05-02 "Linux man-pages 6.8" .SH NAME cpuset \- confine processes to processor and memory node subsets .SH DESCRIPTION @@ -14,7 +14,7 @@ which is used to control the processor placement and memory placement of processes. It is commonly mounted at .IR /dev/cpuset . -.PP +.P On systems with kernels compiled with built in support for cpusets, all processes are attached to a cpuset, and cpusets are always present. If a system supports cpusets, then it will have the entry @@ -31,9 +31,9 @@ By default, if the cpuset configuration on a system is not modified or if the cpuset filesystem is not even mounted, then the cpuset mechanism, though present, has no effect on the system's behavior. -.PP +.P A cpuset defines a list of CPUs and memory nodes. -.PP +.P The CPUs of a system include all the logical processing units on which a process can execute, including, if present, multiple processor cores within a package and Hyper-Threads @@ -42,7 +42,7 @@ Memory nodes include all distinct banks of main memory; small and SMP systems typically have just one memory node that contains all the system's main memory, while NUMA (non-uniform memory access) systems have multiple memory nodes. -.PP +.P Cpusets are represented as directories in a hierarchical pseudo-filesystem, where the top directory in the hierarchy .RI ( /dev/cpuset ) @@ -52,7 +52,7 @@ another parent cpuset contains a subset of that parent's CPUs and memory nodes. The directories and files representing cpusets have normal filesystem permissions. -.PP +.P Every process in the system belongs to exactly one cpuset. A process is confined to run only on the CPUs in the cpuset it belongs to, and to allocate memory only @@ -63,7 +63,7 @@ the child process is placed in the same cpuset as its parent. With sufficient privilege, a process may be moved from one cpuset to another and the allowed CPUs and memory nodes of an existing cpuset may be changed. -.PP +.P When the system begins booting, a single cpuset is defined that includes all CPUs and memory nodes on the system, and all processes are in that cpuset. @@ -71,7 +71,7 @@ During the boot process, or later during normal system operation, other cpusets may be created, as subdirectories of this top cpuset, under the control of the system administrator, and processes may be placed in these other cpusets. -.PP +.P Cpusets are integrated with the .BR sched_setaffinity (2) scheduling affinity mechanism and the @@ -93,7 +93,7 @@ other calls returning an error, if for example, such a call ends up requesting an empty set of CPUs or memory nodes, after that request is restricted to the invoking process's cpuset. -.PP +.P Typically, a cpuset is used to manage the CPU and memory-node confinement for a set of cooperating processes such as a batch scheduler job, and these @@ -104,7 +104,7 @@ Each directory below .I /dev/cpuset represents a cpuset and contains a fixed set of pseudo-files describing the state of that cpuset. -.PP +.P New cpusets are created using the .BR mkdir (2) system call or the @@ -114,13 +114,13 @@ The properties of a cpuset, such as its flags, allowed CPUs and memory nodes, and attached processes, are queried and modified by reading or writing to the appropriate file in that cpuset's directory, as listed below. -.PP +.P The pseudo-files in each cpuset directory are automatically created when the cpuset is created, as a result of the .BR mkdir (2) invocation. It is not possible to directly add or remove these pseudo-files. -.PP +.P A cpuset directory that contains no child cpuset directories, and has no attached processes, can be removed using .BR rmdir (2) @@ -128,7 +128,7 @@ or .BR rmdir (1). It is not necessary, or possible, to remove the pseudo-files inside the directory before removing it. -.PP +.P The pseudo-files in each cpuset directory are small text files that may be read and written using traditional shell utilities such as @@ -142,7 +142,7 @@ such as .BR write (2), and .BR close (2). -.PP +.P The pseudo-files in a cpuset directory represent internal kernel state and do not have any persistent image on disk. Each of these per-cpuset files is listed and described below. @@ -338,7 +338,7 @@ the wider the range of CPUs over which immediate load balancing is attempted. See \fBScheduler Relax Domain Level\fR, below, for further details. .\" ================== proc cpuset ================== -.PP +.P In addition to the above pseudo-files in each directory below .IR /dev/cpuset , each process has a pseudo-file, @@ -346,7 +346,7 @@ each process has a pseudo-file, that displays the path of the process's cpuset directory relative to the root of the cpuset filesystem. .\" ================== proc status ================== -.PP +.P Also the .IR /proc/ pid /status file for each process has four added lines, @@ -357,7 +357,7 @@ displaying the process's (on which memory nodes it may obtain memory), in the two formats \fBMask Format\fR and \fBList Format\fR (see below) as shown in the following example: -.PP +.P .in +4n .EX Cpus_allowed: ffffffff,ffffffff,ffffffff,ffffffff @@ -366,7 +366,7 @@ Mems_allowed: ffffffff,ffffffff Mems_allowed_list: 0\-63 .EE .in -.PP +.P The "allowed" fields were added in Linux 2.6.24; the "allowed_list" fields were added in Linux 2.6.26. .\" ================== EXTENDED CAPABILITIES ================== @@ -385,7 +385,7 @@ or .IR mem_exclusive , no other cpuset, other than a direct ancestor or descendant, may share any of the same CPUs or memory nodes. -.PP +.P A cpuset that is .I mem_exclusive restricts kernel allocations for @@ -426,7 +426,7 @@ and other data commonly shared by the kernel across multiple users. All cpusets, whether .I hardwall or not, restrict allocations of memory for user space. -.PP +.P This enables configuring a system so that several independent jobs can share common kernel data, such as filesystem pages, while isolating each job's user allocation in its own cpuset. @@ -437,7 +437,7 @@ all the jobs, and construct child cpusets for each individual job which are not .I hardwall cpusets. -.PP +.P Only a small amount of kernel memory, such as requests from interrupt handlers, is allowed to be taken outside even a .I hardwall @@ -455,7 +455,7 @@ the kernel will run the command supplying the pathname (relative to the mount point of the cpuset filesystem) of the abandoned cpuset. This enables automatic removal of abandoned cpusets. -.PP +.P The default value of .I notify_on_release in the root cpuset at system boot is disabled (0). @@ -463,7 +463,7 @@ The default value of other cpusets at creation is the current value of their parent's .I notify_on_release setting. -.PP +.P The command .I /sbin/cpuset_release_agent is invoked, with the name @@ -471,18 +471,18 @@ is invoked, with the name relative path) of the to-be-released cpuset in .IR argv[1] . -.PP +.P The usual contents of the command .I /sbin/cpuset_release_agent is simply the shell script: -.PP +.P .in +4n .EX #!/bin/sh rmdir /dev/cpuset/$1 .EE .in -.PP +.P As with other flag values below, this flag can be changed by writing an ASCII number 0 or 1 (with optional trailing newline) @@ -494,30 +494,30 @@ The of a cpuset provides a simple per-cpuset running average of the rate that the processes in a cpuset are attempting to free up in-use memory on the nodes of the cpuset to satisfy additional memory requests. -.PP +.P This enables batch managers that are monitoring jobs running in dedicated cpusets to efficiently detect what level of memory pressure that job is causing. -.PP +.P This is useful both on tightly managed systems running a wide mix of submitted jobs, which may choose to terminate or reprioritize jobs that are trying to use more memory than allowed on the nodes assigned them, and with tightly coupled, long-running, massively parallel scientific computing jobs that will dramatically fail to meet required performance goals if they start to use more memory than allowed to them. -.PP +.P This mechanism provides a very economical way for the batch manager to monitor a cpuset for signs of memory pressure. It's up to the batch manager or other user code to decide what action to take if it detects signs of memory pressure. -.PP +.P Unless memory pressure calculation is enabled by setting the pseudo-file .IR /dev/cpuset/cpuset.memory_pressure_enabled , it is not computed for any cpuset, and reads from any .I memory_pressure always return zero, as represented by the ASCII string "0\en". See the \fBWARNINGS\fR section, below. -.PP +.P A per-cpuset, running average is employed for the following reasons: .IP \[bu] 3 Because this meter is per-cpuset rather than per-process or per virtual @@ -535,7 +535,7 @@ the batch scheduler can obtain the key information\[em]memory pressure in a cpuset\[em]with a single read, rather than having to query and accumulate results over all the (dynamically changing) set of processes in the cpuset. -.PP +.P The .I memory_pressure of a cpuset is calculated using a per-cpuset simple digital filter @@ -543,7 +543,7 @@ that is kept within the kernel. For each cpuset, this filter tracks the recent rate at which processes attached to that cpuset enter the kernel direct reclaim code. -.PP +.P The kernel direct reclaim code is entered whenever a process has to satisfy a memory page request by first finding some other page to repurpose, due to lack of any readily available already free pages. @@ -552,7 +552,7 @@ to disk. Unmodified filesystem buffer pages are repurposed by simply dropping them, though if that page is needed again, it will have to be reread from disk. -.PP +.P The .I cpuset.memory_pressure file provides an integer number representing the recent (half-life of @@ -568,14 +568,14 @@ They are called .I cpuset.memory_spread_page and .IR cpuset.memory_spread_slab . -.PP +.P If the per-cpuset Boolean flag file .I cpuset.memory_spread_page is set, then the kernel will spread the filesystem buffers (page cache) evenly over all the nodes that the faulting process is allowed to use, instead of preferring to put those pages on the node where the process is running. -.PP +.P If the per-cpuset Boolean flag file .I cpuset.memory_spread_slab is set, @@ -583,12 +583,12 @@ then the kernel will spread some filesystem-related slab caches, such as those for inodes and directory entries, evenly over all the nodes that the faulting process is allowed to use, instead of preferring to put those pages on the node where the process is running. -.PP +.P The setting of these flags does not affect the data segment (see .BR brk (2)) or stack segment pages of a process. -.PP +.P By default, both kinds of memory spreading are off and the kernel prefers to allocate memory pages on the node local to where the requesting process is running. @@ -596,10 +596,10 @@ If that node is not allowed by the process's NUMA memory policy or cpuset configuration or if there are insufficient free memory pages on that node, then the kernel looks for the nearest node that is allowed and has sufficient free memory. -.PP +.P When new cpusets are created, they inherit the memory spread settings of their parent. -.PP +.P Setting memory spreading causes allocations for the affected page or slab caches to ignore the process's NUMA memory policy and be spread instead. @@ -614,7 +614,7 @@ no cpuset-specified memory spreading is in effect, even if it is. If cpuset memory spreading is subsequently turned off, the NUMA memory policy most recently specified by these calls is automatically reapplied. -.PP +.P Both .I cpuset.memory_spread_page and @@ -623,10 +623,10 @@ are Boolean flag files. By default, they contain "0", meaning that the feature is off for that cpuset. If a "1" is written to that file, that turns the named feature on. -.PP +.P Cpuset-specified memory spreading behaves similarly to what is known (in other contexts) as round-robin or interleave memory placement. -.PP +.P Cpuset-specified memory spreading can provide substantial performance improvements for jobs that: .IP \[bu] 3 @@ -636,7 +636,7 @@ frequently access that data; but also .IP \[bu] need to access large filesystem data sets that must to be spread across the several nodes in the job's cpuset in order to fit. -.PP +.P Without this policy, the memory allocation across the nodes in the job's cpuset can become very uneven, @@ -652,19 +652,19 @@ was allocated, so long as it remains allocated, even if the cpuset's memory-placement policy .I mems subsequently changes. -.PP +.P When memory migration is enabled in a cpuset, if the .I mems setting of the cpuset is changed, then any memory page in use by any process in the cpuset that is on a memory node that is no longer allowed will be migrated to a memory node that is allowed. -.PP +.P Furthermore, if a process is moved into a cpuset with .I memory_migrate enabled, any memory pages it uses that were on memory nodes allowed in its previous cpuset, but which are not allowed in its new cpuset, will be migrated to a memory node allowed in the new cpuset. -.PP +.P The relative placement of a migrated page within the cpuset is preserved during these migration operations if possible. For example, @@ -679,7 +679,7 @@ the kernel will look for processes on other more overloaded CPUs and move those processes to the underutilized CPU, within the constraints of such placement mechanisms as cpusets and .BR sched_setaffinity (2). -.PP +.P The algorithmic cost of load balancing and its impact on key shared kernel data structures such as the process list increases more than linearly with the number of CPUs being balanced. @@ -692,17 +692,17 @@ and the cost of load balancing depends on implementation details of the kernel process scheduler, which is subject to change over time, as improved kernel scheduler algorithms are implemented.) -.PP +.P The per-cpuset flag .I sched_load_balance provides a mechanism to suppress this automatic scheduler load balancing in cases where it is not needed and suppressing it would have worthwhile performance benefits. -.PP +.P By default, load balancing is done across all CPUs, except those marked isolated using the kernel boot time "isolcpus=" argument. (See \fBScheduler Relax Domain Level\fR, below, to change this default.) -.PP +.P This default load balancing across all CPUs is not well suited to the following two situations: .IP \[bu] 3 @@ -713,7 +713,7 @@ on separate sets of CPUs, full load balancing is unnecessary. Systems supporting real-time on some CPUs need to minimize system overhead on those CPUs, including avoiding process load balancing if that is not needed. -.PP +.P When the per-cpuset flag .I sched_load_balance is enabled (the default setting), @@ -723,7 +723,7 @@ ensuring that load balancing can move a process (not otherwise pinned, as by .BR sched_setaffinity (2)) from any CPU in that cpuset to any other. -.PP +.P When the per-cpuset flag .I sched_load_balance is disabled, then the @@ -732,7 +732,7 @@ scheduler will avoid load balancing across the CPUs in that cpuset, has .I sched_load_balance enabled. -.PP +.P So, for example, if the top cpuset has the flag .I sched_load_balance enabled, then the scheduler will load balance across all @@ -740,12 +740,12 @@ CPUs, and the setting of the .I sched_load_balance flag in other cpusets has no effect, as we're already fully load balancing. -.PP +.P Therefore in the above two situations, the flag .I sched_load_balance should be disabled in the top cpuset, and only some of the smaller, child cpusets would have this flag enabled. -.PP +.P When doing this, you don't usually want to leave any unpinned processes in the top cpuset that might use nontrivial amounts of CPU, as such processes may be artificially constrained to some subset of CPUs, depending on @@ -753,7 +753,7 @@ the particulars of this flag setting in descendant cpusets. Even if such a process could use spare CPU cycles in some other CPUs, the kernel scheduler might not consider the possibility of load balancing that process to the underused CPU. -.PP +.P Of course, processes pinned to a particular CPU can be left in a cpuset that disables .I sched_load_balance @@ -780,7 +780,7 @@ In any case, of course, tasks will be scheduled to run only on CPUs allowed by their cpuset, as modified by .BR sched_setaffinity (2) system calls. -.PP +.P On small systems, such as those with just a few CPUs, immediate load balancing is useful to improve system interactivity and to minimize wasteful idle CPU cycles. @@ -788,7 +788,7 @@ But on large systems, attempting immediate load balancing across a large number of CPUs can be more costly than it is worth, depending on the particular performance characteristics of the job mix and the hardware. -.PP +.P The exact meaning of the small integer values of .I sched_relax_domain_level will depend on internal @@ -796,12 +796,12 @@ implementation details of the kernel scheduler code and on the non-uniform architecture of the hardware. Both of these will evolve over time and vary by system architecture and kernel version. -.PP +.P As of this writing, when this capability was introduced in Linux 2.6.26, on certain popular architectures, the positive values of .I sched_relax_domain_level have the following meanings. -.PP +.P .PD 0 .TP .B 1 @@ -823,7 +823,7 @@ Perform immediate load balancing across over several Perform immediate load balancing across over all CPUs in system [On NUMA systems]. .PD -.PP +.P The .I sched_relax_domain_level value of zero (0) always means @@ -831,7 +831,7 @@ don't perform immediate load balancing, hence that load balancing is done only periodically, not immediately when a CPU becomes available or another task becomes runnable. -.PP +.P The .I sched_relax_domain_level value of minus one (\-1) @@ -839,7 +839,7 @@ always means use the system default value. The system default value can vary by architecture and kernel version. This system default value can be changed by kernel boot-time "relax_domain_level=" argument. -.PP +.P In the case of multiple overlapping cpusets which have conflicting .I sched_relax_domain_level values, then the highest such value @@ -860,7 +860,7 @@ The \fBMask Format\fR is used to represent CPU and memory-node bit masks in the .IR /proc/ pid /status file. -.PP +.P This format displays each 32-bit word in hexadecimal (using ASCII characters "0" - "9" and "a" - "f"); words are filled with leading zeros, if required. @@ -868,12 +868,12 @@ For masks longer than one word, a comma separator is used between words. Words are displayed in big-endian order, which has the most significant bit first. The hex digits within a word are also in big-endian order. -.PP +.P The number of 32-bit words displayed is the minimum number needed to display all bits of the bit mask, based on the size of the bit mask. -.PP +.P Examples of the \fBMask Format\fR: -.PP +.P .in +4n .EX 00000001 # just bit 0 set @@ -883,15 +883,15 @@ Examples of the \fBMask Format\fR: 00000000,000e3862 # 1,5,6,11\-13,17\-19 set .EE .in -.PP +.P A mask with bits 0, 1, 2, 4, 8, 16, 32, and 64 set displays as: -.PP +.P .in +4n .EX 00000001,00000001,00010117 .EE .in -.PP +.P The first "1" is for bit 64, the second for bit 32, the third for bit 16, the fourth for bit 8, the fifth for bit 4, and the "7" is for bits 2, 1, and 0. @@ -903,9 +903,9 @@ and .I mems is a comma-separated list of CPU or memory-node numbers and ranges of numbers, in ASCII decimal. -.PP +.P Examples of the \fBList Format\fR: -.PP +.P .in +4n .EX 0\-4,9 # bits 0, 1, 2, 3, 4, and 9 set @@ -940,7 +940,7 @@ The permissions of a cpuset are determined by the permissions of the directories and pseudo-files in the cpuset filesystem, normally mounted at .IR /dev/cpuset . -.PP +.P For instance, a process can put itself in some other cpuset (than its current one) if it can write the .I tasks @@ -949,14 +949,14 @@ This requires execute permission on the encompassing directories and write permission on the .I tasks file. -.PP +.P An additional constraint is applied to requests to place some other process in a cpuset. One process may not attach another to a cpuset unless it would have permission to send that process a signal (see .BR kill (2)). -.PP +.P A process may create a child cpuset if it can access and write the parent cpuset directory. It can modify the CPUs or memory nodes @@ -967,7 +967,7 @@ corresponding or .I mems file. -.PP +.P There is one minor difference between the manner in which these permissions are evaluated and the manner in which normal filesystem operation permissions are evaluated. @@ -988,7 +988,7 @@ to its cpuset directory beneath which is a bit unusual) or if some user code converts the relative cpuset path to a full filesystem path. -.PP +.P In theory, this means that user code should specify cpusets using absolute pathnames, which requires knowing the mount point of the cpuset filesystem (usually, but not necessarily, @@ -1024,13 +1024,13 @@ command in some shells does not display an error message if the system call fails. .\" Gack! csh(1)'s echo does this For example, if the command: -.PP +.P .in +4n .EX echo 19 > cpuset.mems .EE .in -.PP +.P failed because memory node 19 was not allowed (perhaps the current system does not have a memory node 19), then the .B echo @@ -1041,7 +1041,7 @@ external command to change cpuset file settings, as this command will display .BR write (2) errors, as in the example: -.PP +.P .in +4n .EX /bin/echo 19 > cpuset.mems @@ -1053,7 +1053,7 @@ errors, as in the example: .SS Memory placement Not all allocations of system memory are constrained by cpusets, for the following reasons. -.PP +.P If hot-plug functionality is used to remove all the CPUs that are currently assigned to a cpuset, then the kernel will automatically update the @@ -1068,7 +1068,7 @@ rather than starving a process that has had all its allowed CPUs or memory nodes taken offline. User code should reconfigure cpusets to refer only to online CPUs and memory nodes when using hot-plug to add or remove such resources. -.PP +.P A few kernel-critical, internal memory-allocation requests, marked GFP_ATOMIC, must be satisfied immediately. The kernel may drop some @@ -1076,7 +1076,7 @@ request or malfunction if one of these allocations fail. If such a request cannot be satisfied within the current process's cpuset, then we relax the cpuset, and look for memory anywhere we can find it. It's better to violate the cpuset than stress the kernel. -.PP +.P Allocations of memory requested by kernel drivers while processing an interrupt lack any relevant process context, and are not confined by cpusets. @@ -1092,7 +1092,7 @@ a different directory is not permitted. The Linux kernel implementation of cpusets sets .I errno to specify the reason for a failed system call affecting cpusets. -.PP +.P The possible .I errno settings and their meaning when set on @@ -1359,7 +1359,7 @@ options using shell commands. .SS Creating and attaching to a cpuset. To create a new cpuset and attach the current command shell to it, the steps are: -.PP +.P .PD 0 .IP (1) 5 mkdir /dev/cpuset (if not already done) @@ -1373,11 +1373,11 @@ Assign CPUs and memory nodes to the new cpuset. .IP (5) Attach the shell to the new cpuset. .PD -.PP +.P For example, the following sequence of commands will set up a cpuset named "Charlie", containing just CPUs 2 and 3, and memory node 1, and then attach the current shell to that cpuset. -.PP +.P .in +4n .EX .RB "$" " mkdir /dev/cpuset" @@ -1399,7 +1399,7 @@ To migrate a job (the set of processes attached to a cpuset) to different CPUs and memory nodes in the system, including moving the memory pages currently allocated to that job, perform the following steps. -.PP +.P .PD 0 .IP (1) 5 Let's say we want to move the job in cpuset @@ -1424,9 +1424,9 @@ Then move each process from to .IR beta . .PD -.PP +.P The following sequence of commands accomplishes this. -.PP +.P .in +4n .EX .RB "$" " cd /dev/cpuset" @@ -1438,22 +1438,22 @@ The following sequence of commands accomplishes this. .RB "$" " while read i; do /bin/echo $i; done < ../alpha/tasks > tasks" .EE .in -.PP +.P The above should move any processes in .I alpha to .IR beta , and any memory held by these processes on memory nodes 2\[en]3 to memory nodes 8\[en]9, respectively. -.PP +.P Notice that the last step of the above sequence did not do: -.PP +.P .in +4n .EX .RB "$" " cp ../alpha/tasks tasks" .EE .in -.PP +.P The .I while loop, rather than the seemingly easier use of the @@ -1462,7 +1462,7 @@ command, was necessary because only one process PID at a time may be written to the .I tasks file. -.PP +.P The same effect (writing one PID at a time) as the .I while loop can be accomplished more efficiently, in fewer keystrokes and in @@ -1470,7 +1470,7 @@ syntax that works on any shell, but alas more obscurely, by using the .B \-u (unbuffered) option of .BR sed (1): -.PP +.P .in +4n .EX .RB "$" " sed \-un p < ../alpha/tasks > tasks" @@ -1493,7 +1493,7 @@ syntax that works on any shell, but alas more obscurely, by using the .BR sched (7), .BR migratepages (8), .BR numactl (8) -.PP +.P .I Documentation/admin\-guide/cgroup\-v1/cpusets.rst in the Linux kernel source tree .\" commit 45ce80fb6b6f9594d1396d44dd7e7c02d596fef8 diff --git a/upstream/debian-unstable/man7/credentials.7 b/upstream/debian-unstable/man7/credentials.7 index 653e7a33..9e8db23a 100644 --- a/upstream/debian-unstable/man7/credentials.7 +++ b/upstream/debian-unstable/man7/credentials.7 @@ -4,7 +4,7 @@ .\" .\" 2007-06-13 Creation .\" -.TH credentials 7 2023-03-30 "Linux man-pages 6.05.01" +.TH credentials 7 2024-05-02 "Linux man-pages 6.8" .SH NAME credentials \- process identifiers .SH DESCRIPTION @@ -18,7 +18,7 @@ A PID is represented using the type .I pid_t (defined in .IR <sys/types.h> ). -.PP +.P PIDs are used in a range of system calls to identify the process affected by the call, for example: .BR kill (2), @@ -39,7 +39,7 @@ and .BR waitpid (2). .\" .BR waitid (2), .\" .BR wait4 (2), -.PP +.P A process's PID is preserved across an .BR execve (2). .SS Parent process ID (PPID) @@ -50,7 +50,7 @@ A process can obtain its PPID using .BR getppid (2). A PPID is represented using the type .IR pid_t . -.PP +.P A process's PPID is preserved across an .BR execve (2). .SS Process group ID and session ID @@ -61,13 +61,13 @@ A process can obtain its session ID using .BR getsid (2), and its process group ID using .BR getpgrp (2). -.PP +.P A child created by .BR fork (2) inherits its parent's session ID and process group ID. A process's session ID and process group ID are preserved across an .BR execve (2). -.PP +.P Sessions and process groups are abstractions devised to support shell job control. A process group (sometimes called a "job") is a collection of @@ -80,7 +80,7 @@ A process's group membership can be set using .BR setpgid (2). The process whose process ID is the same as its process group ID is the \fIprocess group leader\fP for that group. -.PP +.P A session is a collection of processes that share the same session ID. All of the members of a process group also have the same session ID (i.e., all of the members of a process group always belong to the @@ -92,7 +92,7 @@ which creates a new session whose session ID is the same as the PID of the process that called .BR setsid (2). The creator of the session is called the \fIsession leader\fP. -.PP +.P All of the processes in a session share a .IR "controlling terminal" . The controlling terminal is established when the session leader @@ -101,7 +101,7 @@ first opens a terminal (unless the flag is specified when calling .BR open (2)). A terminal may be the controlling terminal of at most one session. -.PP +.P At most one of the jobs in a session may be the .IR "foreground job" ; other jobs in the session are @@ -123,7 +123,7 @@ When terminal keys that generate a signal (such as the .I interrupt key, normally control-C) are pressed, the signal is sent to the processes in the foreground job. -.PP +.P Various system calls and library functions may operate on all members of a process group, including @@ -152,7 +152,7 @@ and .I gid_t (defined in .IR <sys/types.h> ). -.PP +.P On Linux, each process has the following user and group identifiers: .IP \[bu] 3 Real user ID and real group ID. @@ -228,7 +228,7 @@ of which a process may be a member. .\" As at 2.6.22-rc2, this file is still read-only. A process can obtain its set of supplementary group IDs using .BR getgroups (2). -.PP +.P A child process created by .BR fork (2) inherits copies of its parent's user and groups IDs. @@ -238,7 +238,7 @@ a process's real user and group ID and supplementary group IDs are preserved; the effective and saved set IDs may be changed, as described in .BR execve (2). -.PP +.P Aside from the purposes noted above, a process's user IDs are also employed in a number of other contexts: .IP \[bu] 3 @@ -267,33 +267,38 @@ that the process may create (see Subject to rules described in the relevant manual pages, a process can use the following APIs to modify its user and group IDs: .TP -.BR setuid "(2) (" setgid (2)) +.BR setuid (2)\~(\c +.BR setgid (2)) Modify the process's real (and possibly effective and saved-set) user (group) IDs. .TP -.BR seteuid "(2) (" setegid (2)) +.BR seteuid (2)\~(\c +.BR setegid (2)) Modify the process's effective user (group) ID. .TP -.BR setfsuid "(2) (" setfsgid (2)) +.BR setfsuid (2)\~(\c +.BR setfsgid (2)) Modify the process's filesystem user (group) ID. .TP -.BR setreuid "(2) (" setregid (2)) +.BR setreuid (2)\~(\c +.BR setregid (2)) Modify the process's real and effective (and possibly saved-set) user (group) IDs. .TP -.BR setresuid "(2) (" setresgid (2)) +.BR setresuid (2)\~(\c +.BR setresgid (2)) Modify the process's real, effective, and saved-set user (group) IDs. .TP .BR setgroups (2) Modify the process's supplementary group list. -.PP +.P Any changes to a process's effective user (group) ID are automatically carried over to the process's filesystem user (group) ID. Changes to a process's effective user or group ID can also affect the process "dumpable" attribute, as described in .BR prctl (2). -.PP +.P Changes to process user and group IDs can affect the capabilities of the process, as described in .BR capabilities (7). @@ -302,7 +307,7 @@ Process IDs, parent process IDs, process group IDs, and session IDs are specified in POSIX.1. The real, effective, and saved set user and groups IDs, and the supplementary group IDs, are specified in POSIX.1. -.PP +.P The filesystem user and group IDs are a Linux extension. .SH NOTES Various fields in the @@ -311,7 +316,7 @@ file show the process credentials described above. See .BR proc (5) for further information. -.PP +.P The POSIX threads specification requires that credentials are shared by all of the threads in a process. However, at the kernel level, Linux maintains separate user and group diff --git a/upstream/debian-unstable/man7/crypto.7ssl b/upstream/debian-unstable/man7/crypto.7ssl deleted file mode 100644 index ccead12c..00000000 --- a/upstream/debian-unstable/man7/crypto.7ssl +++ /dev/null @@ -1,611 +0,0 @@ -.\" -*- mode: troff; coding: utf-8 -*- -.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. -.ie n \{\ -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds C` -. ds C' -'br\} -.\" -.\" Escape single quotes in literal strings from groff's Unicode transform. -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.\" -.\" If the F register is >0, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.\" -.\" Avoid warning from groff about undefined register 'F'. -.de IX -.. -.nr rF 0 -.if \n(.g .if rF .nr rF 1 -.if (\n(rF:(\n(.g==0)) \{\ -. if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. if !\nF==2 \{\ -. nr % 0 -. nr F 2 -. \} -. \} -.\} -.rr rF -.\" ======================================================================== -.\" -.IX Title "CRYPTO 7SSL" -.TH CRYPTO 7SSL 2024-02-03 3.1.5 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 -crypto \- OpenSSL cryptographic library -.SH SYNOPSIS -.IX Header "SYNOPSIS" -See the individual manual pages for details. -.SH DESCRIPTION -.IX Header "DESCRIPTION" -The OpenSSL crypto library (\f(CW\*(C`libcrypto\*(C'\fR) implements a wide range of -cryptographic algorithms used in various Internet standards. The services -provided by this library are used by the OpenSSL implementations of TLS and -CMS, and they have also been used to implement many other third party products -and protocols. -.PP -The functionality includes symmetric encryption, public key cryptography, key -agreement, certificate handling, cryptographic hash functions, cryptographic -pseudo-random number generators, message authentication codes (MACs), key -derivation functions (KDFs), and various utilities. -.SS Algorithms -.IX Subsection "Algorithms" -Cryptographic primitives such as the SHA256 digest, or AES encryption are -referred to in OpenSSL as "algorithms". Each algorithm may have multiple -implementations available for use. For example the RSA algorithm is available as -a "default" implementation suitable for general use, and a "fips" implementation -which has been validated to FIPS standards for situations where that is -important. It is also possible that a third party could add additional -implementations such as in a hardware security module (HSM). -.SS Operations -.IX Subsection "Operations" -Different algorithms can be grouped together by their purpose. For example there -are algorithms for encryption, and different algorithms for digesting data. -These different groups are known as "operations" in OpenSSL. Each operation -has a different set of functions associated with it. For example to perform an -encryption operation using AES (or any other encryption algorithm) you would use -the encryption functions detailed on the \fBEVP_EncryptInit\fR\|(3) page. Or to -perform a digest operation using SHA256 then you would use the digesting -functions on the \fBEVP_DigestInit\fR\|(3) page. -.SS Providers -.IX Subsection "Providers" -A provider in OpenSSL is a component that collects together algorithm -implementations. In order to use an algorithm you must have at least one -provider loaded that contains an implementation of it. OpenSSL comes with a -number of providers and they may also be obtained from third parties. If you -don't load a provider explicitly (either in program code or via config) then the -OpenSSL built-in "default" provider will be automatically loaded. -.SS "Library contexts" -.IX Subsection "Library contexts" -A library context can be thought of as a "scope" within which configuration -options take effect. When a provider is loaded, it is only loaded within the -scope of a given library context. In this way it is possible for different -components of a complex application to each use a different library context and -have different providers loaded with different configuration settings. -.PP -If an application does not explicitly create a library context then the -"default" library context will be used. -.PP -Library contexts are represented by the \fBOSSL_LIB_CTX\fR type. Many OpenSSL API -functions take a library context as a parameter. Applications can always pass -\&\fBNULL\fR for this parameter to just use the default library context. -.PP -The default library context is automatically created the first time it is -needed. This will automatically load any available configuration file and will -initialise OpenSSL for use. Unlike in earlier versions of OpenSSL (prior to -1.1.0) no explicit initialisation steps need to be taken. -.PP -Similarly when the application exits the default library context is -automatically destroyed. No explicit de-initialisation steps need to be taken. -.PP -See \fBOSSL_LIB_CTX\fR\|(3) for more information about library contexts. -See also "ALGORITHM FETCHING". -.SS "Multi-threaded applications" -.IX Subsection "Multi-threaded applications" -As long as OpenSSL has been built with support for threads (the default case -on most platforms) then most OpenSSL \fIfunctions\fR are thread-safe in the sense -that it is safe to call the same function from multiple threads at the same -time. However most OpenSSL \fIdata structures\fR are not thread-safe. For example -the \fBBIO_write\fR\|(3) and \fBBIO_read\fR\|(3) functions are thread safe. However it -would not be thread safe to call \fBBIO_write()\fR from one thread while calling -\&\fBBIO_read()\fR in another where both functions are passed the same \fBBIO\fR object -since both of them may attempt to make changes to the same \fBBIO\fR object. -.PP -There are exceptions to these rules. A small number of functions are not thread -safe at all. Where this is the case this restriction should be noted in the -documentation for the function. Similarly some data structures may be partially -or fully thread safe. For example it is safe to use an \fBOSSL_LIB_CTX\fR in -multiple threads. -.PP -See \fBopenssl\-threads\fR\|(7) for a more detailed discussion on OpenSSL threading -support. -.SH "ALGORITHM FETCHING" -.IX Header "ALGORITHM FETCHING" -In order to use an algorithm an implementation for it must first be "fetched". -Fetching is the process of looking through the available implementations, -applying selection criteria (via a property query string), and finally choosing -the implementation that will be used. -.PP -Two types of fetching are supported by OpenSSL \- explicit fetching and implicit -fetching. -.SS "Property query strings" -.IX Subsection "Property query strings" -When fetching an algorithm it is possible to specify a property query string to -guide the selection process. For example a property query string of -"provider=default" could be used to force the selection to only consider -algorithm implementations in the default provider. -.PP -Property query strings can be specified explicitly as an argument to a function. -It is also possible to specify a default property query string for the whole -library context using the \fBEVP_set_default_properties\fR\|(3) or -\&\fBEVP_default_properties_enable_fips\fR\|(3) functions. Where both -default properties and function specific properties are specified then they are -combined. Function specific properties will override default properties where -there is a conflict. -.PP -See \fBproperty\fR\|(7) for more information about properties. -.SS "Explicit fetching" -.IX Subsection "Explicit fetching" -Users of the OpenSSL libraries never query a provider directly for an algorithm -implementation. Instead, the diverse OpenSSL APIs often have explicit fetching -functions that do the work, and they return an appropriate algorithm object back -to the user. These functions usually have the name \f(CW\*(C`APINAME_fetch\*(C'\fR, where -\&\f(CW\*(C`APINAME\*(C'\fR is the name of the operation. For example \fBEVP_MD_fetch\fR\|(3) can -be used to explicitly fetch a digest algorithm implementation. The user is -responsible for freeing the object returned from the \f(CW\*(C`APINAME_fetch\*(C'\fR function -using \f(CW\*(C`APINAME_free\*(C'\fR when it is no longer needed. -.PP -These fetching functions follow a fairly common pattern, where three -arguments are passed: -.IP "The library context" 4 -.IX Item "The library context" -See \fBOSSL_LIB_CTX\fR\|(3) for a more detailed description. -This may be NULL to signify the default (global) library context, or a -context created by the user. Only providers loaded in this library context (see -\&\fBOSSL_PROVIDER_load\fR\|(3)) will be considered by the fetching function. In case -no provider has been loaded in this library context then the default provider -will be loaded as a fallback (see \fBOSSL_PROVIDER\-default\fR\|(7)). -.IP "An identifier" 4 -.IX Item "An identifier" -For all currently implemented fetching functions this is the algorithm name. -.IP "A property query string" 4 -.IX Item "A property query string" -The property query string used to guide selection of the algorithm -implementation. -.PP -The algorithm implementation that is fetched can then be used with other diverse -functions that use them. For example the \fBEVP_DigestInit_ex\fR\|(3) function takes -as a parameter an \fBEVP_MD\fR object which may have been returned from an earlier -call to \fBEVP_MD_fetch\fR\|(3). -.SS "Implicit fetching" -.IX Subsection "Implicit fetching" -OpenSSL has a number of functions that return an algorithm object with no -associated implementation, such as \fBEVP_sha256\fR\|(3), \fBEVP_aes_128_cbc\fR\|(3), -\&\fBEVP_get_cipherbyname\fR\|(3) or \fBEVP_get_digestbyname\fR\|(3). These are present for -compatibility with OpenSSL before version 3.0 where explicit fetching was not -available. -.PP -When they are used with functions like \fBEVP_DigestInit_ex\fR\|(3) or -\&\fBEVP_CipherInit_ex\fR\|(3), the actual implementation to be used is -fetched implicitly using default search criteria. -.PP -In some cases implicit fetching can also occur when a NULL algorithm parameter -is supplied. In this case an algorithm implementation is implicitly fetched -using default search criteria and an algorithm name that is consistent with -the context in which it is being used. -.PP -Functions that revolve around \fBEVP_PKEY_CTX\fR and \fBEVP_PKEY\fR\|(3), such as -\&\fBEVP_DigestSignInit\fR\|(3) and friends, all fetch the implementations -implicitly. Because these functions involve both an operation type (such as -\&\fBEVP_SIGNATURE\fR\|(3)) and an \fBEVP_KEYMGMT\fR\|(3) for the \fBEVP_PKEY\fR\|(3), they try -the following: -.IP 1. 4 -Fetch the operation type implementation from any provider given a library -context and property string stored in the \fBEVP_PKEY_CTX\fR. -.Sp -If the provider of the operation type implementation is different from the -provider of the \fBEVP_PKEY\fR\|(3)'s \fBEVP_KEYMGMT\fR\|(3) implementation, try to -fetch a \fBEVP_KEYMGMT\fR\|(3) implementation in the same provider as the operation -type implementation and export the \fBEVP_PKEY\fR\|(3) to it (effectively making a -temporary copy of the original key). -.Sp -If anything in this step fails, the next step is used as a fallback. -.IP 2. 4 -As a fallback, try to fetch the operation type implementation from the same -provider as the original \fBEVP_PKEY\fR\|(3)'s \fBEVP_KEYMGMT\fR\|(3), still using the -property string from the \fBEVP_PKEY_CTX\fR. -.SS Performance -.IX Subsection "Performance" -If you perform the same operation many times then it is recommended to use -"Explicit fetching" to prefetch an algorithm once initially, -and then pass this created object to any operations that are currently -using "Implicit fetching". -See an example of Explicit fetching in "USING ALGORITHMS IN APPLICATIONS". -.PP -Prior to OpenSSL 3.0, constant method tables (such as \fBEVP_sha256()\fR) were used -directly to access methods. If you pass one of these convenience functions -to an operation the fixed methods are ignored, and only the name is used to -internally fetch methods from a provider. -.PP -If the prefetched object is not passed to operations, then any implicit -fetch will use the internally cached prefetched object, but it will -still be slower than passing the prefetched object directly. -.PP -Fetching via a provider offers more flexibility, but it is slower than the -old method, since it must search for the algorithm in all loaded providers, -and then populate the method table using provider supplied methods. -Internally OpenSSL caches similar algorithms on the first fetch -(so loading a digest caches all digests). -.PP -The following methods can be used for prefetching: -.IP \fBEVP_MD_fetch\fR\|(3) 4 -.IX Item "EVP_MD_fetch" -.PD 0 -.IP \fBEVP_CIPHER_fetch\fR\|(3) 4 -.IX Item "EVP_CIPHER_fetch" -.IP \fBEVP_KDF_fetch\fR\|(3) 4 -.IX Item "EVP_KDF_fetch" -.IP \fBEVP_MAC_fetch\fR\|(3) 4 -.IX Item "EVP_MAC_fetch" -.IP \fBEVP_KEM_fetch\fR\|(3) 4 -.IX Item "EVP_KEM_fetch" -.IP \fBOSSL_ENCODER_fetch\fR\|(3) 4 -.IX Item "OSSL_ENCODER_fetch" -.IP \fBOSSL_DECODER_fetch\fR\|(3) 4 -.IX Item "OSSL_DECODER_fetch" -.IP \fBEVP_RAND_fetch\fR\|(3) 4 -.IX Item "EVP_RAND_fetch" -.PD -.PP -The following methods are used internally when performing operations: -.IP \fBEVP_KEYMGMT_fetch\fR\|(3) 4 -.IX Item "EVP_KEYMGMT_fetch" -.PD 0 -.IP \fBEVP_KEYEXCH_fetch\fR\|(3) 4 -.IX Item "EVP_KEYEXCH_fetch" -.IP \fBEVP_SIGNATURE_fetch\fR\|(3) 4 -.IX Item "EVP_SIGNATURE_fetch" -.IP \fBOSSL_STORE_LOADER_fetch\fR\|(3) 4 -.IX Item "OSSL_STORE_LOADER_fetch" -.PD -.PP -See \fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-FIPS\fR\|(7) and -\&\fBOSSL_PROVIDER\-legacy\fR\|(7) for a list of algorithm names that -can be fetched. -.SH "FETCHING EXAMPLES" -.IX Header "FETCHING EXAMPLES" -The following section provides a series of examples of fetching algorithm -implementations. -.PP -Fetch any available implementation of SHA2\-256 in the default context. Note -that some algorithms have aliases. So "SHA256" and "SHA2\-256" are synonymous: -.PP -.Vb 3 -\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", NULL); -\& ... -\& EVP_MD_free(md); -.Ve -.PP -Fetch any available implementation of AES\-128\-CBC in the default context: -.PP -.Vb 3 -\& EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES\-128\-CBC", NULL); -\& ... -\& EVP_CIPHER_free(cipher); -.Ve -.PP -Fetch an implementation of SHA2\-256 from the default provider in the default -context: -.PP -.Vb 3 -\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=default"); -\& ... -\& EVP_MD_free(md); -.Ve -.PP -Fetch an implementation of SHA2\-256 that is not from the default provider in the -default context: -.PP -.Vb 3 -\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider!=default"); -\& ... -\& EVP_MD_free(md); -.Ve -.PP -Fetch an implementation of SHA2\-256 from the default provider in the specified -context: -.PP -.Vb 3 -\& EVP_MD *md = EVP_MD_fetch(ctx, "SHA2\-256", "provider=default"); -\& ... -\& EVP_MD_free(md); -.Ve -.PP -Load the legacy provider into the default context and then fetch an -implementation of WHIRLPOOL from it: -.PP -.Vb 2 -\& /* This only needs to be done once \- usually at application start up */ -\& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); -\& -\& EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy"); -\& ... -\& EVP_MD_free(md); -.Ve -.PP -Note that in the above example the property string "provider=legacy" is optional -since, assuming no other providers have been loaded, the only implementation of -the "whirlpool" algorithm is in the "legacy" provider. Also note that the -default provider should be explicitly loaded if it is required in addition to -other providers: -.PP -.Vb 3 -\& /* This only needs to be done once \- usually at application start up */ -\& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); -\& OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default"); -\& -\& EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL); -\& EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2\-256", NULL); -\& ... -\& EVP_MD_free(md_whirlpool); -\& EVP_MD_free(md_sha256); -.Ve -.SH "OPENSSL PROVIDERS" -.IX Header "OPENSSL PROVIDERS" -OpenSSL comes with a set of providers. -.PP -The algorithms available in each of these providers may vary due to build time -configuration options. The \fBopenssl\-list\fR\|(1) command can be used to list the -currently available algorithms. -.PP -The names of the algorithms shown from \fBopenssl\-list\fR\|(1) can be used as an -algorithm identifier to the appropriate fetching function. Also see the provider -specific manual pages linked below for further details about using the -algorithms available in each of the providers. -.PP -As well as the OpenSSL providers third parties can also implement providers. -For information on writing a provider see \fBprovider\fR\|(7). -.SS "Default provider" -.IX Subsection "Default provider" -The default provider is built in as part of the \fIlibcrypto\fR library and -contains all of the most commonly used algorithm implementations. Should it be -needed (if other providers are loaded and offer implementations of the same -algorithms), the property query string "provider=default" can be used as a -search criterion for these implementations. The default provider includes all -of the functionality in the base provider below. -.PP -If you don't load any providers at all then the "default" provider will be -automatically loaded. If you explicitly load any provider then the "default" -provider would also need to be explicitly loaded if it is required. -.PP -See \fBOSSL_PROVIDER\-default\fR\|(7). -.SS "Base provider" -.IX Subsection "Base provider" -The base provider is built in as part of the \fIlibcrypto\fR library and contains -algorithm implementations for encoding and decoding for OpenSSL keys. -Should it be needed (if other providers are loaded and offer -implementations of the same algorithms), the property query string -"provider=base" can be used as a search criterion for these implementations. -Some encoding and decoding algorithm implementations are not FIPS algorithm -implementations in themselves but support algorithms from the FIPS provider and -are allowed for use in "FIPS mode". The property query string "fips=yes" can be -used to select such algorithms. -.PP -See \fBOSSL_PROVIDER\-base\fR\|(7). -.SS "FIPS provider" -.IX Subsection "FIPS provider" -The FIPS provider is a dynamically loadable module, and must therefore -be loaded explicitly, either in code or through OpenSSL configuration -(see \fBconfig\fR\|(5)). It contains algorithm implementations that have been -validated according to the FIPS 140\-2 standard. Should it be needed (if other -providers are loaded and offer implementations of the same algorithms), the -property query string "provider=fips" can be used as a search criterion for -these implementations. All approved algorithm implementations in the FIPS -provider can also be selected with the property "fips=yes". The FIPS provider -may also contain non-approved algorithm implementations and these can be -selected with the property "fips=no". -.PP -See \fBOSSL_PROVIDER\-FIPS\fR\|(7) and \fBfips_module\fR\|(7). -.SS "Legacy provider" -.IX Subsection "Legacy provider" -The legacy provider is a dynamically loadable module, and must therefore -be loaded explicitly, either in code or through OpenSSL configuration -(see \fBconfig\fR\|(5)). It contains algorithm implementations that are considered -insecure, or are no longer in common use such as MD2 or RC4. Should it be needed -(if other providers are loaded and offer implementations of the same algorithms), -the property "provider=legacy" can be used as a search criterion for these -implementations. -.PP -See \fBOSSL_PROVIDER\-legacy\fR\|(7). -.SS "Null provider" -.IX Subsection "Null provider" -The null provider is built in as part of the \fIlibcrypto\fR library. It contains -no algorithms in it at all. When fetching algorithms the default provider will -be automatically loaded if no other provider has been explicitly loaded. To -prevent that from happening you can explicitly load the null provider. -.PP -See \fBOSSL_PROVIDER\-null\fR\|(7). -.SH "USING ALGORITHMS IN APPLICATIONS" -.IX Header "USING ALGORITHMS IN APPLICATIONS" -Cryptographic algorithms are made available to applications through use of the -"EVP" APIs. Each of the various operations such as encryption, digesting, -message authentication codes, etc., have a set of EVP function calls that can -be invoked to use them. See the \fBevp\fR\|(7) page for further details. -.PP -Most of these follow a common pattern. A "context" object is first created. For -example for a digest operation you would use an \fBEVP_MD_CTX\fR, and for an -encryption/decryption operation you would use an \fBEVP_CIPHER_CTX\fR. The -operation is then initialised ready for use via an "init" function \- optionally -passing in a set of parameters (using the \fBOSSL_PARAM\fR\|(3) type) to configure how -the operation should behave. Next data is fed into the operation in a series of -"update" calls. The operation is finalised using a "final" call which will -typically provide some kind of output. Finally the context is cleaned up and -freed. -.PP -The following shows a complete example for doing this process for digesting -data using SHA256. The process is similar for other operations such as -encryption/decryption, signatures, message authentication codes, etc. -.PP -.Vb 4 -\& #include <stdio.h> -\& #include <openssl/evp.h> -\& #include <openssl/bio.h> -\& #include <openssl/err.h> -\& -\& int main(void) -\& { -\& EVP_MD_CTX *ctx = NULL; -\& EVP_MD *sha256 = NULL; -\& const unsigned char msg[] = { -\& 0x00, 0x01, 0x02, 0x03 -\& }; -\& unsigned int len = 0; -\& unsigned char *outdigest = NULL; -\& int ret = 1; -\& -\& /* Create a context for the digest operation */ -\& ctx = EVP_MD_CTX_new(); -\& if (ctx == NULL) -\& goto err; -\& -\& /* -\& * Fetch the SHA256 algorithm implementation for doing the digest. We\*(Aqre -\& * using the "default" library context here (first NULL parameter), and -\& * we\*(Aqre not supplying any particular search criteria for our SHA256 -\& * implementation (second NULL parameter). Any SHA256 implementation will -\& * do. -\& * In a larger application this fetch would just be done once, and could -\& * be used for multiple calls to other operations such as EVP_DigestInit_ex(). -\& */ -\& sha256 = EVP_MD_fetch(NULL, "SHA256", NULL); -\& if (sha256 == NULL) -\& goto err; -\& -\& /* Initialise the digest operation */ -\& if (!EVP_DigestInit_ex(ctx, sha256, NULL)) -\& goto err; -\& -\& /* -\& * Pass the message to be digested. This can be passed in over multiple -\& * EVP_DigestUpdate calls if necessary -\& */ -\& if (!EVP_DigestUpdate(ctx, msg, sizeof(msg))) -\& goto err; -\& -\& /* Allocate the output buffer */ -\& outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256)); -\& if (outdigest == NULL) -\& goto err; -\& -\& /* Now calculate the digest itself */ -\& if (!EVP_DigestFinal_ex(ctx, outdigest, &len)) -\& goto err; -\& -\& /* Print out the digest result */ -\& BIO_dump_fp(stdout, outdigest, len); -\& -\& ret = 0; -\& -\& err: -\& /* Clean up all the resources we allocated */ -\& OPENSSL_free(outdigest); -\& EVP_MD_free(sha256); -\& EVP_MD_CTX_free(ctx); -\& if (ret != 0) -\& ERR_print_errors_fp(stderr); -\& return ret; -\& } -.Ve -.SH CONFIGURATION -.IX Header "CONFIGURATION" -By default OpenSSL will load a configuration file when it is first used. This -will set up various configuration settings within the default library context. -Applications that create their own library contexts may optionally configure -them with a config file using the \fBOSSL_LIB_CTX_load_config\fR\|(3) function. -.PP -The configuration file can be used to automatically load providers and set up -default property query strings. -.PP -For information on the OpenSSL configuration file format see \fBconfig\fR\|(5). -.SH "ENCODING AND DECODING KEYS" -.IX Header "ENCODING AND DECODING KEYS" -Many algorithms require the use of a key. Keys can be generated dynamically -using the EVP APIs (for example see \fBEVP_PKEY_Q_keygen\fR\|(3)). However it is often -necessary to save or load keys (or their associated parameters) to or from some -external format such as PEM or DER (see \fBopenssl\-glossary\fR\|(7)). OpenSSL uses -encoders and decoders to perform this task. -.PP -Encoders and decoders are just algorithm implementations in the same way as -any other algorithm implementation in OpenSSL. They are implemented by -providers. The OpenSSL encoders and decoders are available in the default -provider. They are also duplicated in the base provider. -.PP -For information about encoders see \fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3). For -information about decoders see \fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3). -.SH "LIBRARY CONVENTIONS" -.IX Header "LIBRARY CONVENTIONS" -Many OpenSSL functions that "get" or "set" a value follow a naming convention -using the numbers \fB0\fR and \fB1\fR, i.e. "get0", "get1", "set0" and "set1". This -can also apply to some functions that "add" a value to an existing set, i.e. -"add0" and "add1". -.PP -For example the functions: -.PP -.Vb 2 -\& int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); -\& int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj); -.Ve -.PP -In the \fB0\fR version the ownership of the object is passed to (for an add or set) -or retained by (for a get) the parent object. For example after calling the -\&\fBX509_CRL_add0_revoked()\fR function above, ownership of the \fIrev\fR object is passed -to the \fIcrl\fR object. Therefore, after calling this function \fIrev\fR should not -be freed directly. It will be freed implicitly when \fIcrl\fR is freed. -.PP -In the \fB1\fR version the ownership of the object is not passed to or retained by -the parent object. Instead a copy or "up ref" of the object is performed. So -after calling the \fBX509_add1_trust_object()\fR function above the application will -still be responsible for freeing the \fIobj\fR value where appropriate. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -\&\fBopenssl\fR\|(1), \fBssl\fR\|(7), \fBevp\fR\|(7), \fBOSSL_LIB_CTX\fR\|(3), \fBopenssl\-threads\fR\|(7), -\&\fBproperty\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-base\fR\|(7), -\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7), \fBOSSL_PROVIDER\-null\fR\|(7), -\&\fBopenssl\-glossary\fR\|(7), \fBprovider\fR\|(7) -.SH COPYRIGHT -.IX Header "COPYRIGHT" -Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. -.PP -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 LICENSE in the source distribution or at -<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/ct.7ssl b/upstream/debian-unstable/man7/ct.7ssl index 7159ad7a..d4377352 100644 --- a/upstream/debian-unstable/man7/ct.7ssl +++ b/upstream/debian-unstable/man7/ct.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "CT 7SSL" -.TH CT 7SSL 2024-02-03 3.1.5 OpenSSL +.TH CT 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/daemon.7 b/upstream/debian-unstable/man7/daemon.7 index 6fcf79b7..459ca89c 100644 --- a/upstream/debian-unstable/man7/daemon.7 +++ b/upstream/debian-unstable/man7/daemon.7 @@ -1,5 +1,5 @@ '\" t -.TH "DAEMON" "7" "" "systemd 255" "daemon" +.TH "DAEMON" "7" "" "systemd 256~rc3" "daemon" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -116,7 +116,7 @@ to detach from any terminal and create an independent session\&. .\} In the child, call \fBfork()\fR -again, to ensure that the daemon can never re\-acquire a terminal again\&. (This relevant if the program \(em and all its dependencies \(em does not carefully specify `O_NOCTTY` on each and every single `open()` call that might potentially open a TTY device node\&.) +again, to ensure that the daemon can never re\-acquire a terminal again\&. (This is relevant if the program \(em and all its dependencies \(em does not carefully specify `O_NOCTTY` on each and every single `open()` call that might potentially open a TTY device node\&.) .RE .sp .RS 4 @@ -375,7 +375,7 @@ If your daemon provides services to other local processes or remote clients via If the service opens sockets or other files on it own, and those file descriptors shall survive a restart, the daemon should store them in the service manager via \fBsd_notify\fR(3) with -\fIFDSTORE=1\fR\&.\&. +\fIFDSTORE=1\fR\&. .RE .sp .RS 4 @@ -831,13 +831,7 @@ It is recommended to follow the general guidelines for placing package files, as \fBfile-hierarchy\fR(7)\&. .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBsd-daemon\fR(3), -\fBsd_listen_fds\fR(3), -\fBsd_notify\fR(3), -\fBdaemon\fR(3), -\fBsystemd.service\fR(5), -\fBfile-hierarchy\fR(7) +\fBsystemd\fR(1), \fBsd-daemon\fR(3), \fBsd_listen_fds\fR(3), \fBsd_notify\fR(3), \fBdaemon\fR(3), \fBsystemd.service\fR(5), \fBfile-hierarchy\fR(7) .SH "NOTES" .IP " 1." 4 LSB recommendations for SysV init scripts diff --git a/upstream/debian-unstable/man7/ddp.7 b/upstream/debian-unstable/man7/ddp.7 index 0b7eb154..362644d5 100644 --- a/upstream/debian-unstable/man7/ddp.7 +++ b/upstream/debian-unstable/man7/ddp.7 @@ -4,14 +4,14 @@ .\" .\" $Id: ddp.7,v 1.3 1999/05/13 11:33:22 freitag Exp $ .\" -.TH ddp 7 2023-05-26 "Linux man-pages 6.05.01" +.TH ddp 7 2024-05-02 "Linux man-pages 6.8" .SH NAME ddp \- Linux AppleTalk protocol implementation .SH SYNOPSIS .nf .B #include <sys/socket.h> .B #include <netatalk/at.h> -.PP +.P .IB ddp_socket " = socket(AF_APPLETALK, SOCK_DGRAM, 0);" .IB raw_socket " = socket(AF_APPLETALK, SOCK_RAW, " protocol ");" .fi @@ -26,12 +26,12 @@ protocol libraries. This page documents the interface for those who wish or need to use the DDP layer directly. -.PP +.P The communication between AppleTalk and the user program works using a BSD-compatible socket interface. For more information on sockets, see .BR socket (7). -.PP +.P An AppleTalk socket is created by calling the .BR socket (2) function with a @@ -52,7 +52,7 @@ For .B SOCK_RAW you must specify .BR ATPROTO_DDP . -.PP +.P Raw sockets may be opened only by a process with effective user ID 0 or when the process has the .B CAP_NET_RAW @@ -60,7 +60,7 @@ capability. .SS Address format An AppleTalk socket address is defined as a combination of a network number, a node number, and a port number. -.PP +.P .in +4n .EX struct at_addr { @@ -75,7 +75,7 @@ struct sockaddr_atalk { }; .EE .in -.PP +.P .I sat_family is always set to .BR AF_APPLETALK . @@ -133,7 +133,7 @@ dead. .TP .I aarp\-tick\-time The timer rate (in seconds) for the timer driving AARP. -.PP +.P The default values match the specification and should never need to be changed. .SS Ioctls @@ -228,14 +228,14 @@ on BSD-derived systems. Many BSD systems fail to check .B SO_BROADCAST when sending broadcast frames; this can lead to compatibility problems. -.PP +.P The raw socket mode is unique to Linux and exists to support the alternative CAP package and AppleTalk monitoring tools more easily. .SH BUGS There are too many inconsistent error values. -.PP +.P The ioctls used to configure routing tables, devices, AARP tables, and other devices are not yet described. .SH SEE ALSO diff --git a/upstream/debian-unstable/man7/des_modes.7ssl b/upstream/debian-unstable/man7/des_modes.7ssl index 7aeca1ad..867c6b22 100644 --- a/upstream/debian-unstable/man7/des_modes.7ssl +++ b/upstream/debian-unstable/man7/des_modes.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "DES_MODES 7SSL" -.TH DES_MODES 7SSL 2024-02-03 3.1.5 OpenSSL +.TH DES_MODES 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/environ.7 b/upstream/debian-unstable/man7/environ.7 index 345b350b..1dd3eb5d 100644 --- a/upstream/debian-unstable/man7/environ.7 +++ b/upstream/debian-unstable/man7/environ.7 @@ -12,7 +12,7 @@ .\" Modified Wed Jan 24 06:37:24 2001 by Eric S. Raymond (esr@thyrsus.com) .\" Modified Thu Dec 13 23:53:27 2001 by Martin Schulze <joey@infodrom.org> .\" -.TH environ 7 2023-02-05 "Linux man-pages 6.05.01" +.TH environ 7 2024-05-02 "Linux man-pages 6.8" .SH NAME environ \- user environment .SH SYNOPSIS @@ -32,7 +32,7 @@ When a child process is created via it inherits a .I copy of its parent's environment. -.PP +.P By convention, the strings in .I environ have the form "\fIname\fP\fB=\fP\fIvalue\fP". @@ -41,7 +41,7 @@ the character "\fB=\fP". The value can be anything that can be represented as a string. The name and the value may not contain an embedded null byte (\[aq]\e0\[aq]), since this is assumed to terminate the string. -.PP +.P Environment variables may be placed in the shell's environment by the .I export command in @@ -50,7 +50,7 @@ or by the .I setenv command if you use .BR csh (1). -.PP +.P The initial environment of the shell is populated in various ways, such as definitions from .I /etc/environment @@ -63,21 +63,21 @@ In addition, various shell initialization scripts, such as the system-wide script and per-user initializations script may include commands that add variables to the shell's environment; see the manual page of your preferred shell for details. -.PP +.P Bourne-style shells support the syntax -.PP +.P .in +4n .EX NAME=value command .EE .in -.PP +.P to create an environment variable definition only in the scope of the process that executes .IR command . Multiple variable definitions, separated by white space, may precede .IR command . -.PP +.P Arguments may also be placed in the environment at the point of an .BR exec (3). @@ -87,7 +87,7 @@ A C program can manipulate its environment using the functions .BR setenv (3), and .BR unsetenv (3). -.PP +.P What follows is a list of environment variables typically seen on a system. This list is incomplete and includes only common variables seen @@ -194,7 +194,7 @@ command shall be valid. .\" .B BROWSER .\" The user's preferred utility to browse URLs. Sequence of colon-separated .\" browser commands. See http://www.catb.org/\[ti]esr/BROWSER/ . -.PP +.P Note that the behavior of many programs and library routines is influenced by the presence or value of certain environment variables. Examples include the following: @@ -272,14 +272,14 @@ if the .B _GNU_SOURCE feature test macro is defined (see .BR feature_test_macros (7)). -.PP +.P The .BR prctl (2) .B PR_SET_MM_ENV_START and .B PR_SET_MM_ENV_END operations can be used to control the location of the process's environment. -.PP +.P The .BR HOME , .BR LOGNAME , @@ -305,7 +305,7 @@ Clearly there is a security risk here. Many a system command has been tricked into mischief by a user who specified unusual values for .BR IFS " or " LD_LIBRARY_PATH . -.PP +.P There is also the risk of name space pollution. Programs like .I make diff --git a/upstream/debian-unstable/man7/epoll.7 b/upstream/debian-unstable/man7/epoll.7 index 02a53e97..e45ebe29 100644 --- a/upstream/debian-unstable/man7/epoll.7 +++ b/upstream/debian-unstable/man7/epoll.7 @@ -4,7 +4,7 @@ .\" .\" Davide Libenzi <davidel@xmailserver.org> .\" -.TH epoll 7 2023-05-03 "Linux man-pages 6.05.01" +.TH epoll 7 2024-05-02 "Linux man-pages 6.8" .SH NAME epoll \- I/O event notification facility .SH SYNOPSIS @@ -21,7 +21,7 @@ The .B epoll API can be used either as an edge-triggered or a level-triggered interface and scales well to large numbers of watched file descriptors. -.PP +.P The central concept of the .B epoll API is the @@ -45,7 +45,7 @@ The ready list is a subset of the file descriptors in the interest list. The ready list is dynamically populated by the kernel as a result of I/O activity on those file descriptors. -.PP +.P The following system calls are provided to create and manage an .B epoll @@ -104,7 +104,7 @@ The pipe reader reads 1\ kB of data from A call to .BR epoll_wait (2) is done. -.PP +.P If the .I rfd file descriptor has been added to the @@ -139,7 +139,7 @@ does not consume the whole buffer data, the call to done in step .B 5 might block indefinitely. -.PP +.P An application that employs the .B EPOLLET flag should use nonblocking file descriptors to avoid having a blocking @@ -158,7 +158,7 @@ or .BR write (2) return .BR EAGAIN . -.PP +.P By contrast, when used as a level-triggered interface (the default, when .B EPOLLET @@ -168,7 +168,7 @@ is simply a faster .BR poll (2), and can be used wherever the latter is used since it shares the same semantics. -.PP +.P Since even with edge-triggered .BR epoll , multiple events can be generated upon receipt of multiple chunks of data, @@ -185,7 +185,7 @@ it is the caller's responsibility to rearm the file descriptor using .BR epoll_ctl (2) with .BR EPOLL_CTL_MOD . -.PP +.P If multiple threads (or processes, if child processes have inherited the .B epoll @@ -214,7 +214,7 @@ it is necessary to use the .BR epoll_ctl (2) .B EPOLLWAKEUP flag. -.PP +.P When the .B EPOLLWAKEUP flag is set in the @@ -284,7 +284,7 @@ it will continue to or .BR write (2) from where it stopped before. -.PP +.P .in +4n .EX #define MAX_EVENTS 10 @@ -337,7 +337,7 @@ for (;;) { } .EE .in -.PP +.P When used as an edge-triggered interface, for performance reasons, it is possible to add the file descriptor inside the .B epoll @@ -595,7 +595,7 @@ directory. See .BR proc (5) for further details. -.PP +.P The .BR kcmp (2) .B KCMP_EPOLL_TFD diff --git a/upstream/debian-unstable/man7/evp.7ssl b/upstream/debian-unstable/man7/evp.7ssl index 6ae6d3fe..1435461a 100644 --- a/upstream/debian-unstable/man7/evp.7ssl +++ b/upstream/debian-unstable/man7/evp.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "EVP 7SSL" -.TH EVP 7SSL 2024-02-03 3.1.5 OpenSSL +.TH EVP 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/fanotify.7 b/upstream/debian-unstable/man7/fanotify.7 index eea8835e..3223195a 100644 --- a/upstream/debian-unstable/man7/fanotify.7 +++ b/upstream/debian-unstable/man7/fanotify.7 @@ -2,7 +2,7 @@ .\" and Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com> .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH fanotify 7 2023-05-03 "Linux man-pages 6.05.01" +.TH fanotify 7 2024-05-02 "Linux man-pages 6.8" .SH NAME fanotify \- monitoring filesystem events .SH DESCRIPTION @@ -15,14 +15,14 @@ The support for those events was added in Linux 5.1. (See .BR inotify (7) for details of an API that did notify those events pre Linux 5.1.) -.PP +.P Additional capabilities compared to the .BR inotify (7) API include the ability to monitor all of the objects in a mounted filesystem, the ability to make access permission decisions, and the possibility to read or modify files before access by other applications. -.PP +.P The following system calls are used with this API: .BR fanotify_init (2), .BR fanotify_mark (2), @@ -35,11 +35,11 @@ The .BR fanotify_init (2) system call creates and initializes an fanotify notification group and returns a file descriptor referring to it. -.PP +.P An fanotify notification group is a kernel-internal object that holds a list of files, directories, filesystems, and mounts for which events shall be created. -.PP +.P For each entry in an fanotify notification group, two bit masks exist: the .I mark mask and the @@ -50,13 +50,13 @@ The ignore mask defines activities for which no event shall be generated. Having these two types of masks permits a filesystem, mount, or directory to be marked for receiving events, while at the same time ignoring events for specific objects under a mount or directory. -.PP +.P The .BR fanotify_mark (2) system call adds a file, directory, filesystem, or mount to a notification group and specifies which events shall be reported (or ignored), or removes or modifies such an entry. -.PP +.P A possible usage of the ignore mask is for a file cache. Events of interest for a file cache are modification of a file and closing of the same. @@ -69,7 +69,7 @@ is closed. Hence, the modify event can be added to the ignore mask. Upon receiving the close event, the modify event can be removed from the ignore mask and the file cache entry can be updated. -.PP +.P The entries in the fanotify notification groups refer to files and directories via their inode number and to mounts via their mount ID. If files or directories are renamed or moved within the same mount, @@ -85,7 +85,7 @@ or similar) from the fanotify file descriptor returned by .BR fanotify_init (2). -.PP +.P Two types of events are generated: .I notification events and @@ -98,7 +98,7 @@ Permission events are requests to the receiving application to decide whether permission for a file access shall be granted. For these events, the recipient must write a response which decides whether access is granted or not. -.PP +.P An event is removed from the event queue of the fanotify group when it has been read. Permission events that have been read are kept in an internal list of the @@ -117,11 +117,11 @@ is not specified in the call to until either a file event occurs or the call is interrupted by a signal (see .BR signal (7)). -.PP +.P After a successful .BR read (2), the read buffer contains one or more of the following structures: -.PP +.P .in +4n .EX struct fanotify_event_metadata { @@ -135,7 +135,7 @@ struct fanotify_event_metadata { }; .EE .in -.PP +.P Information records are supplemental pieces of information that may be provided alongside the generic @@ -193,7 +193,7 @@ It is imperative for event listeners to inspect the field of this structure in order to determine the type of information record that had been received for a given event. -.PP +.P In cases where an fanotify group identifies filesystem objects by file handles, event listeners should also expect to @@ -201,24 +201,24 @@ receive one or more of the below information record objects alongside the generic .I fanotify_event_metadata structure within the read buffer: -.PP +.P .in +4n .EX struct fanotify_event_info_fid { struct fanotify_event_info_header hdr; __kernel_fsid_t fsid; - unsigned char file_handle[0]; + unsigned char handle[]; }; .EE .in -.PP +.P In cases where an fanotify group is initialized with .BR FAN_REPORT_PIDFD , event listeners should expect to receive the below information record object alongside the generic .I fanotify_event_metadata structure within the read buffer: -.PP +.P .in +4n .EX struct fanotify_event_info_pidfd { @@ -227,7 +227,7 @@ struct fanotify_event_info_pidfd { }; .EE .in -.PP +.P In case of a .B FAN_FS_ERROR event, @@ -236,7 +236,7 @@ is returned alongside the generic .I fanotify_event_metadata structure within the read buffer. This structure is defined as follows: -.PP +.P .in +4n .EX struct fanotify_event_info_error { @@ -246,7 +246,7 @@ struct fanotify_event_info_error { }; .EE .in -.PP +.P All information records contain a nested structure of type .IR fanotify_event_info_header . This structure holds meta-information about the information record @@ -254,7 +254,7 @@ that may have been returned alongside the generic .I fanotify_event_metadata structure. This structure is defined as follows: -.PP +.P .in +4n .EX struct fanotify_event_info_header { @@ -264,17 +264,17 @@ struct fanotify_event_info_header { }; .EE .in -.PP +.P For performance reasons, it is recommended to use a large buffer size (for example, 4096 bytes), so that multiple events can be retrieved by a single .BR read (2). -.PP +.P The return value of .BR read (2) is the number of bytes placed in the buffer, or \-1 in case of an error (but see BUGS). -.PP +.P The fields of the .I fanotify_event_metadata structure are as follows: @@ -343,13 +343,13 @@ was set in .BR fanotify_init (2), this is the TID of the thread that caused the event. Otherwise, this the PID of the process that caused the event. -.PP +.P A program listening to fanotify events can compare this PID to the PID returned by .BR getpid (2), to determine whether the event is caused by the listener itself, or is due to a file access by another process. -.PP +.P The bit mask in .I mask indicates which events have occurred for a single filesystem object. @@ -359,7 +359,7 @@ In particular, consecutive events for the same filesystem object and originating from the same process may be merged into a single event, with the exception that two permission events are never merged into one queue entry. -.PP +.P The bits that may appear in .I mask are as follows: @@ -446,7 +446,7 @@ open the filesystem object for execution shall be granted. See NOTES in .BR fanotify_mark (2) for additional details. -.PP +.P To check for any close event, the following bit mask may be used: .TP .B FAN_CLOSE @@ -458,7 +458,7 @@ This is a synonym for: FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE .EE .in -.PP +.P To check for any move event, the following bit mask may be used: .TP .B FAN_MOVE @@ -470,7 +470,7 @@ This is a synonym for: FAN_MOVED_FROM | FAN_MOVED_TO .EE .in -.PP +.P The following bits may appear in .I mask only in conjunction with other event type bits: @@ -487,7 +487,7 @@ The .B FAN_ONDIR flag is reported in an event mask only if the fanotify group identifies filesystem objects by file handles. -.PP +.P Information records that are supplied alongside the generic .I fanotify_event_metadata structure will always contain a nested structure of type @@ -528,7 +528,7 @@ is not expected to be larger than .RI ( event_len \- .IR metadata_len ). -.PP +.P The fields of the .I fanotify_event_info_fid structure are as follows: @@ -576,8 +576,9 @@ and contains the same value as when calling .BR statfs (2). .TP -.I file_handle -This is a variable length structure of type struct file_handle. +.I handle +This field contains a variable-length structure of type +.IR "struct file_handle" . It is an opaque handle that corresponds to a specified object on a filesystem as returned by .BR name_to_handle_at (2). @@ -601,14 +602,14 @@ if the value of field is .BR FAN_EVENT_INFO_TYPE_FID , the -.I file_handle +.I handle identifies the object correlated to the event. If the value of .I info_type field is .BR FAN_EVENT_INFO_TYPE_DFID , the -.I file_handle +.I handle identifies the directory object correlated to the event or the parent directory of a non-directory object correlated to the event. If the value of @@ -616,13 +617,13 @@ If the value of field is .BR FAN_EVENT_INFO_TYPE_DFID_NAME , the -.I file_handle +.I handle identifies the same directory object that would be reported with .B FAN_EVENT_INFO_TYPE_DFID and the file handle is followed by a null terminated string that identifies the name of a directory entry in that directory, or '.' to identify the directory object itself. -.PP +.P The fields of the .I fanotify_event_info_pidfd structure are as follows: @@ -667,7 +668,7 @@ Once the event listener has dealt with an event and the pidfd is no longer required, the pidfd should be closed via .BR close (2). -.PP +.P The fields of the .I fanotify_event_info_error structure are as follows: @@ -686,7 +687,7 @@ Identifies the type of error that occurred. .I error_count This is a counter of the number of errors suppressed since the last error was read. -.PP +.P The following macros are provided to iterate over a buffer containing fanotify event metadata returned by a .BR read (2) @@ -719,7 +720,7 @@ has been skipped over (i.e., it subtracts .I meta\->event_len from .IR len ). -.PP +.P In addition, there is: .TP .B FAN_EVENT_METADATA_LEN @@ -739,7 +740,7 @@ For permission events, the application must .BR write (2) a structure of the following form to the fanotify file descriptor: -.PP +.P .in +4n .EX struct fanotify_response { @@ -748,7 +749,7 @@ struct fanotify_response { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I fd @@ -762,7 +763,7 @@ Its value must be either to allow the file operation or .B FAN_DENY to deny the file operation. -.PP +.P If access is denied, the requesting application call will receive an .B EPERM error. @@ -786,19 +787,19 @@ field of the existing .B FAN_FS_ERROR event record, but details about the errors are lost. -.PP +.P Errors reported by .B FAN_FS_ERROR are generic .I errno values, but not all kinds of error types are reported by all filesystems. -.PP +.P Errors not directly related to a file (i.e. super block corruption) are reported with an invalid -.IR file_handle . +.IR handle . For these errors, the -.I file_handle +.I handle will have the field .I handle_type set to @@ -823,7 +824,7 @@ of process See .BR proc (5) for details. -.PP +.P Since Linux 5.13, .\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b the following interfaces can be used to control the amount of @@ -889,7 +890,7 @@ was specified in the argument when calling .BR fanotify_init (2) and an event occurred for a monitored file that is currently being executed. -.PP +.P In addition to the usual errors for .BR write (2), the following errors can occur when writing to the fanotify file descriptor: @@ -924,19 +925,19 @@ Fanotify reports only events that a user-space program triggers through the filesystem API. As a result, it does not catch remote events that occur on network filesystems. -.PP +.P The fanotify API does not report file accesses and modifications that may occur because of .BR mmap (2), .BR msync (2), and .BR munmap (2). -.PP +.P Events for directories are created only if the directory itself is opened, read, and closed. Adding, removing, or changing children of a marked directory does not create events for the monitored directory itself. -.PP +.P Fanotify monitoring of directories is not recursive: to monitor subdirectories under a directory, additional marks must be created. @@ -951,7 +952,7 @@ Monitoring mounts offers the capability to monitor a whole directory tree in a race-free manner. Monitoring filesystems offers the capability to monitor changes made from any mount of a filesystem instance in a race-free manner. -.PP +.P The event queue can overflow. In this case, events are lost. .SH BUGS @@ -965,7 +966,7 @@ calls to generate .B FAN_MODIFY events. -.PP +.P As of Linux 3.17, the following bugs exist: .IP \[bu] 3 @@ -1010,7 +1011,7 @@ and When a permission event occurs, a .B FAN_ALLOW response is given. -.PP +.P The following shell session shows an example of running this program. This session involved editing the file @@ -1022,7 +1023,7 @@ After the file was closed, a .B FAN_CLOSE_WRITE event occurred. Execution of the program ends when the user presses the ENTER key. -.PP +.P .in +4n .EX # \fB./fanotify_example /home\fP @@ -1240,10 +1241,10 @@ The event mask indicates which type of filesystem object\[em]either a file or a directory\[em]was created. Once all events have been read from the buffer and processed accordingly, the program simply terminates. -.PP +.P The following shell sessions show two different invocations of this program, with different actions performed on a watched object. -.PP +.P The first session shows a mark being placed on .IR /home/user . This is followed by the creation of a regular file, @@ -1254,7 +1255,7 @@ event being generated and reported against the file's parent watched directory object and with the created file name. Program execution ends once all events captured within the buffer have been processed. -.PP +.P .in +4n .EX # \fB./fanotify_fid /home/user\fP @@ -1267,7 +1268,7 @@ All events processed successfully. Program exiting. $ \fBtouch /home/user/testfile.txt\fP # In another terminal .EE .in -.PP +.P The second session shows a mark being placed on .IR /home/user . This is followed by the creation of a directory, @@ -1277,7 +1278,7 @@ This specific action results in a event being generated and is reported with the .B FAN_ONDIR flag set and with the created directory name. -.PP +.P .in +4n .EX # \fB./fanotify_fid /home/user\fP diff --git a/upstream/debian-unstable/man7/feature_test_macros.7 b/upstream/debian-unstable/man7/feature_test_macros.7 index 4e264d8c..d09c8166 100644 --- a/upstream/debian-unstable/man7/feature_test_macros.7 +++ b/upstream/debian-unstable/man7/feature_test_macros.7 @@ -2,13 +2,13 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH feature_test_macros 7 2023-07-15 "Linux man-pages 6.05.01" +.TH feature_test_macros 7 2024-05-02 "Linux man-pages 6.8" .SH NAME feature_test_macros \- feature test macros .SH DESCRIPTION Feature test macros allow the programmer to control the definitions that are exposed by system header files when a program is compiled. -.PP +.P .B NOTE: In order to be effective, a feature test macro .IR "must be defined before including any header files" . @@ -25,7 +25,7 @@ macro may have no effect because the header itself includes .I <xyz.h> (POSIX explicitly allows this): -.PP +.P .in +4n .EX #include <abc.h> @@ -33,12 +33,12 @@ itself includes #include <xyz.h> .EE .in -.PP +.P Some feature test macros are useful for creating portable applications, by preventing nonstandard definitions from being exposed. Other macros can be used to expose nonstandard definitions that are not exposed by default. -.PP +.P The precise effects of each of the feature test macros described below can be ascertained by inspecting the .I <features.h> @@ -56,23 +56,23 @@ the manual page SYNOPSIS typically includes a note of the following form (this example from the .BR acct (2) manual page): -.PP +.P .RS .B #include <unistd.h> -.PP +.P .BI "int acct(const char *" filename ); -.PP +.P .RS -4 .EX Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .EE .RE -.PP +.P .BR acct (): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) .RE -.PP +.P The .B || means that in order to obtain the declaration of @@ -82,44 +82,44 @@ from .I either of the following macro definitions must be made before including any header files: -.PP +.P .in +4n .EX #define _BSD_SOURCE #define _XOPEN_SOURCE /* or any value < 500 */ .EE .in -.PP +.P Alternatively, equivalent definitions can be included in the compilation command: -.PP +.P .in +4n .EX cc \-D_BSD_SOURCE cc \-D_XOPEN_SOURCE # Or any value < 500 .EE .in -.PP +.P Note that, as described below, .BR "some feature test macros are defined by default" , so that it may not always be necessary to explicitly specify the feature test macro(s) shown in the SYNOPSIS. -.PP +.P In a few cases, manual pages use a shorthand for expressing the feature test macro requirements (this example from .BR readahead (2)): -.PP +.P .RS +4 .EX .B #define _GNU_SOURCE .B #define _FILE_OFFSET_BITS 64 .B #include <fcntl.h> -.PP +.P .BI "ssize_t readahead(int " fd ", off_t *" offset ", size_t " count ); .EE .RE -.PP +.P This format is employed when the feature test macros ensure that the proper function declarations are visible, and the macros are not defined by default. @@ -128,7 +128,7 @@ The paragraphs below explain how feature test macros are handled in glibc 2.\fIx\fP, .I x > 0. -.PP +.P First, though, a summary of a few details for the impatient: .IP \[bu] 3 The macros that you most likely need to use in modern source code are @@ -193,7 +193,7 @@ _XOPEN_SOURCE >= 700 .\" The details in glibc 2.0 are simpler, but combining a .\" a description of them with the details in later glibc versions .\" would make for a complicated description. -.PP +.P glibc understands the following feature test macros: .TP .B __STRICT_ANSI__ @@ -683,7 +683,7 @@ and (200112L before glibc 2.10; 199506L before glibc 2.4; 199309L before glibc 2.1). -.PP +.P If any of .BR __STRICT_ANSI__ , .BR _ISOC99_SOURCE , @@ -705,7 +705,7 @@ is explicitly defined, then and .B _DEFAULT_SOURCE are not defined by default. -.PP +.P If .B _POSIX_SOURCE and @@ -722,7 +722,7 @@ is defined with the value 1; and .IP \[bu] .B _POSIX_C_SOURCE is defined with one of the following values: -.RS 3 +.RS .IP \[bu] 3 2, if @@ -760,7 +760,7 @@ depends on the glibc version: 200112L, since glibc 2.4 to glibc 2.9; and 200809L, since glibc 2.10. .RE -.PP +.P Multiple macros can be defined; the results are additive. .SH STANDARDS POSIX.1 specifies @@ -768,11 +768,11 @@ POSIX.1 specifies .BR _POSIX_SOURCE , and .BR _XOPEN_SOURCE . -.PP +.P .B _FILE_OFFSET_BITS is not specified by any standard, but is employed on some other implementations. -.PP +.P .BR _BSD_SOURCE , .BR _SVID_SOURCE , .BR _DEFAULT_SOURCE , @@ -793,7 +793,7 @@ Other systems have an analogous file, but typically with a different name. This header file is automatically included by other header files as required: it is not necessary to explicitly include it in order to employ feature test macros. -.PP +.P According to which of the above feature test macros are defined, .I <features.h> internally defines various other macros that are checked by @@ -811,7 +811,7 @@ feature test macros are set depending on the glibc version and what feature test macros are explicitly set. The following shell session, on a system with glibc 2.10, shows some examples of what we would see: -.PP +.P .in +4n .EX $ \fBcc ftm.c\fP @@ -929,9 +929,9 @@ main(int argc, char *argv[]) .BR libc (7), .BR standards (7), .BR system_data_types (7) -.PP +.P The section "Feature Test Macros" under .IR "info libc" . .\" But beware: the info libc document is out of date (Jul 07, mtk) -.PP +.P .I /usr/include/features.h diff --git a/upstream/debian-unstable/man7/fifo.7 b/upstream/debian-unstable/man7/fifo.7 index f27dcc76..80261c2c 100644 --- a/upstream/debian-unstable/man7/fifo.7 +++ b/upstream/debian-unstable/man7/fifo.7 @@ -4,7 +4,7 @@ .\" .\" 990620 - page created - aeb@cwi.nl .\" -.TH fifo 7 2023-07-15 "Linux man-pages 6.05.01" +.TH fifo 7 2024-05-02 "Linux man-pages 6.8" .SH NAME fifo \- first-in first-out special file, named pipe .SH DESCRIPTION @@ -19,14 +19,14 @@ Thus, the FIFO special file has no contents on the filesystem; the filesystem entry merely serves as a reference point so that processes can access the pipe using a name in the filesystem. -.PP +.P The kernel maintains exactly one pipe object for each FIFO special file that is opened by at least one process. The FIFO must be opened on both ends (reading and writing) before data can be passed. Normally, opening the FIFO blocks until the other end is opened also. -.PP +.P A process can open a FIFO in nonblocking mode. In this case, opening for read-only succeeds even if no one has @@ -35,7 +35,7 @@ fails with .B ENXIO (no such device or address) unless the other end has already been opened. -.PP +.P Under Linux, opening a FIFO for read and write will succeed both in blocking and nonblocking mode. POSIX leaves this @@ -48,12 +48,12 @@ with itself should be very careful to avoid deadlocks. .SH NOTES For details of the semantics of I/O on FIFOs, see .BR pipe (7). -.PP +.P When a process tries to write to a FIFO that is not opened for read on the other side, the process is sent a .B SIGPIPE signal. -.PP +.P FIFO special files can be created by .BR mkfifo (3), and are indicated by diff --git a/upstream/debian-unstable/man7/file-hierarchy.7 b/upstream/debian-unstable/man7/file-hierarchy.7 index 42d4d706..949d4bfe 100644 --- a/upstream/debian-unstable/man7/file-hierarchy.7 +++ b/upstream/debian-unstable/man7/file-hierarchy.7 @@ -1,5 +1,5 @@ '\" t -.TH "FILE\-HIERARCHY" "7" "" "systemd 255" "file-hierarchy" +.TH "FILE\-HIERARCHY" "7" "" "systemd 256~rc3" "file-hierarchy" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -763,14 +763,7 @@ T} .sp 1 .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBhier\fR(7), -\fBsystemd-path\fR(1), -\fBsystemd-gpt-auto-generator\fR(8), -\fBsysctl.d\fR(5), -\fBtmpfiles.d\fR(5), -\fBpkg-config\fR(1), -\fBsystemd.unit\fR(5) +\fBsystemd\fR(1), \fBhier\fR(7), \fBsystemd-path\fR(1), \fBsystemd-gpt-auto-generator\fR(8), \fBsysctl.d\fR(5), \fBtmpfiles.d\fR(5), \fBpkg-config\fR(1), \fBsystemd.unit\fR(5) .SH "NOTES" .IP " 1." 4 File System Hierarchy diff --git a/upstream/debian-unstable/man7/fips_module.7ssl b/upstream/debian-unstable/man7/fips_module.7ssl index 1545f13d..ef3598a3 100644 --- a/upstream/debian-unstable/man7/fips_module.7ssl +++ b/upstream/debian-unstable/man7/fips_module.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "FIPS_MODULE 7SSL" -.TH FIPS_MODULE 7SSL 2024-02-03 3.1.5 OpenSSL +.TH FIPS_MODULE 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -89,7 +89,7 @@ Any functions that create or modify custom "METHODS" (for example \&\fBEC_KEY_METHOD_new()\fR, etc.) .PP All of the above APIs are deprecated in OpenSSL 3.0 \- so a simple rule is to -avoid using all deprecated functions. See \fBmigration_guide\fR\|(7) for a list of +avoid using all deprecated functions. See \fBossl\-guide\-migration\fR\|(7) for a list of deprecated functions. .SS "Making all applications use the FIPS module by default" .IX Subsection "Making all applications use the FIPS module by default" @@ -443,7 +443,7 @@ explicitly loaded, the default provider will not automatically load. This means code using the default context by accident will fail because no algorithms will be available. .PP -See "Library Context" in \fBmigration_guide\fR\|(7) for additional information about the +See "Library Context" in \fBossl\-guide\-migration\fR\|(7) for additional information about the Library Context. .SS "Using Encoders and Decoders with the FIPS module" .IX Subsection "Using Encoders and Decoders with the FIPS module" @@ -547,7 +547,7 @@ want to operate in a FIPS approved manner. The algorithms are: .PD .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\fBmigration_guide\fR\|(7), \fBcrypto\fR\|(7), \fBfips_config\fR\|(5), +\&\fBossl\-guide\-migration\fR\|(7), \fBcrypto\fR\|(7), \fBfips_config\fR\|(5), <https://www.openssl.org/source/> .SH HISTORY .IX Header "HISTORY" diff --git a/upstream/debian-unstable/man7/futex.7 b/upstream/debian-unstable/man7/futex.7 index 233933b9..347b9b37 100644 --- a/upstream/debian-unstable/man7/futex.7 +++ b/upstream/debian-unstable/man7/futex.7 @@ -6,7 +6,7 @@ .\" .\" SPDX-License-Identifier: MIT .\" -.TH futex 7 2022-10-30 "Linux man-pages 6.05.01" +.TH futex 7 2024-05-02 "Linux man-pages 6.8" .SH NAME futex \- fast user-space locking .SH SYNOPSIS @@ -20,24 +20,24 @@ locking and semaphores. Futexes are very basic and lend themselves well for building higher-level locking abstractions such as mutexes, condition variables, read-write locks, barriers, and semaphores. -.PP +.P Most programmers will in fact not be using futexes directly but will instead rely on system libraries built on them, such as the Native POSIX Thread Library (NPTL) (see .BR pthreads (7)). -.PP +.P A futex is identified by a piece of memory which can be shared between processes or threads. In these different processes, the futex need not have identical addresses. In its bare form, a futex has semaphore semantics; it is a counter that can be incremented and decremented atomically; processes can wait for the value to become positive. -.PP +.P Futex operation occurs entirely in user space for the noncontended case. The kernel is involved only to arbitrate the contended case. As any sane design will strive for noncontention, futexes are also optimized for this situation. -.PP +.P In its bare form, a futex is an aligned integer which is touched only by atomic assembler instructions. This integer is four bytes long on all platforms. @@ -50,13 +50,13 @@ Any futex operation starts in user space, but it may be necessary to communicate with the kernel using the .BR futex (2) system call. -.PP +.P To "up" a futex, execute the proper assembler instructions that will cause the host CPU to atomically increment the integer. Afterward, check if it has in fact changed from 0 to 1, in which case there were no waiters and the operation is done. This is the noncontended case which is fast and should be common. -.PP +.P In the contended case, the atomic increment changed the counter from \-1 (or some other negative number). If this is detected, there are waiters. @@ -64,7 +64,7 @@ User space should now set the counter to 1 and instruct the kernel to wake up any waiters using the .B FUTEX_WAKE operation. -.PP +.P Waiting on a futex, to "down" it, is the reverse operation. Atomically decrement the counter and check if it changed to 0, in which case the operation is done and the futex was uncontended. @@ -73,7 +73,7 @@ and request that the kernel wait for another process to up the futex. This is done using the .B FUTEX_WAIT operation. -.PP +.P The .BR futex (2) system call can optionally be passed a timeout specifying how long @@ -95,12 +95,12 @@ abstraction for end users. Implementors are expected to be assembly literate and to have read the sources of the futex user-space library referenced below. -.PP +.P This man page illustrates the most common use of the .BR futex (2) primitives; it is by no means the only one. .\" .SH AUTHORS -.\" .PP +.\" .P .\" Futexes were designed and worked on by Hubertus Franke .\" (IBM Thomas J. Watson Research Center), .\" Matthew Kirkwood, Ingo Molnar (Red Hat) and @@ -113,7 +113,7 @@ primitives; it is by no means the only one. .BR set_robust_list (2), .BR set_tid_address (2), .BR pthreads (7) -.PP +.P .I Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux (proceedings of the Ottawa Linux Symposium 2002), futex example library, futex-*.tar.bz2 diff --git a/upstream/debian-unstable/man7/glob.7 b/upstream/debian-unstable/man7/glob.7 index c5c45771..ef1a4f29 100644 --- a/upstream/debian-unstable/man7/glob.7 +++ b/upstream/debian-unstable/man7/glob.7 @@ -4,7 +4,7 @@ .\" .\" 2003-08-24 fix for / by John Kristoff + joey .\" -.TH glob 7 2023-03-08 "Linux man-pages 6.05.01" +.TH glob 7 2024-05-02 "Linux man-pages 6.8" .SH NAME glob \- globbing pathnames .SH DESCRIPTION @@ -12,11 +12,11 @@ Long ago, in UNIX\ V6, there was a program .I /etc/glob that would expand wildcard patterns. Soon afterward this became a shell built-in. -.PP +.P These days there is also a library routine .BR glob (3) that will perform this function for a user program. -.PP +.P The rules are as follows (POSIX.2, 3.13). .SS Wildcard matching A string is a wildcard pattern if it contains one of the @@ -25,14 +25,14 @@ Globbing is the operation that expands a wildcard pattern into the list of pathnames matching the pattern. Matching is defined by: -.PP +.P A \[aq]?\[aq] (not between brackets) matches any single character. -.PP +.P A \[aq]*\[aq] (not between brackets) matches any string, including the empty string. -.PP +.P .B "Character classes" -.PP +.P An expression "\fI[...]\fP" where the first character after the leading \[aq][\[aq] is not an \[aq]!\[aq] matches a single character, namely any of the characters enclosed by the brackets. @@ -41,9 +41,9 @@ therefore \[aq]]\[aq] can be allowed between the brackets, provided that it is the first character. (Thus, "\fI[][!]\fP" matches the three characters \[aq][\[aq], \[aq]]\[aq], and \[aq]!\[aq].) -.PP +.P .B Ranges -.PP +.P There is one special convention: two characters separated by \[aq]\-\[aq] denote a range. (Thus, @@ -55,15 +55,15 @@ by making it the first or last character between the brackets. and "\fI[\-\-0]\fP" matches the three characters \[aq]\-\[aq], \[aq].\[aq], and \[aq]0\[aq], since \[aq]/\[aq] cannot be matched.) -.PP +.P .B Complementation -.PP +.P An expression "\fI[!...]\fP" matches a single character, namely any character that is not matched by the expression obtained by removing the first \[aq]!\[aq] from it. (Thus, "\fI[!]a\-]\fP" matches any single character except \[aq]]\[aq], \[aq]a\[aq], and \[aq]\-\[aq].) -.PP +.P One can remove the special meaning of \[aq]?\[aq], \[aq]*\[aq], and \[aq][\[aq] by preceding them by a backslash, or, @@ -79,7 +79,7 @@ A \[aq]/\[aq] in a pathname cannot be matched by a \[aq]?\[aq] or \[aq]*\[aq] wildcard, or by a range like "\fI[.\-0]\fP". A range containing an explicit \[aq]/\[aq] character is syntactically incorrect. (POSIX requires that syntactically incorrect patterns are left unchanged.) -.PP +.P If a filename starts with a \[aq].\[aq], this character must be matched explicitly. (Thus, \fIrm\ *\fP will not remove .profile, and \fItar\ c\ *\fP will not @@ -90,11 +90,11 @@ into the list of matching pathnames" was the original UNIX definition. It allowed one to have patterns that expand into an empty list, as in -.PP +.P .nf xv \-wait 0 *.gif *.jpg .fi -.PP +.P where perhaps no *.gif files are present (and this is not an error). However, POSIX requires that a wildcard pattern is left @@ -103,31 +103,31 @@ matching pathnames is empty. With .I bash one can force the classical behavior using this command: -.PP +.P .in +4n .EX shopt \-s nullglob .EE .in .\" In Bash v1, by setting allow_null_glob_expansion=true -.PP +.P (Similar problems occur elsewhere. For example, where old scripts have -.PP +.P .in +4n .EX rm \`find . \-name "*\[ti]"\` .EE .in -.PP +.P new scripts require -.PP +.P .in +4n .EX rm \-f nosuchfile \`find . \-name "*\[ti]"\` .EE .in -.PP +.P to avoid error messages from .I rm called with an empty argument list.) @@ -139,7 +139,7 @@ First of all, they match filenames, rather than text, and secondly, the conventions are not the same: for example, in a regular expression \[aq]*\[aq] means zero or more copies of the preceding thing. -.PP +.P Now that regular expressions have bracket expressions where the negation is indicated by a \[aq]\[ha]\[aq], POSIX has declared the effect of a wildcard pattern "\fI[\[ha]...]\fP" to be undefined. @@ -161,21 +161,21 @@ expression: namely (i) the negation, (ii) explicit single characters, and (iii) ranges. POSIX specifies ranges in an internationally more useful way and adds three more types: -.PP +.P (iii) Ranges X\-Y comprise all characters that fall between X and Y (inclusive) in the current collating sequence as defined by the .B LC_COLLATE category in the current locale. -.PP +.P (iv) Named character classes, like -.PP +.P .nf [:alnum:] [:alpha:] [:blank:] [:cntrl:] [:digit:] [:graph:] [:lower:] [:print:] [:punct:] [:space:] [:upper:] [:xdigit:] .fi -.PP +.P so that one can say "\fI[[:lower:]]\fP" instead of "\fI[a\-z]\fP", and have things work in Denmark, too, where there are three letters past \[aq]z\[aq] in the alphabet. @@ -183,13 +183,13 @@ These character classes are defined by the .B LC_CTYPE category in the current locale. -.PP +.P (v) Collating symbols, like "\fI[.ch.]\fP" or "\fI[.a-acute.]\fP", where the string between "\fI[.\fP" and "\fI.]\fP" is a collating element defined for the current locale. Note that this may be a multicharacter element. -.PP +.P (vi) Equivalence class expressions, like "\fI[=a=]\fP", where the string between "\fI[=\fP" and "\fI=]\fP" is any collating element from its equivalence class, as defined for the diff --git a/upstream/debian-unstable/man7/groff.7 b/upstream/debian-unstable/man7/groff.7 index 189d9e85..af308f4e 100644 --- a/upstream/debian-unstable/man7/groff.7 +++ b/upstream/debian-unstable/man7/groff.7 @@ -1,5 +1,5 @@ '\" t -.TH groff 7 "16 October 2023" "groff 1.23.0" +.TH groff 7 "30 April 2024" "groff 1.23.0" .SH Name groff \- GNU .I roff diff --git a/upstream/debian-unstable/man7/groff_char.7 b/upstream/debian-unstable/man7/groff_char.7 index 01781e94..1467d97f 100644 --- a/upstream/debian-unstable/man7/groff_char.7 +++ b/upstream/debian-unstable/man7/groff_char.7 @@ -1,5 +1,5 @@ '\" t -.TH groff_char 7 "16 October 2023" "groff 1.23.0" +.TH groff_char 7 "30 April 2024" "groff 1.23.0" .SH Name groff_char \- GNU .I roff diff --git a/upstream/debian-unstable/man7/groff_diff.7 b/upstream/debian-unstable/man7/groff_diff.7 index c8ef2a6c..a596eb68 100644 --- a/upstream/debian-unstable/man7/groff_diff.7 +++ b/upstream/debian-unstable/man7/groff_diff.7 @@ -1,5 +1,5 @@ '\" e -.TH groff_diff 7 "16 October 2023" "groff 1.23.0" +.TH groff_diff 7 "30 April 2024" "groff 1.23.0" .SH Name groff_diff \- differences between GNU .I roff diff --git a/upstream/debian-unstable/man7/groff_hdtbl.7 b/upstream/debian-unstable/man7/groff_hdtbl.7 index fadf10ae..e5bb9f7c 100644 --- a/upstream/debian-unstable/man7/groff_hdtbl.7 +++ b/upstream/debian-unstable/man7/groff_hdtbl.7 @@ -1,4 +1,4 @@ -.TH groff_hdtbl 7 "16 October 2023" "groff 1.23.0" +.TH groff_hdtbl 7 "30 April 2024" "groff 1.23.0" .SH Name groff_hdtbl \- Heidelberger table macros for GNU .I roff diff --git a/upstream/debian-unstable/man7/groff_man.7 b/upstream/debian-unstable/man7/groff_man.7 index 8fcd213f..e3f1a614 100644 --- a/upstream/debian-unstable/man7/groff_man.7 +++ b/upstream/debian-unstable/man7/groff_man.7 @@ -1,6 +1,6 @@ '\" t .\" This page is generated by m4 from tmac/groff_man.7.man.in. -.TH groff_man 7 "16 October 2023" "groff 1.23.0" +.TH groff_man 7 "30 April 2024" "groff 1.23.0" .SH Name groff_man \- compose manual pages with GNU .I roff diff --git a/upstream/debian-unstable/man7/groff_man_style.7 b/upstream/debian-unstable/man7/groff_man_style.7 index 47066e45..ce4c9001 100644 --- a/upstream/debian-unstable/man7/groff_man_style.7 +++ b/upstream/debian-unstable/man7/groff_man_style.7 @@ -1,6 +1,6 @@ '\" t .\" This page is generated by m4 from tmac/groff_man.7.man.in. -.TH groff_man_style 7 "16 October 2023" "groff 1.23.0" +.TH groff_man_style 7 "30 April 2024" "groff 1.23.0" .SH Name groff_man_style \- GNU .I roff diff --git a/upstream/debian-unstable/man7/groff_mdoc.7 b/upstream/debian-unstable/man7/groff_mdoc.7 index 1400dfc0..cda200e5 100644 --- a/upstream/debian-unstable/man7/groff_mdoc.7 +++ b/upstream/debian-unstable/man7/groff_mdoc.7 @@ -52,7 +52,7 @@ .cp 0 . . -.Dd 16 October 2023 +.Dd 30 April 2024 .Dt groff_mdoc 7 .Os groff 1.23.0 . diff --git a/upstream/debian-unstable/man7/groff_me.7 b/upstream/debian-unstable/man7/groff_me.7 index 639ae2d6..8f13747d 100644 --- a/upstream/debian-unstable/man7/groff_me.7 +++ b/upstream/debian-unstable/man7/groff_me.7 @@ -1,5 +1,5 @@ '\" t -.TH groff_me 7 "16 October 2023" "groff 1.23.0" +.TH groff_me 7 "30 April 2024" "groff 1.23.0" .SH Name groff_me \- \(lqme\(rq macro package for formatting .I roff diff --git a/upstream/debian-unstable/man7/groff_mm.7 b/upstream/debian-unstable/man7/groff_mm.7 index 40676b2d..5ed700e1 100644 --- a/upstream/debian-unstable/man7/groff_mm.7 +++ b/upstream/debian-unstable/man7/groff_mm.7 @@ -1,5 +1,5 @@ '\" t -.TH groff_mm 7 "16 October 2023" "groff 1.23.0" +.TH groff_mm 7 "30 April 2024" "groff 1.23.0" .SH Name groff_mm \- memorandum macros for GNU .I roff diff --git a/upstream/debian-unstable/man7/groff_mom.7 b/upstream/debian-unstable/man7/groff_mom.7 index e2927cf2..7881490b 100644 --- a/upstream/debian-unstable/man7/groff_mom.7 +++ b/upstream/debian-unstable/man7/groff_mom.7 @@ -1,4 +1,4 @@ -.TH groff_mom 7 "16 October 2023" "groff 1.23.0" +.TH groff_mom 7 "30 April 2024" "groff 1.23.0" .SH Name groff_mom \- modern macros for document composition with GNU .I roff diff --git a/upstream/debian-unstable/man7/groff_ms.7 b/upstream/debian-unstable/man7/groff_ms.7 index eef75cff..034327d6 100644 --- a/upstream/debian-unstable/man7/groff_ms.7 +++ b/upstream/debian-unstable/man7/groff_ms.7 @@ -1,5 +1,5 @@ '\" t -.TH groff_ms 7 "16 October 2023" "groff 1.23.0" +.TH groff_ms 7 "30 April 2024" "groff 1.23.0" .SH Name groff_ms \- GNU .I roff diff --git a/upstream/debian-unstable/man7/groff_rfc1345.7 b/upstream/debian-unstable/man7/groff_rfc1345.7 index 7f65a666..9ef7f657 100644 --- a/upstream/debian-unstable/man7/groff_rfc1345.7 +++ b/upstream/debian-unstable/man7/groff_rfc1345.7 @@ -1,4 +1,4 @@ -.TH groff_rfc1345 7 "16 October 2023" "groff 1.23.0" +.TH groff_rfc1345 7 "30 April 2024" "groff 1.23.0" .SH Name groff_rfc1345 \- special character names from RFC 1345 and Vim digraphs . diff --git a/upstream/debian-unstable/man7/groff_trace.7 b/upstream/debian-unstable/man7/groff_trace.7 index c38f5c13..77551d91 100644 --- a/upstream/debian-unstable/man7/groff_trace.7 +++ b/upstream/debian-unstable/man7/groff_trace.7 @@ -1,4 +1,4 @@ -.TH groff_trace 7 "16 October 2023" "groff 1.23.0" +.TH groff_trace 7 "30 April 2024" "groff 1.23.0" .SH Name groff_trace \- macros for debugging GNU .I roff diff --git a/upstream/debian-unstable/man7/groff_www.7 b/upstream/debian-unstable/man7/groff_www.7 index 1bc16898..42bc8867 100644 --- a/upstream/debian-unstable/man7/groff_www.7 +++ b/upstream/debian-unstable/man7/groff_www.7 @@ -1,4 +1,4 @@ -.TH groff_www 7 "16 October 2023" "groff 1.23.0" +.TH groff_www 7 "30 April 2024" "groff 1.23.0" .SH Name groff_www \- GNU .I roff diff --git a/upstream/debian-unstable/man7/hier.7 b/upstream/debian-unstable/man7/hier.7 index 314d28a9..5c56e5e2 100644 --- a/upstream/debian-unstable/man7/hier.7 +++ b/upstream/debian-unstable/man7/hier.7 @@ -8,7 +8,7 @@ .\" Modified Mon Feb 6 16:41:00 1999 by Nicolás Lichtmaier <nick@debian.org> .\" Modified Tue Feb 8 16:46:45 2000 by Chris Pepper <pepper@tgg.com> .\" Modified Fri Sep 7 20:32:45 2001 by Tammy Fox <tfox@redhat.com> -.TH hier 7 2023-04-18 "Linux man-pages 6.05.01" +.TH hier 7 2024-05-02 "Linux man-pages 6.8" .SH NAME hier \- description of the filesystem hierarchy .SH DESCRIPTION @@ -650,5 +650,5 @@ different distributions and systems may be configured differently. .BR proc (5), .BR file\-hierarchy (7), .BR mount (8) -.PP +.P The Filesystem Hierarchy Standard diff --git a/upstream/debian-unstable/man7/hostname.7 b/upstream/debian-unstable/man7/hostname.7 index 60940ba0..d2ce2b12 100644 --- a/upstream/debian-unstable/man7/hostname.7 +++ b/upstream/debian-unstable/man7/hostname.7 @@ -8,14 +8,14 @@ .\" .\" 2008-06-11, mtk, Taken from FreeBSD 6.2 and modified for Linux. .\" -.TH hostname 7 2022-10-30 "Linux man-pages 6.05.01" +.TH hostname 7 2024-05-02 "Linux man-pages 6.8" .SH NAME hostname \- hostname resolution description .SH DESCRIPTION Hostnames are domains, where a domain is a hierarchical, dot-separated list of subdomains; for example, the machine "monet", in the "example" subdomain of the "com" domain would be represented as "monet.example.com". -.PP +.P Each element of the hostname must be from 1 to 63 characters long and the entire hostname, including the dots, can be at most 253 characters long. Valid characters for hostnames are @@ -30,24 +30,24 @@ to .IR 9 , and the hyphen (\-). A hostname may not start with a hyphen. -.PP +.P Hostnames are often used with network client and server programs, which must generally translate the name to an address for use. (This task is generally performed by either .BR getaddrinfo (3) or the obsolete .BR gethostbyname (3).) -.PP +.P Hostnames are resolved by the NSS framework in glibc according to the .B hosts configuration in -.BR nsswitch.conf . +.BR nsswitch.conf (5). The DNS-based name resolver (in the .B dns NSS service module) resolves them in the following fashion. -.PP +.P If the name consists of a single component, that is, contains no dot, and if the environment variable .B HOSTALIASES @@ -60,11 +60,11 @@ to be substituted for that alias. If a case-insensitive match is found between the hostname to be resolved and the first field of a line in the file, the substituted name is looked up with no further processing. -.PP +.P If the input name ends with a trailing dot, the trailing dot is removed, and the remaining name is looked up with no further processing. -.PP +.P If the input name does not end with a trailing dot, it is looked up by searching through a list of domains until a match is found. The default search list includes first the local domain, @@ -84,11 +84,11 @@ by a system-wide configuration file (see .BR resolver (5), .BR mailaddr (7), .BR named (8) -.PP +.P .UR http://www.ietf.org\:/rfc\:/rfc1123.txt IETF RFC\ 1123 .UE -.PP +.P .UR http://www.ietf.org\:/rfc\:/rfc1178.txt IETF RFC\ 1178 .UE diff --git a/upstream/debian-unstable/man7/hwdb.7 b/upstream/debian-unstable/man7/hwdb.7 index cf1e66f5..2b8665ee 100644 --- a/upstream/debian-unstable/man7/hwdb.7 +++ b/upstream/debian-unstable/man7/hwdb.7 @@ -1,5 +1,5 @@ '\" t -.TH "HWDB" "7" "" "systemd 255" "hwdb" +.TH "HWDB" "7" "" "systemd 256~rc3" "hwdb" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/upstream/debian-unstable/man7/icmp.7 b/upstream/debian-unstable/man7/icmp.7 index cd54614d..3c643a1b 100644 --- a/upstream/debian-unstable/man7/icmp.7 +++ b/upstream/debian-unstable/man7/icmp.7 @@ -5,7 +5,7 @@ .\" .\" $Id: icmp.7,v 1.6 2000/08/14 08:03:45 ak Exp $ .\" -.TH icmp 7 2023-07-15 "Linux man-pages 6.05.01" +.TH icmp 7 2024-05-02 "Linux man-pages 6.8" .SH NAME icmp \- Linux IPv4 ICMP kernel module. .SH DESCRIPTION @@ -16,7 +16,7 @@ The user doesn't interact directly with this module; instead it communicates with the other protocols in the kernel and these pass the ICMP errors to the application layers. The kernel ICMP module also answers ICMP requests. -.PP +.P A user protocol may receive ICMP packets for all local sockets by opening a raw socket with the protocol .BR IPPROTO_ICMP . @@ -28,7 +28,7 @@ The types of ICMP packets passed to the socket can be filtered using the socket option. ICMP packets are always processed by the kernel too, even when passed to a user socket. -.PP +.P Linux limits the rate of ICMP error packets to each destination. .B ICMP_REDIRECT and @@ -143,7 +143,7 @@ H Address Mask Request I Address Mask Reply .TE .RE -.PP +.P The bits marked with an asterisk are rate limited by default (see the default mask above). .TP @@ -163,7 +163,7 @@ means no group is allowed to create ICMP Echo sockets. Support for the .B ICMP_ADDRESS request was removed in Linux 2.2. -.PP +.P Support for .B ICMP_SOURCE_QUENCH was removed in Linux 2.2. @@ -173,18 +173,18 @@ As many other implementations don't support raw sockets, this feature should not be relied on in portable programs. .\" not really true ATM -.\" .PP +.\" .P .\" Linux ICMP should be compliant to RFC 1122. -.PP +.P .B ICMP_REDIRECT packets are not sent when Linux is not acting as a router. They are also accepted only from the old gateway defined in the routing table and the redirect routes are expired after some time. -.PP +.P The 64-bit timestamp returned by .B ICMP_TIMESTAMP is in milliseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). -.PP +.P Linux ICMP internally uses a raw socket to send ICMPs. This raw socket may appear in .BR netstat (8) @@ -192,5 +192,5 @@ output with a zero inode. .SH SEE ALSO .BR ip (7), .BR rdisc (8) -.PP +.P RFC\ 792 for a description of the ICMP protocol. diff --git a/upstream/debian-unstable/man7/inode.7 b/upstream/debian-unstable/man7/inode.7 index 3cbdeeea..61936472 100644 --- a/upstream/debian-unstable/man7/inode.7 +++ b/upstream/debian-unstable/man7/inode.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH inode 7 2023-07-30 "Linux man-pages 6.05.01" +.TH inode 7 2024-05-02 "Linux man-pages 6.8" .SH NAME inode \- file inode information .SH DESCRIPTION @@ -17,7 +17,7 @@ structure, or which returns a .I statx structure. -.PP +.P The following is a list of the information typically found in, or associated with, the file inode, with the names of the corresponding structure fields returned by @@ -56,7 +56,6 @@ Additional links to an existing file are created using .BR link (2). .TP User ID -.I st_uid \fIstat.st_uid\fP; \fIstatx.stx_uid\fP .IP This field records the user ID of the owner of the file. @@ -99,7 +98,7 @@ This field gives the "preferred" blocksize for efficient filesystem I/O. an inefficient read-modify-rewrite.) .TP Number of blocks allocated to the file -\fIstat.st_blocks\fP; \fIstatx.stx_size\fP +\fIstat.st_blocks\fP; \fIstatx.stx_blocks\fP .IP This field indicates the number of blocks allocated to the file, 512-byte units, @@ -185,12 +184,12 @@ Last status change timestamp (ctime) This is the file's last status change timestamp. It is changed by writing or by setting inode information (i.e., owner, group, link count, mode, etc.). -.PP +.P The timestamp fields report time measured with a zero point at the .IR Epoch , 1970-01-01 00:00:00 +0000, UTC (see .BR time (7)). -.PP +.P Nanosecond timestamps are supported on XFS, JFS, Btrfs, and ext4 (since Linux 2.6.23). .\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80 @@ -221,7 +220,7 @@ field (for the .I statx.stx_mode field) contains the file type and mode. -.PP +.P POSIX refers to the .I stat.st_mode bits corresponding to the mask @@ -232,7 +231,7 @@ the 12 bits corresponding to the mask 07777 as the .I file mode bits and the least significant 9 bits (0777) as the .IR "file permission bits" . -.PP +.P The following mask values are defined for the file type: .in +4n .TS @@ -248,9 +247,9 @@ S_IFCHR 0020000 character device S_IFIFO 0010000 FIFO .TE .in -.PP +.P Thus, to test for a regular file (for example), one could write: -.PP +.P .in +4n .EX stat(pathname, &sb); @@ -259,7 +258,7 @@ if ((sb.st_mode & S_IFMT) == S_IFREG) { } .EE .in -.PP +.P Because tests of the above form are common, additional macros are defined by POSIX to allow the test of the file type in .I st_mode @@ -287,9 +286,9 @@ symbolic link? (Not in POSIX.1-1996.) .BR S_ISSOCK (m) socket? (Not in POSIX.1-1996.) .RE -.PP +.P The preceding code snippet could thus be rewritten as: -.PP +.P .in +4n .EX stat(pathname, &sb); @@ -298,7 +297,7 @@ if (S_ISREG(sb.st_mode)) { } .EE .in -.PP +.P The definitions of most of the above file type test macros are provided if any of the following feature test macros is defined: .B _BSD_SOURCE @@ -315,7 +314,7 @@ and are provided if .B _XOPEN_SOURCE is defined. -.PP +.P The definition of .B S_IFSOCK can also be exposed either by defining @@ -324,7 +323,7 @@ with a value of 500 or greater or (since glibc 2.24) by defining both .B _XOPEN_SOURCE and .BR _XOPEN_SOURCE_EXTENDED . -.PP +.P The definition of .BR S_ISSOCK () is exposed if any of the following feature test macros is defined: @@ -339,7 +338,7 @@ with a value of 200112L or greater, or (since glibc 2.24) by defining both .B _XOPEN_SOURCE and .BR _XOPEN_SOURCE_EXTENDED . -.PP +.P The following mask values are defined for the file mode component of the .I st_mode @@ -397,7 +396,7 @@ others have execute permission T} .TE .in -.PP +.P The set-group-ID bit .RB ( S_ISGID ) has several special uses. @@ -414,7 +413,7 @@ For a file that does not have the group execution bit .RB ( S_IXGRP ) set, the set-group-ID bit indicates mandatory file/record locking. -.PP +.P The sticky bit .RB ( S_ISVTX ) on a directory means that a file @@ -425,7 +424,7 @@ process. POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P POSIX.1-1990 did not describe the .BR S_IFMT , .BR S_IFSOCK , @@ -441,7 +440,7 @@ constants, but instead specified the use of the macros .BR S_ISDIR () and so on. -.PP +.P The .BR S_ISLNK () and @@ -449,7 +448,7 @@ and macros were not in POSIX.1-1996; the former is from SVID 4, the latter from SUSv2. -.PP +.P UNIX\ V7 (and later systems) had .BR S_IREAD , .BR S_IWRITE , diff --git a/upstream/debian-unstable/man7/inotify.7 b/upstream/debian-unstable/man7/inotify.7 index 73a6ab05..ac612087 100644 --- a/upstream/debian-unstable/man7/inotify.7 +++ b/upstream/debian-unstable/man7/inotify.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH inotify 7 2023-07-08 "Linux man-pages 6.05.01" +.TH inotify 7 2024-05-02 "Linux man-pages 6.8" .SH NAME inotify \- monitoring filesystem events .SH DESCRIPTION @@ -14,7 +14,7 @@ Inotify can be used to monitor individual files, or to monitor directories. When a directory is monitored, inotify will return events for the directory itself, and for files inside the directory. -.PP +.P The following system calls are used with this API: .IP \[bu] 3 .BR inotify_init (2) @@ -56,7 +56,7 @@ instance have been closed (using the underlying object and its resources are freed for reuse by the kernel; all associated watches are automatically freed. -.PP +.P With careful programming, an application can use inotify to efficiently monitor and cache the state of a set of filesystem objects. @@ -78,11 +78,11 @@ in which case the call fails with the error .BR EINTR ; see .BR signal (7)). -.PP +.P Each successful .BR read (2) returns a buffer containing one or more of the following structures: -.PP +.P .in +4n .EX struct inotify_event { @@ -99,15 +99,15 @@ struct inotify_event { }; .EE .in -.PP +.P .I wd identifies the watch for which this event occurs. It is one of the watch descriptors returned by a previous call to .BR inotify_add_watch (2). -.PP +.P .I mask contains bits that describe the event that occurred (see below). -.PP +.P .I cookie is a unique integer that connects related events. Currently, this is used only for rename events, and @@ -119,7 +119,7 @@ events to be connected by the application. For all other event types, .I cookie is set to 0. -.PP +.P The .I name field is present only when an event is returned @@ -128,7 +128,7 @@ it identifies the filename within the watched directory. This filename is null-terminated, and may include further null bytes (\[aq]\e0\[aq]) to align subsequent reads to a suitable address boundary. -.PP +.P The .I len field counts all of the bytes in @@ -138,7 +138,7 @@ the length of each .I inotify_event structure is thus .IR "sizeof(struct inotify_event)+len" . -.PP +.P The behavior when the buffer given to .BR read (2) is too small to return information about the next event depends @@ -149,13 +149,13 @@ returns 0; since Linux 2.6.21, fails with the error .BR EINVAL . Specifying a buffer of size -.PP +.P .in +4n .EX sizeof(struct inotify_event) + NAME_MAX + 1 .EE .in -.PP +.P will be sufficient to read at least one event. .SS inotify events The @@ -252,12 +252,12 @@ when a file is renamed. .BR IN_OPEN " (*)" File or directory was opened. .RE -.PP +.P Inotify monitoring is inode-based: when monitoring a file (but not when monitoring the directory containing a file), an event can be generated for activity on any link to the file (in the same or a different directory). -.PP +.P When monitoring a directory: .IP \[bu] 3 the events marked above with an asterisk (*) can occur both @@ -265,19 +265,19 @@ for the directory itself and for objects inside the directory; and .IP \[bu] the events marked with a plus sign (+) occur only for objects inside the directory (not for the directory itself). -.PP +.P .IR Note : when monitoring a directory, events are not generated for the files inside the directory when the events are performed via a pathname (i.e., a link) that lies outside the monitored directory. -.PP +.P When events are generated for objects inside a watched directory, the .I name field in the returned .I inotify_event structure identifies the name of the file within the directory. -.PP +.P The .B IN_ALL_EVENTS macro is defined as a bit mask of all of the above events. @@ -285,7 +285,7 @@ This macro can be used as the .I mask argument when calling .BR inotify_add_watch (2). -.PP +.P Two additional convenience macros are defined: .RS 4 .TP @@ -297,7 +297,7 @@ Equates to Equates to .BR "IN_CLOSE_WRITE | IN_CLOSE_NOWRITE" . .RE -.PP +.P The following further bits can be specified in .I mask when calling @@ -372,7 +372,7 @@ and multiple calls to .BR inotify_add_watch (2) without this flag may clobber existing watch masks. .RE -.PP +.P The following bits may be set in the .I mask field returned by @@ -449,7 +449,7 @@ events for both and .IR dir/myfile . .RE -.PP +.P Suppose an application is watching the directories .I dir1 and @@ -490,7 +490,7 @@ events will have the same .I cookie value. .RE -.PP +.P Suppose that .I dir1/xx and @@ -529,7 +529,7 @@ and an event for .IR dir1 . .RE -.PP +.P Suppose an application is watching the directory .I dir and (the empty) directory @@ -592,7 +592,7 @@ Inotify file descriptors can be monitored using and .BR epoll (7). When an event is available, the file descriptor indicates as readable. -.PP +.P Since Linux 2.6.25, signal-driven I/O notification is available for inotify file descriptors; see the discussion of @@ -621,7 +621,7 @@ and .B POLLIN is set in .IR si_band . -.PP +.P If successive output inotify events produced on the inotify file descriptor are identical (same .IR wd , @@ -634,13 +634,13 @@ older event has not yet been read (but see BUGS). This reduces the amount of kernel memory required for the event queue, but also means that an application can't use inotify to reliably count file events. -.PP +.P The events returned by reading from an inotify file descriptor form an ordered queue. Thus, for example, it is guaranteed that when renaming from one directory to another, events will be produced in the correct order on the inotify file descriptor. -.PP +.P The set of watch descriptors that is being monitored via an inotify file descriptor can be viewed via the entry for the inotify file descriptor in the process's @@ -661,7 +661,7 @@ In particular, there is no easy way for a process that is monitoring events via inotify to distinguish events that it triggers itself from those that are triggered by other processes. -.PP +.P Inotify reports only events that a user-space program triggers through the filesystem API. As a result, it does not catch remote events that occur @@ -674,28 +674,28 @@ Furthermore, various pseudo-filesystems such as and .I /dev/pts are not monitorable with inotify. -.PP +.P The inotify API does not report file accesses and modifications that may occur because of .BR mmap (2), .BR msync (2), and .BR munmap (2). -.PP +.P The inotify API identifies affected files by filename. However, by the time an application processes an inotify event, the filename may already have been deleted or renamed. -.PP +.P The inotify API identifies events via watch descriptors. It is the application's responsibility to cache a mapping (if one is needed) between watch descriptors and pathnames. Be aware that directory renamings may affect multiple cached pathnames. -.PP +.P Inotify monitoring of directories is not recursive: to monitor subdirectories under a directory, additional watches must be created. This can take a significant amount time for large directory trees. -.PP +.P If monitoring an entire directory subtree, and a new subdirectory is created in that tree or an existing directory is renamed into that tree, @@ -704,7 +704,7 @@ new files (and subdirectories) may already exist inside the subdirectory. Therefore, you may want to scan the contents of the subdirectory immediately after adding the watch (and, if desired, recursively add watches for any subdirectories that it contains). -.PP +.P Note that the event queue can overflow. In this case, events are lost. Robust applications should handle the possibility of @@ -716,7 +716,7 @@ approach is to close the inotify file descriptor, empty the cache, create a new inotify file descriptor, and then re-create watches and cache entries for the objects to be monitored.) -.PP +.P If a filesystem is mounted on top of a monitored directory, no event is generated, and no events are generated for objects immediately under the new mount point. @@ -733,7 +733,7 @@ event pair that is generated by .BR rename (2) can be matched up via their shared cookie value. However, the task of matching has some challenges. -.PP +.P These two events are usually consecutive in the event stream available when reading from the inotify file descriptor. However, this is not guaranteed. @@ -750,7 +750,7 @@ inserted into the queue: there may be a brief interval where the has appeared, but the .B IN_MOVED_TO has not. -.PP +.P Matching up the .B IN_MOVED_FROM and @@ -775,7 +775,7 @@ then those watch descriptors will be inconsistent with the watch descriptors in any pending events. (Re-creating the inotify file descriptor and rebuilding the cache may be useful to deal with this scenario.) -.PP +.P Applications should also allow for the possibility that the .B IN_MOVED_FROM event was the last event that could fit in the buffer @@ -803,7 +803,7 @@ calls to generate .B IN_MODIFY events. -.PP +.P .\" FIXME . kernel commit 611da04f7a31b2208e838be55a42c7a1310ae321 .\" implies that unmount events were buggy since Linux 2.6.11 to Linux 2.6.36 .\" @@ -811,7 +811,7 @@ Before Linux 2.6.16, the .B IN_ONESHOT .I mask flag does not work. -.PP +.P As originally designed and implemented, the .B IN_ONESHOT flag did not cause an @@ -821,7 +821,7 @@ However, as an unintended effect of other changes, since Linux 2.6.36, an .B IN_IGNORED event is generated in this case. -.PP +.P Before Linux 2.6.25, .\" commit 1c17d18e3775485bf1e0ce79575eb637a94494a2 the kernel code that was intended to coalesce successive identical events @@ -830,7 +830,7 @@ if the older had not yet been read) instead checked if the most recent event could be coalesced with the .I oldest unread event. -.PP +.P When a watch descriptor is removed by calling .BR inotify_rm_watch (2) (or because a watch file is deleted or the filesystem @@ -868,7 +868,7 @@ and waits for events of type .BR IN_CLOSE_NOWRITE , and .BR IN_CLOSE_WRITE . -.PP +.P The following output was recorded while editing the file .I /home/user/temp/foo and listing directory @@ -1095,6 +1095,6 @@ main(int argc, char* argv[]) .BR read (2), .BR stat (2), .BR fanotify (7) -.PP +.P .I Documentation/filesystems/inotify.txt in the Linux kernel source tree diff --git a/upstream/debian-unstable/man7/intro.7 b/upstream/debian-unstable/man7/intro.7 index e12ff9d0..dbae9d32 100644 --- a/upstream/debian-unstable/man7/intro.7 +++ b/upstream/debian-unstable/man7/intro.7 @@ -6,7 +6,7 @@ .\" .\" Modified by Thomas Koenig (ig25@rz.uni-karlsruhe.de) 24 Apr 1993 .\" Modified Sat Jul 24 17:28:08 1993 by Rik Faith (faith@cs.unc.edu) -.TH intro 7 2022-10-30 "Linux man-pages 6.05.01" +.TH intro 7 2024-05-02 "Linux man-pages 6.8" .SH NAME intro \- introduction to overview and miscellany section .SH DESCRIPTION diff --git a/upstream/debian-unstable/man7/ip.7 b/upstream/debian-unstable/man7/ip.7 index d96afc71..8975394c 100644 --- a/upstream/debian-unstable/man7/ip.7 +++ b/upstream/debian-unstable/man7/ip.7 @@ -35,7 +35,7 @@ .\" commit 76e21053b5bf33a07c76f99d27a74238310e3c71 .\" Author: Erich E. Hoover <ehoover@mines.edu> .\" -.TH ip 7 2023-07-15 "Linux man-pages 6.05.01" +.TH ip 7 2024-05-02 "Linux man-pages 6.8" .SH NAME ip \- Linux IPv4 protocol implementation .SH SYNOPSIS @@ -45,7 +45,7 @@ ip \- Linux IPv4 protocol implementation .\" .B #include <linux/errqueue.h> -- never include <linux/foo.h> .B #include <netinet/in.h> .B #include <netinet/ip.h> \fR/* superset of previous */ -.PP +.P .IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);" .IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" .IB raw_socket " = socket(AF_INET, SOCK_RAW, " protocol ");" @@ -56,20 +56,20 @@ described in RFC\ 791 and RFC\ 1122. .B ip contains a level 2 multicasting implementation conforming to RFC\ 1112. It also contains an IP router including a packet filter. -.PP +.P The programming interface is BSD-sockets compatible. For more information on sockets, see .BR socket (7). -.PP +.P An IP socket is created using .BR socket (2): -.PP +.P .in +4n .EX socket(AF_INET, socket_type, protocol); .EE .in -.PP +.P Valid socket types include .B SOCK_STREAM to open a stream socket, @@ -79,7 +79,7 @@ to open a datagram socket, and to open a .BR raw (7) socket to access the IP protocol directly. -.PP +.P .I protocol is the IP protocol in the IP header to be received or sent. Valid values for @@ -107,12 +107,12 @@ stream sockets; and for .BR udplite (7) datagram sockets. -.PP +.P For .B SOCK_RAW you may specify a valid IANA IP protocol defined in RFC\ 1700 assigned numbers. -.PP +.P When a process wants to receive new incoming packets or connections, it should bind a socket to a local interface address using .BR bind (2). @@ -134,7 +134,7 @@ is called on an unbound socket, the socket is automatically bound to a random free port or to a usable shared port with the local address set to .BR INADDR_ANY . -.PP +.P A TCP local socket address that has been bound is unavailable for some time after closing, unless the .B SO_REUSEADDR @@ -151,7 +151,7 @@ and On raw sockets .I sin_port is set to the IP protocol. -.PP +.P .in +4n .EX struct sockaddr_in { @@ -166,7 +166,7 @@ struct in_addr { }; .EE .in -.PP +.P .I sin_family is always set to .BR AF_INET . @@ -190,7 +190,7 @@ port, they are implemented only by higher protocols like .BR tcp (7) and .BR udp (7). -.PP +.P .I sin_addr is the IP host address. The @@ -212,7 +212,7 @@ or set using the .BR inet_makeaddr (3) library functions or directly with the name resolver (see .BR gethostbyname (3)). -.PP +.P IPv4 addresses are divided into unicast, broadcast, and multicast addresses. Unicast addresses specify a single interface of a host, @@ -224,7 +224,7 @@ socket flag is set. In the current implementation, connection-oriented sockets are allowed to use only unicast addresses. .\" Leave a loophole for XTP @) -.PP +.P Note that the address and the port are always stored in network byte order. In particular, this means that you need to call @@ -275,7 +275,7 @@ Since Linux 5.14, .\" commit 58fee5fc83658aaacf60246aeab738946a9ba516 it is treated as an ordinary unicast address and can be assigned to an interface. -.PP +.P Internet standards have traditionally also reserved various addresses for particular uses, though Linux no longer treats some of these specially. @@ -314,7 +314,7 @@ The socket option level for IP is .BR IPPROTO_IP . .\" or SOL_IP on Linux A boolean integer flag is zero when it is false, otherwise true. -.PP +.P When an invalid socket option is specified, .BR getsockopt (2) and @@ -607,7 +607,7 @@ IP_PMTUDISC_DONT:Never do Path MTU Discovery. IP_PMTUDISC_DO:Always do Path MTU Discovery. IP_PMTUDISC_PROBE:Set DF but ignore Path MTU. .TE -.sp 1 +.IP When PMTU discovery is enabled, the kernel automatically keeps track of the path MTU per destination host. When it is connected to a specific peer with @@ -828,6 +828,10 @@ is not zero, the primary local address of the interface specified by the index overwrites .I ipi_spec_dst for the routing table lookup. +.IP +Not supported for +.B SOCK_STREAM +sockets. .TP .BR IP_RECVERR " (since Linux 2.2)" .\" Precisely: since Linux 2.1.15 @@ -989,6 +993,9 @@ in which the kernel returns the original destination address of the datagram being received. The ancillary message contains a .IR "struct sockaddr_in" . +Not supported for +.B SOCK_STREAM +sockets. .TP .BR IP_RECVTOS " (since Linux 2.2)" .\" Precisely: since Linux 2.1.68 @@ -998,6 +1005,9 @@ ancillary message is passed with incoming packets. It contains a byte which specifies the Type of Service/Precedence field of the packet header. Expects a boolean integer flag. +Not supported for +.B SOCK_STREAM +sockets. .TP .BR IP_RECVTTL " (since Linux 2.2)" .\" Precisely: since Linux 2.1.68 @@ -1015,6 +1025,9 @@ Identical to .BR IP_RECVOPTS , but returns raw unprocessed options with timestamp and route record options not filled in for this hop. +Not supported for +.B SOCK_STREAM +sockets. .TP .BR IP_ROUTER_ALERT " (since Linux 2.2)" .\" Precisely: since Linux 2.1.68 @@ -1287,7 +1300,9 @@ Time in seconds to keep an IPv6 fragment in memory. Regeneration interval (in seconds) of the hash secret (or lifetime for the hash secret) for IPv6 fragments. .TP -.IR ipfrag_high_thresh " (integer), " ipfrag_low_thresh " (integer)" +.IR ipfrag_high_thresh " (integer)" +.TQ +.IR ipfrag_low_thresh " (integer)" If the amount of queued IP fragments reaches .IR ipfrag_high_thresh , the queue is pruned down to @@ -1305,7 +1320,7 @@ All ioctls described in .BR socket (7) apply to .BR ip . -.PP +.P Ioctls to configure generic device parameters are described in .BR netdevice (7). .\" FIXME Add a discussion of multicasting @@ -1365,7 +1380,9 @@ was called on an already connected socket. .B EMSGSIZE Datagram is bigger than an MTU on the path and it cannot be fragmented. .TP -.BR ENOBUFS ", " ENOMEM +.B ENOBUFS +.TQ +.B ENOMEM Not enough free memory. This often means that the memory allocation is limited by the socket buffer limits, not by the system memory, but this is not 100% consistent. @@ -1393,7 +1410,7 @@ The connection was unexpectedly closed or shut down by the other end. .TP .B ESOCKTNOSUPPORT The socket is not configured or an unknown socket type was requested. -.PP +.P Other errors may be generated by the overlaying protocols; see .BR tcp (7), .BR raw (7), @@ -1415,7 +1432,7 @@ and are Linux-specific. .\" IP_XFRM_POLICY is Linux-specific .\" IP_IPSEC_POLICY is a nonstandard extension, also present on some BSDs -.PP +.P Be very careful with the .B SO_BROADCAST option \- it is not privileged in Linux. @@ -1428,7 +1445,7 @@ See RFC 6762 for an example of a protocol (mDNS) using the more modern multicast approach to communicating with an open-ended group of hosts on the local network. -.PP +.P Some other BSD sockets implementations provide .B IP_RCVDSTADDR and @@ -1438,7 +1455,7 @@ received datagrams. Linux has the more general .B IP_PKTINFO for the same task. -.PP +.P Some BSD sockets implementations also provide an .B IP_RECVTTL option, but an ancillary message with type @@ -1447,13 +1464,13 @@ is passed with the incoming packet. This is different from the .B IP_TTL option used in Linux. -.PP +.P Using the .B SOL_IP socket options level isn't portable; BSD-based stacks use the .B IPPROTO_IP level. -.PP +.P .B INADDR_ANY (0.0.0.0) and .B INADDR_BROADCAST @@ -1476,7 +1493,7 @@ address structure for generic link layer information instead of the old .BR sockaddr_pkt . .SH BUGS There are too many inconsistent error values. -.PP +.P The error used to diagnose exhaustion of the ephemeral port range differs across the various system calls .RB ( connect (2), @@ -1484,14 +1501,14 @@ across the various system calls .BR listen (2), .BR sendto (2)) that can assign ephemeral ports. -.PP +.P The ioctls to configure IP-specific interface options and ARP tables are not described. -.\" .PP +.\" .P .\" Some versions of glibc forget to declare .\" .IR in_pktinfo . .\" Workaround currently is to copy it into your program from this man page. -.PP +.P Receiving the original destination address with .B MSG_ERRQUEUE in @@ -1515,10 +1532,10 @@ does not work in some Linux 2.2 kernels. .BR tcp (7), .BR udp (7), .BR ip (8) -.PP +.P The kernel source file .IR Documentation/networking/ip\-sysctl.txt . -.PP +.P RFC\ 791 for the original IP specification. RFC\ 1122 for the IPv4 host requirements. RFC\ 1812 for the IPv4 router requirements. diff --git a/upstream/debian-unstable/man7/ipc_namespaces.7 b/upstream/debian-unstable/man7/ipc_namespaces.7 index 0b13f073..f9d54fe9 100644 --- a/upstream/debian-unstable/man7/ipc_namespaces.7 +++ b/upstream/debian-unstable/man7/ipc_namespaces.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH ipc_namespaces 7 2023-02-05 "Linux man-pages 6.05.01" +.TH ipc_namespaces 7 2024-05-02 "Linux man-pages 6.8" .SH NAME ipc_namespaces \- overview of Linux IPC namespaces .SH DESCRIPTION @@ -18,13 +18,13 @@ POSIX message queues (see The common characteristic of these IPC mechanisms is that IPC objects are identified by mechanisms other than filesystem pathnames. -.PP +.P Each IPC namespace has its own set of System V IPC identifiers and its own POSIX message queue filesystem. Objects created in an IPC namespace are visible to all other processes that are members of that namespace, but are not visible to processes in other IPC namespaces. -.PP +.P The following .I /proc interfaces are distinct in each IPC namespace: @@ -47,11 +47,11 @@ and .IP \[bu] The System V IPC interfaces in .IR /proc/sysvipc . -.PP +.P When an IPC namespace is destroyed (i.e., when the last process that is a member of the namespace terminates), all IPC objects in the namespace are automatically destroyed. -.PP +.P Use of IPC namespaces requires a kernel that is configured with the .B CONFIG_IPC_NS option. diff --git a/upstream/debian-unstable/man7/ipv6.7 b/upstream/debian-unstable/man7/ipv6.7 index e6f9d54a..c9e332e7 100644 --- a/upstream/debian-unstable/man7/ipv6.7 +++ b/upstream/debian-unstable/man7/ipv6.7 @@ -78,14 +78,14 @@ .\" commit c4062dfc425e94290ac427a98d6b4721dd2bc91f .\" Author: Erich E. Hoover <ehoover@mines.edu> .\" -.TH ipv6 7 2023-07-30 "Linux man-pages 6.05.01" +.TH ipv6 7 2024-05-02 "Linux man-pages 6.8" .SH NAME ipv6 \- Linux IPv6 protocol implementation .SH SYNOPSIS .nf .B #include <sys/socket.h> .B #include <netinet/in.h> -.PP +.P .IB tcp6_socket " = socket(AF_INET6, SOCK_STREAM, 0);" .IB raw6_socket " = socket(AF_INET6, SOCK_RAW, " protocol ");" .IB udp6_socket " = socket(AF_INET6, SOCK_DGRAM, " protocol ");" @@ -97,12 +97,12 @@ implemented by the Linux kernel and glibc 2.1. The interface is based on the BSD sockets interface; see .BR socket (7). -.PP +.P The IPv6 API aims to be mostly compatible with the IPv4 API (see .BR ip (7)). Only differences are described in this man page. -.PP +.P To bind an .B AF_INET6 socket to any process, the local address should be copied from the @@ -114,21 +114,21 @@ In static initializations, .B IN6ADDR_ANY_INIT may also be used, which expands to a constant expression. Both of them are in network byte order. -.PP +.P The IPv6 loopback address (::1) is available in the global .I in6addr_loopback variable. For initializations, .B IN6ADDR_LOOPBACK_INIT should be used. -.PP +.P IPv4 connections can be handled with the v6 API by using the v4-mapped-on-v6 address type; thus a program needs to support only this API type to support both protocols. This is handled transparently by the address handling functions in the C library. -.PP +.P IPv4 and IPv6 share the local port space. When you get an IPv4 connection or packet to an IPv6 socket, @@ -149,7 +149,7 @@ struct in6_addr { }; .EE .in -.PP +.P .I sin6_family is always set to .BR AF_INET6 ; @@ -169,19 +169,19 @@ Linux supports it only for link-local addresses, in that case .I sin6_scope_id contains the interface index (see .BR netdevice (7)) -.PP +.P IPv6 supports several address types: unicast to address a single host, multicast to address a group of hosts, anycast to address the nearest member of a group of hosts (not implemented in Linux), IPv4-on-IPv6 to address an IPv4 host, and other reserved address types. -.PP +.P The address notation for IPv6 is a group of 8 4-digit hexadecimal numbers, separated with a \[aq]:\[aq]. \&"::" stands for a string of 0 bits. Special addresses are ::1 for loopback and ::FFFF:<IPv4 address> for IPv4-mapped-on-IPv6. -.PP +.P The port space of IPv6 is shared with IPv4. .SS Socket options IPv6 supports some protocol-specific socket options that can be set with @@ -368,7 +368,7 @@ or into other structures may not be. This is not a problem for 32-bit hosts like i386. -.PP +.P The .I sin6_flowinfo field is new in Linux 2.4. @@ -386,7 +386,7 @@ Programs that assume that all address types can be stored safely in a need to be changed to use .I struct sockaddr_storage for that instead. -.PP +.P .BR SOL_IP , .BR SOL_IPV6 , .BR SOL_ICMPV6 , @@ -401,16 +401,16 @@ The IPv6 extended API as in RFC\ 2292 is currently only partly implemented; although the 2.2 kernel has near complete support for receiving options, the macros for generating IPv6 options are missing in glibc 2.1. -.PP +.P IPSec support for EH and AH headers is missing. -.PP +.P Flow label management is not complete and not documented here. -.PP +.P This man page is not complete. .SH SEE ALSO .BR cmsg (3), .BR ip (7) -.PP +.P RFC\ 2553: IPv6 BASIC API; Linux tries to be compliant to this. RFC\ 2460: IPv6 specification. diff --git a/upstream/debian-unstable/man7/iso_8859-1.7 b/upstream/debian-unstable/man7/iso_8859-1.7 index 7534a855..fa69b2af 100644 --- a/upstream/debian-unstable/man7/iso_8859-1.7 +++ b/upstream/debian-unstable/man7/iso_8859-1.7 @@ -5,37 +5,37 @@ .\" .\" Slightly rearranged, aeb, 950713 .\" Updated, dpo, 990531 -.TH ISO_8859-1 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-1 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-1 \- ISO 8859-1 character set encoded in octal, decimal, +iso_8859-1 \- ISO/IEC\~8859-1 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-1 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-1 encodes the characters used in many West European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-1 characters -The following table displays the characters in ISO 8859-1 that +.SS ISO/IEC\~8859-1 characters +The following table displays the characters in ISO/IEC\~8859-1 that are printable and unlisted in the .BR ascii (7) manual page. @@ -141,7 +141,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-1 is also known as Latin-1. +ISO/IEC\~8859-1 is also known as Latin-1. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/upstream/debian-unstable/man7/iso_8859-10.7 b/upstream/debian-unstable/man7/iso_8859-10.7 index d43a00a8..cc1cdda0 100644 --- a/upstream/debian-unstable/man7/iso_8859-10.7 +++ b/upstream/debian-unstable/man7/iso_8859-10.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-10 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-10 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-10 \- ISO 8859-10 character set encoded in octal, decimal, +iso_8859-10 \- ISO/IEC\~8859-10 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-10 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-10 encodes the characters used in Nordic languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-10 characters -The following table displays the characters in ISO 8859-10 that +.SS ISO/IEC\~8859-10 characters +The following table displays the characters in ISO/IEC\~8859-10 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ĸ LATIN SMALL LETTER KRA .TE .SH NOTES -ISO 8859-10 is also known as Latin-6. +ISO/IEC\~8859-10 is also known as Latin-6. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/upstream/debian-unstable/man7/iso_8859-11.7 b/upstream/debian-unstable/man7/iso_8859-11.7 index e4886067..af60f2de 100644 --- a/upstream/debian-unstable/man7/iso_8859-11.7 +++ b/upstream/debian-unstable/man7/iso_8859-11.7 @@ -5,37 +5,37 @@ .\" .\"Thanomsub Noppaburana <donga.nb@gmail.com> made valuable suggestions. .\" -.TH ISO_8859-11 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-11 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-11 \- ISO 8859-11 character set encoded in octal, decimal, +iso_8859-11 \- ISO/IEC\~8859-11 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-11 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-11 encodes the characters used in the Thai language. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-11 characters -The following table displays the characters in ISO 8859-11 that +.SS ISO/IEC\~8859-11 characters +The following table displays the characters in ISO/IEC\~8859-11 that are printable and unlisted in the .BR ascii (7) manual page. @@ -133,9 +133,9 @@ _ 373 251 FB ๛ THAI CHARACTER KHOMUT .TE .SH NOTES -ISO 8859-11 is the same as TIS (Thai Industrial Standard) 620-2253, +ISO/IEC\~8859-11 is the same as TIS (Thai Industrial Standard) 620-2253, commonly known as TIS-620, except for the character in position A0: -ISO 8859-11 defines this as NO-BREAK SPACE, +ISO/IEC\~8859-11 defines this as NO-BREAK SPACE, while TIS-620 leaves it undefined. .SH SEE ALSO .BR ascii (7), diff --git a/upstream/debian-unstable/man7/iso_8859-13.7 b/upstream/debian-unstable/man7/iso_8859-13.7 index 11583479..937d2503 100644 --- a/upstream/debian-unstable/man7/iso_8859-13.7 +++ b/upstream/debian-unstable/man7/iso_8859-13.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-13 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-13 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-13 \- ISO 8859-13 character set encoded in octal, decimal, +iso_8859-13 \- ISO/IEC\~8859-13 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-13 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-13 encodes the characters used in Baltic Rim languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-13 characters -The following table displays the characters in ISO 8859-13 that +.SS ISO/IEC\~8859-13 characters +The following table displays the characters in ISO/IEC\~8859-13 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ’ RIGHT SINGLE QUOTATION MARK .TE .SH NOTES -ISO 8859-13 is also known as Latin-7. +ISO/IEC\~8859-13 is also known as Latin-7. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/upstream/debian-unstable/man7/iso_8859-14.7 b/upstream/debian-unstable/man7/iso_8859-14.7 index eedac822..0ba348eb 100644 --- a/upstream/debian-unstable/man7/iso_8859-14.7 +++ b/upstream/debian-unstable/man7/iso_8859-14.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-14 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-14 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-14 \- ISO 8859-14 character set encoded in octal, decimal, +iso_8859-14 \- ISO/IEC\~8859-14 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-14 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-14 encodes the characters used in Celtic languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-14 characters -The following table displays the characters in ISO 8859-14 that +.SS ISO/IEC\~8859-14 characters +The following table displays the characters in ISO/IEC\~8859-14 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-14 is also known as Latin-8. +ISO/IEC\~8859-14 is also known as Latin-8. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/upstream/debian-unstable/man7/iso_8859-15.7 b/upstream/debian-unstable/man7/iso_8859-15.7 index 908bb9be..743b86a6 100644 --- a/upstream/debian-unstable/man7/iso_8859-15.7 +++ b/upstream/debian-unstable/man7/iso_8859-15.7 @@ -4,37 +4,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-15 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-15 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-15 \- ISO 8859-15 character set encoded in octal, decimal, +iso_8859-15 \- ISO/IEC\~8859-15 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-15 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-15 encodes the characters used in many West European languages and adds the Euro sign. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-15 characters -The following table displays the characters in ISO 8859-15 that +.SS ISO/IEC\~8859-15 characters +The following table displays the characters in ISO/IEC\~8859-15 that are printable and unlisted in the .BR ascii (7) manual page. @@ -140,7 +140,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-15 is also known as Latin-9 (or sometimes as Latin-0). +ISO/IEC\~8859-15 is also known as Latin-9 (or sometimes as Latin-0). .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/upstream/debian-unstable/man7/iso_8859-16.7 b/upstream/debian-unstable/man7/iso_8859-16.7 index 697a3f9c..6aee6295 100644 --- a/upstream/debian-unstable/man7/iso_8859-16.7 +++ b/upstream/debian-unstable/man7/iso_8859-16.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-16 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-16 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-16 \- ISO 8859-16 character set encoded in octal, decimal, +iso_8859-16 \- ISO/IEC\~8859-16 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-16 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-16 encodes the Latin characters used in Southeast European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-16 characters -The following table displays the characters in ISO 8859-16 that +.SS ISO/IEC\~8859-16 characters +The following table displays the characters in ISO/IEC\~8859-16 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-16 is also known as Latin-10. +ISO/IEC\~8859-16 is also known as Latin-10. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/upstream/debian-unstable/man7/iso_8859-2.7 b/upstream/debian-unstable/man7/iso_8859-2.7 index 403e85e5..32ba325a 100644 --- a/upstream/debian-unstable/man7/iso_8859-2.7 +++ b/upstream/debian-unstable/man7/iso_8859-2.7 @@ -6,37 +6,37 @@ .\" .\" Slightly rearranged, aeb, 950713 .\" Updated, dpo, 990531 -.TH ISO_8859-2 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-2 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-2 \- ISO 8859-2 character set encoded in octal, decimal, +iso_8859-2 \- ISO/IEC\~8859-2 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-2 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-2 encodes the Latin characters used in many Central and East European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-2 characters -The following table displays the characters in ISO 8859-2 that +.SS ISO/IEC\~8859-2 characters +The following table displays the characters in ISO/IEC\~8859-2 that are printable and unlisted in the .BR ascii (7) manual page. @@ -142,7 +142,7 @@ _ 377 255 FF ˙ DOT ABOVE .TE .SH NOTES -ISO 8859-2 is also known as Latin-2. +ISO/IEC\~8859-2 is also known as Latin-2. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/upstream/debian-unstable/man7/iso_8859-3.7 b/upstream/debian-unstable/man7/iso_8859-3.7 index 8eb9a24b..df8c7b7f 100644 --- a/upstream/debian-unstable/man7/iso_8859-3.7 +++ b/upstream/debian-unstable/man7/iso_8859-3.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-3 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-3 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-3 \- ISO 8859-3 character set encoded in octal, decimal, +iso_8859-3 \- ISO/IEC\~8859-3 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-3 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-3 encodes the characters used in certain Southeast European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-3 characters -The following table displays the characters in ISO 8859-3 that +.SS ISO/IEC\~8859-3 characters +The following table displays the characters in ISO/IEC\~8859-3 that are printable and unlisted in the .BR ascii (7) manual page. @@ -132,7 +132,7 @@ _ 377 255 FF ˙ DOT ABOVE .TE .SH NOTES -ISO 8859-3 is also known as Latin-3. +ISO/IEC\~8859-3 is also known as Latin-3. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/upstream/debian-unstable/man7/iso_8859-4.7 b/upstream/debian-unstable/man7/iso_8859-4.7 index b209bf14..643aedbc 100644 --- a/upstream/debian-unstable/man7/iso_8859-4.7 +++ b/upstream/debian-unstable/man7/iso_8859-4.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-4 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-4 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-4 \- ISO 8859-4 character set encoded in octal, decimal, +iso_8859-4 \- ISO/IEC\~8859-4 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-4 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-4 encodes the characters used in Scandinavian and Baltic languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-4 characters -The following table displays the characters in ISO 8859-4 that +.SS ISO/IEC\~8859-4 characters +The following table displays the characters in ISO/IEC\~8859-4 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ˙ DOT ABOVE .TE .SH NOTES -ISO 8859-4 is also known as Latin-4. +ISO/IEC\~8859-4 is also known as Latin-4. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/upstream/debian-unstable/man7/iso_8859-5.7 b/upstream/debian-unstable/man7/iso_8859-5.7 index 1fbb2662..a62b7321 100644 --- a/upstream/debian-unstable/man7/iso_8859-5.7 +++ b/upstream/debian-unstable/man7/iso_8859-5.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-5 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-5 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-5 \- ISO 8859-5 character set encoded in octal, decimal, +iso_8859-5 \- ISO/IEC\~8859-5 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-5 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-5 encodes the Cyrillic characters used in many East European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-5 characters -The following table displays the characters in ISO 8859-5 that +.SS ISO/IEC\~8859-5 characters +The following table displays the characters in ISO/IEC\~8859-5 that are printable and unlisted in the .BR ascii (7) manual page. diff --git a/upstream/debian-unstable/man7/iso_8859-6.7 b/upstream/debian-unstable/man7/iso_8859-6.7 index b73e846e..6b65f5c9 100644 --- a/upstream/debian-unstable/man7/iso_8859-6.7 +++ b/upstream/debian-unstable/man7/iso_8859-6.7 @@ -3,37 +3,39 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-6 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-6 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-6 \- ISO 8859-6 character set encoded in octal, decimal, +iso_8859-6 +\- +ISO/IEC\~8859-6 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-6 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-6 encodes the characters used in the Arabic language. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-6 characters -The following table displays the characters in ISO 8859-6 that +.SS ISO/IEC\~8859-6 characters +The following table displays the characters in ISO/IEC\~8859-6 that are printable and unlisted in the .BR ascii (7) manual page. @@ -94,7 +96,7 @@ _ 362 242 F2 ْ ARABIC SUKUN .TE .SH NOTES -ISO 8859-6 lacks the glyphs required for many related languages, +ISO/IEC\~8859-6 lacks the glyphs required for many related languages, such as Urdu and Persian (Farsi). .SH SEE ALSO .BR ascii (7), diff --git a/upstream/debian-unstable/man7/iso_8859-7.7 b/upstream/debian-unstable/man7/iso_8859-7.7 index a66a28e8..48f92a3e 100644 --- a/upstream/debian-unstable/man7/iso_8859-7.7 +++ b/upstream/debian-unstable/man7/iso_8859-7.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-7 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-7 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-7 \- ISO 8859-7 character set encoded in octal, decimal, +iso_8859-7 \- ISO/IEC\~8859-7 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-7 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-7 encodes the characters used in modern monotonic Greek. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-7 characters -The following table displays the characters in ISO 8859-7 that +.SS ISO/IEC\~8859-7 characters +The following table displays the characters in ISO/IEC\~8859-7 that are printable and unlisted in the .BR ascii (7) manual page. @@ -143,7 +143,7 @@ T} 376 254 FE ώ GREEK SMALL LETTER OMEGA WITH TONOS .TE .SH NOTES -ISO 8859-7 was formerly known as ELOT-928 or ECMA-118:1986. +ISO/IEC\~8859-7 was formerly known as ELOT-928 or ECMA-118:1986. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/upstream/debian-unstable/man7/iso_8859-8.7 b/upstream/debian-unstable/man7/iso_8859-8.7 index d8541162..c256ebd5 100644 --- a/upstream/debian-unstable/man7/iso_8859-8.7 +++ b/upstream/debian-unstable/man7/iso_8859-8.7 @@ -5,37 +5,37 @@ .\" .\" Eli Zaretskii <eliz@gnu.org> made valuable suggestions .\" -.TH ISO_8859-8 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-8 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-8 \- ISO 8859-8 character set encoded in octal, decimal, +iso_8859-8 \- ISO/IEC\~8859-8 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-8 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-8 encodes the characters used in Modern Hebrew. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-8 characters -The following table displays the characters in ISO 8859-8 that +.SS ISO/IEC\~8859-8 characters +The following table displays the characters in ISO/IEC\~8859-8 that are printable and unlisted in the .BR ascii (7) manual page. @@ -105,8 +105,8 @@ _ 376 254 FE RIGHT-TO-LEFT MARK .TE .SH NOTES -ISO 8859-8 was also known as ISO-IR-138. -ISO 8859-8 includes neither short vowels nor diacritical marks, +ISO/IEC\~8859-8 was also known as ISO-IR-138. +ISO/IEC\~8859-8 includes neither short vowels nor diacritical marks, and Yiddish is not provided for. .SH SEE ALSO .BR ascii (7), diff --git a/upstream/debian-unstable/man7/iso_8859-9.7 b/upstream/debian-unstable/man7/iso_8859-9.7 index 6386144e..2b05ac70 100644 --- a/upstream/debian-unstable/man7/iso_8859-9.7 +++ b/upstream/debian-unstable/man7/iso_8859-9.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-9 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-9 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -iso_8859-9 \- ISO 8859-9 character set encoded in octal, decimal, +iso_8859-9 \- ISO/IEC\~8859-9 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-9 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-9 encodes the characters used in Turkish. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-9 characters -The following table displays the characters in ISO 8859-9 that +.SS ISO/IEC\~8859-9 characters +The following table displays the characters in ISO/IEC\~8859-9 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-9 is also known as Latin-5. +ISO/IEC\~8859-9 is also known as Latin-5. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/upstream/debian-unstable/man7/kernel-command-line.7 b/upstream/debian-unstable/man7/kernel-command-line.7 index e36aac8f..769870af 100644 --- a/upstream/debian-unstable/man7/kernel-command-line.7 +++ b/upstream/debian-unstable/man7/kernel-command-line.7 @@ -1,5 +1,5 @@ '\" t -.TH "KERNEL\-COMMAND\-LINE" "7" "" "systemd 255" "kernel-command-line" +.TH "KERNEL\-COMMAND\-LINE" "7" "" "systemd 256~rc3" "kernel-command-line" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -36,11 +36,10 @@ For command line parameters understood by the kernel, please see and \fBbootparam\fR(7)\&. .PP -For command line parameters understood by the initrd, see -\fBdracut.cmdline\fR(7), or the documentation of the specific initrd implementation of your installation\&. +For command line parameters understood by the initrd, see the documentation of the specific initrd implementation of your installation\&. .SH "CORE OS COMMAND LINE ARGUMENTS" .PP -\fIsystemd\&.unit=\fR, \fIrd\&.systemd\&.unit=\fR, \fIsystemd\&.dump_core\fR, \fIsystemd\&.crash_chvt\fR, \fIsystemd\&.crash_shell\fR, \fIsystemd\&.crash_reboot\fR, \fIsystemd\&.confirm_spawn\fR, \fIsystemd\&.service_watchdogs\fR, \fIsystemd\&.show_status\fR, \fIsystemd\&.status_unit_format=\fR, \fIsystemd\&.log_target=\fR, \fIsystemd\&.log_level=\fR, \fIsystemd\&.log_location=\fR, \fIsystemd\&.log_color\fR, \fIsystemd\&.log_ratelimit_kmsg\fR, \fIsystemd\&.default_standard_output=\fR, \fIsystemd\&.default_standard_error=\fR, \fIsystemd\&.setenv=\fR, \fIsystemd\&.machine_id=\fR, \fIsystemd\&.set_credential=\fR, \fIsystemd\&.set_credential_binary=\fR, \fIsystemd\&.import_credentials=\fR, \fIsystemd\&.reload_limit_interval_sec=\fR, \fIsystemd\&.reload_limit_burst=\fR +\fIsystemd\&.unit=\fR, \fIrd\&.systemd\&.unit=\fR, \fIsystemd\&.dump_core\fR, \fIsystemd\&.crash_chvt\fR, \fIsystemd\&.crash_shell\fR, \fIsystemd\&.crash_action=\fR, \fIsystemd\&.confirm_spawn\fR, \fIsystemd\&.service_watchdogs\fR, \fIsystemd\&.show_status\fR, \fIsystemd\&.status_unit_format=\fR, \fIsystemd\&.log_target=\fR, \fIsystemd\&.log_level=\fR, \fIsystemd\&.log_location=\fR, \fIsystemd\&.log_color\fR, \fIsystemd\&.log_ratelimit_kmsg\fR, \fIsystemd\&.default_standard_output=\fR, \fIsystemd\&.default_standard_error=\fR, \fIsystemd\&.setenv=\fR, \fIsystemd\&.machine_id=\fR, \fIsystemd\&.set_credential=\fR, \fIsystemd\&.set_credential_binary=\fR, \fIsystemd\&.import_credentials=\fR, \fIsystemd\&.reload_limit_interval_sec=\fR, \fIsystemd\&.reload_limit_burst=\fR .RS 4 Parameters understood by the system and service manager to control system behavior\&. For details, see \fBsystemd\fR(1)\&. @@ -48,7 +47,7 @@ Parameters understood by the system and service manager to control system behavi Added in version 186\&. .RE .PP -\fIsystemd\&.mask=\fR, \fIsystemd\&.wants=\fR, \fIsystemd\&.debug_shell\fR +\fIsystemd\&.mask=\fR, \fIsystemd\&.wants=\fR, \fIsystemd\&.debug_shell\fR, \fIsystemd\&.default_debug_tty=\fR .RS 4 Additional parameters understood by \fBsystemd-debug-generator\fR(8), to mask or start specific units at boot, or invoke a debug shell on tty9\&. @@ -83,6 +82,15 @@ and Added in version 209\&. .RE .PP +\fIsystemd\&.ssh_auto=\fR, \fIsystemd\&.ssh_listen=\fR +.RS 4 +These parameters are interpreted by +\fBsystemd-ssh-generator\fR(8) +and may be used to control SSH sockets the system shall be reachable on\&. +.sp +Added in version 256\&. +.RE +.PP \fIsystemd\&.volatile=\fR .RS 4 This parameter controls whether the system shall boot up in volatile mode\&. Takes a boolean argument, or the special value @@ -176,7 +184,7 @@ Parameters understood by the virtual console setup logic\&. For details, see Added in version 186\&. .RE .PP -\fIudev\&.log_level=\fR, \fIrd\&.udev\&.log_level=\fR, \fIudev\&.children_max=\fR, \fIrd\&.udev\&.children_max=\fR, \fIudev\&.exec_delay=\fR, \fIrd\&.udev\&.exec_delay=\fR, \fIudev\&.event_timeout=\fR, \fIrd\&.udev\&.event_timeout=\fR, \fIudev\&.timeout_signal=\fR, \fIrd\&.udev\&.timeout_signal=\fR, \fIudev\&.blockdev_read_only\fR, \fIrd\&.udev\&.blockdev_read_only\fR, \fInet\&.ifnames=\fR, \fInet\&.naming\-scheme=\fR +\fIudev\&.log_level=\fR, \fIrd\&.udev\&.log_level=\fR, \fIudev\&.children_max=\fR, \fIrd\&.udev\&.children_max=\fR, \fIudev\&.exec_delay=\fR, \fIrd\&.udev\&.exec_delay=\fR, \fIudev\&.event_timeout=\fR, \fIrd\&.udev\&.event_timeout=\fR, \fIudev\&.timeout_signal=\fR, \fIrd\&.udev\&.timeout_signal=\fR, \fIudev\&.blockdev_read_only\fR, \fIrd\&.udev\&.blockdev_read_only\fR, \fInet\&.ifnames=\fR, \fInet\&.naming_scheme=\fR .RS 4 Parameters understood by the device event managing daemon\&. For details, see \fBsystemd-udevd.service\fR(8)\&. @@ -370,19 +378,29 @@ Added in version 253\&. .PP \fIresume=\fR, \fIresumeflags=\fR .RS 4 -Enables resume from hibernation using the specified device and mount options\&. All -\fBfstab\fR(5)\-like paths are supported\&. For details, see +Enable resume from hibernation using the specified device and timeout options\&. All +\fBfstab\fR(5)\-style device identifiers are supported\&. For details, see \fBsystemd-hibernate-resume-generator\fR(8)\&. .sp Added in version 217\&. .RE .PP +\fIresume_offset=\fR +.RS 4 +Configure the page offset of the swap space from the resume device\&. For details, see +\fBsystemd-hibernate-resume-generator\fR(8)\&. +.sp +Added in version 254\&. +.RE +.PP \fIsystemd\&.firstboot=\fR .RS 4 Takes a boolean argument, defaults to on\&. If off, \fBsystemd-firstboot.service\fR(8) +and +\fBsystemd-homed-firstboot.service\fR(1) will not query the user for basic system settings, even if the system boots up for the first time and the relevant settings are not initialized yet\&. Not to be confused with -\fIsystemd\&.condition\-first\-boot=\fR +\fIsystemd\&.condition_first_boot=\fR (see below), which overrides the result of the \fIConditionFirstBoot=\fR unit file condition, and thus controls more than just @@ -392,7 +410,7 @@ behaviour\&. Added in version 233\&. .RE .PP -\fIsystemd\&.condition\-needs\-update=\fR +\fIsystemd\&.condition_needs_update=\fR .RS 4 Takes a boolean argument\&. If specified, overrides the result of \fIConditionNeedsUpdate=\fR @@ -403,7 +421,7 @@ for details\&. Added in version 246\&. .RE .PP -\fIsystemd\&.condition\-first\-boot=\fR +\fIsystemd\&.condition_first_boot=\fR .RS 4 Takes a boolean argument\&. If specified, overrides the result of \fIConditionFirstBoot=\fR @@ -418,14 +436,14 @@ system service but has no effect on the condition check (see above)\&. Added in version 246\&. .RE .PP -\fIsystemd\&.clock\-usec=\fR +\fIsystemd\&.clock_usec=\fR .RS 4 Takes a decimal, numeric timestamp in μs since January 1st 1970, 00:00am, to set the system clock to\&. The system time is set to the specified timestamp early during boot\&. It is not propagated to the hardware clock (RTC)\&. .sp Added in version 246\&. .RE .PP -\fIsystemd\&.random\-seed=\fR +\fIsystemd\&.random_seed=\fR .RS 4 Takes a base64 encoded random seed value to credit with full entropy to the kernel\*(Aqs random pool during early service manager initialization\&. This option is useful in testing environments where delays due to random pool initialization in entropy starved virtual machines shall be avoided\&. .sp @@ -449,6 +467,15 @@ Again: do not use this option outside of testing environments, it\*(Aqs a securi Added in version 246\&. .RE .PP +\fIsystemd\&.allow_userspace_verity=\fR +.RS 4 +Takes a boolean argument\&. Controls whether disk images that are Verity protected may be authenticated in userspace signature checks via +/etc/verity\&.d/ +(and related directories) public key drop\-ins, or whether in\-kernel signature checking only\&. Defaults to on\&. +.sp +Added in version 256\&. +.RE +.PP \fIsystemd\&.hostname=\fR .RS 4 Accepts a hostname to set during early boot\&. If specified takes precedence over what is set in @@ -479,6 +506,31 @@ prefix (e\&.g\&. .sp Added in version 254\&. .RE +.PP +\fIsystemd\&.battery_check=\fR +.RS 4 +Accepts a boolean argument\&. If false the boot\-time battery charge check implemented by +\fBsystemd-battery-check.service\fR(8) +is disabled\&. +.sp +Added in version 254\&. +.RE +.PP +\fIifname=\fR, \fInet\&.ifname_policy=\fR +.RS 4 +Controls interface naming policies, implemented by +\fBsystemd-network-generator.service\fR(8)\&. +.sp +Added in version 245\&. +.RE +.PP +\fIsystemd\&.tpm2_wait=\fR +.RS 4 +Controls whether to wait for a TPM2 device at boot, implemented by +\fBsystemd-tpm2-generator\fR(8)\&. +.sp +Added in version 256\&. +.RE .SH "HISTORY" .PP systemd 252 @@ -493,31 +545,7 @@ Added in version 252\&. .RE .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBsystemd-system.conf\fR(5), -\fBbootparam\fR(7), -\fBsystemd.system-credentials\fR(7) -\fBsmbios-type-11\fR(7), -\fBdracut.cmdline\fR(7), -\fBsystemd-debug-generator\fR(8), -\fBsystemd-fsck@.service\fR(8), -\fBsystemd-quotacheck.service\fR(8), -\fBsystemd-journald.service\fR(8), -\fBsystemd-vconsole-setup.service\fR(8), -\fBsystemd-udevd.service\fR(8), -\fBplymouth\fR(8), -\fBsystemd-cryptsetup-generator\fR(8), -\fBsystemd-veritysetup-generator\fR(8), -\fBsystemd-fstab-generator\fR(8), -\fBsystemd-getty-generator\fR(8), -\fBsystemd-gpt-auto-generator\fR(8), -\fBsystemd-volatile-root.service\fR(8), -\fBsystemd-modules-load.service\fR(8), -\fBsystemd-backlight@.service\fR(8), -\fBsystemd-rfkill.service\fR(8), -\fBsystemd-hibernate-resume-generator\fR(8), -\fBsystemd-firstboot.service\fR(8), -\fBbootctl\fR(1) +\fBsystemd\fR(1), \fBsystemd-system.conf\fR(5), \fBbootparam\fR(7), \fBsystemd.system-credentials\fR(7), \fBsmbios-type-11\fR(7), \fBsystemd-debug-generator\fR(8), \fBsystemd-fsck@.service\fR(8), \fBsystemd-quotacheck.service\fR(8), \fBsystemd-journald.service\fR(8), \fBsystemd-vconsole-setup.service\fR(8), \fBsystemd-udevd.service\fR(8), \fBplymouth\fR(8), \fBsystemd-cryptsetup-generator\fR(8), \fBsystemd-veritysetup-generator\fR(8), \fBsystemd-fstab-generator\fR(8), \fBsystemd-getty-generator\fR(8), \fBsystemd-gpt-auto-generator\fR(8), \fBsystemd-volatile-root.service\fR(8), \fBsystemd-modules-load.service\fR(8), \fBsystemd-backlight@.service\fR(8), \fBsystemd-rfkill.service\fR(8), \fBsystemd-hibernate-resume-generator\fR(8), \fBsystemd-firstboot.service\fR(8), \fBbootctl\fR(1) .SH "NOTES" .IP " 1." 4 kernel-parameters.html diff --git a/upstream/debian-unstable/man7/kernel_lockdown.7 b/upstream/debian-unstable/man7/kernel_lockdown.7 index aac19aa0..cb5babb3 100644 --- a/upstream/debian-unstable/man7/kernel_lockdown.7 +++ b/upstream/debian-unstable/man7/kernel_lockdown.7 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH kernel_lockdown 7 2023-02-05 "Linux man-pages 6.05.01" +.TH kernel_lockdown 7 2024-05-02 "Linux man-pages 6.8" .SH NAME kernel_lockdown \- kernel image access prevention feature .SH DESCRIPTION @@ -13,18 +13,18 @@ access to a running kernel image, attempting to protect against unauthorized modification of the kernel image and to prevent access to security and cryptographic data located in kernel memory, whilst still permitting driver modules to be loaded. -.PP +.P If a prohibited or restricted feature is accessed or used, the kernel will emit a message that looks like: -.PP +.P .in +4n .EX Lockdown: X: Y is restricted, see man kernel_lockdown.7 .EE .in -.PP +.P where X indicates the process name and Y indicates what is restricted. -.PP +.P On an EFI-enabled x86 or arm64 machine, lockdown will be automatically enabled if the system boots in EFI Secure Boot mode. .\" @@ -33,7 +33,7 @@ When lockdown is in effect, a number of features are disabled or have their use restricted. This includes special device files and kernel services that allow direct access of the kernel image: -.PP +.P .RS /dev/mem .br @@ -47,7 +47,7 @@ BPF .br kprobes .RE -.PP +.P and the ability to directly configure and control devices, so as to prevent the use of a device to access or modify a kernel image: .IP \[bu] 3 @@ -73,7 +73,7 @@ The use of ACPI error injection. The specification of the ACPI RDSP address. .IP \[bu] The use of ACPI custom methods. -.PP +.P Certain facilities are restricted: .IP \[bu] 3 Only validly signed modules may be loaded (waived if the module file being diff --git a/upstream/debian-unstable/man7/keyrings.7 b/upstream/debian-unstable/man7/keyrings.7 index 1ebd25fe..0050de50 100644 --- a/upstream/debian-unstable/man7/keyrings.7 +++ b/upstream/debian-unstable/man7/keyrings.7 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH keyrings 7 2023-02-05 "Linux man-pages 6.05.01" +.TH keyrings 7 2024-05-02 "Linux man-pages 6.8" .SH NAME keyrings \- in-kernel key management and retention facility .SH DESCRIPTION @@ -12,14 +12,14 @@ The Linux key-management facility is primarily a way for various kernel components to retain or cache security data, authentication keys, encryption keys, and other data in the kernel. -.PP +.P System call interfaces are provided so that user-space programs can manage those objects and also use the facility for their own purposes; see .BR add_key (2), .BR request_key (2), and .BR keyctl (2). -.PP +.P A library and some user-space utilities are provided to allow access to the facility. See @@ -98,7 +98,7 @@ the key is scheduled for garbage collection. .SS Key types The kernel provides several basic types of key: .TP -.I """keyring""" +.I \[dq]keyring\[dq] .\" Note that keyrings use different fields in struct key in order to store .\" their data - index_key instead of type/description and name_link/keys .\" instead of payload. @@ -111,7 +111,7 @@ being garbage collected because nothing refers to them. Keyrings with descriptions (names) that begin with a period (\[aq].\[aq]) are reserved to the implementation. .TP -.I """user""" +.I \[dq]user\[dq] This is a general-purpose key type. The key is kept entirely within kernel memory. The payload may be read and updated by user-space applications. @@ -123,12 +123,12 @@ The description may be any valid string, though it is preferred that it start with a colon-delimited prefix representing the service to which the key is of interest (for instance -.IR """afs:mykey""" ). +.IR \[dq]afs:mykey\[dq] ). .TP -.IR """logon""" " (since Linux 3.3)" +.IR \[dq]logon\[dq] " (since Linux 3.3)" .\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b This key type is essentially the same as -.IR """user""" , +.IR \[dq]user\[dq] , but it does not provide reading (i.e., the .BR keyctl (2) .B KEYCTL_READ @@ -138,19 +138,19 @@ This is suitable for storing username-password pairs that should not be readable from user space. .IP The description of a -.I """logon""" +.I \[dq]logon\[dq] key .I must start with a non-empty colon-delimited prefix whose purpose is to identify the service to which the key belongs. (Note that this differs from keys of the -.I """user""" +.I \[dq]user\[dq] type, where the inclusion of a prefix is recommended but is not enforced.) .TP -.IR """big_key""" " (since Linux 3.13)" +.IR \[dq]big_key\[dq] " (since Linux 3.13)" .\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10 This key type is similar to the -.I """user""" +.I \[dq]user\[dq] key type, but it may hold a payload of up to 1\ MiB in size. This key type is useful for purposes such as holding Kerberos ticket caches. .IP @@ -165,11 +165,11 @@ Since Linux 4.8, .\" commit 13100a72f40f5748a04017e0ab3df4cf27c809ef the payload data is encrypted when stored in tmpfs, thereby preventing it from being written unencrypted into swap space. -.PP +.P There are more specialized key types available also, but they aren't discussed here because they aren't intended for normal user-space use. -.PP +.P Key type names that begin with a period (\[aq].\[aq]) are reserved to the implementation. .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -179,7 +179,7 @@ links to other keys (which may include other keyrings). Keys may be linked to by multiple keyrings. Keyrings may be considered as analogous to UNIX directories where each directory contains a set of hard links to files. -.PP +.P Various operations (system calls) may be applied only to keyrings: .TP Adding @@ -204,7 +204,7 @@ A keyring may be considered the root of a tree or subtree in which keyrings form the branches and non-keyrings the leaves. This tree may be searched for a key matching a particular type and description. -.PP +.P See .BR keyctl_clear (3), .BR keyctl_link (3), @@ -217,13 +217,13 @@ for more information. To prevent a key from being garbage collected, it must be anchored to keep its reference count elevated when it is not in active use by the kernel. -.PP +.P Keyrings are used to anchor other keys: each link is a reference on a key. Note that keyrings themselves are just keys and are also subject to the same anchoring requirement to prevent them being garbage collected. -.PP +.P The kernel makes available a number of anchor keyrings. Note that some of these keyrings will be created only when first accessed. .TP @@ -302,7 +302,7 @@ encryption keys for module signature verification. .IP These special keyrings are usually closed to direct alteration by user space. -.PP +.P An originally planned "group keyring", for storing keys associated with each GID known to the kernel, is not so far implemented, is unlikely to be implemented. @@ -335,16 +335,16 @@ If a process is upcalled from the kernel to instantiate a key (see .BR request_key (2)), then it also possesses the requester's keyrings as in rule (1) as if it were the requester. -.PP +.P Note that possession is not a fundamental property of a key, but must rather be calculated each time the key is needed. -.PP +.P Possession is designed to allow set-user-ID programs run from, say a user's shell to access the user's keys. Granting permissions to the key possessor while denying them to the key owner and group allows the prevention of access to keys on the basis of UID and GID matches. -.PP +.P When it creates the session keyring, .BR pam_keyinit (8) adds a link to the @@ -361,7 +361,7 @@ The ID of a group that is permitted to access the key A security label .IP \[bu] A permissions mask -.PP +.P The permissions mask contains four sets of rights. The first three sets are mutually exclusive. One and only one will be in force for a particular access check. @@ -379,17 +379,17 @@ filesystem GID or one of the caller's supplementary group IDs. .I other The set specifies the rights granted if neither the key's user ID nor group ID matched. -.PP +.P The fourth set of rights is: .TP .I possessor The set specifies the rights granted if a key is determined to be possessed by the caller. -.PP +.P The complete set of rights for a key is the union of whichever of the first three sets is applicable plus the fourth set if the key is possessed. -.PP +.P The set of rights that may be granted in each of the four masks is as follows: .TP @@ -421,14 +421,14 @@ doesn't require this permission. .I setattr The ownership details and security label of the key may be changed, the key's expiration time may be set, and the key may be revoked. -.PP +.P In addition to access rights, any active Linux Security Module (LSM) may prevent access to a key if its policy so dictates. A key may be given a security label or other attribute by the LSM; this label is retrievable via .BR keyctl_get_security (3). -.PP +.P See .BR keyctl_chown (3), .BR keyctl_describe (3), @@ -447,7 +447,7 @@ system call is the primary point of access for user-space applications to find a key. (Internally, the kernel has something similar available for use by internal components that make use of keys.) -.PP +.P The search algorithm works as follows: .IP (1) 5 The process keyrings are searched in the following order: the @@ -480,10 +480,10 @@ If no valid matching key is found, then the first noted error state is returned; otherwise, an .B ENOKEY error is returned. -.PP +.P It is also possible to search a specific keyring, in which case only steps (3) to (6) apply. -.PP +.P See .BR request_key (2) and @@ -498,18 +498,18 @@ will, if given a argument, create a new key and then upcall to user space to instantiate the key. This allows keys to be created on an as-needed basis. -.PP +.P Typically, this will involve the kernel creating a new process that executes the .BR request\-key (8) program, which will then execute the appropriate handler based on its configuration. -.PP +.P The handler is passed a special authorization key that allows it and only it to instantiate the new key. This is also used to permit searches performed by the handler program to also search the requester's keyrings. -.PP +.P See .BR request_key (2), .BR keyctl_assume_authority (3), @@ -685,16 +685,16 @@ field provides some further information about the key. The information that appears here depends on the key type, as follows: .RS .TP -.IR """user""" " and " """logon""" +.IR \[dq]user\[dq] " and " \[dq]logon\[dq] The size in bytes of the key payload (expressed in decimal). .TP -.I """keyring""" +.I \[dq]keyring\[dq] The number of keys linked to the keyring, or the string .I empty if there are no keys linked to the keyring. .TP -.I """big_key""" +.I \[dq]big_key\[dq] The payload size in bytes, followed either by the string .IR [file] , if the key payload exceeds the threshold that means that the @@ -707,7 +707,7 @@ indicating that the key is small enough to reside in kernel memory. .RE .IP For the -.I """.request_key_auth""" +.I \[dq].request_key_auth\[dq] key type (authorization key; see .BR request_key (2)), @@ -796,7 +796,7 @@ or the operation.) .IP The default value in this file is 259200 (i.e., 3 days). -.PP +.P The following files (which are writable by privileged processes) are used to enforce quotas on the number of keys and number of bytes of data that can be stored in key payloads: @@ -833,14 +833,14 @@ may own. .IP .\"738c5d190f6540539a04baf36ce21d46b5da04bd The default value in this file is 1,000,000 (200 before Linux 3.17). -.PP +.P With respect to keyrings, note that each link in a keyring consumes 4 bytes of the keyring payload. .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .SS Users The Linux key-management facility has a number of users and usages, but is not limited to those that already exist. -.PP +.P In-kernel users of this facility include: .TP Network filesystems - DNS @@ -863,7 +863,7 @@ The CIFS filesystem uses keys to store passwords for accessing remote shares. Module verification The kernel build process can be made to cryptographically sign modules. That signature is then checked when a module is loaded. -.PP +.P User-space users of this facility include: .TP Kerberos key storage @@ -892,7 +892,7 @@ scripts can use them. .BR user\-session\-keyring (7), .BR pam_keyinit (8), .BR request\-key (8) -.PP +.P The kernel source files .I Documentation/crypto/asymmetric\-keys.txt and under diff --git a/upstream/debian-unstable/man7/koi8-r.7 b/upstream/debian-unstable/man7/koi8-r.7 index 65fc642b..cddfd887 100644 --- a/upstream/debian-unstable/man7/koi8-r.7 +++ b/upstream/debian-unstable/man7/koi8-r.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH KOI8-R 7 2022-12-15 "Linux man-pages 6.05.01" +.TH KOI8-R 7 2024-05-02 "Linux man-pages 6.8" .SH NAME koi8-r \- Russian character set encoded in octal, decimal, and hexadecimal diff --git a/upstream/debian-unstable/man7/koi8-u.7 b/upstream/debian-unstable/man7/koi8-u.7 index c515c2a5..8fded1e7 100644 --- a/upstream/debian-unstable/man7/koi8-u.7 +++ b/upstream/debian-unstable/man7/koi8-u.7 @@ -5,7 +5,7 @@ .\" .\" 2009-01-15, mtk, Some edits .\" -.TH KOI8-U 7 2022-12-15 "Linux man-pages 6.05.01" +.TH KOI8-U 7 2024-05-02 "Linux man-pages 6.8" .SH NAME koi8-u \- Ukrainian character set encoded in octal, decimal, and hexadecimal diff --git a/upstream/debian-unstable/man7/landlock.7 b/upstream/debian-unstable/man7/landlock.7 index 96f82174..87b2135b 100644 --- a/upstream/debian-unstable/man7/landlock.7 +++ b/upstream/debian-unstable/man7/landlock.7 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH Landlock 7 2023-05-03 "Linux man-pages 6.05.01" +.TH Landlock 7 2024-05-02 "Linux man-pages 6.8" .SH NAME Landlock \- unprivileged access-control .SH DESCRIPTION @@ -18,7 +18,7 @@ the existing system-wide access-controls. This kind of sandbox is expected to help mitigate the security impact of bugs, and unexpected or malicious behaviors in applications. -.PP +.P A Landlock security policy is a set of access rights (e.g., open a file in read-only, make a directory, etc.) tied to a file hierarchy. @@ -33,7 +33,7 @@ adds a new rule to a ruleset; .IP \[bu] .BR landlock_restrict_self (2) enforces a ruleset on the calling thread. -.PP +.P To be able to use these system calls, the running kernel must support Landlock and it must be enabled at boot time. @@ -57,7 +57,7 @@ See and .BR landlock_create_ruleset (2) for more context. -.PP +.P A file can only receive these access rights: .TP .B LANDLOCK_ACCESS_FS_EXECUTE @@ -98,14 +98,14 @@ using and .BR LANDLOCK_ACCESS_FS_WRITE_FILE . This access right is available since the third version of the Landlock ABI. -.PP +.P A directory can receive access rights related to files or directories. The following access right is applied to the directory itself, and the directories beneath it: .TP .B LANDLOCK_ACCESS_FS_READ_DIR Open a directory or list its content. -.PP +.P However, the following access rights only apply to the content of a directory, not the directory itself: @@ -194,7 +194,7 @@ Indeed, this complementary policy is composed with the potentially other rulesets already restricting this thread. A sandboxed thread can then safely add more constraints to itself with a new enforced ruleset. -.PP +.P One policy layer grants access to a file path if at least one of its rules encountered on the path grants the access. A sandboxed thread can only access a file path @@ -208,7 +208,7 @@ which means that these access rights can be propagated with bind mounts (cf. .BR mount_namespaces (7)) but not with OverlayFS. -.PP +.P A bind mount mirrors a source file hierarchy to a destination. The destination hierarchy is then composed of the exact same files, on which Landlock rules can be tied, @@ -217,7 +217,7 @@ These rules restrict access when they are encountered on a path, which means that they can restrict access to multiple file hierarchies at the same time, whether these hierarchies are the result of bind mounts or not. -.PP +.P An OverlayFS mount point consists of upper and lower layers. These layers are combined in a merge directory, result of the mount point. This merge hierarchy may include files from the upper and lower layers, @@ -244,7 +244,7 @@ For instance, one process's thread may apply Landlock rules to itself, but they will not be automatically applied to other sibling threads (unlike POSIX thread credential changes, cf. .BR nptl (7)). -.PP +.P When a thread sandboxes itself, we have the guarantee that the related security policy will stay enforced on all this thread's descendants. @@ -271,14 +271,14 @@ and both change the contents of a file and sometimes overlap in non-intuitive ways. It is recommended to always specify both of these together. -.PP +.P A particularly surprising example is .BR creat (2). The name suggests that this system call requires the rights to create and write files. However, it also requires the truncate right if an existing file under the same name is already present. -.PP +.P It should also be noted that truncating files does not require the .B LANDLOCK_ACCESS_FS_WRITE_FILE right. @@ -288,7 +288,7 @@ system call, this can also be done through .BR open (2) with the flags .IR "O_RDONLY\ |\ O_TRUNC" . -.PP +.P When opening a file, the availability of the .B LANDLOCK_ACCESS_FS_TRUNCATE right is associated with the newly created file descriptor @@ -302,7 +302,7 @@ but not during the subsequent and .BR write (2) calls. -.PP +.P As a consequence, it is possible to have multiple open file descriptors for the same file, where one grants the right to truncate the file and the other does not. @@ -311,7 +311,7 @@ keeping their Landlock properties, even when these processes do not have an enforced Landlock ruleset. .SH VERSIONS Landlock was introduced in Linux 5.13. -.PP +.P To determine which Landlock features are available, users should query the Landlock ABI version: .TS @@ -338,20 +338,19 @@ _ _ _ _ _ _ 3 6.2 LANDLOCK_ACCESS_FS_TRUNCATE .TE -.sp 1 -.PP +.P Users should use the Landlock ABI version rather than the kernel version to determine which features are available. The mainline kernel versions listed here are only included for orientation. Kernels from other sources may contain backported features, and their version numbers may not match. -.PP +.P To query the running kernel's Landlock ABI version, programs may pass the .B LANDLOCK_CREATE_RULESET_VERSION flag to .BR landlock_create_ruleset (2). -.PP +.P When building fallback mechanisms for compatibility with older kernels, users are advised to consider the special semantics of the .B LANDLOCK_ACCESS_FS_REFER @@ -394,7 +393,7 @@ accessible through these system call families: Future Landlock evolutions will enable to restrict them. .SH EXAMPLES We first need to create the ruleset that will contain our rules. -.PP +.P For this example, the ruleset will contain rules that only allow read actions, but write actions will be denied. @@ -402,7 +401,7 @@ The ruleset then needs to handle both of these kinds of actions. See the .B DESCRIPTION section for the description of filesystem actions. -.PP +.P .in +4n .EX struct landlock_ruleset_attr attr = {0}; @@ -426,11 +425,11 @@ attr.handled_access_fs = LANDLOCK_ACCESS_FS_TRUNCATE; .EE .in -.PP +.P To be compatible with older Linux versions, we detect the available Landlock ABI version, and only use the available subset of access rights: -.PP +.P .in +4n .EX /* @@ -459,11 +458,11 @@ abi = MIN(abi, 3); attr.handled_access_fs &= landlock_fs_access_rights[abi \- 1]; .EE .in -.PP +.P The available access rights for each ABI version are listed in the .B VERSIONS section. -.PP +.P If our program needed to create hard links or rename files between different directories .RB ( LANDLOCK_ACCESS_FS_REFER ), @@ -474,13 +473,13 @@ Therefore, if the program needed to do file reparenting, and if only Landlock ABI version 1 was available, we could not restrict the process. -.PP +.P Now that the ruleset attributes are determined, we create the Landlock ruleset and acquire a file descriptor as a handle to it, using .BR landlock_create_ruleset (2): -.PP +.P .in +4n .EX ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0); @@ -490,13 +489,13 @@ if (ruleset_fd == \-1) { } .EE .in -.PP +.P We can now add a new rule to the ruleset through the ruleset's file descriptor. The requested access rights must be a subset of the access rights which were specified in .I attr.handled_access_fs at ruleset creation time. -.PP +.P In this example, the rule will only allow reading the file hierarchy .IR /usr . Without another rule, write actions would then be denied by the ruleset. @@ -507,7 +506,7 @@ to the ruleset, we open it with the flag and fill the .I struct landlock_path_beneath_attr with this file descriptor. -.PP +.P .in +4n .EX struct landlock_path_beneath_attr path_beneath = {0}; @@ -534,14 +533,14 @@ if (err) { } .EE .in -.PP +.P We now have a ruleset with one rule allowing read access to .I /usr while denying all other handled accesses for the filesystem. The next step is to restrict the current thread from gaining more privileges (e.g., thanks to a set-user-ID binary). -.PP +.P .in +4n .EX if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { @@ -551,9 +550,9 @@ if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { } .EE .in -.PP +.P The current thread is now ready to sandbox itself with the ruleset. -.PP +.P .in +4n .EX if (landlock_restrict_self(ruleset_fd, 0)) { @@ -564,7 +563,7 @@ if (landlock_restrict_self(ruleset_fd, 0)) { close(ruleset_fd); .EE .in -.PP +.P If the .BR landlock_restrict_self (2) system call succeeds, the current thread is now restricted and @@ -573,7 +572,7 @@ Once a thread is landlocked, there is no way to remove its security policy; only adding more restrictions is allowed. These threads are now in a new Landlock domain, merge of their parent one (if any) with the new ruleset. -.PP +.P Full working code can be found in .UR https://git.kernel.org/\:pub/\:scm/\:linux/\:kernel/\:git/\:stable/\:linux.git/\:tree/\:samples/\:landlock/\:sandboxer.c .UE @@ -581,6 +580,6 @@ Full working code can be found in .BR landlock_create_ruleset (2), .BR landlock_add_rule (2), .BR landlock_restrict_self (2) -.PP +.P .UR https://landlock.io/ .UE diff --git a/upstream/debian-unstable/man7/libc.7 b/upstream/debian-unstable/man7/libc.7 index 7a62251d..25f6ccd6 100644 --- a/upstream/debian-unstable/man7/libc.7 +++ b/upstream/debian-unstable/man7/libc.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH libc 7 2023-02-05 "Linux man-pages 6.05.01" +.TH libc 7 2024-05-02 "Linux man-pages 6.8" .SH NAME libc \- overview of standard C libraries on Linux .SH DESCRIPTION @@ -36,7 +36,7 @@ Release 1.0 of glibc was made in September 1992. (There were earlier 0.x releases.) The next major release of glibc was 2.0, at the beginning of 1997. -.PP +.P The pathname .I /lib/libc.so.6 (or something similar) @@ -61,7 +61,7 @@ this version used the shared library soname .IR libc.so.5 . For a while, Linux libc was the standard C library in many Linux distributions. -.PP +.P However, notwithstanding the original motivations of the Linux libc effort, by the time glibc 2.0 was released @@ -72,7 +72,7 @@ soon switched back to glibc. To avoid any confusion with Linux libc versions, glibc 2.0 and later used the shared library soname .IR libc.so.6 . -.PP +.P Since the switch from Linux libc to glibc 2.0 occurred long ago, .I man-pages no longer takes care to document Linux libc details. diff --git a/upstream/debian-unstable/man7/life_cycle-cipher.7ssl b/upstream/debian-unstable/man7/life_cycle-cipher.7ssl index e76fa882..5af164d0 100644 --- a/upstream/debian-unstable/man7/life_cycle-cipher.7ssl +++ b/upstream/debian-unstable/man7/life_cycle-cipher.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "LIFE_CYCLE-CIPHER 7SSL" -.TH LIFE_CYCLE-CIPHER 7SSL 2024-02-03 3.1.5 OpenSSL +.TH LIFE_CYCLE-CIPHER 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/life_cycle-digest.7ssl b/upstream/debian-unstable/man7/life_cycle-digest.7ssl index 0442c495..9c96c63b 100644 --- a/upstream/debian-unstable/man7/life_cycle-digest.7ssl +++ b/upstream/debian-unstable/man7/life_cycle-digest.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "LIFE_CYCLE-DIGEST 7SSL" -.TH LIFE_CYCLE-DIGEST 7SSL 2024-02-03 3.1.5 OpenSSL +.TH LIFE_CYCLE-DIGEST 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/life_cycle-kdf.7ssl b/upstream/debian-unstable/man7/life_cycle-kdf.7ssl index 7c0db3bf..44b97548 100644 --- a/upstream/debian-unstable/man7/life_cycle-kdf.7ssl +++ b/upstream/debian-unstable/man7/life_cycle-kdf.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "LIFE_CYCLE-KDF 7SSL" -.TH LIFE_CYCLE-KDF 7SSL 2024-02-03 3.1.5 OpenSSL +.TH LIFE_CYCLE-KDF 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/life_cycle-mac.7ssl b/upstream/debian-unstable/man7/life_cycle-mac.7ssl index 7b8a1e4b..f2f13add 100644 --- a/upstream/debian-unstable/man7/life_cycle-mac.7ssl +++ b/upstream/debian-unstable/man7/life_cycle-mac.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "LIFE_CYCLE-MAC 7SSL" -.TH LIFE_CYCLE-MAC 7SSL 2024-02-03 3.1.5 OpenSSL +.TH LIFE_CYCLE-MAC 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/life_cycle-pkey.7ssl b/upstream/debian-unstable/man7/life_cycle-pkey.7ssl index f57ea6ad..59736cd7 100644 --- a/upstream/debian-unstable/man7/life_cycle-pkey.7ssl +++ b/upstream/debian-unstable/man7/life_cycle-pkey.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "LIFE_CYCLE-PKEY 7SSL" -.TH LIFE_CYCLE-PKEY 7SSL 2024-02-03 3.1.5 OpenSSL +.TH LIFE_CYCLE-PKEY 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/life_cycle-rand.7ssl b/upstream/debian-unstable/man7/life_cycle-rand.7ssl index e03ca584..99b2c548 100644 --- a/upstream/debian-unstable/man7/life_cycle-rand.7ssl +++ b/upstream/debian-unstable/man7/life_cycle-rand.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "LIFE_CYCLE-RAND 7SSL" -.TH LIFE_CYCLE-RAND 7SSL 2024-02-03 3.1.5 OpenSSL +.TH LIFE_CYCLE-RAND 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/locale.7 b/upstream/debian-unstable/man7/locale.7 index 49aa3670..5dc832c2 100644 --- a/upstream/debian-unstable/man7/locale.7 +++ b/upstream/debian-unstable/man7/locale.7 @@ -8,7 +8,7 @@ .\" <jochen.hein@delphi.central.de> .\" Modified Thu Apr 25 00:43:19 2002 by Bruno Haible <bruno@clisp.org> .\" -.TH locale 7 2023-05-03 "Linux man-pages 6.05.01" +.TH locale 7 2024-05-02 "Linux man-pages 6.8" .SH NAME locale \- description of multilanguage support .SH SYNOPSIS @@ -22,18 +22,18 @@ such as language for messages, different character sets, lexicographic conventions, and so on. A program needs to be able to determine its locale and act accordingly to be portable to different cultures. -.PP +.P The header .I <locale.h> declares data types, functions, and macros which are useful in this task. -.PP +.P The functions it declares are .BR setlocale (3) to set the current locale, and .BR localeconv (3) to get information about number formatting. -.PP +.P There are different categories for locale information a program might need; they are declared as macros. Using them as the first argument @@ -131,7 +131,7 @@ functions also obey the environment variable .B LANGUAGE (containing a colon-separated list of locales) if the category is set to a valid locale other than -.BR """C""" . +.BR \[dq]C\[dq] . This category also affects the behavior of .BR catopen (3). .TP @@ -213,7 +213,7 @@ and .TP .B LC_ALL All of the above. -.PP +.P If the second argument to .BR setlocale (3) is an empty string, @@ -234,13 +234,13 @@ If there is a non-null environment variable the value of .B LANG is used. -.PP +.P Values about local numeric formatting is made available in a .I struct lconv returned by the .BR localeconv (3) function, which has the following declaration: -.PP +.P .in +4n .EX struct lconv { @@ -299,7 +299,7 @@ based on implementations that first appeared in glibc 2.3. These extensions are designed to address the problem that the traditional locale APIs do not mix well with multithreaded applications and with applications that must deal with multiple locales. -.PP +.P The extensions take the form of new functions for creating and manipulating locale objects .RB ( newlocale (3), diff --git a/upstream/debian-unstable/man7/mailaddr.7 b/upstream/debian-unstable/man7/mailaddr.7 index 8218daaa..6154e8dd 100644 --- a/upstream/debian-unstable/man7/mailaddr.7 +++ b/upstream/debian-unstable/man7/mailaddr.7 @@ -24,7 +24,7 @@ .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" %%%LICENSE_END .\" -.TH mailaddr 7 2023-02-05 "Linux man-pages 6.05.01" +.TH mailaddr 7 2024-05-02 "Linux man-pages 6.8" .UC 5 .SH NAME mailaddr \- mail addressing description @@ -33,16 +33,16 @@ mailaddr \- mail addressing description This manual page gives a brief introduction to SMTP mail addresses, as used on the Internet. These addresses are in the general format -.PP +.P .in +4n .EX user@domain .EE .in -.PP +.P where a domain is a hierarchical dot-separated list of subdomains. These examples are valid forms of the same address: -.PP +.P .in +4n .EX john.doe@monet.example.com @@ -50,11 +50,11 @@ John Doe <john.doe@monet.example.com> john.doe@monet.example.com (John Doe) .EE .in -.PP +.P The domain part ("monet.example.com") is a mail-accepting domain. It can be a host and in the past it usually was, but it doesn't have to be. The domain part is not case sensitive. -.PP +.P The local part ("john.doe") is often a username, but its meaning is defined by the local software. Sometimes it is case sensitive, @@ -62,7 +62,7 @@ although that is unusual. If you see a local-part that looks like garbage, it is usually because of a gateway between an internal e-mail system and the net, here are some examples: -.PP +.P .in +4n .EX "surname/admd=telemail/c=us/o=hp/prmd=hp"@some.where @@ -71,17 +71,17 @@ machine!machine!name@some.where I2461572@some.where .EE .in -.PP +.P (These are, respectively, an X.400 gateway, a gateway to an arbitrary internal mail system that lacks proper internet support, an UUCP gateway, and the last one is just boring username policy.) -.PP +.P The real-name part ("John Doe") can either be placed before <>, or in () at the end. (Strictly speaking the two aren't the same, but the difference is beyond the scope of this page.) The name may have to be quoted using "", for example, if it contains ".": -.PP +.P .in +4n .EX "John Q. Doe" <john.doe@monet.example.com> @@ -99,17 +99,17 @@ In the past, sometimes one had to route a message through several hosts to get it to its final destination. Addresses which show these relays are termed "route-addrs". These use the syntax: -.PP +.P .in +4n .EX <@hosta,@hostb:user@hostc> .EE .in -.PP +.P This specifies that the message should be sent to hosta, from there to hostb, and finally to hostc. Many hosts disregard route-addrs and send directly to hostc. -.PP +.P Route-addrs are very unusual now. They occur sometimes in old mail archives. It is generally possible to ignore all but the "user@hostc" @@ -128,7 +128,7 @@ The "postmaster" address is not case sensitive. .BR aliases (5), .BR forward (5), .BR sendmail (8) -.PP +.P .UR http://www.ietf.org\:/rfc\:/rfc5322.txt IETF RFC\ 5322 .UE diff --git a/upstream/debian-unstable/man7/man-pages.7 b/upstream/debian-unstable/man7/man-pages.7 index 6d8b0ea8..053d9fcc 100644 --- a/upstream/debian-unstable/man7/man-pages.7 +++ b/upstream/debian-unstable/man7/man-pages.7 @@ -8,7 +8,7 @@ .\" 2007-05-30 created by mtk, using text from old man.7 plus .\" rewrites and additional text. .\" -.TH man-pages 7 2023-03-30 "Linux man-pages 6.05.01" +.TH man-pages 7 2024-05-02 "Linux man-pages 6.8" .SH NAME man-pages \- conventions for writing Linux man pages .SH SYNOPSIS @@ -86,12 +86,12 @@ submitted inline. The first command in a man page should be a .B TH command: -.PP +.P .RS .B \&.TH .I "title section date source manual-section" .RE -.PP +.P The arguments of the command are as follows: .TP .I title @@ -126,7 +126,7 @@ Most manual pages should include at least the sections. Arrange a new manual page so that sections are placed in the order shown in the list. -.PP +.P .RS .TS l l. @@ -163,7 +163,7 @@ COPYRIGHT [Not used in man-pages] \fBSEE ALSO\fP .TE .RE -.PP +.P .IR "Where a traditional heading would apply" ", " "please use it" ; this kind of consistency can make the information easier to understand. If you must, you can create your own @@ -172,7 +172,7 @@ be especially useful for pages in Sections 4 and 5). However, before doing this, consider whether you could use the traditional headings, with some subsections (\fI.SS\fP) within those sections. -.PP +.P The following list elaborates on the contents of each of the above sections. .TP @@ -386,7 +386,7 @@ The .BR syscalls (2) manual page also provides information about kernel versions in which various system calls first appeared. -.PP +.P Old versions of standards should be mentioned here, rather than in STANDARDS, for example, @@ -479,13 +479,13 @@ project. Wrap the function prototype(s) in a .IR .nf / .fi pair to prevent filling. -.PP +.P In general, where more than one function prototype is shown in the SYNOPSIS, the prototypes should .I not be separated by blank lines. However, blank lines (achieved using -.IR .PP ) +.IR .P ) may be added in the following cases: .IP \[bu] 3 to separate long lists of function prototypes into related groups @@ -493,7 +493,7 @@ to separate long lists of function prototypes into related groups .BR list (3)); .IP \[bu] in other cases that may improve readability. -.PP +.P In the SYNOPSIS, a long function prototype may need to be continued over to the next line. The continuation line is indented according to the following rules: @@ -565,7 +565,7 @@ Make free use of macro pairs to allow table cells to be broken over multiple lines (also bearing in mind that pages may sometimes be rendered to a width of less than 80 columns). -.PP +.P For examples of all of the above, see the source code of various pages. .SH STYLE GUIDE The following subsections describe the preferred style for the @@ -584,7 +584,7 @@ pronoun is acceptable. For manual pages that describe a command (typically in Sections 1 and 8), the arguments are always specified using italics, .IR "even in the SYNOPSIS section" . -.PP +.P The name of the command, and its options, should always be formatted in bold. .\" @@ -593,11 +593,11 @@ For manual pages that describe functions (typically in Sections 2 and 3), the arguments are always specified using italics, .IR "even in the SYNOPSIS section" , where the rest of the function is specified in bold: -.PP +.P .BI " int myfunction(int " argc ", char **" argv ); -.PP +.P Variable names should, like argument names, be specified in italics. -.PP +.P Any reference to the subject of the current manual page should be written with the name in bold followed by a pair of parentheses in Roman (normal) font. @@ -606,11 +606,11 @@ For example, in the man page, references to the subject of the page would be written as: .BR fcntl (). The preferred way to write this in the source file is: -.PP +.P .EX .BR fcntl () .EE -.PP +.P (Using this format, rather than the use of "\efB...\efP()" makes it easier to write tools that parse man page source files.) .\" @@ -676,7 +676,7 @@ usually covered by this type of list. Numbered notes Not really a list, but the syntax is identical to "positional lists". -.PP +.P There should always be exactly 2 spaces between the list symbol and the elements. This doesn't apply to "tagged paragraphs", @@ -684,14 +684,14 @@ which use the default indentation rules. .\" .SS Formatting conventions (general) Paragraphs should be separated by suitable markers (usually either -.I .PP +.I .P or .IR .IP ). Do .I not separate paragraphs using blank lines, as this results in poor rendering in some output formats (such as PostScript and PDF). -.PP +.P Filenames (whether pathnames, or references to header files) are always in italics (e.g., .IR <stdio.h> ), @@ -701,26 +701,26 @@ When referring to a standard header file include, specify the header file surrounded by angle brackets, in the usual C way (e.g., .IR <stdio.h> ). -.PP +.P Special macros, which are usually in uppercase, are in bold (e.g., .BR MAXINT ). Exception: don't boldface NULL. -.PP +.P When enumerating a list of error codes, the codes are in bold (this list usually uses the .B \&.TP macro). -.PP +.P Complete commands should, if long, be written as an indented line on their own, with a blank line before and after the command, for example -.PP +.P .in +4n .EX man 7 man\-pages .EE .in -.PP +.P If the command is short, then it can be included inline in the text, in italic format, for example, .IR "man 7 man-pages" . @@ -728,23 +728,23 @@ In this case, it may be worth using nonbreaking spaces (\e[ti]) at suitable places in the command. Command options should be written in italics (e.g., .IR \-l ). -.PP +.P Expressions, if not written on a separate indented line, should be specified in italics. Again, the use of nonbreaking spaces may be appropriate if the expression is inlined with normal text. -.PP +.P When showing example shell sessions, user input should be formatted in bold, for example -.PP +.P .in +4n .EX $ \fBdate\fP Thu Jul 7 13:01:27 CEST 2016 .EE .in -.PP +.P Any reference to another man page should be written with the name in bold, .I always @@ -753,15 +753,15 @@ formatted in Roman (normal) font, without any separating spaces (e.g., .BR intro (2)). The preferred way to write this in the source file is: -.PP +.P .EX .BR intro (2) .EE -.PP +.P (Including the section number in cross references lets tools like .BR man2html (1) create properly hyperlinked pages.) -.PP +.P Control characters should be written in bold face, with no quotes; for example, .BR \[ha]X . @@ -771,7 +771,7 @@ Starting with release 2.59, follows American spelling conventions (previously, there was a random mix of British and American spellings); please write all new pages and patches according to these conventions. -.PP +.P Aside from the well-known spelling differences, there are a few other subtleties to watch for: .IP \[bu] 3 @@ -797,7 +797,7 @@ capitalize the first word in the heading, but otherwise use lowercase, except where English usage (e.g., proper nouns) or programming language requirements (e.g., identifier names) dictate otherwise. For example: -.PP +.P .in +4n .EX \&.SS Unicode under Linux @@ -815,14 +815,14 @@ format them using the and .I .EE macros, and surround them with suitable paragraph markers (either -.I .PP +.I .P or .IR .IP ). For example: -.PP +.P .in +4n .EX -\&.PP +\&.P \&.in +4n \&.EX int @@ -832,7 +832,7 @@ main(int argc, char *argv[]) } \&.EE \&.in -\&.PP +\&.P .EE .in .SS Preferred terms @@ -897,7 +897,7 @@ Except if referring to result of "uname\ \-m" or similar T} zeros zeroes .TE -.PP +.P See also the discussion .I Hyphenation of attributive compounds below. @@ -958,10 +958,10 @@ is the .IR "null byte" , a byte with the value 0, represented in C via the character constant .IR \[aq]\e0\[aq] . -.PP +.P The preferred term for the pointer is "null pointer" or simply "NULL"; avoid writing "NULL pointer". -.PP +.P The preferred term for the byte is "null byte". Avoid writing "NUL", since it is too easily confused with "NULL". Avoid also the terms "zero byte" and "null character". @@ -977,7 +977,7 @@ macro pair .BR groff_man (7)). This produces proper hyperlinks that can be used in a web browser, when rendering a page with, say: -.PP +.P .in +4n .EX BROWSER=firefox man -H pagename @@ -988,11 +988,11 @@ In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", "cf.", and "a.k.a." should be avoided, in favor of suitable full wordings ("for example", "that is", "and so on", "compare to", "also known as"). -.PP +.P The only place where such abbreviations may be acceptable is in .I short parenthetical asides (e.g., like this one). -.PP +.P Always include periods in such abbreviations, as shown here. In addition, "e.g." and "i.e." should always be followed by a comma. .SS Em-dashes @@ -1046,7 +1046,7 @@ subcomponent subdirectory subsystem .TE -.PP +.P Hyphens should be retained when the prefixes are used in nonstandard English words, with trademarks, proper nouns, acronyms, or compound terms. Some examples: @@ -1058,7 +1058,7 @@ non-English non-NULL non-real-time .TE -.PP +.P Finally, note that "re-create" and "recreate" are two different verbs, and the former is probably what you want. .\" @@ -1069,15 +1069,15 @@ for man page cross references such as or when writing options that have a leading dash, such as in .IR "ls\ \-l"), use the following form in the man page source: -.PP +.P .in +4n .EX \e\- .EE .in -.PP +.P This guideline applies also to code examples. -.PP +.P The use of real minus signs serves the following purposes: .\" https://lore.kernel.org/linux-man/20210121061158.5ul7226fgbrmodbt@localhost.localdomain/ .IP \[bu] 3 @@ -1087,26 +1087,26 @@ notably in PDF and on Unicode/UTF\-8-capable terminals. .IP \[bu] To generate glyphs that when copied from rendered pages will produce real minus signs when pasted into a terminal. -.PP +.P To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF, use "\e[aq]" ("apostrophe quote"); for example -.PP +.P .in +4n .EX \e[aq]C\e[aq] .EE .in -.PP +.P where .I C is the quoted character. This guideline applies also to character constants used in code examples. -.PP +.P Where a proper caret (\[ha]) that renders well in both a terminal and PDF is required, use "\\[ha]". This is especially necessary in code samples, to get a nicely rendered caret when rendering to PDF. -.PP +.P Using a naked "\[ti]" character results in a poor rendering in PDF. Instead use "\\[ti]". This is especially necessary in code samples, @@ -1195,7 +1195,7 @@ as in: .in .IP Always do this if the explanatory text includes a shell session log. -.PP +.P If you include a shell session log demonstrating the use of a program or other system feature: .IP \[bu] 3 @@ -1205,7 +1205,7 @@ Indent the session log by four spaces. .IP \[bu] Boldface the user input text, to distinguish it from output produced by the system. -.PP +.P For some examples of what example programs should look like, see .BR wait (2) and diff --git a/upstream/debian-unstable/man7/man.7 b/upstream/debian-unstable/man7/man.7 deleted file mode 100644 index 62c9f563..00000000 --- a/upstream/debian-unstable/man7/man.7 +++ /dev/null @@ -1,508 +0,0 @@ -.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler -.\" (faith@cs.unc.edu and dwheeler@ida.org) -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" Modified Sun Jul 25 11:06:05 1993 by Rik Faith (faith@cs.unc.edu) -.\" Modified Sat Jun 8 00:39:52 1996 by aeb -.\" Modified Wed Jun 16 23:00:00 1999 by David A. Wheeler (dwheeler@ida.org) -.\" Modified Thu Jul 15 12:43:28 1999 by aeb -.\" Modified Sun Jan 6 18:26:25 2002 by Martin Schulze <joey@infodrom.org> -.\" Modified Tue Jul 27 20:12:02 2004 by Colin Watson <cjwatson@debian.org> -.\" 2007-05-30, mtk: various rewrites and moved much text to new man-pages.7. -.\" -.TH man 7 2023-07-29 "Linux man-pages 6.05.01" -.SH NAME -man \- macros to format man pages -.SH SYNOPSIS -.B groff \-Tascii \-man -.I file -\&... -.br -.B groff \-Tps \-man -.I file -\&... -.PP -.B man -.RI [ section ] -.I title -.SH DESCRIPTION -This manual page explains the -.B "groff an.tmac" -macro package (often called the -.B man -macro package). -This macro package should be used by developers when -writing or porting man pages for Linux. -It is fairly compatible with other -versions of this macro package, so porting man pages should not be a major -problem (exceptions include the NET-2 BSD release, which uses a totally -different macro package called mdoc; see -.BR mdoc (7)). -.PP -Note that NET-2 BSD mdoc man pages can be used with -.B groff -simply by specifying the -.B \-mdoc -option instead of the -.B \-man -option. -Using the -.B \-mandoc -option is, however, recommended, since this will automatically detect which -macro package is in use. -.PP -For conventions that should be employed when writing man pages -for the Linux \fIman-pages\fP package, see -.BR man\-pages (7). -.SS Title line -The first command in a man page (after comment lines, -that is, lines that start with \fB.\e"\fP) should be -.PP -.RS -.B .TH -.I "title section date source manual" -.RE -.PP -For details of the arguments that should be supplied to the -.B TH -command, see -.BR man\-pages (7). -.PP -Note that BSD mdoc-formatted pages begin with the -.B Dd -command, not the -.B TH -command. -.SS Sections -Sections are started with -.B .SH -followed by the heading name. -.\" The following doesn't seem to be required (see Debian bug 411303), -.\" If the name contains spaces and appears -.\" on the same line as -.\" .BR .SH , -.\" then place the heading in double quotes. -.PP -The only mandatory heading is NAME, which should be the first section and -be followed on the next line by a one-line description of the program: -.PP -.RS -\&.SH NAME -.br -item \e- description -.RE -.PP -It is extremely important that this format is followed, and that there is a -backslash before the single dash which follows the item name. -This syntax is used by the -.BR mandb (8) -program to create a database of short descriptions for the -.BR whatis (1) -and -.BR apropos (1) -commands. -(See -.BR lexgrog (1) -for further details on the syntax of the NAME section.) -.PP -For a list of other sections that might appear in a manual page, see -.BR man\-pages (7). -.SS Fonts -The commands to select the type face are: -.TP 4 -.B .B -Bold -.TP -.B .BI -Bold alternating with italics -(especially useful for function specifications) -.TP -.B .BR -Bold alternating with Roman -(especially useful for referring to other -manual pages) -.TP -.B .I -Italics -.TP -.B .IB -Italics alternating with bold -.TP -.B .IR -Italics alternating with Roman -.TP -.B .RB -Roman alternating with bold -.TP -.B .RI -Roman alternating with italics -.TP -.B .SB -Small alternating with bold -.TP -.B .SM -Small (useful for acronyms) -.PP -Traditionally, each command can have up to six arguments, but the GNU -implementation removes this limitation (you might still want to limit -yourself to 6 arguments for portability's sake). -Arguments are delimited by spaces. -Double quotes can be used to specify an argument which contains spaces. -For the macros that produce alternating type faces, -the arguments will be printed next to each other without -intervening spaces, so that the -.B .BR -command can be used to specify a word in bold followed by a mark of -punctuation in Roman. -If no arguments are given, the command is applied to the following line -of text. -.SS Other macros and strings -Below are other relevant macros and predefined strings. -Unless noted otherwise, all macros -cause a break (end the current line of text). -Many of these macros set or use the "prevailing indent". -The "prevailing indent" value is set by any macro with the parameter -.I i -below; -macros may omit -.I i -in which case the current prevailing indent will be used. -As a result, successive indented paragraphs can use the same indent without -respecifying the indent value. -A normal (nonindented) paragraph resets the prevailing indent value -to its default value (0.5 inches). -By default, a given indent is measured in ens; -try to use ens or ems as units for -indents, since these will automatically adjust to font size changes. -The other key macro definitions are: -.SS Normal paragraphs -.TP 9m -.B .LP -Same as -.B .PP -(begin a new paragraph). -.TP -.B .P -Same as -.B .PP -(begin a new paragraph). -.TP -.B .PP -Begin a new paragraph and reset prevailing indent. -.SS Relative margin indent -.TP 9m -.BI .RS " i" -Start relative margin indent: moves the left margin -.I i -to the right (if -.I i -is omitted, the prevailing indent value is used). -A new prevailing indent is set to 0.5 inches. -As a result, all following paragraph(s) will be -indented until the corresponding -.BR .RE . -.TP -.B .RE -End relative margin indent and -restores the previous value of the prevailing indent. -.SS Indented paragraph macros -.TP 9m -.BI .HP " i" -Begin paragraph with a hanging indent -(the first line of the paragraph is at the left margin of -normal paragraphs, and the rest of the paragraph's lines are indented). -.TP -.BI .IP " x i" -Indented paragraph with optional hanging tag. -If the tag -.I x -is omitted, the entire following paragraph is indented by -.IR i . -If the tag -.I x -is provided, it is hung at the left margin -before the following indented paragraph -(this is just like -.B .TP -except the tag is included with the command instead of being on the -following line). -If the tag is too long, the text after the tag will be moved down to the -next line (text will not be lost or garbled). -For bulleted lists, use this macro with \e(bu (bullet) or \e(em (em dash) -as the tag, and for numbered lists, use the number or letter followed by -a period as the tag; -this simplifies translation to other formats. -.TP -.BI .TP " i" -Begin paragraph with hanging tag. -The tag is given on the next line, but -its results are like those of the -.B .IP -command. -.SS Hypertext link macros -.TP -.BI .UR " url" -Insert a hypertext link to the URI (URL) -.IR url , -with all text up to the following -.B .UE -macro as the link text. -.TP -.BR .UE \~\c -.RI [ trailer ] -Terminate the link text of the preceding -.B .UR -macro, with the optional -.I trailer -(if present, usually a closing parenthesis and/or end-of-sentence -punctuation) immediately following. -For non-HTML output devices (e.g., -.BR "man \-Tutf8" ), -the link text is followed by the URL in angle brackets; if there is no -link text, the URL is printed as its own link text, surrounded by angle -brackets. -(Angle brackets may not be available on all output devices.) -For the HTML output device, the link text is hyperlinked to the URL; if -there is no link text, the URL is printed as its own link text. -.PP -These macros have been supported since GNU Troff 1.20 (2009-01-05) and -Heirloom Doctools Troff since 160217 (2016-02-17). -.SS Miscellaneous macros -.TP 9m -.B .DT -Reset tabs to default tab values (every 0.5 inches); -does not cause a break. -.TP -.BI .PD " d" -Set inter-paragraph vertical distance to d -(if omitted, d=0.4v); -does not cause a break. -.TP -.BI .SS " t" -Subheading -.I t -(like -.BR .SH , -but used for a subsection inside a section). -.SS Predefined strings -The -.B man -package has the following predefined strings: -.TP -\e*R -Registration Symbol: \*R -.TP -\e*S -Change to default font size -.TP -\e*(Tm -Trademark Symbol: \*(Tm -.TP -\e*(lq -Left angled double quote: \*(lq -.TP -\e*(rq -Right angled double quote: \*(rq -.SS Safe subset -Although technically -.B man -is a troff macro package, in reality a large number of other tools -process man page files that don't implement all of troff's abilities. -Thus, it's best to avoid some of troff's more exotic abilities -where possible to permit these other tools to work correctly. -Avoid using the various troff preprocessors -(if you must, go ahead and use -.BR tbl (1), -but try to use the -.B IP -and -.B TP -commands instead for two-column tables). -Avoid using computations; most other tools can't process them. -Use simple commands that are easy to translate to other formats. -The following troff macros are believed to be safe (though in many cases -they will be ignored by translators): -.BR \e" , -.BR . , -.BR ad , -.BR bp , -.BR br , -.BR ce , -.BR de , -.BR ds , -.BR el , -.BR ie , -.BR if , -.BR fi , -.BR ft , -.BR hy , -.BR ig , -.BR in , -.BR na , -.BR ne , -.BR nf , -.BR nh , -.BR ps , -.BR so , -.BR sp , -.BR ti , -.BR tr . -.PP -You may also use many troff escape sequences (those sequences beginning -with \e). -When you need to include the backslash character as normal text, -use \ee. -Other sequences you may use, where x or xx are any characters and N -is any digit, include: -.BR \e\[aq] , -.BR \e\[ga] , -.BR \e- , -.BR \e. , -.BR \e" , -.BR \e% , -.BR \e*x , -.BR \e*(xx , -.BR \e(xx , -.BR \e$N , -.BR \enx , -.BR \en(xx , -.BR \efx , -and -.BR \ef(xx . -Avoid using the escape sequences for drawing graphics. -.PP -Do not use the optional parameter for -.B bp -(break page). -Use only positive values for -.B sp -(vertical space). -Don't define a macro -.RB ( de ) -with the same name as a macro in this or the -mdoc macro package with a different meaning; it's likely that -such redefinitions will be ignored. -Every positive indent -.RB ( in ) -should be paired with a matching negative indent -(although you should be using the -.B RS -and -.B RE -macros instead). -The condition test -.RB ( if,ie ) -should only have \[aq]t\[aq] or \[aq]n\[aq] as the condition. -Only translations -.RB ( tr ) -that can be ignored should be used. -Font changes -.RB ( ft -and the \fB\ef\fP escape sequence) -should only have the values 1, 2, 3, 4, R, I, B, P, or CW -(the ft command may also have no parameters). -.PP -If you use capabilities beyond these, check the -results carefully on several tools. -Once you've confirmed that the additional capability is safe, -let the maintainer of this -document know about the safe command or sequence -that should be added to this list. -.SH FILES -.IR /usr/share/groff/ [*/] tmac/an.tmac -.br -.I /usr/man/whatis -.SH NOTES -By all means include full URLs (or URIs) in the text itself; -some tools such as -.BR man2html (1) -can automatically turn them into hypertext links. -You can also use the -.B UR -and -.B UE -macros to identify links to related information. -If you include URLs, use the full URL -(e.g., -.UR http://www.kernel.org -.UE ) -to ensure that tools can automatically find the URLs. -.PP -Tools processing these files should open the file and examine the first -nonwhitespace character. -A period (.) or single quote (\[aq]) at the beginning -of a line indicates a troff-based file (such as man or mdoc). -A left angle bracket (<) indicates an SGML/XML-based -file (such as HTML or Docbook). -Anything else suggests simple ASCII -text (e.g., a "catman" result). -.PP -Many man pages begin with \fB\[aq]\e"\fP followed by a -space and a list of characters, -indicating how the page is to be preprocessed. -For portability's sake to non-troff translators we recommend -that you avoid using anything other than -.BR tbl (1), -and Linux can detect that automatically. -However, you might want to include this information so your man page -can be handled by other (less capable) systems. -Here are the definitions of the preprocessors invoked by these characters: -.TP 3 -.B e -eqn(1) -.TP -.B g -grap(1) -.TP -.B p -pic(1) -.TP -.B r -refer(1) -.TP -.B t -tbl(1) -.TP -.B v -vgrind(1) -.SH BUGS -Most of the macros describe formatting (e.g., font type and spacing) instead -of marking semantic content (e.g., this text is a reference to another page), -compared to formats like mdoc and DocBook (even HTML has more semantic -markings). -This situation makes it harder to vary the -.B man -format for different media, -to make the formatting consistent for a given media, and to automatically -insert cross-references. -By sticking to the safe subset described above, it should be easier to -automate transitioning to a different reference page format in the future. -.PP -The Sun macro -.B TX -is not implemented. -.\" .SH AUTHORS -.\" .IP \[em] 3m -.\" James Clark (jjc@jclark.com) wrote the implementation of the macro package. -.\" .IP \[em] -.\" Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of -.\" this manual page. -.\" .IP \[em] -.\" Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO -.\" (which influenced this manual page). -.\" .IP \[em] -.\" David A. Wheeler (dwheeler@ida.org) heavily modified this -.\" manual page, such as adding detailed information on sections and macros. -.SH SEE ALSO -.BR apropos (1), -.BR groff (1), -.BR lexgrog (1), -.BR man (1), -.BR man2html (1), -.BR groff_mdoc (7), -.BR whatis (1), -.BR groff_man (7), -.BR groff_www (7), -.BR man\-pages (7), -.BR mdoc (7) diff --git a/upstream/debian-unstable/man7/math_error.7 b/upstream/debian-unstable/man7/math_error.7 index d3b3c1aa..8a0eb7f0 100644 --- a/upstream/debian-unstable/man7/math_error.7 +++ b/upstream/debian-unstable/man7/math_error.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH math_error 7 2023-05-03 "Linux man-pages 6.05.01" +.TH math_error 7 2024-05-02 "Linux man-pages 6.8" .SH NAME math_error \- detecting errors from mathematical functions .SH SYNOPSIS @@ -30,33 +30,33 @@ and as outlined below) described in .BR fenv (3). -.PP +.P A portable program that needs to check for an error from a mathematical function should set .I errno to zero, and make the following call -.PP +.P .in +4n .EX feclearexcept(FE_ALL_EXCEPT); .EE .in -.PP +.P before calling a mathematical function. -.PP +.P Upon return from the mathematical function, if .I errno is nonzero, or the following call (see .BR fenv (3)) returns nonzero -.PP +.P .in +4n .EX fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW); .EE .in -.PP +.P .\" enum .\" { .\" FE_INVALID = 0x01, @@ -67,7 +67,7 @@ fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | .\" FE_INEXACT = 0x20 .\" }; then an error occurred in the mathematical function. -.PP +.P The error conditions that can occur for mathematical functions are described below. .SS Domain error @@ -117,7 +117,7 @@ occurs when the magnitude of the function result means that it cannot be represented in the result type of the function. The return value of the function depends on whether the range error was an overflow or an underflow. -.PP +.P A floating result .I overflows if the result is finite, @@ -139,7 +139,7 @@ is set to and an "overflow" .RB ( FE_OVERFLOW ) floating-point exception is raised. -.PP +.P A floating result .I underflows if the result is too small to be represented in the result type. @@ -154,7 +154,7 @@ may be set to and an "underflow" .RB ( FE_UNDERFLOW ) floating-point exception may be raised. -.PP +.P Some functions deliver a range error if the supplied argument value, or the correct function result, would be .IR subnormal . @@ -186,7 +186,7 @@ A few functions set but don't raise an exception. A very few functions do neither. See the individual manual pages for details. -.PP +.P To avoid the complexities of using .I errno and @@ -199,7 +199,7 @@ For example, the following code ensures that .BR log (3)'s argument is not a NaN and is not zero (a pole error) or less than zero (a domain error): -.PP +.P .in +4n .EX double x, r; @@ -211,13 +211,13 @@ if (isnan(x) || islessequal(x, 0)) { r = log(x); .EE .in -.PP +.P The discussion on this page does not apply to the complex mathematical functions (i.e., those declared by .IR <complex.h> ), which in general are not required to return errors by C99 and POSIX.1. -.PP +.P The .BR gcc (1) .I "\-fno\-math\-errno" @@ -242,5 +242,5 @@ An error can still be tested for using .BR isgreater (3), .BR matherr (3), .BR nan (3) -.PP +.P .I "info libc" diff --git a/upstream/debian-unstable/man7/mount_namespaces.7 b/upstream/debian-unstable/man7/mount_namespaces.7 index 0ce2feef..f187bc12 100644 --- a/upstream/debian-unstable/man7/mount_namespaces.7 +++ b/upstream/debian-unstable/man7/mount_namespaces.7 @@ -4,18 +4,18 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH mount_namespaces 7 2023-05-03 "Linux man-pages 6.05.01" +.TH mount_namespaces 7 2024-05-02 "Linux man-pages 6.8" .SH NAME mount_namespaces \- overview of Linux mount namespaces .SH DESCRIPTION For an overview of namespaces, see .BR namespaces (7). -.PP +.P Mount namespaces provide isolation of the list of mounts seen by the processes in each namespace instance. Thus, the processes in each of the mount namespace instances will see distinct single-directory hierarchies. -.PP +.P The views provided by the .IR /proc/ pid /mounts , .IR /proc/ pid /mountinfo , @@ -28,7 +28,7 @@ correspond to the mount namespace in which the process with the PID resides. (All of the processes that reside in the same mount namespace will see the same view in these files.) -.PP +.P A new mount namespace is created using either .BR clone (2) or @@ -48,7 +48,7 @@ If the namespace is created using .BR unshare (2), the mount list of the new namespace is a copy of the mount list in the caller's previous mount namespace. -.PP +.P Subsequent modifications to the mount list .RB ( mount (2) and @@ -75,7 +75,7 @@ between namespaces (or, more precisely, between the mounts that are members of a .I peer group that are propagating events to one another). -.PP +.P Each mount is marked (via .BR mount (2)) as having one of the following @@ -148,16 +148,16 @@ flags) is performed on a directory subtree, any bind mounts within the subtree are automatically pruned (i.e., not replicated) when replicating that subtree to produce the target subtree. -.PP +.P For a discussion of the propagation type assigned to a new mount, see NOTES. -.PP +.P The propagation type is a per-mount-point setting; some mounts may be marked as shared (with each shared mount being a member of a distinct peer group), while others are private (or slaved or unbindable). -.PP +.P Note that a mount's propagation type determines whether .BR mount (2) and @@ -171,7 +171,7 @@ What happens if the mount itself is unmounted is determined by the propagation type that is in effect for the .I parent of the mount. -.PP +.P Members are added to a .I peer group when a mount is marked as shared and either: @@ -179,21 +179,21 @@ when a mount is marked as shared and either: the mount is replicated during the creation of a new mount namespace; or .IP (b) a new bind mount is created from the mount. -.PP +.P In both of these cases, the new mount joins the peer group of which the existing mount is a member. -.PP +.P A new peer group is also created when a child mount is created under an existing mount that is marked as shared. In this case, the new child mount is also marked as shared and the resulting peer group consists of all the mounts that are replicated under the peers of parent mounts. -.PP +.P A mount ceases to be a member of a peer group when either the mount is explicitly unmounted, or when the mount is implicitly unmounted because a mount namespace is removed (because it has no more member processes). -.PP +.P The propagation type of the mounts in a mount namespace can be discovered via the "optional fields" exposed in .IR /proc/ pid /mountinfo . @@ -239,14 +239,14 @@ For further details, see below. .TP .I unbindable This is an unbindable mount. -.PP +.P If none of the above tags is present, then this is a private mount. .SS MS_SHARED and MS_PRIVATE example Suppose that on a terminal in the initial mount namespace, we mark one mount as shared and another as private, and then view the mounts in .IR /proc/self/mountinfo : -.PP +.P .in +4n .EX sh1# \fBmount \-\-make\-shared /mntS\fP @@ -256,7 +256,7 @@ sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 83 61 8:15 / /mntP rw,relatime .EE .in -.PP +.P From the .I /proc/self/mountinfo output, we see that @@ -273,18 +273,18 @@ and is the root directory, .IR / , which is mounted as private: -.PP +.P .in +4n .EX sh1# \fBcat /proc/self/mountinfo | awk \[aq]$1 == 61\[aq] | sed \[aq]s/ \- .*//\[aq]\fP 61 0 8:2 / / rw,relatime .EE .in -.PP +.P On a second terminal, we create a new mount namespace where we run a second shell and inspect the mounts: -.PP +.P .in +4n .EX $ \fBPS1=\[aq]sh2# \[aq] sudo unshare \-m \-\-propagation unchanged sh\fP @@ -293,7 +293,7 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 225 145 8:15 / /mntP rw,relatime .EE .in -.PP +.P The new mount namespace received a copy of the initial mount namespace's mounts. These new mounts maintain the same propagation types, @@ -305,13 +305,13 @@ option prevents from marking all mounts as private when creating a new mount namespace, .\" Since util-linux 2.27 which it does by default.) -.PP +.P In the second terminal, we then create submounts under each of .I /mntS and .I /mntP and inspect the set-up: -.PP +.P .in +4n .EX sh2# \fBmkdir /mntS/a\fP @@ -325,13 +325,13 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 230 225 8:23 / /mntP/b rw,relatime .EE .in -.PP +.P From the above, it can be seen that .I /mntS/a was created as shared (inheriting this setting from its parent mount) and .I /mntP/b was created as a private mount. -.PP +.P Returning to the first terminal and inspecting the set-up, we see that the new mount created under the shared mount .I /mntS @@ -339,7 +339,7 @@ propagated to its peer mount (in the initial mount namespace), but the new mount created under the private mount .I /mntP did not propagate: -.PP +.P .in +4n .EX sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP @@ -365,10 +365,10 @@ and .BR umount (2) events under the slave mount from having side effects in other namespaces. -.PP +.P We can demonstrate the effect of slaving by first marking two mounts as shared in the initial mount namespace: -.PP +.P .in +4n .EX sh1# \fBmount \-\-make\-shared /mntX\fP @@ -378,10 +378,10 @@ sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 133 83 8:22 / /mntY rw,relatime shared:2 .EE .in -.PP +.P On a second terminal, we create a new mount namespace and inspect the mounts: -.PP +.P .in +4n .EX sh2# \fBunshare \-m \-\-propagation unchanged sh\fP @@ -390,9 +390,9 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 169 167 8:22 / /mntY rw,relatime shared:2 .EE .in -.PP +.P In the new mount namespace, we then mark one of the mounts as a slave: -.PP +.P .in +4n .EX sh2# \fBmount \-\-make\-slave /mntY\fP @@ -401,17 +401,17 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 169 167 8:22 / /mntY rw,relatime master:2 .EE .in -.PP +.P From the above output, we see that .I /mntY is now a slave mount that is receiving propagation events from the shared peer group with the ID 2. -.PP +.P Continuing in the new namespace, we create submounts under each of .I /mntX and .IR /mntY : -.PP +.P .in +4n .EX sh2# \fBmkdir /mntX/a\fP @@ -420,7 +420,7 @@ sh2# \fBmkdir /mntY/b\fP sh2# \fBmount /dev/sda5 /mntY/b\fP .EE .in -.PP +.P When we inspect the state of the mounts in the new mount namespace, we see that .I /mntX/a @@ -428,7 +428,7 @@ was created as a new shared mount (inheriting the "shared" setting from its parent mount) and .I /mntY/b was created as a private mount: -.PP +.P .in +4n .EX sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP @@ -438,7 +438,7 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 175 169 8:5 / /mntY/b rw,relatime .EE .in -.PP +.P Returning to the first terminal (in the initial mount namespace), we see that the mount .I /mntX/a @@ -447,7 +447,7 @@ propagated to the peer (the shared but the mount .I /mntY/b was not propagated: -.PP +.P .in +4n .EX sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP @@ -456,11 +456,11 @@ sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 174 132 8:3 / /mntX/a rw,relatime shared:3 .EE .in -.PP +.P Now we create a new mount under .I /mntY in the first shell: -.PP +.P .in +4n .EX sh1# \fBmkdir /mntY/c\fP @@ -472,12 +472,12 @@ sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 178 133 8:1 / /mntY/c rw,relatime shared:4 .EE .in -.PP +.P When we examine the mounts in the second mount namespace, we see that in this case the new mount has been propagated to the slave mount, and that the new mount is itself a slave mount (to peer group 4): -.PP +.P .in +4n .EX sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP @@ -494,9 +494,9 @@ One of the primary purposes of unbindable mounts is to avoid the "mount explosion" problem when repeatedly performing bind mounts of a higher-level subtree at a lower-level mount. The problem is illustrated by the following shell session. -.PP +.P Suppose we have a system with the following mounts: -.PP +.P .in +4n .EX # \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP @@ -505,11 +505,11 @@ Suppose we have a system with the following mounts: /dev/sdb7 on /mntY .EE .in -.PP +.P Suppose furthermore that we wish to recursively bind mount the root directory under several users' home directories. We do this for the first user, and inspect the mounts: -.PP +.P .in +4n .EX # \fBmount \-\-rbind / /home/cecilia/\fP @@ -522,10 +522,10 @@ We do this for the first user, and inspect the mounts: /dev/sdb7 on /home/cecilia/mntY .EE .in -.PP +.P When we repeat this operation for the second user, we start to see the explosion problem: -.PP +.P .in +4n .EX # \fBmount \-\-rbind / /home/henry\fP @@ -544,7 +544,7 @@ we start to see the explosion problem: /dev/sdb7 on /home/henry/home/cecilia/mntY .EE .in -.PP +.P Under .IR /home/henry , we have not only recursively added the @@ -556,7 +556,7 @@ mounts, but also the recursive mounts of those directories under that were created in the previous step. Upon repeating the step for a third user, it becomes obvious that the explosion is exponential in nature: -.PP +.P .in +4n .EX # \fBmount \-\-rbind / /home/otto\fP @@ -587,21 +587,21 @@ it becomes obvious that the explosion is exponential in nature: /dev/sdb7 on /home/otto/home/henry/home/cecilia/mntY .EE .in -.PP +.P The mount explosion problem in the above scenario can be avoided by making each of the new mounts unbindable. The effect of doing this is that recursive mounts of the root directory will not replicate the unbindable mounts. We make such a mount for the first user: -.PP +.P .in +4n .EX # \fBmount \-\-rbind \-\-make\-unbindable / /home/cecilia\fP .EE .in -.PP +.P Before going further, we show that unbindable mounts are indeed unbindable: -.PP +.P .in +4n .EX # \fBmkdir /mntZ\fP @@ -613,21 +613,21 @@ mount: wrong fs type, bad option, bad superblock on /home/cecilia, dmesg | tail or so. .EE .in -.PP +.P Now we create unbindable recursive bind mounts for the other two users: -.PP +.P .in +4n .EX # \fBmount \-\-rbind \-\-make\-unbindable / /home/henry\fP # \fBmount \-\-rbind \-\-make\-unbindable / /home/otto\fP .EE .in -.PP +.P Upon examining the list of mounts, we see there has been no explosion of mounts, because the unbindable mounts were not replicated under each user's directory: -.PP +.P .in +4n .EX # \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP @@ -666,9 +666,9 @@ slave+shared slave+shared slave priv unbind private shared priv [2] priv unbind unbindable shared unbind [2] priv unbind .TE -.sp 1 +.P Note the following details to the table: -.IP [1] 4 +.IP [1] 5 If a shared mount is the only mount in its peer group, making it a slave automatically makes it private. .IP [2] @@ -676,13 +676,13 @@ Slaving a nonshared mount has no effect on the mount. .\" .SS Bind (MS_BIND) semantics Suppose that the following command is performed: -.PP +.P .in +4n .EX mount \-\-bind A/a B/b .EE .in -.PP +.P Here, .I A is the source mount, @@ -702,7 +702,7 @@ depends on the propagation types of the mounts and .IR B , and is summarized in the following table. -.PP +.P .TS lb2 lb1 lb2 lb2 lb2 lb0 lb2 lb1 lb2 lb2 lb2 lb0 @@ -713,24 +713,24 @@ _ dest(B) shared shared shared slave+shared invalid nonshared shared private slave invalid .TE -.sp 1 +.P Note that a recursive bind of a subtree follows the same semantics as for a bind operation on each mount in the subtree. (Unbindable mounts are automatically pruned at the target mount point.) -.PP +.P For further details, see .I Documentation/filesystems/sharedsubtree.rst in the kernel source tree. .\" .SS Move (MS_MOVE) semantics Suppose that the following command is performed: -.PP +.P .in +4n .EX mount \-\-move A B/b .EE .in -.PP +.P Here, .I A is the source mount, @@ -746,7 +746,7 @@ depends on the propagation types of the mounts and .IR B , and is summarized in the following table. -.PP +.P .TS lb2 lb1 lb2 lb2 lb2 lb0 lb2 lb1 lb2 lb2 lb2 lb0 @@ -757,22 +757,22 @@ _ dest(B) shared shared shared slave+shared invalid nonshared shared private slave unbindable .TE -.sp 1 +.P Note: moving a mount that resides under a shared mount is invalid. -.PP +.P For further details, see .I Documentation/filesystems/sharedsubtree.rst in the kernel source tree. .\" .SS Mount semantics Suppose that we use the following command to create a mount: -.PP +.P .in +4n .EX mount device B/b .EE .in -.PP +.P Here, .I B is the destination mount, and @@ -787,13 +787,13 @@ is considered always to be private. .\" .SS Unmount semantics Suppose that we use the following command to tear down a mount: -.PP +.P .in +4n .EX umount A .EE .in -.PP +.P Here, .I A is a mount on @@ -822,7 +822,7 @@ record in cases where a process can't see a slave's immediate master the filesystem root directory) and so cannot determine the chain of propagation between the mounts it can see. -.PP +.P In the following example, we first create a two-link master-slave chain between the mounts .IR /mnt , @@ -837,7 +837,7 @@ mount point unreachable from the root directory, creating a situation where the master of .I /mnt/tmp/etc is not reachable from the (new) root directory of the process. -.PP +.P First, we bind mount the root directory onto .I /mnt and then bind mount @@ -850,7 +850,7 @@ the .BR proc (5) filesystem remains visible at the correct location in the chroot-ed environment. -.PP +.P .in +4n .EX # \fBmkdir \-p /mnt/proc\fP @@ -858,11 +858,11 @@ in the chroot-ed environment. # \fBmount \-\-bind /proc /mnt/proc\fP .EE .in -.PP +.P Next, we ensure that the .I /mnt mount is a shared mount in a new peer group (with no peers): -.PP +.P .in +4n .EX # \fBmount \-\-make\-private /mnt\fP # Isolate from any previous peer group @@ -872,12 +872,12 @@ mount is a shared mount in a new peer group (with no peers): 248 239 0:4 / /mnt/proc ... shared:5 .EE .in -.PP +.P Next, we bind mount .I /mnt/etc onto .IR /tmp/etc : -.PP +.P .in +4n .EX # \fBmkdir \-p /tmp/etc\fP @@ -888,7 +888,7 @@ onto 267 40 8:2 /etc /tmp/etc ... shared:102 .EE .in -.PP +.P Initially, these two mounts are in the same peer group, but we then make the .I /tmp/etc @@ -898,7 +898,7 @@ and then make .I /tmp/etc shared as well, so that it can propagate events to the next slave in the chain: -.PP +.P .in +4n .EX # \fBmount \-\-make\-slave /tmp/etc\fP @@ -909,7 +909,7 @@ so that it can propagate events to the next slave in the chain: 267 40 8:2 /etc /tmp/etc ... shared:105 master:102 .EE .in -.PP +.P Then we bind mount .I /tmp/etc onto @@ -919,7 +919,7 @@ but we then make .I /mnt/tmp/etc a slave of .IR /tmp/etc : -.PP +.P .in +4n .EX # \fBmkdir \-p /mnt/tmp/etc\fP @@ -932,30 +932,30 @@ a slave of 273 239 8:2 /etc /mnt/tmp/etc ... master:105 .EE .in -.PP +.P From the above, we see that .I /mnt is the master of the slave .IR /tmp/etc , which in turn is the master of the slave .IR /mnt/tmp/etc . -.PP +.P We then .BR chroot (1) to the .I /mnt directory, which renders the mount with ID 267 unreachable from the (new) root directory: -.PP +.P .in +4n .EX # \fBchroot /mnt\fP .EE .in -.PP +.P When we examine the state of the mounts inside the chroot-ed environment, we see the following: -.PP +.P .in +4n .EX # \fBcat /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]\fP @@ -964,7 +964,7 @@ we see the following: 273 239 8:2 /etc /tmp/etc ... master:105 propagate_from:102 .EE .in -.PP +.P Above, we see that the mount with ID 273 is a slave whose master is the peer group 105. The mount point for that master is unreachable, and so a @@ -992,7 +992,7 @@ then the propagation type of the new mount is also .BR MS_SHARED . Otherwise, the propagation type of the new mount is .BR MS_PRIVATE . -.PP +.P Notwithstanding the fact that the default propagation type for new mount is in many cases .BR MS_PRIVATE , @@ -1005,7 +1005,7 @@ automatically remounts all mounts as on system startup. Thus, on most modern systems, the default propagation type is in practice .BR MS_SHARED . -.PP +.P Since, when one uses .BR unshare (1) to create a mount namespace, @@ -1020,18 +1020,18 @@ by making all mounts private in the new namespace. That is, .BR unshare (1) performs the equivalent of the following in the new mount namespace: -.PP +.P .in +4n .EX mount \-\-make\-rprivate / .EE .in -.PP +.P To prevent this, one can use the .I \-\-propagation\~unchanged option to .BR unshare (1). -.PP +.P An application that creates a new mount namespace directly using .BR clone (2) or @@ -1045,13 +1045,13 @@ mounts in the new namespace to either or .BR MS_PRIVATE , using a call such as the following: -.PP +.P .in +4n .EX mount(NULL, "/", MS_SLAVE | MS_REC, NULL); .EE .in -.PP +.P For a discussion of propagation types when moving mounts .RB ( MS_MOVE ) and creating bind mounts @@ -1063,7 +1063,7 @@ see .\" .SS Restrictions on mount namespaces Note the following points with respect to mount namespaces: -.IP [1] 4 +.IP [1] 5 Each mount namespace has an owner user namespace. As explained above, when a new mount namespace is created, its mount list is initialized as a copy of the mount list @@ -1366,6 +1366,6 @@ See .BR pam_namespace (8), .BR pivot_root (8), .BR umount (8) -.PP +.P .I Documentation/filesystems/sharedsubtree.rst in the kernel source tree. diff --git a/upstream/debian-unstable/man7/mq_overview.7 b/upstream/debian-unstable/man7/mq_overview.7 index b022ea05..a564a174 100644 --- a/upstream/debian-unstable/man7/mq_overview.7 +++ b/upstream/debian-unstable/man7/mq_overview.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mq_overview 7 2023-02-05 "Linux man-pages 6.05.01" +.TH mq_overview 7 2024-05-02 "Linux man-pages 6.8" .SH NAME mq_overview \- overview of POSIX message queues .SH DESCRIPTION @@ -14,7 +14,7 @@ This API is distinct from that provided by System V message queues .BR msgsnd (2), .BR msgrcv (2), etc.), but provides similar functionality. -.PP +.P Message queues are created and opened using .BR mq_open (3); this function returns a @@ -29,7 +29,7 @@ that is, a null-terminated string of up to followed by one or more characters, none of which are slashes. Two processes can operate on the same queue by passing the same name to .BR mq_open (3). -.PP +.P Messages are transferred to and from a queue using .BR mq_send (3) and @@ -45,7 +45,7 @@ and A process can request asynchronous notification of the arrival of a message on a previously empty queue using .BR mq_notify (3). -.PP +.P A message queue descriptor is a reference to an .I "open message queue description" (see @@ -58,7 +58,7 @@ as the corresponding message queue descriptors in the parent. Corresponding message queue descriptors in the two processes share the flags .RI ( mq_flags ) that are associated with the open message queue description. -.PP +.P Each message has an associated .IR priority , and messages are always delivered to the receiving process @@ -71,7 +71,7 @@ On Linux, returns 32768, but POSIX.1 requires only that an implementation support at least priorities in the range 0 to 31; some implementations provide only this range. -.PP +.P The remainder of this section describes some specific details of the Linux implementation of POSIX message queues. .SS Library interfaces and system calls @@ -265,33 +265,33 @@ On Linux, message queues are created in a virtual filesystem. but the details are likely to differ.) This filesystem can be mounted (by the superuser) using the following commands: -.PP +.P .in +4n .EX .RB "#" " mkdir /dev/mqueue" .RB "#" " mount \-t mqueue none /dev/mqueue" .EE .in -.PP +.P The sticky bit is automatically enabled on the mount directory. -.PP +.P After the filesystem has been mounted, the message queues on the system can be viewed and manipulated using the commands usually used for files (e.g., .BR ls (1) and .BR rm (1)). -.PP +.P The contents of each file in the directory consist of a single line containing information about the queue: -.PP +.P .in +4n .EX .RB "$" " cat /dev/mqueue/mymq" QSIZE:129 NOTIFY:2 SIGNO:0 NOTIFY_PID:8260 .EE .in -.PP +.P These fields are as follows: .TP .B QSIZE @@ -325,7 +325,7 @@ This means that a message queue descriptor can be monitored using or .BR epoll (7). This is not portable. -.PP +.P The close-on-exec flag (see .BR open (2)) is automatically set on the file descriptor returned by @@ -344,7 +344,7 @@ POSIX message queues provide a better designed interface than System V message queues; on the other hand POSIX message queues are less widely available (especially on older systems) than System V message queues. -.PP +.P Linux does not currently (Linux 2.6.26) support the use of access control lists (ACLs) for POSIX message queues. .SH BUGS @@ -356,7 +356,7 @@ limit could be raised, and the ceiling was enforced even for privileged processes. This ceiling value was removed in Linux 3.14, and patches to stable Linux 3.5.x to Linux 3.13.x also removed the ceiling. -.PP +.P As originally implemented (and documented), the QSIZE field displayed the total number of (user-supplied) bytes in all messages in the message queue. diff --git a/upstream/debian-unstable/man7/namespaces.7 b/upstream/debian-unstable/man7/namespaces.7 index 6ff11af6..69e34d9f 100644 --- a/upstream/debian-unstable/man7/namespaces.7 +++ b/upstream/debian-unstable/man7/namespaces.7 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH namespaces 7 2023-07-20 "Linux man-pages 6.05.01" +.TH namespaces 7 2024-05-02 "Linux man-pages 6.8" .SH NAME namespaces \- overview of Linux namespaces .SH DESCRIPTION @@ -15,7 +15,7 @@ have their own isolated instance of the global resource. Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes. One use of namespaces is to implement containers. -.PP +.P This page provides pointers to information on the various namespace types, describes the associated .I /proc @@ -108,7 +108,7 @@ Various operations can be used to discover information about namespaces. These operations are described in .BR ioctl_ns (2). -.PP +.P Creation of new namespaces using .BR clone (2) and @@ -131,7 +131,7 @@ Each process has a subdirectory containing one entry for each namespace that supports being manipulated by .BR setns (2): -.PP +.P .in +4n .EX $ \fBls \-l /proc/$$/ns | awk \[aq]{print $1, $9, $10, $11}\[aq]\fP @@ -148,7 +148,7 @@ lrwxrwxrwx. user \-> user:[4026531837] lrwxrwxrwx. uts \-> uts:[4026531838] .EE .in -.PP +.P Bind mounting (see .BR mount (2)) one of the files in this directory @@ -156,7 +156,7 @@ to somewhere else in the filesystem keeps the corresponding namespace of the process specified by .I pid alive even if all processes currently in the namespace terminate. -.PP +.P Opening one of the files in this directory (or a file that is bind mounted to one of these files) returns a file handle for @@ -167,7 +167,7 @@ the namespace will remain alive, even if all processes in the namespace terminate. The file descriptor can be passed to .BR setns (2). -.PP +.P In Linux 3.7 and earlier, these files were visible as hard links. Since Linux 3.8, .\" commit bf056bfa80596a5d14b26b17276a56a0dcb080e5 @@ -188,14 +188,14 @@ fields returned by .BR stat (2). The content of this symbolic link is a string containing the namespace type and inode number as in the following example: -.PP +.P .in +4n .EX $ \fBreadlink /proc/$$/ns/uts\fP uts:[4026531838] .EE .in -.PP +.P The symbolic links in this subdirectory are as follows: .TP .IR /proc/ pid /ns/cgroup " (since Linux 4.6)" @@ -256,7 +256,7 @@ This file is a handle for the user namespace of the process. .TP .IR /proc/ pid /ns/uts " (since Linux 3.0)" This file is a handle for the UTS namespace of the process. -.PP +.P Permission to dereference or read .RB ( readlink (2)) these symbolic links is governed by a ptrace access mode @@ -305,7 +305,7 @@ user namespaces that may be created in the user namespace. .I max_uts_namespaces The value in this file defines a per-user limit on the number of uts namespaces that may be created in the user namespace. -.PP +.P Note the following details about these files: .IP \[bu] 3 The values in these files are modifiable by privileged processes. diff --git a/upstream/debian-unstable/man7/netdevice.7 b/upstream/debian-unstable/man7/netdevice.7 index a0f00496..6ffe0695 100644 --- a/upstream/debian-unstable/man7/netdevice.7 +++ b/upstream/debian-unstable/man7/netdevice.7 @@ -10,7 +10,7 @@ .\" Modified, 2011-11-02, <bidulock@openss7.org>, added many basic .\" but missing ioctls, such as SIOCGIFADDR. .\" -.TH netdevice 7 2023-07-15 "Linux man-pages 6.05.01" +.TH netdevice 7 2024-05-02 "Linux man-pages 6.8" .SH NAME netdevice \- low-level access to Linux network devices .SH SYNOPSIS @@ -21,14 +21,14 @@ netdevice \- low-level access to Linux network devices .SH DESCRIPTION This man page describes the sockets interface which is used to configure network devices. -.PP +.P Linux supports some standard ioctls to configure network devices. They can be used on any socket's file descriptor regardless of the family or type. Most of them pass an .I ifreq structure: -.PP +.P .in +4n .EX struct ifreq { @@ -51,13 +51,13 @@ struct ifreq { }; .EE .in -.PP +.P .B AF_INET6 is an exception. It passes an .I in6_ifreq structure: -.PP +.P .in +4n .EX struct in6_ifreq { @@ -67,7 +67,7 @@ struct in6_ifreq { }; .EE .in -.PP +.P Normally, the user specifies which device to affect by setting .I ifr_name to the name of the interface or @@ -96,7 +96,9 @@ This is the only ioctl which returns its result in Retrieve the interface index of the interface into .IR ifr_ifindex . .TP -.BR SIOCGIFFLAGS ", " SIOCSIFFLAGS +.B SIOCGIFFLAGS +.TQ +.B SIOCSIFFLAGS Get or set the active flag word of the device. .I ifr_flags contains a bit mask of the following values: @@ -132,11 +134,13 @@ IFF_DORMANT:Driver signals dormant (since Linux 2.6.17) IFF_ECHO:Echo sent packets (since Linux 2.6.25) .TE .ad -.PP +.P Setting the active flag word is a privileged operation, but any process may read it. .TP -.BR SIOCGIFPFLAGS ", " SIOCSIFPFLAGS +.B SIOCGIFPFLAGS +.TQ +.B SIOCSIFPFLAGS Get or set extended (private) flags for the device. .I ifr_flags contains a bit mask of the following values: @@ -154,10 +158,14 @@ IFF_BONDING:Interface is a bonding master or slave. IFF_SLAVE_NEEDARP:Interface needs ARPs for validation. IFF_ISATAP:Interface is RFC4214 ISATAP interface. .TE -.PP +.P Setting the extended (private) interface flags is a privileged operation. .TP -.BR SIOCGIFADDR ", " SIOCSIFADDR ", " SIOCDIFADDR +.B SIOCGIFADDR +.TQ +.B SIOCSIFADDR +.TQ +.B SIOCDIFADDR Get, set, or delete the address of the device using .IR ifr_addr , or @@ -185,7 +193,9 @@ A address can be deleted by setting it to zero via .BR SIOCSIFADDR . .TP -.BR SIOCGIFDSTADDR ", " SIOCSIFDSTADDR +.B SIOCGIFDSTADDR +.TQ +.B SIOCSIFDSTADDR Get or set the destination address of a point-to-point device using .IR ifr_dstaddr . For compatibility, only @@ -193,7 +203,9 @@ For compatibility, only addresses are accepted or returned. Setting the destination address is a privileged operation. .TP -.BR SIOCGIFBRDADDR ", " SIOCSIFBRDADDR +.B SIOCGIFBRDADDR +.TQ +.B SIOCSIFBRDADDR Get or set the broadcast address for a device using .IR ifr_brdaddr . For compatibility, only @@ -201,7 +213,9 @@ For compatibility, only addresses are accepted or returned. Setting the broadcast address is a privileged operation. .TP -.BR SIOCGIFNETMASK ", " SIOCSIFNETMASK +.B SIOCGIFNETMASK +.TQ +.B SIOCSIFNETMASK Get or set the network mask for a device using .IR ifr_netmask . For compatibility, only @@ -209,7 +223,9 @@ For compatibility, only addresses are accepted or returned. Setting the network mask is a privileged operation. .TP -.BR SIOCGIFMETRIC ", " SIOCSIFMETRIC +.B SIOCGIFMETRIC +.TQ +.B SIOCSIFMETRIC Get or set the metric of the device using .IR ifr_metric . This is currently not implemented; it sets @@ -218,14 +234,18 @@ to 0 if you attempt to read it and returns .B EOPNOTSUPP if you attempt to set it. .TP -.BR SIOCGIFMTU ", " SIOCSIFMTU +.B SIOCGIFMTU +.TQ +.B SIOCSIFMTU Get or set the MTU (Maximum Transfer Unit) of a device using .IR ifr_mtu . Setting the MTU is a privileged operation. Setting the MTU to too small values may cause kernel crashes. .TP -.BR SIOCGIFHWADDR ", " SIOCSIFHWADDR +.B SIOCGIFHWADDR +.TQ +.B SIOCSIFHWADDR Get or set the hardware address of a device using .IR ifr_hwaddr . The hardware address is specified in a struct @@ -241,7 +261,9 @@ Set the hardware broadcast address of a device from .IR ifr_hwaddr . This is a privileged operation. .TP -.BR SIOCGIFMAP ", " SIOCSIFMAP +.B SIOCGIFMAP +.TQ +.B SIOCSIFMAP Get or set the interface's hardware parameters using .IR ifr_map . Setting the parameters is a privileged operation. @@ -262,7 +284,9 @@ struct ifmap { The interpretation of the ifmap structure depends on the device driver and the architecture. .TP -.BR SIOCADDMULTI ", " SIOCDELMULTI +.B SIOCADDMULTI +.TQ +.B SIOCDELMULTI Add an address to or delete an address from the device's link layer multicast filters using .IR ifr_hwaddr . @@ -271,7 +295,9 @@ See also .BR packet (7) for an alternative. .TP -.BR SIOCGIFTXQLEN ", " SIOCSIFTXQLEN +.B SIOCGIFTXQLEN +.TQ +.B SIOCSIFTXQLEN Get or set the transmit queue length of a device using .IR ifr_qlen . Setting the transmit queue length is a privileged operation. @@ -357,19 +383,21 @@ will be returned. .\" Slaving isn't supported in Linux 2.2 .\" . .\" .TP -.\" .BR SIOCGIFSLAVE ", " SIOCSIFSLAVE +.\" .B SIOCGIFSLAVE +.\" .TQ +.\" .B SIOCSIFSLAVE .\" Get or set the slave device using .\" .IR ifr_slave . .\" Setting the slave device is a privileged operation. -.\" .PP +.\" .P .\" FIXME . add amateur radio stuff. -.PP +.P Most protocols support their own ioctls to configure protocol-specific interface options. See the protocol man pages for a description. For configuring IP addresses, see .BR ip (7). -.PP +.P In addition, some devices support private ioctls. These are not described here. .SH NOTES @@ -379,12 +407,12 @@ and the other ioctls that accept or return only socket addresses are IP-specific and perhaps should rather be documented in .BR ip (7). -.PP +.P The names of interfaces with no addresses or that don't have the .B IFF_RUNNING flag set can be found via .IR /proc/net/dev . -.PP +.P .B AF_INET6 IPv6 addresses can be read from .I /proc/net/if_inet6 @@ -406,7 +434,7 @@ glibc 2.1 is missing the macro in .IR <net/if.h> . Add the following to your program as a workaround: -.PP +.P .in +4n .EX #ifndef ifr_newname diff --git a/upstream/debian-unstable/man7/netlink.7 b/upstream/debian-unstable/man7/netlink.7 index 4d6cdbc2..e76ce6b5 100644 --- a/upstream/debian-unstable/man7/netlink.7 +++ b/upstream/debian-unstable/man7/netlink.7 @@ -6,7 +6,7 @@ .\" Based on the original comments from Alexey Kuznetsov .\" Modified 2005-12-27 by Hasso Tepper <hasso@estpak.ee> .\" $Id: netlink.7,v 1.8 2000/06/22 13:23:00 ak Exp $ -.TH netlink 7 2023-07-30 "Linux man-pages 6.05.01" +.TH netlink 7 2024-05-02 "Linux man-pages 6.8" .SH NAME netlink \- communication between kernel and user space (AF_NETLINK) .SH SYNOPSIS @@ -14,7 +14,7 @@ netlink \- communication between kernel and user space (AF_NETLINK) .B #include <asm/types.h> .B #include <sys/socket.h> .B #include <linux/netlink.h> -.PP +.P .BI "netlink_socket = socket(AF_NETLINK, " socket_type ", " netlink_family ); .fi .SH DESCRIPTION @@ -26,7 +26,7 @@ The internal kernel interface is not documented in this manual page. There is also an obsolete netlink interface via netlink character devices; this interface is not documented here and is provided only for backward compatibility. -.PP +.P Netlink is a datagram-oriented service. Both .B SOCK_RAW @@ -36,7 +36,7 @@ are valid values for .IR socket_type . However, the netlink protocol does not distinguish between datagram and raw sockets. -.PP +.P .I netlink_family selects the kernel module or netlink group to communicate with. The currently assigned netlink families are: @@ -144,7 +144,7 @@ Generic netlink family for simplified netlink usage. Netlink interface to request information about ciphers registered with the kernel crypto API as well as allow configuration of the kernel crypto API. -.PP +.P Netlink messages consist of a byte stream with one or multiple .I nlmsghdr headers and associated payload. @@ -154,7 +154,7 @@ macros. See .BR netlink (3) for further information. -.PP +.P In multipart messages (multiple .I nlmsghdr headers with associated payload in one byte stream) the first and all @@ -162,11 +162,11 @@ following headers have the .B NLM_F_MULTI flag set, except for the last header which has the type .BR NLMSG_DONE . -.PP +.P After each .I nlmsghdr the payload follows. -.PP +.P .in +4n .EX struct nlmsghdr { @@ -178,7 +178,7 @@ struct nlmsghdr { }; .EE .in -.PP +.P .I nlmsg_type can be one of the standard message types: .B NLMSG_NOOP @@ -192,7 +192,7 @@ message terminates a multipart message. Error messages get the original request appended, unless the user requests to cap the error message, and get extra error data if requested. -.PP +.P .in +4n .EX struct nlmsgerr { @@ -212,7 +212,7 @@ struct nlmsgerr { }; .EE .in -.PP +.P A netlink family usually specifies more message types, see the appropriate manual pages for that, for example, .BR rtnetlink (7) @@ -261,7 +261,7 @@ Convenience macro; equivalent to T} .TE .\" FIXME NLM_F_ATOMIC is not used anymore? -.PP +.P Note that .B NLM_F_ATOMIC requires the @@ -286,7 +286,7 @@ NLM_F_APPEND:T{ Add to the end of the object list. T} .TE -.PP +.P .I nlmsg_seq and .I nlmsg_pid @@ -300,14 +300,14 @@ socket. See the .B ADDRESS FORMATS section for further information. -.PP +.P Both .I nlmsg_seq and .I nlmsg_pid .\" FIXME Explain more about nlmsg_seq and nlmsg_pid. are opaque to netlink core. -.PP +.P Netlink is not a reliable protocol. It tries its best to deliver a message to its destination(s), but may drop messages when an out-of-memory condition or @@ -325,7 +325,7 @@ The kernel tries to send an .B NLMSG_ERROR message for every failed packet. A user process should follow this convention too. -.PP +.P However, reliable transmissions from kernel to user are impossible in any case. The kernel can't send a netlink message if the socket buffer is full: @@ -346,7 +346,7 @@ can be either unicast (only sent to one peer) or sent to netlink multicast groups .RI ( nl_groups not equal 0). -.PP +.P .in +4n .EX struct sockaddr_nl { @@ -357,7 +357,7 @@ struct sockaddr_nl { }; .EE .in -.PP +.P .I nl_pid is the unicast address of netlink socket. It's always 0 if the destination is in the kernel. @@ -386,7 +386,7 @@ The kernel assigns the process ID to the first netlink socket the process opens and assigns a unique .I nl_pid to every netlink socket that the process subsequently creates. -.PP +.P .I nl_groups is a bit mask with every bit representing a netlink group number. Each netlink family has a set of 32 multicast groups. @@ -443,7 +443,9 @@ Enable control messages for received packets to get the extended destination group number. .TP -.BR NETLINK_ADD_MEMBERSHIP ,\ NETLINK_DROP_MEMBERSHIP " (since Linux 2.6.14)" +.B NETLINK_ADD_MEMBERSHIP +.TQ +.BR NETLINK_DROP_MEMBERSHIP " (since Linux 2.6.14)" .\" commit 9a4595bc7e67962f13232ee55a64e063062c3a99 .\" Author: Patrick McHardy <kaber@trash.net> Join/leave a group specified by @@ -502,7 +504,7 @@ The netlink message header is still included, so the user can guess from the sequence number which message triggered the acknowledgement. .SH VERSIONS The socket interface to netlink first appeared Linux 2.2. -.PP +.P Linux 2.0 supported a more primitive device-based netlink interface (which is still available as a compatibility option). This obsolete interface is not described here. @@ -522,7 +524,7 @@ netlink socket which will listen to the (network interface create/delete/up/down events) and .B RTMGRP_IPV4_IFADDR (IPv4 addresses add/delete events) multicast groups. -.PP +.P .in +4n .EX struct sockaddr_nl sa; @@ -535,12 +537,12 @@ fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE); bind(fd, (struct sockaddr *) &sa, sizeof(sa)); .EE .in -.PP +.P The next example demonstrates how to send a netlink message to the kernel (pid 0). Note that the application must take care of message sequence numbers in order to reliably track acknowledgements. -.PP +.P .in +4n .EX struct nlmsghdr *nh; /* The nlmsghdr with payload to send */ @@ -559,9 +561,9 @@ nh\->nlmsg_flags |= NLM_F_ACK; sendmsg(fd, &msg, 0); .EE .in -.PP +.P And the last example is about reading netlink message. -.PP +.P .in +4n .EX int len; @@ -597,13 +599,13 @@ for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len); .BR capabilities (7), .BR rtnetlink (7), .BR sock_diag (7) -.PP +.P .UR ftp://ftp.inr.ac.ru\:/ip\-routing\:/iproute2* information about libnetlink .UE -.PP +.P .UR http://www.infradead.org\:/\[ti]tgr\:/libnl/ information about libnl .UE -.PP +.P RFC 3549 "Linux Netlink as an IP Services Protocol" diff --git a/upstream/debian-unstable/man7/network_namespaces.7 b/upstream/debian-unstable/man7/network_namespaces.7 index a9e6306d..0aea0c42 100644 --- a/upstream/debian-unstable/man7/network_namespaces.7 +++ b/upstream/debian-unstable/man7/network_namespaces.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH network_namespaces 7 2023-03-12 "Linux man-pages 6.05.01" +.TH network_namespaces 7 2024-05-02 "Linux man-pages 6.8" .SH NAME network_namespaces \- overview of Linux network namespaces .SH DESCRIPTION @@ -21,7 +21,7 @@ port numbers (sockets), and so on. In addition, network namespaces isolate the UNIX domain abstract socket namespace (see .BR unix (7)). -.PP +.P A physical network device can live in exactly one network namespace. When a network namespace is freed @@ -29,7 +29,7 @@ When a network namespace is freed its physical network devices are moved back to the initial network namespace (not to the namespace of the parent of the process). -.PP +.P A virtual network .RB ( veth (4)) device pair provides a pipe-like abstraction @@ -39,7 +39,7 @@ in another namespace. When a namespace is freed, the .BR veth (4) devices that it contains are destroyed. -.PP +.P Use of network namespaces requires a kernel that is configured with the .B CONFIG_NET_NS option. diff --git a/upstream/debian-unstable/man7/nptl.7 b/upstream/debian-unstable/man7/nptl.7 index a00c845b..a4a71a90 100644 --- a/upstream/debian-unstable/man7/nptl.7 +++ b/upstream/debian-unstable/man7/nptl.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH nptl 7 2023-02-05 "Linux man-pages 6.05.01" +.TH nptl 7 2024-05-02 "Linux man-pages 6.8" .SH NAME nptl \- Native POSIX Threads Library .SH DESCRIPTION @@ -20,7 +20,7 @@ One of these signals is used to support thread cancelation and POSIX timers the other is used as part of a mechanism that ensures all threads in a process always have the same UIDs and GIDs, as required by POSIX. These signals cannot be used in applications. -.PP +.P To prevent accidental use of these signals in applications, which might interfere with the operation of the NPTL implementation, various glibc library functions and system call wrapper functions @@ -66,7 +66,7 @@ the NPTL implementation wraps all of the system calls that change process credentials with functions that, in addition to invoking the underlying system call, arrange for all other threads in the process to also change their credentials. -.PP +.P The implementation of each of these system calls involves the use of a real-time signal that is sent (using .BR tgkill (2)) @@ -76,7 +76,7 @@ saves the new credential(s) and records the system call being employed in a global buffer. A signal handler in the receiving thread(s) fetches this information and then uses the same system call to change its credentials. -.PP +.P Wrapper functions employing this technique are provided for .BR setgid (2), .BR setuid (2), diff --git a/upstream/debian-unstable/man7/numa.7 b/upstream/debian-unstable/man7/numa.7 index 9ac50972..2c32d084 100644 --- a/upstream/debian-unstable/man7/numa.7 +++ b/upstream/debian-unstable/man7/numa.7 @@ -6,7 +6,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH numa 7 2023-04-03 "Linux man-pages 6.05.01" +.TH numa 7 2024-05-02 "Linux man-pages 6.8" .SH NAME numa \- overview of Non-Uniform Memory Architecture .SH DESCRIPTION @@ -35,11 +35,11 @@ see "Library Support" below. .\" See also Changelog-2.6.14 This file displays information about a process's NUMA memory policy and allocation. -.PP +.P Each line contains information about a memory range used by the process, displaying\[em]among other information\[em]the effective memory policy for that memory range and on which nodes the pages have been allocated. -.PP +.P .I numa_maps is a read-only file. When @@ -47,14 +47,14 @@ When is read, the kernel will scan the virtual address space of the process and report how memory is used. One line is displayed for each unique memory range of the process. -.PP +.P The first field of each line shows the starting address of the memory range. This field allows a correlation with the contents of the .IR /proc/ pid /maps file, which contains the end address of the range and other information, such as the access permissions and sharing. -.PP +.P The second field shows the memory policy currently in effect for the memory range. Note that the effective policy is not necessarily the policy @@ -62,7 +62,7 @@ installed by the process for that memory range. Specifically, if the process installed a "default" policy for that range, the effective policy for that range will be the process policy, which may or may not be "default". -.PP +.P The rest of the line contains information about the pages allocated in the memory range, as follows: .TP @@ -143,7 +143,7 @@ and the required header are available in the .I numactl package. -.PP +.P However, applications should not use these system calls directly. Instead, the higher level interface provided by the .BR numa (3) diff --git a/upstream/debian-unstable/man7/openssl-core.h.7ssl b/upstream/debian-unstable/man7/openssl-core.h.7ssl index 0d8685c5..745d2e0d 100644 --- a/upstream/debian-unstable/man7/openssl-core.h.7ssl +++ b/upstream/debian-unstable/man7/openssl-core.h.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OPENSSL-CORE.H 7SSL" -.TH OPENSSL-CORE.H 7SSL 2024-02-03 3.1.5 OpenSSL +.TH OPENSSL-CORE.H 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -98,7 +98,7 @@ The types are: The types described here were added in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2019\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/openssl-core_dispatch.h.7ssl b/upstream/debian-unstable/man7/openssl-core_dispatch.h.7ssl index 0fe94737..87a84c84 100644 --- a/upstream/debian-unstable/man7/openssl-core_dispatch.h.7ssl +++ b/upstream/debian-unstable/man7/openssl-core_dispatch.h.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OPENSSL-CORE_DISPATCH.H 7SSL" -.TH OPENSSL-CORE_DISPATCH.H 7SSL 2024-02-03 3.1.5 OpenSSL +.TH OPENSSL-CORE_DISPATCH.H 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/openssl-core_names.h.7ssl b/upstream/debian-unstable/man7/openssl-core_names.h.7ssl index 8726165d..7de9b810 100644 --- a/upstream/debian-unstable/man7/openssl-core_names.h.7ssl +++ b/upstream/debian-unstable/man7/openssl-core_names.h.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OPENSSL-CORE_NAMES.H 7SSL" -.TH OPENSSL-CORE_NAMES.H 7SSL 2024-02-03 3.1.5 OpenSSL +.TH OPENSSL-CORE_NAMES.H 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/openssl-env.7ssl b/upstream/debian-unstable/man7/openssl-env.7ssl index 76f6bf06..c7993f6d 100644 --- a/upstream/debian-unstable/man7/openssl-env.7ssl +++ b/upstream/debian-unstable/man7/openssl-env.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OPENSSL-ENV 7SSL" -.TH OPENSSL-ENV 7SSL 2024-02-03 3.1.5 OpenSSL +.TH OPENSSL-ENV 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/openssl-glossary.7ssl b/upstream/debian-unstable/man7/openssl-glossary.7ssl index bbbbdaff..d7d41f46 100644 --- a/upstream/debian-unstable/man7/openssl-glossary.7ssl +++ b/upstream/debian-unstable/man7/openssl-glossary.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OPENSSL-GLOSSARY 7SSL" -.TH OPENSSL-GLOSSARY 7SSL 2024-02-03 3.1.5 OpenSSL +.TH OPENSSL-GLOSSARY 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/openssl-quic.7ssl b/upstream/debian-unstable/man7/openssl-quic.7ssl new file mode 100644 index 00000000..6bd1eb19 --- /dev/null +++ b/upstream/debian-unstable/man7/openssl-quic.7ssl @@ -0,0 +1,713 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OPENSSL-QUIC 7SSL" +.TH OPENSSL-QUIC 7SSL 2024-04-04 3.2.2-dev 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 +openssl\-quic \- OpenSSL QUIC +.SH DESCRIPTION +.IX Header "DESCRIPTION" +OpenSSL 3.2 and later features support for the QUIC transport protocol. +Currently, only client connectivity is supported. This man page describes the +usage of QUIC client functionality for both existing and new applications. +.PP +QUIC functionality uses the standard SSL API. A QUIC connection is represented +by an SSL object in the same way that a TLS connection is. Only minimal changes +are needed to existing applications making use of the libssl APIs to make use of +QUIC client functionality. To make use of QUIC, use the SSL method +\&\fBOSSL_QUIC_client_method\fR\|(3) or \fBOSSL_QUIC_client_thread_method\fR\|(3) with +\&\fBSSL_CTX_new\fR\|(3). +.PP +When a QUIC connection is created, by default, it operates in default stream +mode, which is intended to provide compatibility with existing non-QUIC +application usage patterns. In this mode, the connection has a single +stream associated with it. Calls to \fBSSL_read\fR\|(3) and +\&\fBSSL_write\fR\|(3) on the QUIC connection SSL object read and write from that +stream. Whether the stream is client-initiated or server-initiated from a QUIC +perspective depends on whether \fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called +first. See the MODES OF OPERATION section for more information. +.PP +The default stream mode is intended for compatibility with existing +applications. New applications using QUIC are recommended to disable default +stream mode and use the multi-stream API; see the MODES OF OPERATION section and +the RECOMMENDATIONS FOR NEW APPLICATIONS section for more information. +.PP +The remainder of this man page discusses, in order: +.IP \(bu 4 +Default stream mode versus multi-stream mode; +.IP \(bu 4 +The changes to existing libssl APIs which are driven by QUIC-related implementation +requirements, which existing applications should bear in mind; +.IP \(bu 4 +Aspects which must be considered by existing applications when adopting QUIC, +including potential changes which may be needed. +.IP \(bu 4 +Recommended usage approaches for new applications. +.IP \(bu 4 +New, QUIC-specific APIs. +.SH "MODES OF OPERATION" +.IX Header "MODES OF OPERATION" +.SS "Default Stream Mode" +.IX Subsection "Default Stream Mode" +A QUIC client connection can be used in either default stream mode or +multi-stream mode. By default, a newly created QUIC connection SSL object uses +default stream mode. +.PP +In default stream mode, a stream is implicitly created and bound to the QUIC +connection SSL object; \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) calls to the QUIC +connection SSL object work by default and are mapped to that stream. +.PP +When default stream mode is used, any API function which can be called on a QUIC +stream SSL object can also be called on a QUIC connection SSL object, in which +case it affects the default stream bound to the connection. +.PP +The identity of a QUIC stream, including its stream ID, varies depending on +whether a stream is client-initiated or server-initiated. In default stream +mode, if a client application calls \fBSSL_read\fR\|(3) first before any call to +\&\fBSSL_write\fR\|(3) on the connection, it is assumed that the application protocol +is using a server-initiated stream, and the \fBSSL_read\fR\|(3) call will not +complete (either blocking, or failing appropriately if nonblocking mode is +configured) until the server initiates a stream. Conversely, if the client +application calls \fBSSL_write\fR\|(3) before any call to \fBSSL_read\fR\|(3) on the +connection, it is assumed that a client-initiated stream is to be used +and such a stream is created automatically. +.PP +Default stream mode is intended to aid compatibility with legacy applications. +New applications adopting QUIC should use multi-stream mode, described below, +and avoid use of the default stream functionality. +.PP +It is possible to use additional streams in default stream mode using +\&\fBSSL_new_stream\fR\|(3) and \fBSSL_accept_stream\fR\|(3); note that the default incoming +stream policy will need to be changed using \fBSSL_set_incoming_stream_policy\fR\|(3) +in order to use \fBSSL_accept_stream\fR\|(3) in this case. However, applications +using additional streams are strongly recommended to use multi-stream mode +instead. +.PP +Calling \fBSSL_new_stream\fR\|(3) or \fBSSL_accept_stream\fR\|(3) before a default stream +has been associated with the QUIC connection SSL object will inhibit future +creation of a default stream. +.SS "Multi-Stream Mode" +.IX Subsection "Multi-Stream Mode" +The recommended usage mode for new applications adopting QUIC is multi-stream +mode, in which no default stream is attached to the QUIC connection SSL object +and attempts to call \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) on the QUIC connection +SSL object fail. Instead, an application calls \fBSSL_new_stream\fR\|(3) or +\&\fBSSL_accept_stream\fR\|(3) to create individual stream SSL objects for sending and +receiving application data using \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3). +.PP +To use multi-stream mode, call \fBSSL_set_default_stream_mode\fR\|(3) with an +argument of \fBSSL_DEFAULT_STREAM_MODE_NONE\fR; this function must be called prior +to initiating the connection. The default stream mode cannot be changed after +initiating a connection. +.PP +When multi-stream mode is used, meaning that no default stream is associated +with the connection, calls to API functions which are defined as operating on a +QUIC stream fail if called on the QUIC connection SSL object. For example, calls +such as \fBSSL_write\fR\|(3) or \fBSSL_get_stream_id\fR\|(3) will fail. +.SH "CHANGES TO EXISTING APIS" +.IX Header "CHANGES TO EXISTING APIS" +Most SSL APIs, such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3), function as they do +for TLS connections and do not have changed semantics, with some exceptions. The +changes to the semantics of existing APIs are as follows: +.IP \(bu 4 +Since QUIC uses UDP, \fBSSL_set_bio\fR\|(3), \fBSSL_set0_rbio\fR\|(3) and +\&\fBSSL_set0_wbio\fR\|(3) function as before, but must now receive a BIO with datagram +semantics. There are broadly four options for applications to use as a network +BIO: +.RS 4 +.IP \(bu 4 +\&\fBBIO_s_datagram\fR\|(3), recommended for most applications, replaces +\&\fBBIO_s_socket\fR\|(3) and provides a UDP socket. +.IP \(bu 4 +\&\fBBIO_s_dgram_pair\fR\|(3) provides BIO pair-like functionality but with datagram +semantics, and is recommended for existing applications which use a BIO pair or +memory BIO to manage libssl's communication with the network. +.IP \(bu 4 +\&\fBBIO_s_dgram_mem\fR\|(3) provides a simple memory BIO-like interface but with +datagram semantics. Unlike \fBBIO_s_dgram_pair\fR\|(3), it is unidirectional. +.IP \(bu 4 +An application may also choose to implement a custom BIO. The new +\&\fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) APIs must be supported. +.RE +.RS 4 +.RE +.IP \(bu 4 +\&\fBSSL_set_fd\fR\|(3), \fBSSL_set_rfd\fR\|(3) and \fBSSL_set_wfd\fR\|(3) traditionally +instantiate a \fBBIO_s_socket\fR\|(3). For QUIC, these functions instead instantiate +a \fBBIO_s_datagram\fR\|(3). This is equivalent to instantiating a +\&\fBBIO_s_datagram\fR\|(3) and using \fBSSL_set0_rbio\fR\|(3) and \fBSSL_set0_wbio\fR\|(3). +.IP \(bu 4 +Traditionally, whether the application-level I/O APIs (such as \fBSSL_read\fR\|(3) +and \fBSSL_write\fR\|(3) operated in a blocking fashion was directly correlated with +whether the underlying network socket was configured in a blocking fashion. This +is no longer the case; applications must explicitly configure the desired +application-level blocking mode using \fBSSL_set_blocking_mode\fR\|(3). See +\&\fBSSL_set_blocking_mode\fR\|(3) for details. +.IP \(bu 4 +Network-level I/O must always be performed in a nonblocking manner. The +application can still enjoy blocking semantics for calls to application-level +I/O functions such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3), but the underlying +network BIO provided to QUIC (such as a \fBBIO_s_datagram\fR\|(3)) must be configured +in nonblocking mode. For application-level blocking functionality, see +\&\fBSSL_set_blocking_mode\fR\|(3). +.IP \(bu 4 +\&\fBBIO_new_ssl_connect\fR\|(3) has been changed to automatically use a +\&\fBBIO_s_datagram\fR\|(3) when used with QUIC, therefore applications which use this +do not need to change the BIO they use. +.IP \(bu 4 +\&\fBBIO_new_buffer_ssl_connect\fR\|(3) cannot be used with QUIC and applications must +change to use \fBBIO_new_ssl_connect\fR\|(3) instead. +.IP \(bu 4 +\&\fBSSL_shutdown\fR\|(3) has significant changes in relation to how QUIC connections +must be shut down. In particular, applications should be advised that the full +RFC-conformant QUIC shutdown process may take an extended amount of time. This +may not be suitable for short-lived processes which should exit immediately +after their usage of a QUIC connection is completed. A rapid shutdown mode +is available for such applications. For details, see \fBSSL_shutdown\fR\|(3). +.IP \(bu 4 +\&\fBSSL_want\fR\|(3), \fBSSL_want_read\fR\|(3) and \fBSSL_want_write\fR\|(3) no longer reflect +the I/O state of the network BIO passed to the QUIC SSL object, but instead +reflect the flow control state of the QUIC stream associated with the SSL +object. +.Sp +When used in nonblocking mode, \fBSSL_ERROR_WANT_READ\fR indicates that the +receive part of a QUIC stream does not currently have any more data available to +be read, and \fBSSL_ERROR_WANT_WRITE\fR indicates that the stream's internal buffer +is full. +.Sp +To determine if the QUIC implementation currently wishes to be informed of +incoming network datagrams, use the new function \fBSSL_net_read_desired\fR\|(3); +likewise, to determine if the QUIC implementation currently wishes to be +informed when it is possible to transmit network datagrams, use the new function +\&\fBSSL_net_write_desired\fR\|(3). Only applications which wish to manage their own event +loops need to use these functions; see \fBAPPLICATION-DRIVEN EVENT LOOPS\fR for +further discussion. +.IP \(bu 4 +The use of ALPN is mandatory when using QUIC. Attempts to connect without +configuring ALPN will fail. For information on how to configure ALPN, see +\&\fBSSL_set_alpn_protos\fR\|(3). +.IP \(bu 4 +Whether QUIC operates in a client or server mode is determined by the +\&\fBSSL_METHOD\fR used, rather than by calls to \fBSSL_set_connect_state\fR\|(3) or +\&\fBSSL_set_accept_state\fR\|(3). It is not necessary to call either of +\&\fBSSL_set_connect_state\fR\|(3) or \fBSSL_set_accept_state\fR\|(3) before connecting, but +if either of these are called, the function called must be congruent with the +\&\fBSSL_METHOD\fR being used. Currently, only client mode is supported. +.IP \(bu 4 +The \fBSSL_set_min_proto_version\fR\|(3) and \fBSSL_set_max_proto_version\fR\|(3) APIs are +not used and the values passed to them are ignored, as OpenSSL QUIC currently +always uses TLS 1.3. +.IP \(bu 4 +The following libssl functionality is not available when used with QUIC. +.RS 4 +.IP \(bu 4 +Async functionality +.IP \(bu 4 +\&\fBSSL_MODE_AUTO_RETRY\fR +.IP \(bu 4 +Record Padding and Fragmentation (\fBSSL_set_block_padding\fR\|(3), etc.) +.IP \(bu 4 +\&\fBSSL_stateless\fR\|(3) support +.IP \(bu 4 +SRTP functionality +.IP \(bu 4 +TLSv1.3 Early Data +.IP \(bu 4 +TLS Next Protocol Negotiation cannot be used and is superseded by ALPN, which +must be used instead. The use of ALPN is mandatory with QUIC. +.IP \(bu 4 +Post-Handshake Client Authentication is not available as QUIC prohibits its use. +.IP \(bu 4 +QUIC requires the use of TLSv1.3 or later, therefore functionality only relevant +to older TLS versions is not available. +.IP \(bu 4 +Some cipher suites which are generally available for TLSv1.3 are not available +for QUIC, such as \fBTLS_AES_128_CCM_8_SHA256\fR. Your application may need to +adjust the list of acceptable cipher suites it passes to libssl. +.IP \(bu 4 +CCM mode is not currently supported. +.RE +.RS 4 +.Sp +The following libssl functionality is also not available when used with QUIC, +but calls to the relevant functions are treated as no-ops: +.IP \(bu 4 +Readahead (\fBSSL_set_read_ahead\fR\|(3), etc.) +.RE +.RS 4 +.RE +.SH "CONSIDERATIONS FOR EXISTING APPLICATIONS" +.IX Header "CONSIDERATIONS FOR EXISTING APPLICATIONS" +Existing applications seeking to adopt QUIC should apply the following list to +determine what changes they will need to make: +.IP \(bu 4 +An application wishing to use QUIC must use \fBOSSL_QUIC_client_method\fR\|(3) or +\&\fBOSSL_QUIC_client_thread_method\fR\|(3) as its SSL method. For more information +on the differences between these two methods, see \fBTHREAD ASSISTED MODE\fR. +.IP \(bu 4 +Determine how to provide QUIC with network access. Determine which of the below +apply for your application: +.RS 4 +.IP \(bu 4 +Your application uses \fBBIO_s_socket\fR\|(3) to construct a BIO which is passed to +the SSL object to provide it with network access. +.Sp +Changes needed: Change your application to use \fBBIO_s_datagram\fR\|(3) instead when +using QUIC. The socket must be configured in nonblocking mode. You may or may +not need to use \fBSSL_set1_initial_peer_addr\fR\|(3) to set the initial peer +address; see the \fBQUIC-SPECIFIC APIS\fR section for details. +.IP \(bu 4 +Your application uses \fBBIO_new_ssl_connect\fR\|(3) to +construct a BIO which is passed to the SSL object to provide it with network +access. +.Sp +Changes needed: No changes needed. Use of QUIC is detected automatically and a +datagram socket is created instead of a normal TCP socket. +.IP \(bu 4 +Your application uses any other I/O strategy in this list but combines it with a +\&\fBBIO_f_buffer\fR\|(3), for example using \fBBIO_push\fR\|(3). +.Sp +Changes needed: Disable the usage of \fBBIO_f_buffer\fR\|(3) when using QUIC. Usage +of such a buffer is incompatible with QUIC as QUIC requires datagram semantics +in its interaction with the network. +.IP \(bu 4 +Your application uses a BIO pair to cause the SSL object to read and write +network traffic to a memory buffer. Your application manages the transmission +and reception of buffered data itself in a way unknown to libssl. +.Sp +Changes needed: Switch from using a conventional BIO pair to using +\&\fBBIO_s_dgram_pair\fR\|(3) instead, which has the necessary datagram semantics. You +will need to modify your application to transmit and receive using a UDP socket +and to use datagram semantics when interacting with the \fBBIO_s_dgram_pair\fR\|(3) +instance. +.IP \(bu 4 +Your application uses a custom BIO method to provide the SSL object with network +access. +.Sp +Changes needed: The custom BIO must be re-architected to have datagram +semantics. \fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) must be implemented. These +calls must operate in a nonblocking fashion. Optionally, implement the +\&\fBBIO_get_rpoll_descriptor\fR\|(3) and \fBBIO_get_wpoll_descriptor\fR\|(3) methods if +desired. Implementing these methods is required if blocking semantics at the SSL +API level are desired. +.RE +.RS 4 +.RE +.IP \(bu 4 +An application must explicitly configure whether it wishes to use the SSL APIs +in blocking mode or not. Traditionally, an SSL object has automatically operated +in blocking or nonblocking mode based on whether the underlying network BIO +operates in blocking or nonblocking mode. QUIC requires the use of a +nonblocking network BIO, therefore the blocking mode at the application level +must be explicitly configured by the application using the new +\&\fBSSL_set_blocking_mode\fR\|(3) API. The default mode is blocking. If an application +wishes to use the SSL object APIs at application level in a nonblocking manner, +it must add a call to \fBSSL_set_blocking_mode\fR\|(3) to disable blocking mode. +.IP \(bu 4 +If your application does not choose to use thread assisted mode, it must ensure +that it calls an I/O function on the SSL object (for example, \fBSSL_read\fR\|(3) or +\&\fBSSL_write\fR\|(3)), or the new function \fBSSL_handle_events\fR\|(3), regularly. If the +SSL object is used in blocking mode, an ongoing blocking call to an I/O function +satisfies this requirement. This is required to ensure that timer events +required by QUIC are handled in a timely fashion. +.Sp +Most applications will service the SSL object by calling \fBSSL_read\fR\|(3) or +\&\fBSSL_write\fR\|(3) regularly. If an application does not do this, it should ensure +that \fBSSL_handle_events\fR\|(3) is called regularly. +.Sp +\&\fBSSL_get_event_timeout\fR\|(3) can be used to determine when +\&\fBSSL_handle_events\fR\|(3) must next be called. +.Sp +If the SSL object is being used with an underlying network BIO which is pollable +(such as \fBBIO_s_datagram\fR\|(3)), the application can use +\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3) to obtain +resources which can be used to determine when \fBSSL_handle_events\fR\|(3) should be +called due to network I/O. +.Sp +Applications which use thread assisted mode do not need to be concerned +with this requirement, as the QUIC implementation ensures timeout events +are handled in a timely manner. See \fBTHREAD ASSISTED MODE\fR for details. +.IP \(bu 4 +Ensure that your usage of \fBSSL_want\fR\|(3), \fBSSL_want_read\fR\|(3) and +\&\fBSSL_want_write\fR\|(3) reflects the API changes described in \fBCHANGES TO EXISTING +APIS\fR. In particular, you should use these APIs to determine the ability of a +QUIC stream to receive or provide application data, not to to determine if +network I/O is required. +.IP \(bu 4 +Evaluate your application's use of \fBSSL_shutdown\fR\|(3) in light of the changes +discussed in \fBCHANGES TO EXISTING APIS\fR. Depending on whether your application +wishes to prioritise RFC conformance or rapid shutdown, consider using the new +\&\fBSSL_shutdown_ex\fR\|(3) API instead. See \fBQUIC-SPECIFIC APIS\fR for details. +.SH "RECOMMENDED USAGE IN NEW APPLICATIONS" +.IX Header "RECOMMENDED USAGE IN NEW APPLICATIONS" +The recommended usage in new applications varies depending on three independent +design decisions: +.IP \(bu 4 +Whether the application will use blocking or nonblocking I/O at the application +level (configured using \fBSSL_set_blocking_mode\fR\|(3)). +.Sp +If the application does nonblocking I/O at the application level it can choose +to manage its own polling and event loop; see \fBAPPLICATION-DRIVEN EVENT LOOPS\fR. +.IP \(bu 4 +Whether the application intends to give the QUIC implementation direct access to +a network socket (e.g. via \fBBIO_s_datagram\fR\|(3)) or whether it intends to buffer +transmitted and received datagrams via a \fBBIO_s_dgram_pair\fR\|(3) or custom BIO. +.Sp +The former is preferred where possible as it reduces latency to the network, +which enables QUIC to achieve higher performance and more accurate connection +round trip time (RTT) estimation. +.IP \(bu 4 +Whether thread assisted mode will be used (see \fBTHREAD ASSISTED MODE\fR). +.PP +Simple demos for QUIC usage under these various scenarios can be found at +<https://github.com/openssl/openssl/tree/master/doc/designs/ddd>. +.PP +Applications which wish to implement QUIC-specific protocols should be aware of +the APIs listed under \fBQUIC-SPECIFIC APIS\fR which provide access to +QUIC-specific functionality. For example, \fBSSL_stream_conclude\fR\|(3) can be used +to indicate the end of the sending part of a stream, and \fBSSL_shutdown_ex\fR\|(3) +can be used to provide a QUIC application error code when closing a connection. +.PP +Regardless of the design decisions chosen above, it is recommended that new +applications avoid use of the default stream mode and use the multi-stream API +by calling \fBSSL_set_default_stream_mode\fR\|(3); see the MODES OF OPERATION section +for details. +.SH "QUIC-SPECIFIC APIS" +.IX Header "QUIC-SPECIFIC APIS" +This section details new APIs which are directly or indirectly related to QUIC. +For details on the operation of each API, see the referenced man pages. +.PP +The following SSL APIs are new but relevant to both QUIC and DTLS: +.IP \fBSSL_get_event_timeout\fR\|(3) 4 +.IX Item "SSL_get_event_timeout" +Determines when the QUIC implementation should next be woken up via a call to +\&\fBSSL_handle_events\fR\|(3) (or another I/O function such as \fBSSL_read\fR\|(3) or +\&\fBSSL_write\fR\|(3)), if ever. +.Sp +This can also be used with DTLS and supersedes \fBDTLSv1_get_timeout\fR\|(3) for new +usage. +.IP \fBSSL_handle_events\fR\|(3) 4 +.IX Item "SSL_handle_events" +This is a non-specific I/O operation which makes a best effort attempt to +perform any pending I/O or timeout processing. It can be used to advance the +QUIC state machine by processing incoming network traffic, generating outgoing +network traffic and handling any expired timeout events. Most other I/O +functions on an SSL object, such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) +implicitly perform event handling on the SSL object, so calling this function is +only needed if no other I/O function is to be called. +.Sp +This can also be used with DTLS and supersedes \fBDTLSv1_handle_timeout\fR\|(3) for +new usage. +.PP +The following SSL APIs are specific to QUIC: +.IP "\fBSSL_set_blocking_mode\fR\|(3), \fBSSL_get_blocking_mode\fR\|(3)" 4 +.IX Item "SSL_set_blocking_mode, SSL_get_blocking_mode" +Configures whether blocking semantics are used at the application level. This +determines whether calls to functions such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) +will block. +.IP "\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3)" 4 +.IX Item "SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor" +These functions facilitate operation in nonblocking mode. +.Sp +When an SSL object is being used with an underlying network read BIO which +supports polling, \fBSSL_get_rpoll_descriptor\fR\|(3) outputs an OS resource which +can be used to synchronise on network readability events which should result in +a call to \fBSSL_handle_events\fR\|(3). \fBSSL_get_wpoll_descriptor\fR\|(3) works in an +analogous fashion for the underlying network write BIO. +.Sp +The poll descriptors provided by these functions need only be used when +\&\fBSSL_net_read_desired\fR\|(3) and \fBSSL_net_write_desired\fR\|(3) return 1, respectively. +.IP "\fBSSL_net_read_desired\fR\|(3), \fBSSL_net_write_desired\fR\|(3)" 4 +.IX Item "SSL_net_read_desired, SSL_net_write_desired" +These functions facilitate operation in nonblocking mode and are used in +conjunction with \fBSSL_get_rpoll_descriptor\fR\|(3) and +\&\fBSSL_get_wpoll_descriptor\fR\|(3) respectively. They determine whether the +respective poll descriptor is currently relevant for the purposes of polling. +.IP \fBSSL_set1_initial_peer_addr\fR\|(3) 4 +.IX Item "SSL_set1_initial_peer_addr" +This function can be used to set the initial peer address for an outgoing QUIC +connection. This function must be used in the general case when creating an +outgoing QUIC connection; however, the correct initial peer address can be +autodetected in some cases. See \fBSSL_set1_initial_peer_addr\fR\|(3) for details. +.IP \fBSSL_shutdown_ex\fR\|(3) 4 +.IX Item "SSL_shutdown_ex" +This augments \fBSSL_shutdown\fR\|(3) by allowing an application error code to be +specified. It also allows a client to decide how quickly it wants a shutdown to +be performed, potentially by trading off strict RFC compliance. +.IP \fBSSL_stream_conclude\fR\|(3) 4 +.IX Item "SSL_stream_conclude" +This allows an application to indicate the normal end of the sending part of a +QUIC stream. This corresponds to the FIN flag in the QUIC RFC. The receiving +part of a stream remains usable. +.IP \fBSSL_stream_reset\fR\|(3) 4 +.IX Item "SSL_stream_reset" +This allows an application to indicate the non-normal termination of the sending +part of a stream. This corresponds to the RESET_STREAM frame in the QUIC RFC. +.IP "\fBSSL_get_stream_write_state\fR\|(3) and \fBSSL_get_stream_read_state\fR\|(3)" 4 +.IX Item "SSL_get_stream_write_state and SSL_get_stream_read_state" +This allows an application to determine the current stream states for the +sending and receiving parts of a stream respectively. +.IP "\fBSSL_get_stream_write_error_code\fR\|(3) and \fBSSL_get_stream_read_error_code\fR\|(3)" 4 +.IX Item "SSL_get_stream_write_error_code and SSL_get_stream_read_error_code" +This allows an application to determine the application error code which was +signalled by a peer which has performed a non-normal stream termination of the +respective sending or receiving part of a stream, if any. +.IP \fBSSL_get_conn_close_info\fR\|(3) 4 +.IX Item "SSL_get_conn_close_info" +This allows an application to determine the error code which was signalled when +the local or remote endpoint terminated the QUIC connection. +.IP \fBSSL_get0_connection\fR\|(3) 4 +.IX Item "SSL_get0_connection" +Gets the QUIC connection SSL object from a QUIC stream SSL object. +.IP \fBSSL_is_connection\fR\|(3) 4 +.IX Item "SSL_is_connection" +Returns 1 if a SSL object is not a QUIC stream SSL object. +.IP \fBSSL_get_stream_type\fR\|(3) 4 +.IX Item "SSL_get_stream_type" +Provides information on the kind of QUIC stream which is attached +to the SSL object. +.IP \fBSSL_get_stream_id\fR\|(3) 4 +.IX Item "SSL_get_stream_id" +Returns the QUIC stream ID which the QUIC protocol has associated with a QUIC +stream. +.IP \fBSSL_new_stream\fR\|(3) 4 +.IX Item "SSL_new_stream" +Creates a new QUIC stream SSL object representing a new, locally-initiated QUIC +stream. +.IP \fBSSL_accept_stream\fR\|(3) 4 +.IX Item "SSL_accept_stream" +Potentially yields a new QUIC stream SSL object representing a new +remotely-initiated QUIC stream, blocking until one is available if the +connection is configured to do so. +.IP \fBSSL_get_accept_stream_queue_len\fR\|(3) 4 +.IX Item "SSL_get_accept_stream_queue_len" +Provides information on the number of pending remotely-initiated streams. +.IP \fBSSL_set_incoming_stream_policy\fR\|(3) 4 +.IX Item "SSL_set_incoming_stream_policy" +Configures how incoming, remotely-initiated streams are handled. The incoming +stream policy can be used to automatically reject streams created by the peer, +or allow them to be handled using \fBSSL_accept_stream\fR\|(3). +.IP \fBSSL_set_default_stream_mode\fR\|(3) 4 +.IX Item "SSL_set_default_stream_mode" +Used to configure or disable default stream mode; see the MODES OF OPERATION +section for details. +.PP +The following BIO APIs are not specific to QUIC but have been added to +facilitate QUIC-specific requirements and are closely associated with its use: +.IP \fBBIO_s_dgram_pair\fR\|(3) 4 +.IX Item "BIO_s_dgram_pair" +This is a new BIO method which is similar to a conventional BIO pair but +provides datagram semantics. +.IP "\fBBIO_get_rpoll_descriptor\fR\|(3), \fBBIO_get_wpoll_descriptor\fR\|(3)" 4 +.IX Item "BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor" +This is a new BIO API which allows a BIO to expose a poll descriptor. This API +is used to implement the corresponding SSL APIs \fBSSL_get_rpoll_descriptor\fR\|(3) +and \fBSSL_get_wpoll_descriptor\fR\|(3). +.IP "\fBBIO_sendmmsg\fR\|(3), \fBBIO_recvmmsg\fR\|(3)" 4 +.IX Item "BIO_sendmmsg, BIO_recvmmsg" +This is a new BIO API which can be implemented by BIOs which implement datagram +semantics. It is implemented by \fBBIO_s_datagram\fR\|(3) and \fBBIO_s_dgram_pair\fR\|(3). +It is used by the QUIC implementation to send and receive UDP datagrams. +.IP "\fBBIO_dgram_set_no_trunc\fR\|(3), \fBBIO_dgram_get_no_trunc\fR\|(3)" 4 +.IX Item "BIO_dgram_set_no_trunc, BIO_dgram_get_no_trunc" +By default, \fBBIO_s_dgram_pair\fR\|(3) has semantics comparable to those of Berkeley +sockets being used with datagram semantics. This allows an alternative mode +to be enabled in which datagrams will not be silently truncated if they are +too large. +.IP "\fBBIO_dgram_set_caps\fR\|(3), \fBBIO_dgram_get_caps\fR\|(3)" 4 +.IX Item "BIO_dgram_set_caps, BIO_dgram_get_caps" +These functions are used to allow the user of one end of a +\&\fBBIO_s_dgram_pair\fR\|(3) to indicate its capabilities to the other end of a +\&\fBBIO_s_dgram_pair\fR\|(3). In particular, this allows an application to inform the +QUIC implementation of whether it is prepared to handle local and/or peer +addresses in transmitted datagrams and to provide the applicable information in +received datagrams. +.IP "\fBBIO_dgram_get_local_addr_cap\fR\|(3), \fBBIO_dgram_set_local_addr_enable\fR\|(3), \fBBIO_dgram_get_local_addr_enable\fR\|(3)" 4 +.IX Item "BIO_dgram_get_local_addr_cap, BIO_dgram_set_local_addr_enable, BIO_dgram_get_local_addr_enable" +Local addressing support refers to the ability of a BIO with datagram semantics +to allow a source address to be specified on transmission and to report the +destination address on reception. These functions can be used to determine if a +BIO can support local addressing and to enable local addressing support if it +can. +.IP \fBBIO_err_is_non_fatal\fR\|(3) 4 +.IX Item "BIO_err_is_non_fatal" +This is used to determine if an error while calling \fBBIO_sendmmsg\fR\|(3) or +\&\fBBIO_recvmmsg\fR\|(3) is ephemeral in nature, such as "would block" errors. +.SH "THREAD ASSISTED MODE" +.IX Header "THREAD ASSISTED MODE" +The optional thread assisted mode can be used with +\&\fBOSSL_QUIC_client_thread_method\fR\|(3). In this mode, a background thread is +created automatically. The OpenSSL QUIC implementation then takes responsibility +for ensuring that timeout events are handled on a timely basis even if no SSL +I/O function such as \fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called by the +application for a long time. +.PP +All necessary locking is handled automatically internally, but the thread safety +guarantees for the public SSL API are unchanged. Therefore, an application must +still do its own locking if it wishes to make concurrent use of the public SSL +APIs. +.PP +Because this method relies on threads, it is not available on platforms where +threading support is not available or not supported by OpenSSL. However, it +does provide the simplest mode of usage for an application. +.PP +The implementation may or may not use a common thread or thread pool to service +multiple SSL objects in the same \fBSSL_CTX\fR. +.SH "APPLICATION-DRIVEN EVENT LOOPS" +.IX Header "APPLICATION-DRIVEN EVENT LOOPS" +OpenSSL's QUIC implementation is designed to facilitate applications which wish +to use the SSL APIs in a blocking fashion, but is also designed to facilitate +applications which wish to use the SSL APIs in a nonblocking fashion and manage +their own event loops and polling directly. This is useful when it is desirable +to host OpenSSL's QUIC implementation on top of an application's existing +nonblocking I/O infrastructure. +.PP +This is supported via the concept of poll descriptors; see +\&\fBBIO_get_rpoll_descriptor\fR\|(3) for details. Broadly, a \fBBIO_POLL_DESCRIPTOR\fR is +a structure which expresses some kind of OS resource which can be used to +synchronise on I/O events. The QUIC implementation provides a +\&\fBBIO_POLL_DESCRIPTOR\fR based on the poll descriptor provided by the underlying +network BIO. This is typically an OS socket handle, though custom BIOs could +choose to implement their own custom poll descriptor format. +.PP +Broadly, an application which wishes to manage its own event loop should +interact with the SSL object as follows: +.IP \(bu 4 +It should provide read and write BIOs with nonblocking datagram semantics to +the SSL object using \fBSSL_set0_rbio\fR\|(3) and \fBSSL_set0_wbio\fR\|(3). This could be +a BIO abstracting a network socket such as \fBBIO_s_datagram\fR\|(3), or a BIO +abstracting some kind of memory buffer such as \fBBIO_s_dgram_pair\fR\|(3). Use of a +custom BIO is also possible. +.IP \(bu 4 +It should configure the SSL object into nonblocking mode by calling +\&\fBSSL_set_blocking_mode\fR\|(3). +.IP \(bu 4 +It should configure the SSL object as desired, set an initial peer as needed +using \fBSSL_set1_initial_peer_addr\fR\|(3), and trigger the connection process by +calling \fBSSL_connect\fR\|(3). +.IP \(bu 4 +If the network read and write BIOs provided were pollable (for example, +a \fBBIO_s_datagram\fR\|(3), or a custom BIO which implements +\&\fBBIO_get_rpoll_descriptor\fR\|(3) and \fBBIO_get_wpoll_descriptor\fR\|(3)), it should +perform the following steps repeatedly: +.RS 4 +.IP \(bu 4 +The application should call \fBSSL_get_rpoll_descriptor\fR\|(3) and +\&\fBSSL_get_wpoll_descriptor\fR\|(3) to identify OS resources which can be used for +synchronisation. +.IP \(bu 4 +It should call \fBSSL_net_read_desired\fR\|(3) and \fBSSL_net_write_desired\fR\|(3) to determine +whether the QUIC implementation is currently interested in readability and +writability events on the underlying network BIO which was provided, and call +\&\fBSSL_get_event_timeout\fR\|(3) to determine if any timeout event will become +applicable in the future. +.IP \(bu 4 +It should wait until one of the following events occurs: +.RS 4 +.IP \(bu 4 +The poll descriptor returned by \fBSSL_get_rpoll_descriptor\fR\|(3) becomes readable +(if \fBSSL_net_read_desired\fR\|(3) returned 1); +.IP \(bu 4 +The poll descriptor returned by \fBSSL_get_wpoll_descriptor\fR\|(3) becomes writable +(if \fBSSL_net_write_desired\fR\|(3) returned 1); +.IP \(bu 4 +The timeout returned by \fBSSL_get_event_timeout\fR\|(3) (if any) expires. +.RE +.RS 4 +.Sp +Once any of these events occurs, \fBSSL_handle_events\fR\|(3) should be called. +.RE +.RE +.RS 4 +.RE +.IP \(bu 4 +If the network read and write BIOs provided were not pollable (for example, in +the case of \fBBIO_s_dgram_pair\fR\|(3)), the application is responsible for managing +and synchronising network I/O. It should call \fBSSL_handle_events\fR\|(3) after it +writes data to a \fBBIO_s_dgram_pair\fR\|(3) or otherwise takes action so that the +QUIC implementation can read new datagrams via a call to \fBBIO_recvmmsg\fR\|(3) on +the underlying network BIO. The QUIC implementation may output datagrams via a +call to \fBBIO_sendmmsg\fR\|(3) and the application is responsible for ensuring these +are transmitted. +.Sp +The application must call \fBSSL_get_event_timeout\fR\|(3) after every call to +\&\fBSSL_handle_events\fR\|(3) (or another I/O function on the SSL object), and ensure +that a call to \fBSSL_handle_events\fR\|(3) is performed after the specified timeout +(if any). +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3), +\&\fBSSL_net_read_desired\fR\|(3), \fBSSL_net_write_desired\fR\|(3), +\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3), +\&\fBSSL_set_blocking_mode\fR\|(3), \fBSSL_shutdown_ex\fR\|(3), +\&\fBSSL_set1_initial_peer_addr\fR\|(3), \fBSSL_stream_conclude\fR\|(3), +\&\fBSSL_stream_reset\fR\|(3), \fBSSL_get_stream_read_state\fR\|(3), +\&\fBSSL_get_stream_read_error_code\fR\|(3), \fBSSL_get_conn_close_info\fR\|(3), +\&\fBSSL_get0_connection\fR\|(3), \fBSSL_get_stream_type\fR\|(3), \fBSSL_get_stream_id\fR\|(3), +\&\fBSSL_new_stream\fR\|(3), \fBSSL_accept_stream\fR\|(3), +\&\fBSSL_set_incoming_stream_policy\fR\|(3), \fBSSL_set_default_stream_mode\fR\|(3) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/openssl-threads.7ssl b/upstream/debian-unstable/man7/openssl-threads.7ssl index 8190ed36..89887d68 100644 --- a/upstream/debian-unstable/man7/openssl-threads.7ssl +++ b/upstream/debian-unstable/man7/openssl-threads.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OPENSSL-THREADS 7SSL" -.TH OPENSSL-THREADS 7SSL 2024-02-03 3.1.5 OpenSSL +.TH OPENSSL-THREADS 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -150,7 +150,7 @@ local system threads documentation. This page is admittedly very incomplete. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2021\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/openssl_user_macros.7ssl b/upstream/debian-unstable/man7/openssl_user_macros.7ssl index 3f9855c4..b924774f 100644 --- a/upstream/debian-unstable/man7/openssl_user_macros.7ssl +++ b/upstream/debian-unstable/man7/openssl_user_macros.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OPENSSL_USER_MACROS 7SSL" -.TH OPENSSL_USER_MACROS 7SSL 2024-02-03 3.1.5 OpenSSL +.TH OPENSSL_USER_MACROS 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -137,7 +137,7 @@ minor and patch components of the version number. For example: .Sp If \fBOPENSSL_API_COMPAT\fR is undefined, this default value is used in its place: -\&\f(CW30100\fR +\&\f(CW30200\fR .RE .IP \fBOPENSSL_NO_DEPRECATED\fR 4 .IX Item "OPENSSL_NO_DEPRECATED" diff --git a/upstream/debian-unstable/man7/operator.7 b/upstream/debian-unstable/man7/operator.7 index ec4652f5..1fa7ef30 100644 --- a/upstream/debian-unstable/man7/operator.7 +++ b/upstream/debian-unstable/man7/operator.7 @@ -14,12 +14,12 @@ .\" .\" 2007-12-08, mtk, Converted from mdoc to man macros .\" -.TH operator 7 2023-02-05 "Linux man-pages 6.05.01" +.TH operator 7 2024-05-02 "Linux man-pages 6.8" .SH NAME operator \- C operator precedence and order of evaluation .SH DESCRIPTION This manual page lists C operators and their precedence in evaluation. -.PP +.P .TS lb lb lb l l l. @@ -41,11 +41,11 @@ Operator Associativity Notes = *= /= %= += \-= <<= >>= &= \[ha]= |= right to left , left to right .TE -.PP +.P The following notes provide further information to the above table: -.PP +.P .PD 0 -.IP [1] 4 +.IP [1] 5 The ++ and \-\- operators at this precedence level are the postfix flavors of the operators. .IP [2] diff --git a/upstream/debian-unstable/man7/ossl-guide-introduction.7ssl b/upstream/debian-unstable/man7/ossl-guide-introduction.7ssl new file mode 100644 index 00000000..d237907d --- /dev/null +++ b/upstream/debian-unstable/man7/ossl-guide-introduction.7ssl @@ -0,0 +1,154 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-INTRODUCTION 7SSL" +.TH OSSL-GUIDE-INTRODUCTION 7SSL 2024-04-04 3.2.2-dev 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 +ossl\-guide\-introduction +\&\- OpenSSL Guide: An introduction to OpenSSL +.SH "WHAT IS OPENSSL?" +.IX Header "WHAT IS OPENSSL?" +OpenSSL is a robust, commercial-grade, full-featured toolkit for general-purpose +cryptography and secure communication. Its features are made available via a +command line application that enables users to perform various cryptography +related functions such as generating keys and certificates. Additionally it +supplies two libraries that application developers can use to implement +cryptography based capabilities and to securely communicate across a network. +Finally, it also has a set of providers that supply implementations of a broad +set of cryptographic algorithms. +.PP +OpenSSL is fully open source. Version 3.0 and above are distributed under the +Apache v2 license. +.SH "GETTING AND INSTALLING OPENSSL" +.IX Header "GETTING AND INSTALLING OPENSSL" +The OpenSSL Project develops and distributes the source code for OpenSSL. You +can obtain that source code via the OpenSSL website +(<https://www.openssl.org/source>). +.PP +Many Operating Systems (notably Linux distributions) supply pre-built OpenSSL +binaries either pre-installed or available via the package management system in +use for that OS. It is worth checking whether this applies to you before +attempting to build OpenSSL from the source code. +.PP +Some third parties also supply OpenSSL binaries (e.g. for Windows and some other +platforms). The OpenSSL project maintains a list of these third parties at +<https://wiki.openssl.org/index.php/Binaries>. +.PP +If you build and install OpenSSL from the source code then you should download +the appropriate files for the version that you want to use from the link given +above. Extract the contents of the \fBtar.gz\fR archive file that you downloaded +into an appropriate directory. Inside that archive you will find a file named +\&\fBINSTALL.md\fR which will supply detailed instructions on how to build and +install OpenSSL from source. Make sure you read the contents of that file +carefully in order to achieve a successful build. In the directory you will also +find a set of \fBNOTES\fR files that provide further platform specific information. +Make sure you carefully read the file appropriate to your platform. As well as +the platform specific \fBNOTES\fR files there is also a \fBNOTES\-PERL.md\fR file that +provides information about setting up Perl for use by the OpenSSL build system +across multiple platforms. +.PP +Sometimes you may want to build and install OpenSSL from source on a system +which already has a pre-built version of OpenSSL installed on it via the +Operating System package management system (for example if you want to use a +newer version of OpenSSL than the one supplied by your Operating System). In +this case it is strongly recommended to install OpenSSL to a different location +than where the pre-built version is installed. You should \fBnever\fR replace the +pre-built version with a different version as this may break your system. +.SH "CONTENTS OF THE OPENSSL GUIDE" +.IX Header "CONTENTS OF THE OPENSSL GUIDE" +The OpenSSL Guide is a series of documentation pages (starting with this one) +that introduce some of the main concepts in OpenSSL. The guide can either be +read end-to-end in order, or alternatively you can simply skip to the parts most +applicable to your use case. Note however that later pages may depend on and +assume knowledge from earlier pages. +.PP +The pages in the guide are as follows: +.IP "\fBossl\-guide\-libraries\-introduction\fR\|(7): An introduction to the OpenSSL libraries" 4 +.IX Item "ossl-guide-libraries-introduction: An introduction to the OpenSSL libraries" +.PD 0 +.IP "\fBossl\-guide\-libcrypto\-introduction\fR\|(7): An introduction to libcrypto" 4 +.IX Item "ossl-guide-libcrypto-introduction: An introduction to libcrypto" +.IP "\fBossl\-guide\-libssl\-introduction\fR\|(7): An introduction to libssl" 4 +.IX Item "ossl-guide-libssl-introduction: An introduction to libssl" +.IP "\fBossl\-guide\-tls\-introduction\fR\|(7): An introduction to SSL/TLS in OpenSSL" 4 +.IX Item "ossl-guide-tls-introduction: An introduction to SSL/TLS in OpenSSL" +.IP "\fBossl\-guide\-tls\-client\-block\fR\|(7): Writing a simple blocking TLS client" 4 +.IX Item "ossl-guide-tls-client-block: Writing a simple blocking TLS client" +.IP "\fBossl\-guide\-tls\-client\-non\-block\fR\|(7): Writing a simple nonblocking TLS client" 4 +.IX Item "ossl-guide-tls-client-non-block: Writing a simple nonblocking TLS client" +.IP "\fBossl\-guide\-quic\-introduction\fR\|(7): An introduction to QUIC in OpenSSL" 4 +.IX Item "ossl-guide-quic-introduction: An introduction to QUIC in OpenSSL" +.IP "\fBossl\-guide\-quic\-client\-block\fR\|(7): Writing a simple blocking QUIC client" 4 +.IX Item "ossl-guide-quic-client-block: Writing a simple blocking QUIC client" +.IP "\fBossl\-guide\-quic\-multi\-stream\fR\|(7): Writing a simple multi-stream QUIC client" 4 +.IX Item "ossl-guide-quic-multi-stream: Writing a simple multi-stream QUIC client" +.IP "\fBossl\-guide\-quic\-client\-non\-block\fR\|(7): Writing a simple nonblocking QUIC client" 4 +.IX Item "ossl-guide-quic-client-non-block: Writing a simple nonblocking QUIC client" +.IP "\fBossl\-guide\-migration\fR\|(7): Migrating from older OpenSSL versions" 4 +.IX Item "ossl-guide-migration: Migrating from older OpenSSL versions" +.PD +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/ossl-guide-libcrypto-introduction.7ssl b/upstream/debian-unstable/man7/ossl-guide-libcrypto-introduction.7ssl new file mode 100644 index 00000000..e39a2102 --- /dev/null +++ b/upstream/debian-unstable/man7/ossl-guide-libcrypto-introduction.7ssl @@ -0,0 +1,443 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-LIBCRYPTO-INTRODUCTION 7SSL" +.TH OSSL-GUIDE-LIBCRYPTO-INTRODUCTION 7SSL 2024-04-04 3.2.2-dev 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 +ossl\-guide\-libcrypto\-introduction, crypto +\&\- OpenSSL Guide: An introduction to libcrypto +.SH INTRODUCTION +.IX Header "INTRODUCTION" +The OpenSSL cryptography library (\f(CW\*(C`libcrypto\*(C'\fR) enables access to a wide range +of cryptographic algorithms used in various Internet standards. The services +provided by this library are used by the OpenSSL implementations of TLS and +CMS, and they have also been used to implement many other third party products +and protocols. +.PP +The functionality includes symmetric encryption, public key cryptography, key +agreement, certificate handling, cryptographic hash functions, cryptographic +pseudo-random number generators, message authentication codes (MACs), key +derivation functions (KDFs), and various utilities. +.SS Algorithms +.IX Subsection "Algorithms" +Cryptographic primitives such as the SHA256 digest, or AES encryption are +referred to in OpenSSL as "algorithms". Each algorithm may have multiple +implementations available for use. For example the RSA algorithm is available as +a "default" implementation suitable for general use, and a "fips" implementation +which has been validated to FIPS 140 standards for situations where that is +important. It is also possible that a third party could add additional +implementations such as in a hardware security module (HSM). +.PP +Algorithms are implemented in providers. See +\&\fBossl\-guide\-libraries\-introduction\fR\|(7) for information about providers. +.SS Operations +.IX Subsection "Operations" +Different algorithms can be grouped together by their purpose. For example there +are algorithms for encryption, and different algorithms for digesting data. +These different groups are known as "operations" in OpenSSL. Each operation +has a different set of functions associated with it. For example to perform an +encryption operation using AES (or any other encryption algorithm) you would use +the encryption functions detailed on the \fBEVP_EncryptInit\fR\|(3) page. Or to +perform a digest operation using SHA256 then you would use the digesting +functions on the \fBEVP_DigestInit\fR\|(3) page. +.SH "ALGORITHM FETCHING" +.IX Header "ALGORITHM FETCHING" +In order to use an algorithm an implementation for it must first be "fetched". +Fetching is the process of looking through the available implementations, +applying selection criteria (via a property query string), and finally choosing +the implementation that will be used. +.PP +Two types of fetching are supported by OpenSSL \- "Explicit fetching" and +"Implicit fetching". +.SS "Explicit fetching" +.IX Subsection "Explicit fetching" +Explicit fetching involves directly calling a specific API to fetch an algorithm +implementation from a provider. This fetched object can then be passed to other +APIs. These explicit fetching functions usually have the name \f(CW\*(C`APINAME_fetch\*(C'\fR, +where \f(CW\*(C`APINAME\*(C'\fR is the name of the operation. For example \fBEVP_MD_fetch\fR\|(3) +can be used to explicitly fetch a digest algorithm implementation. The user is +responsible for freeing the object returned from the \f(CW\*(C`APINAME_fetch\*(C'\fR function +using \f(CW\*(C`APINAME_free\*(C'\fR when it is no longer needed. +.PP +These fetching functions follow a fairly common pattern, where three +arguments are passed: +.IP "The library context" 4 +.IX Item "The library context" +See \fBOSSL_LIB_CTX\fR\|(3) for a more detailed description. +This may be NULL to signify the default (global) library context, or a +context created by the user. Only providers loaded in this library context (see +\&\fBOSSL_PROVIDER_load\fR\|(3)) will be considered by the fetching function. In case +no provider has been loaded in this library context then the default provider +will be loaded as a fallback (see \fBOSSL_PROVIDER\-default\fR\|(7)). +.IP "An identifier" 4 +.IX Item "An identifier" +For all currently implemented fetching functions this is the algorithm name. +Each provider supports a list of algorithm implementations. See the provider +specific documentation for information on the algorithm implementations +available in each provider: +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-default\fR\|(7), +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-FIPS\fR\|(7), +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-legacy\fR\|(7) and +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-base\fR\|(7). +.Sp +Note, while providers may register algorithms against a list of names using a +string with a colon separated list of names, fetching algorithms using that +format is currently unsupported. +.IP "A property query string" 4 +.IX Item "A property query string" +The property query string used to guide selection of the algorithm +implementation. See +"PROPERTY QUERY STRINGS" in \fBossl\-guide\-libraries\-introduction\fR\|(7). +.PP +The algorithm implementation that is fetched can then be used with other diverse +functions that use them. For example the \fBEVP_DigestInit_ex\fR\|(3) function takes +as a parameter an \fBEVP_MD\fR object which may have been returned from an earlier +call to \fBEVP_MD_fetch\fR\|(3). +.SS "Implicit fetching" +.IX Subsection "Implicit fetching" +OpenSSL has a number of functions that return an algorithm object with no +associated implementation, such as \fBEVP_sha256\fR\|(3), \fBEVP_aes_128_cbc\fR\|(3), +\&\fBEVP_get_cipherbyname\fR\|(3) or \fBEVP_get_digestbyname\fR\|(3). These are present for +compatibility with OpenSSL before version 3.0 where explicit fetching was not +available. +.PP +When they are used with functions like \fBEVP_DigestInit_ex\fR\|(3) or +\&\fBEVP_CipherInit_ex\fR\|(3), the actual implementation to be used is +fetched implicitly using default search criteria (which uses NULL for the +library context and property query string). +.PP +In some cases implicit fetching can also occur when a NULL algorithm parameter +is supplied. In this case an algorithm implementation is implicitly fetched +using default search criteria and an algorithm name that is consistent with +the context in which it is being used. +.PP +Functions that use an \fBEVP_PKEY_CTX\fR or an \fBEVP_PKEY\fR\|(3), such as +\&\fBEVP_DigestSignInit\fR\|(3), all fetch the implementations implicitly. Usually the +algorithm to fetch is determined based on the type of key that is being used and +the function that has been called. +.SS Performance +.IX Subsection "Performance" +If you perform the same operation many times with the same algorithm then it is +recommended to use a single explicit fetch of the algorithm and then reuse the +explicitly fetched algorithm each subsequent time. This will typically be +faster than implicitly fetching the algorithm every time you use it. See an +example of Explicit fetching in "USING ALGORITHMS IN APPLICATIONS". +.PP +Prior to OpenSSL 3.0, functions such as \fBEVP_sha256()\fR which return a "const" +object were used directly to indicate the algorithm to use in various function +calls. If you pass the return value of one of these convenience functions to an +operation then you are using implicit fetching. If you are converting an +application that worked with an OpenSSL version prior to OpenSSL 3.0 then +consider changing instances of implicit fetching to explicit fetching instead. +.PP +If an explicitly fetched object is not passed to an operation, then any implicit +fetch will use an internally cached prefetched object, but it will +still be slower than passing the explicitly fetched object directly. +.PP +The following functions can be used for explicit fetching: +.IP \fBEVP_MD_fetch\fR\|(3) 4 +.IX Item "EVP_MD_fetch" +Fetch a message digest/hashing algorithm implementation. +.IP \fBEVP_CIPHER_fetch\fR\|(3) 4 +.IX Item "EVP_CIPHER_fetch" +Fetch a symmetric cipher algorithm implementation. +.IP \fBEVP_KDF_fetch\fR\|(3) 4 +.IX Item "EVP_KDF_fetch" +Fetch a Key Derivation Function (KDF) algorithm implementation. +.IP \fBEVP_MAC_fetch\fR\|(3) 4 +.IX Item "EVP_MAC_fetch" +Fetch a Message Authentication Code (MAC) algorithm implementation. +.IP \fBEVP_KEM_fetch\fR\|(3) 4 +.IX Item "EVP_KEM_fetch" +Fetch a Key Encapsulation Mechanism (KEM) algorithm implementation +.IP \fBOSSL_ENCODER_fetch\fR\|(3) 4 +.IX Item "OSSL_ENCODER_fetch" +Fetch an encoder algorithm implementation (e.g. to encode keys to a specified +format). +.IP \fBOSSL_DECODER_fetch\fR\|(3) 4 +.IX Item "OSSL_DECODER_fetch" +Fetch a decoder algorithm implementation (e.g. to decode keys from a specified +format). +.IP \fBEVP_RAND_fetch\fR\|(3) 4 +.IX Item "EVP_RAND_fetch" +Fetch a Pseudo Random Number Generator (PRNG) algorithm implementation. +.PP +See "OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-default\fR\|(7), +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-FIPS\fR\|(7), +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-legacy\fR\|(7) and +"OPERATIONS AND ALGORITHMS" in \fBOSSL_PROVIDER\-base\fR\|(7) for a list of algorithm names +that can be fetched. +.SH "FETCHING EXAMPLES" +.IX Header "FETCHING EXAMPLES" +The following section provides a series of examples of fetching algorithm +implementations. +.PP +Fetch any available implementation of SHA2\-256 in the default context. Note +that some algorithms have aliases. So "SHA256" and "SHA2\-256" are synonymous: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", NULL); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch any available implementation of AES\-128\-CBC in the default context: +.PP +.Vb 3 +\& EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES\-128\-CBC", NULL); +\& ... +\& EVP_CIPHER_free(cipher); +.Ve +.PP +Fetch an implementation of SHA2\-256 from the default provider in the default +context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch an implementation of SHA2\-256 that is not from the default provider in the +default context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider!=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch an implementation of SHA2\-256 that is preferably from the FIPS provider in +the default context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(NULL, "SHA2\-256", "provider=?fips"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Fetch an implementation of SHA2\-256 from the default provider in the specified +library context: +.PP +.Vb 3 +\& EVP_MD *md = EVP_MD_fetch(libctx, "SHA2\-256", "provider=default"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Load the legacy provider into the default context and then fetch an +implementation of WHIRLPOOL from it: +.PP +.Vb 2 +\& /* This only needs to be done once \- usually at application start up */ +\& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); +\& +\& EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy"); +\& ... +\& EVP_MD_free(md); +.Ve +.PP +Note that in the above example the property string "provider=legacy" is optional +since, assuming no other providers have been loaded, the only implementation of +the "whirlpool" algorithm is in the "legacy" provider. Also note that the +default provider should be explicitly loaded if it is required in addition to +other providers: +.PP +.Vb 3 +\& /* This only needs to be done once \- usually at application start up */ +\& OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); +\& OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default"); +\& +\& EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL); +\& EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2\-256", NULL); +\& ... +\& EVP_MD_free(md_whirlpool); +\& EVP_MD_free(md_sha256); +.Ve +.SH "USING ALGORITHMS IN APPLICATIONS" +.IX Header "USING ALGORITHMS IN APPLICATIONS" +Cryptographic algorithms are made available to applications through use of the +"EVP" APIs. Each of the various operations such as encryption, digesting, +message authentication codes, etc., have a set of EVP function calls that can +be invoked to use them. See the \fBevp\fR\|(7) page for further details. +.PP +Most of these follow a common pattern. A "context" object is first created. For +example for a digest operation you would use an \fBEVP_MD_CTX\fR, and for an +encryption/decryption operation you would use an \fBEVP_CIPHER_CTX\fR. The +operation is then initialised ready for use via an "init" function \- optionally +passing in a set of parameters (using the \fBOSSL_PARAM\fR\|(3) type) to configure how +the operation should behave. Next data is fed into the operation in a series of +"update" calls. The operation is finalised using a "final" call which will +typically provide some kind of output. Finally the context is cleaned up and +freed. +.PP +The following shows a complete example for doing this process for digesting +data using SHA256. The process is similar for other operations such as +encryption/decryption, signatures, message authentication codes, etc. Additional +examples can be found in the OpenSSL demos (see +"DEMO APPLICATIONS" in \fBossl\-guide\-libraries\-introduction\fR\|(7)). +.PP +.Vb 4 +\& #include <stdio.h> +\& #include <openssl/evp.h> +\& #include <openssl/bio.h> +\& #include <openssl/err.h> +\& +\& int main(void) +\& { +\& EVP_MD_CTX *ctx = NULL; +\& EVP_MD *sha256 = NULL; +\& const unsigned char msg[] = { +\& 0x00, 0x01, 0x02, 0x03 +\& }; +\& unsigned int len = 0; +\& unsigned char *outdigest = NULL; +\& int ret = 1; +\& +\& /* Create a context for the digest operation */ +\& ctx = EVP_MD_CTX_new(); +\& if (ctx == NULL) +\& goto err; +\& +\& /* +\& * Fetch the SHA256 algorithm implementation for doing the digest. We\*(Aqre +\& * using the "default" library context here (first NULL parameter), and +\& * we\*(Aqre not supplying any particular search criteria for our SHA256 +\& * implementation (second NULL parameter). Any SHA256 implementation will +\& * do. +\& * In a larger application this fetch would just be done once, and could +\& * be used for multiple calls to other operations such as EVP_DigestInit_ex(). +\& */ +\& sha256 = EVP_MD_fetch(NULL, "SHA256", NULL); +\& if (sha256 == NULL) +\& goto err; +\& +\& /* Initialise the digest operation */ +\& if (!EVP_DigestInit_ex(ctx, sha256, NULL)) +\& goto err; +\& +\& /* +\& * Pass the message to be digested. This can be passed in over multiple +\& * EVP_DigestUpdate calls if necessary +\& */ +\& if (!EVP_DigestUpdate(ctx, msg, sizeof(msg))) +\& goto err; +\& +\& /* Allocate the output buffer */ +\& outdigest = OPENSSL_malloc(EVP_MD_get_size(sha256)); +\& if (outdigest == NULL) +\& goto err; +\& +\& /* Now calculate the digest itself */ +\& if (!EVP_DigestFinal_ex(ctx, outdigest, &len)) +\& goto err; +\& +\& /* Print out the digest result */ +\& BIO_dump_fp(stdout, outdigest, len); +\& +\& ret = 0; +\& +\& err: +\& /* Clean up all the resources we allocated */ +\& OPENSSL_free(outdigest); +\& EVP_MD_free(sha256); +\& EVP_MD_CTX_free(ctx); +\& if (ret != 0) +\& ERR_print_errors_fp(stderr); +\& return ret; +\& } +.Ve +.SH "ENCODING AND DECODING KEYS" +.IX Header "ENCODING AND DECODING KEYS" +Many algorithms require the use of a key. Keys can be generated dynamically +using the EVP APIs (for example see \fBEVP_PKEY_Q_keygen\fR\|(3)). However it is often +necessary to save or load keys (or their associated parameters) to or from some +external format such as PEM or DER (see \fBopenssl\-glossary\fR\|(7)). OpenSSL uses +encoders and decoders to perform this task. +.PP +Encoders and decoders are just algorithm implementations in the same way as +any other algorithm implementation in OpenSSL. They are implemented by +providers. The OpenSSL encoders and decoders are available in the default +provider. They are also duplicated in the base provider. +.PP +For information about encoders see \fBOSSL_ENCODER_CTX_new_for_pkey\fR\|(3). For +information about decoders see \fBOSSL_DECODER_CTX_new_for_pkey\fR\|(3). +.PP +As well as using encoders/decoders directly there are also some helper functions +that can be used for certain well known and commonly used formats. For example +see \fBPEM_read_PrivateKey\fR\|(3) and \fBPEM_write_PrivateKey\fR\|(3) for information +about reading and writing key data from PEM encoded files. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-libssl\-introduction\fR\|(7) for an introduction to using \f(CW\*(C`libssl\*(C'\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\fR\|(1), \fBssl\fR\|(7), \fBevp\fR\|(7), \fBOSSL_LIB_CTX\fR\|(3), \fBopenssl\-threads\fR\|(7), +\&\fBproperty\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-base\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7), \fBOSSL_PROVIDER\-null\fR\|(7), +\&\fBopenssl\-glossary\fR\|(7), \fBprovider\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/ossl-guide-libraries-introduction.7ssl b/upstream/debian-unstable/man7/ossl-guide-libraries-introduction.7ssl new file mode 100644 index 00000000..db3b1820 --- /dev/null +++ b/upstream/debian-unstable/man7/ossl-guide-libraries-introduction.7ssl @@ -0,0 +1,372 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-LIBRARIES-INTRODUCTION 7SSL" +.TH OSSL-GUIDE-LIBRARIES-INTRODUCTION 7SSL 2024-04-04 3.2.2-dev 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 +ossl\-guide\-libraries\-introduction +\&\- OpenSSL Guide: An introduction to the OpenSSL libraries +.SH INTRODUCTION +.IX Header "INTRODUCTION" +OpenSSL supplies two libraries that can be used by applications known as +\&\f(CW\*(C`libcrypto\*(C'\fR and \f(CW\*(C`libssl\*(C'\fR. +.PP +The \f(CW\*(C`libcrypto\*(C'\fR library provides APIs for general purpose cryptography such as +encryption, digital signatures, hash functions, etc. It additionally supplies +supporting APIs for cryptography related standards, e.g. for reading and writing +digital certificates (also known as X.509 certificates). Finally it also +supplies various additional supporting APIs that are not directly cryptography +related but are nonetheless useful and depended upon by other APIs. For +example the "BIO" functions provide capabilities for abstracting I/O, e.g. via a +file or over a network. +.PP +The \f(CW\*(C`libssl\*(C'\fR library provides functions to perform secure communication between +two peers across a network. Most significantly it implements support for the +SSL/TLS, DTLS and QUIC standards. +.PP +The \f(CW\*(C`libssl\*(C'\fR library depends on and uses many of the capabilities supplied by +\&\f(CW\*(C`libcrypto\*(C'\fR. Any application linked against \f(CW\*(C`libssl\*(C'\fR will also link against +\&\f(CW\*(C`libcrypto\*(C'\fR, and most applications that do this will directly use API functions +supplied by both libraries. +.PP +Applications may be written that only use \f(CW\*(C`libcrypto\*(C'\fR capabilities and do not +link against \f(CW\*(C`libssl\*(C'\fR at all. +.SH PROVIDERS +.IX Header "PROVIDERS" +As well as the two main libraries, OpenSSL also comes with a set of providers. +.PP +A provider in OpenSSL is a component that collects together algorithm +implementations (for example an implementation of the symmetric encryption +algorithm AES). In order to use an algorithm you must have at least one +provider loaded that contains an implementation of it. OpenSSL comes with a +number of providers and they may also be obtained from third parties. +.PP +Providers may either be "built-in" or in the form of a separate loadable module +file (typically one ending in ".so" or ".dll" dependent on the platform). A +built-in provider is one that is either already present in \f(CW\*(C`libcrypto\*(C'\fR or one +that the application has supplied itself directly. Third parties can also supply +providers in the form of loadable modules. +.PP +If you don't load a provider explicitly (either in program code or via config) +then the OpenSSL built-in "default" provider will be automatically loaded. +.PP +See "OPENSSL PROVIDERS" below for a description of the providers that OpenSSL +itself supplies. +.PP +Loading and unloading providers is quite an expensive operation. It is normally +done once, early on in the application lifecycle and those providers are kept +loaded for the duration of the application execution. +.SH "LIBRARY CONTEXTS" +.IX Header "LIBRARY CONTEXTS" +Many OpenSSL API functions make use of a library context. A library context can +be thought of as a "scope" within which configuration options take effect. When +a provider is loaded, it is only loaded within the scope of a given library +context. In this way it is possible for different components of a complex +application to each use a different library context and have different providers +loaded with different configuration settings. +.PP +If an application does not explicitly create a library context then the +"default" library context will be used. +.PP +Library contexts are represented by the \fBOSSL_LIB_CTX\fR type. Many OpenSSL API +functions take a library context as a parameter. Applications can always pass +\&\fBNULL\fR for this parameter to just use the default library context. +.PP +The default library context is automatically created the first time it is +needed. This will automatically load any available configuration file and will +initialise OpenSSL for use. Unlike in earlier versions of OpenSSL (prior to +1.1.0) no explicit initialisation steps need to be taken. +.PP +Similarly when the application exits, the default library context is +automatically destroyed. No explicit de-initialisation steps need to be taken. +.PP +See \fBOSSL_LIB_CTX\fR\|(3) for more information about library contexts. +See also "ALGORITHM FETCHING" in \fBossl\-guide\-libcrypto\-introduction\fR\|(7). +.SH "PROPERTY QUERY STRINGS" +.IX Header "PROPERTY QUERY STRINGS" +In some cases the available providers may mean that more than one implementation +of any given algorithm might be available. For example the OpenSSL FIPS provider +supplies alternative implementations of many of the same algorithms that are +available in the OpenSSL default provider. +.PP +The process of selecting an algorithm implementation is known as "fetching". +When OpenSSL fetches an algorithm to use it is possible to specify a "property +query string" to guide the selection process. For example a property query +string of "provider=default" could be used to force the selection to only +consider algorithm implementations in the default provider. +.PP +Property query strings can be specified explicitly as an argument to a function. +It is also possible to specify a default property query string for the whole +library context using the \fBEVP_set_default_properties\fR\|(3) or +\&\fBEVP_default_properties_enable_fips\fR\|(3) functions. Where both +default properties and function specific properties are specified then they are +combined. Function specific properties will override default properties where +there is a conflict. +.PP +See "ALGORITHM FETCHING" in \fBossl\-guide\-libcrypto\-introduction\fR\|(7) for more +information about fetching. See \fBproperty\fR\|(7) for more information about +properties. +.SH "MULTI-THREADED APPLICATIONS" +.IX Header "MULTI-THREADED APPLICATIONS" +As long as OpenSSL has been built with support for threads (the default case +on most platforms) then most OpenSSL \fIfunctions\fR are thread-safe in the sense +that it is safe to call the same function from multiple threads at the same +time. However most OpenSSL \fIdata structures\fR are not thread-safe. For example +the \fBBIO_write\fR\|(3) and \fBBIO_read\fR\|(3) functions are thread safe. However it +would not be thread safe to call \fBBIO_write()\fR from one thread while calling +\&\fBBIO_read()\fR in another where both functions are passed the same \fBBIO\fR object +since both of them may attempt to make changes to the same \fBBIO\fR object. +.PP +There are exceptions to these rules. A small number of functions are not thread +safe at all. Where this is the case this restriction should be noted in the +documentation for the function. Similarly some data structures may be partially +or fully thread safe. For example it is always safe to use an \fBOSSL_LIB_CTX\fR in +multiple threads. +.PP +See \fBopenssl\-threads\fR\|(7) for a more detailed discussion on OpenSSL threading +support. +.SH "ERROR HANDLING" +.IX Header "ERROR HANDLING" +Most OpenSSL functions will provide a return value indicating whether the +function has been successful or not. It is considered best practice to always +check the return value from OpenSSL functions (where one is available). +.PP +Most functions that return a pointer value will return NULL in the event of a +failure. +.PP +Most functions that return an integer value will return a positive integer for +success. Some of these functions will return 0 to indicate failure. Others may +return 0 or a negative value for failure. +.PP +Some functions cannot fail and have a \fBvoid\fR return type. There are also a +small number of functions that do not conform to the above conventions (e.g. +they may return 0 to indicate success). +.PP +Due to the above variations in behaviour it is important to check the +documentation for each function for information about how to interpret the +return value for it. +.PP +It is sometimes necessary to get further information about the cause of a +failure (e.g. for debugging or logging purposes). Many (but not all) functions +will add further information about a failure to the OpenSSL error stack. By +using the error stack you can find out information such as a reason code/string +for the error as well as the exact file and source line within OpenSSL that +emitted the error. +.PP +OpenSSL supplies a set of error handling functions to query the error stack. See +\&\fBERR_get_error\fR\|(3) for information about the functions available for querying +error data. Also see \fBERR_print_errors\fR\|(3) for information on some simple +helper functions for printing error data. Finally look at \fBERR_clear_error\fR\|(3) +for how to clear old errors from the error stack. +.SH "OPENSSL PROVIDERS" +.IX Header "OPENSSL PROVIDERS" +OpenSSL comes with a set of providers. +.PP +The algorithms available in each of these providers may vary due to build time +configuration options. The \fBopenssl\-list\fR\|(1) command can be used to list the +currently available algorithms. +.PP +The names of the algorithms shown from \fBopenssl\-list\fR\|(1) can be used as an +algorithm identifier to the appropriate fetching function. Also see the provider +specific manual pages linked below for further details about using the +algorithms available in each of the providers. +.PP +As well as the OpenSSL providers third parties can also implement providers. +For information on writing a provider see \fBprovider\fR\|(7). +.SS "Default provider" +.IX Subsection "Default provider" +The default provider is built-in as part of the \fIlibcrypto\fR library and +contains all of the most commonly used algorithm implementations. Should it be +needed (if other providers are loaded and offer implementations of the same +algorithms), the property query string "provider=default" can be used as a +search criterion for these implementations. The default provider includes all +of the functionality in the base provider below. +.PP +If you don't load any providers at all then the "default" provider will be +automatically loaded. If you explicitly load any provider then the "default" +provider would also need to be explicitly loaded if it is required. +.PP +See \fBOSSL_PROVIDER\-default\fR\|(7). +.SS "Base provider" +.IX Subsection "Base provider" +The base provider is built in as part of the \fIlibcrypto\fR library and contains +algorithm implementations for encoding and decoding of OpenSSL keys. +Should it be needed (if other providers are loaded and offer +implementations of the same algorithms), the property query string +"provider=base" can be used as a search criterion for these implementations. +Some encoding and decoding algorithm implementations are not FIPS algorithm +implementations in themselves but support algorithms from the FIPS provider and +are allowed for use in "FIPS mode". The property query string "fips=yes" can be +used to select such algorithms. +.PP +See \fBOSSL_PROVIDER\-base\fR\|(7). +.SS "FIPS provider" +.IX Subsection "FIPS provider" +The FIPS provider is a dynamically loadable module, and must therefore +be loaded explicitly, either in code or through OpenSSL configuration +(see \fBconfig\fR\|(5)). It contains algorithm implementations that have been +validated according to FIPS standards. Should it be needed (if other +providers are loaded and offer implementations of the same algorithms), the +property query string "provider=fips" can be used as a search criterion for +these implementations. All approved algorithm implementations in the FIPS +provider can also be selected with the property "fips=yes". The FIPS provider +may also contain non-approved algorithm implementations and these can be +selected with the property "fips=no". +.PP +Typically the "Base provider" will also need to be loaded because the FIPS +provider does not support the encoding or decoding of keys. +.PP +See \fBOSSL_PROVIDER\-FIPS\fR\|(7) and \fBfips_module\fR\|(7). +.SS "Legacy provider" +.IX Subsection "Legacy provider" +The legacy provider is a dynamically loadable module, and must therefore +be loaded explicitly, either in code or through OpenSSL configuration +(see \fBconfig\fR\|(5)). It contains algorithm implementations that are considered +insecure, or are no longer in common use such as MD2 or RC4. Should it be needed +(if other providers are loaded and offer implementations of the same algorithms), +the property "provider=legacy" can be used as a search criterion for these +implementations. +.PP +See \fBOSSL_PROVIDER\-legacy\fR\|(7). +.SS "Null provider" +.IX Subsection "Null provider" +The null provider is built in as part of the \fIlibcrypto\fR library. It contains +no algorithms in it at all. When fetching algorithms the default provider will +be automatically loaded if no other provider has been explicitly loaded. To +prevent that from happening you can explicitly load the null provider. +.PP +You can use this if you create your own library context and want to ensure that +all API calls have correctly passed the created library context and are not +accidentally using the default library context. Load the null provider into the +default library context so that the default library context has no algorithm +implementations available. +.PP +See \fBOSSL_PROVIDER\-null\fR\|(7). +.SH CONFIGURATION +.IX Header "CONFIGURATION" +By default OpenSSL will load a configuration file when it is first used. This +will set up various configuration settings within the default library context. +Applications that create their own library contexts may optionally configure +them with a config file using the \fBOSSL_LIB_CTX_load_config\fR\|(3) function. +.PP +The configuration file can be used to automatically load providers and set up +default property query strings. +.PP +For information on the OpenSSL configuration file format see \fBconfig\fR\|(5). +.SH "LIBRARY CONVENTIONS" +.IX Header "LIBRARY CONVENTIONS" +Many OpenSSL functions that "get" or "set" a value follow a naming convention +using the numbers \fB0\fR and \fB1\fR, i.e. "get0", "get1", "set0" and "set1". This +can also apply to some functions that "add" a value to an existing set, i.e. +"add0" and "add1". +.PP +For example the functions: +.PP +.Vb 2 +\& int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); +\& int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj); +.Ve +.PP +In the \fB0\fR version the ownership of the object is passed to (for an add or set) +or retained by (for a get) the parent object. For example after calling the +\&\fBX509_CRL_add0_revoked()\fR function above, ownership of the \fIrev\fR object is passed +to the \fIcrl\fR object. Therefore, after calling this function \fIrev\fR should not +be freed directly. It will be freed implicitly when \fIcrl\fR is freed. +.PP +In the \fB1\fR version the ownership of the object is not passed to or retained by +the parent object. Instead a copy or "up ref" of the object is performed. So +after calling the \fBX509_add1_trust_object()\fR function above the application will +still be responsible for freeing the \fIobj\fR value where appropriate. +.PP +Many OpenSSL functions conform to a naming convention of the form +\&\fBCLASSNAME_func_name()\fR. In this naming convention the \fBCLASSNAME\fR is the name +of an OpenSSL data structure (given in capital letters) that the function is +primarily operating on. The \fBfunc_name\fR portion of the name is usually in +lowercase letters and indicates the purpose of the function. +.SH "DEMO APPLICATIONS" +.IX Header "DEMO APPLICATIONS" +OpenSSL is distributed with a set of demo applications which provide some +examples of how to use the various API functions. To look at them download the +OpenSSL source code from the OpenSSL website +(<https://www.openssl.org/source/>). Extract the downloaded \fB.tar.gz\fR file for +the version of OpenSSL that you are using and look at the various files in the +\&\fBdemos\fR sub-directory. +.PP +The Makefiles in the subdirectories give instructions on how to build and run +the demo applications. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-libcrypto\-introduction\fR\|(7) for a more detailed introduction to +using \f(CW\*(C`libcrypto\*(C'\fR and \fBossl\-guide\-libssl\-introduction\fR\|(7) for more information +on \f(CW\*(C`libssl\*(C'\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\fR\|(1), \fBssl\fR\|(7), \fBevp\fR\|(7), \fBOSSL_LIB_CTX\fR\|(3), \fBopenssl\-threads\fR\|(7), +\&\fBproperty\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7), \fBOSSL_PROVIDER\-base\fR\|(7), +\&\fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-legacy\fR\|(7), \fBOSSL_PROVIDER\-null\fR\|(7), +\&\fBopenssl\-glossary\fR\|(7), \fBprovider\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/ossl-guide-libssl-introduction.7ssl b/upstream/debian-unstable/man7/ossl-guide-libssl-introduction.7ssl new file mode 100644 index 00000000..a63133a2 --- /dev/null +++ b/upstream/debian-unstable/man7/ossl-guide-libssl-introduction.7ssl @@ -0,0 +1,160 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-LIBSSL-INTRODUCTION 7SSL" +.TH OSSL-GUIDE-LIBSSL-INTRODUCTION 7SSL 2024-04-04 3.2.2-dev 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 +ossl\-guide\-libssl\-introduction, ssl +\&\- OpenSSL Guide: An introduction to libssl +.SH INTRODUCTION +.IX Header "INTRODUCTION" +The OpenSSL \f(CW\*(C`libssl\*(C'\fR library provides implementations of several secure network +communications protocols. Specifically it provides SSL/TLS (SSLv3, TLSv1, +TLSv1.1, TLSv1.2 and TLSv1.3), DTLS (DTLSv1 and DTLSv1.2) and QUIC (client side +only). The library depends on \f(CW\*(C`libcrypto\*(C'\fR for its underlying cryptographic +operations (see \fBossl\-guide\-libcrypto\-introduction\fR\|(7)). +.PP +The set of APIs supplied by \f(CW\*(C`libssl\*(C'\fR is common across all of these different +network protocols, so a developer familiar with writing applications using one +of these protocols should be able to transition to using another with relative +ease. +.PP +An application written to use \f(CW\*(C`libssl\*(C'\fR will include the \fI<openssl/ssl.h>\fR +header file and will typically use two main data structures, i.e. \fBSSL\fR and +\&\fBSSL_CTX\fR. +.PP +An \fBSSL\fR object is used to represent a connection to a remote peer. Once a +connection with a remote peer has been established data can be exchanged with +that peer. +.PP +When using DTLS any data that is exchanged uses "datagram" semantics, i.e. +the packets of data can be delivered in any order, and they are not guaranteed +to arrive at all. In this case the \fBSSL\fR object used for the connection is also +used for exchanging data with the peer. +.PP +Both TLS and QUIC support the concept of a "stream" of data. Data sent via a +stream is guaranteed to be delivered in order without any data loss. A stream +can be uni\- or bi-directional. +.PP +SSL/TLS only supports one stream of data per connection and it is always +bi-directional. In this case the \fBSSL\fR object used for the connection also +represents that stream. See \fBossl\-guide\-tls\-introduction\fR\|(7) for more +information. +.PP +The QUIC protocol can support multiple streams per connection and they can be +uni\- or bi-directional. In this case an \fBSSL\fR object can represent the +underlying connection, or a stream, or both. Where multiple streams are in use +a separate \fBSSL\fR object is used for each one. See +\&\fBossl\-guide\-quic\-introduction\fR\|(7) for more information. +.PP +An \fBSSL_CTX\fR object is used to create the \fBSSL\fR object for the underlying +connection. A single \fBSSL_CTX\fR object can be used to create many connections +(each represented by a separate \fBSSL\fR object). Many API functions in libssl +exist in two forms: one that takes an \fBSSL_CTX\fR and one that takes an \fBSSL\fR. +Typically settings that you apply to the \fBSSL_CTX\fR will then be inherited by +any \fBSSL\fR object that you create from it. Alternatively you can apply settings +directly to the \fBSSL\fR object without affecting other \fBSSL\fR objects. Note that +you should not normally make changes to an \fBSSL_CTX\fR after the first \fBSSL\fR +object has been created from it. +.SH "DATA STRUCTURES" +.IX Header "DATA STRUCTURES" +As well as \fBSSL_CTX\fR and \fBSSL\fR there are a number of other data structures +that an application may need to use. They are summarised below. +.IP "\fBSSL_METHOD\fR (SSL Method)" 4 +.IX Item "SSL_METHOD (SSL Method)" +This structure is used to indicate the kind of connection you want to make, e.g. +whether it is to represent the client or the server, and whether it is to use +SSL/TLS, DTLS or QUIC (client only). It is passed as a parameter when creating +the \fBSSL_CTX\fR. +.IP "\fBSSL_SESSION\fR (SSL Session)" 4 +.IX Item "SSL_SESSION (SSL Session)" +After establishing a connection with a peer the agreed cryptographic material +can be reused to create future connections with the same peer more rapidly. The +set of data used for such a future connection establishment attempt is collected +together into an \fBSSL_SESSION\fR object. A single successful connection with a +peer may generate zero or more such \fBSSL_SESSION\fR objects for use in future +connection attempts. +.IP "\fBSSL_CIPHER\fR (SSL Cipher)" 4 +.IX Item "SSL_CIPHER (SSL Cipher)" +During connection establishment the client and server agree upon cryptographic +algorithms they are going to use for encryption and other uses. A single set +of cryptographic algorithms that are to be used together is known as a +ciphersuite. Such a set is represented by an \fBSSL_CIPHER\fR object. +.Sp +The set of available ciphersuites that can be used are configured in the +\&\fBSSL_CTX\fR or \fBSSL\fR. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-tls\-introduction\fR\|(7) for an introduction to the SSL/TLS +protocol and \fBossl\-guide\-quic\-introduction\fR\|(7) for an introduction to QUIC. +.PP +See \fBossl\-guide\-libcrypto\-introduction\fR\|(7) for an introduction to \f(CW\*(C`libcrypto\*(C'\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-libcrypto\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7), +\&\fBossl\-guide\-quic\-introduction\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/migration_guide.7ssl b/upstream/debian-unstable/man7/ossl-guide-migration.7ssl index b0080182..3b94512e 100644 --- a/upstream/debian-unstable/man7/migration_guide.7ssl +++ b/upstream/debian-unstable/man7/ossl-guide-migration.7ssl @@ -54,14 +54,15 @@ .rr rF .\" ======================================================================== .\" -.IX Title "MIGRATION_GUIDE 7SSL" -.TH MIGRATION_GUIDE 7SSL 2024-02-03 3.1.5 OpenSSL +.IX Title "OSSL-GUIDE-MIGRATION 7SSL" +.TH OSSL-GUIDE-MIGRATION 7SSL 2024-04-04 3.2.2-dev 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 -migration_guide \- OpenSSL migration guide +ossl\-guide\-migration, migration_guide +\&\- OpenSSL Guide: Migrating from older OpenSSL versions .SH SYNOPSIS .IX Header "SYNOPSIS" See the individual manual pages for details. @@ -216,6 +217,14 @@ To ensure the future compatibility, the engines should be turned to providers. To prefer the provider-based hardware offload, you can specify the default properties to prefer your provider. .PP +Setting engine-based or application-based default low-level crypto method such +as \fBRSA_METHOD\fR or \fBEC_KEY_METHOD\fR is still possible and keys inside the +default provider will use the engine-based implementation for the crypto +operations. However \fBEVP_PKEY\fRs created by decoding by using \fBOSSL_DECODER\fR, +\&\fBPEM_\fR or \fBd2i_\fR APIs will be provider-based. To create a fully legacy +\&\fBEVP_PKEY\fRs \fBEVP_PKEY_set1_RSA\fR\|(3), \fBEVP_PKEY_set1_EC_KEY\fR\|(3) or similar +functions must be used. +.PP \fIVersioning Scheme\fR .IX Subsection "Versioning Scheme" .PP diff --git a/upstream/debian-unstable/man7/ossl-guide-quic-client-block.7ssl b/upstream/debian-unstable/man7/ossl-guide-quic-client-block.7ssl new file mode 100644 index 00000000..73ef8d9b --- /dev/null +++ b/upstream/debian-unstable/man7/ossl-guide-quic-client-block.7ssl @@ -0,0 +1,436 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-QUIC-CLIENT-BLOCK 7SSL" +.TH OSSL-GUIDE-QUIC-CLIENT-BLOCK 7SSL 2024-04-04 3.2.2-dev 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 +ossl\-guide\-quic\-client\-block +\&\- OpenSSL Guide: Writing a simple blocking QUIC client +.SH "SIMPLE BLOCKING QUIC CLIENT EXAMPLE" +.IX Header "SIMPLE BLOCKING QUIC CLIENT EXAMPLE" +This page will present various source code samples demonstrating how to write +a simple blocking QUIC client application which connects to a server, sends an +HTTP/1.0 request to it, and reads back the response. Note that HTTP/1.0 over +QUIC is non-standard and will not be supported by real world servers. This is +for demonstration purposes only. +.PP +We assume that you already have OpenSSL installed on your system; that you +already have some fundamental understanding of OpenSSL concepts, TLS and QUIC +(see \fBossl\-guide\-libraries\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7) +and \fBossl\-guide\-quic\-introduction\fR\|(7)); and that you know how to +write and build C code and link it against the libcrypto and libssl libraries +that are provided by OpenSSL. It also assumes that you have a basic +understanding of UDP/IP and sockets. The example code that we build in this +tutorial will amend the blocking TLS client example that is covered in +\&\fBossl\-guide\-tls\-client\-block\fR\|(7). Only the differences between that client and +this one will be discussed so we also assume that you have run through and +understand that tutorial. +.PP +For this tutorial our client will be using a single QUIC stream. A subsequent +tutorial will discuss how to write a multi-stream client (see +\&\fBossl\-guide\-quic\-multi\-stream\fR\|(7)). +.PP +The complete source code for this example blocking QUIC client is available in +the \f(CW\*(C`demos/guide\*(C'\fR directory of the OpenSSL source distribution in the file +\&\f(CW\*(C`quic\-client\-block.c\*(C'\fR. It is also available online at +<https://github.com/openssl/openssl/blob/master/demos/guide/quic\-client\-block.c>. +.SS "Creating the SSL_CTX and SSL objects" +.IX Subsection "Creating the SSL_CTX and SSL objects" +In the TLS tutorial (\fBossl\-guide\-tls\-client\-block\fR\|(7)) we created an \fBSSL_CTX\fR +object for our client and used it to create an \fBSSL\fR object to represent the +TLS connection. A QUIC connection works in exactly the same way. We first create +an \fBSSL_CTX\fR object and then use it to create an \fBSSL\fR object to represent the +QUIC connection. +.PP +As in the TLS example the first step is to create an \fBSSL_CTX\fR object for our +client. This is done in the same way as before except that we use a different +"method". OpenSSL offers two different QUIC client methods, i.e. +\&\fBOSSL_QUIC_client_method\fR\|(3) and \fBOSSL_QUIC_client_thread_method\fR\|(3). +.PP +The first one is the equivalent of \fBTLS_client_method\fR\|(3) but for the QUIC +protocol. The second one is the same, but it will additionally create a +background thread for handling time based events (known as "thread assisted +mode", see \fBossl\-guide\-quic\-introduction\fR\|(7)). For this tutorial we will be +using \fBOSSL_QUIC_client_method\fR\|(3) because we will not be leaving the QUIC +connection idle in our application and so thread assisted mode is not needed. +.PP +.Vb 10 +\& /* +\& * Create an SSL_CTX which we can use to create SSL objects from. We +\& * want an SSL_CTX for creating clients so we use OSSL_QUIC_client_method() +\& * here. +\& */ +\& ctx = SSL_CTX_new(OSSL_QUIC_client_method()); +\& if (ctx == NULL) { +\& printf("Failed to create the SSL_CTX\en"); +\& goto end; +\& } +.Ve +.PP +The other setup steps that we applied to the \fBSSL_CTX\fR for TLS also apply to +QUIC except for restricting the TLS versions that we are willing to accept. The +QUIC protocol implementation in OpenSSL currently only supports TLSv1.3. There +is no need to call \fBSSL_CTX_set_min_proto_version\fR\|(3) or +\&\fBSSL_CTX_set_max_proto_version\fR\|(3) in an OpenSSL QUIC application, and any such +call will be ignored. +.PP +Once the \fBSSL_CTX\fR is created, the \fBSSL\fR object is constructed in exactly the +same way as for the TLS application. +.SS "Creating the socket and BIO" +.IX Subsection "Creating the socket and BIO" +A major difference between TLS and QUIC is the underlying transport protocol. +TLS uses TCP while QUIC uses UDP. The way that the QUIC socket is created in our +example code is much the same as for TLS. We use the \fBBIO_lookup_ex\fR\|(3) and +\&\fBBIO_socket\fR\|(3) helper functions as we did in the previous tutorial except that +we pass \fBSOCK_DGRAM\fR as an argument to indicate UDP (instead of \fBSOCK_STREAM\fR +for TCP). +.PP +.Vb 6 +\& /* +\& * Lookup IP address info for the server. +\& */ +\& if (!BIO_lookup_ex(hostname, port, BIO_LOOKUP_CLIENT, family, SOCK_DGRAM, 0, +\& &res)) +\& return NULL; +\& +\& /* +\& * Loop through all the possible addresses for the server and find one +\& * we can connect to. +\& */ +\& for (ai = res; ai != NULL; ai = BIO_ADDRINFO_next(ai)) { +\& /* +\& * Create a TCP socket. We could equally use non\-OpenSSL calls such +\& * as "socket" here for this and the subsequent connect and close +\& * functions. But for portability reasons and also so that we get +\& * errors on the OpenSSL stack in the event of a failure we use +\& * OpenSSL\*(Aqs versions of these functions. +\& */ +\& sock = BIO_socket(BIO_ADDRINFO_family(ai), SOCK_DGRAM, 0, 0); +\& if (sock == \-1) +\& continue; +\& +\& /* Connect the socket to the server\*(Aqs address */ +\& if (!BIO_connect(sock, BIO_ADDRINFO_address(ai), 0)) { +\& BIO_closesocket(sock); +\& sock = \-1; +\& continue; +\& } +\& +\& /* Set to nonblocking mode */ +\& if (!BIO_socket_nbio(sock, 1)) { +\& BIO_closesocket(sock); +\& sock = \-1; +\& continue; +\& } +\& +\& break; +\& } +\& +\& if (sock != \-1) { +\& *peer_addr = BIO_ADDR_dup(BIO_ADDRINFO_address(ai)); +\& if (*peer_addr == NULL) { +\& BIO_closesocket(sock); +\& return NULL; +\& } +\& } +\& +\& /* Free the address information resources we allocated earlier */ +\& BIO_ADDRINFO_free(res); +.Ve +.PP +You may notice a couple of other differences between this code and the version +that we used for TLS. +.PP +Firstly, we set the socket into nonblocking mode. This must always be done for +an OpenSSL QUIC application. This may be surprising considering that we are +trying to write a blocking client. Despite this the \fBSSL\fR object will still +have blocking behaviour. See \fBossl\-guide\-quic\-introduction\fR\|(7) for further +information on this. +.PP +Secondly, we take note of the IP address of the peer that we are connecting to. +We store that information away. We will need it later. +.PP +See \fBBIO_lookup_ex\fR\|(3), \fBBIO_socket\fR\|(3), \fBBIO_connect\fR\|(3), +\&\fBBIO_closesocket\fR\|(3), \fBBIO_ADDRINFO_next\fR\|(3), \fBBIO_ADDRINFO_address\fR\|(3), +\&\fBBIO_ADDRINFO_free\fR\|(3) and \fBBIO_ADDR_dup\fR\|(3) for further information on the +functions used here. In the above example code the \fBhostname\fR and \fBport\fR +variables are strings, e.g. "www.example.com" and "443". +.PP +As for our TLS client, once the socket has been created and connected we need to +associate it with a BIO object: +.PP +.Vb 1 +\& BIO *bio; +\& +\& /* Create a BIO to wrap the socket */ +\& bio = BIO_new(BIO_s_datagram()); +\& if (bio == NULL) { +\& BIO_closesocket(sock); +\& return NULL; +\& } +\& +\& /* +\& * Associate the newly created BIO with the underlying socket. By +\& * passing BIO_CLOSE here the socket will be automatically closed when +\& * the BIO is freed. Alternatively you can use BIO_NOCLOSE, in which +\& * case you must close the socket explicitly when it is no longer +\& * needed. +\& */ +\& BIO_set_fd(bio, sock, BIO_CLOSE); +.Ve +.PP +Note the use of \fBBIO_s_datagram\fR\|(3) here as opposed to \fBBIO_s_socket\fR\|(3) that +we used for our TLS client. This is again due to the fact that QUIC uses UDP +instead of TCP for its transport layer. See \fBBIO_new\fR\|(3), \fBBIO_s_datagram\fR\|(3) +and \fBBIO_set_fd\fR\|(3) for further information on these functions. +.SS "Setting the server's hostname" +.IX Subsection "Setting the server's hostname" +As in the TLS tutorial we need to set the server's hostname both for SNI (Server +Name Indication) and for certificate validation purposes. The steps for this are +identical to the TLS tutorial and won't be repeated here. +.SS "Setting the ALPN" +.IX Subsection "Setting the ALPN" +ALPN (Application-Layer Protocol Negotiation) is a feature of TLS that enables +the application to negotiate which protocol will be used over the connection. +For example, if you intend to use HTTP/3 over the connection then the ALPN value +for that is "h3" (see +<https://www.iana.org/assignments/tls\-extensiontype\-values/tls\-extensiontype\-values.xml#alpn\-protocol\-ids>). +OpenSSL provides the ability for a client to specify the ALPN to use via the +\&\fBSSL_set_alpn_protos\fR\|(3) function. This is optional for a TLS client and so our +simple client that we developed in \fBossl\-guide\-tls\-client\-block\fR\|(7) did not use +it. However QUIC mandates that the TLS handshake used in establishing a QUIC +connection must use ALPN. +.PP +.Vb 1 +\& unsigned char alpn[] = { 8, \*(Aqh\*(Aq, \*(Aqt\*(Aq, \*(Aqt\*(Aq, \*(Aqp\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq, \*(Aq.\*(Aq, \*(Aq0\*(Aq }; +\& +\& /* SSL_set_alpn_protos returns 0 for success! */ +\& if (SSL_set_alpn_protos(ssl, alpn, sizeof(alpn)) != 0) { +\& printf("Failed to set the ALPN for the connection\en"); +\& goto end; +\& } +.Ve +.PP +The ALPN is specified using a length prefixed array of unsigned chars (it is not +a NUL terminated string). Our original TLS blocking client demo was using +HTTP/1.0. We will use the same for this example. Unlike most OpenSSL functions +\&\fBSSL_set_alpn_protos\fR\|(3) returns zero for success and nonzero for failure. +.SS "Setting the peer address" +.IX Subsection "Setting the peer address" +An OpenSSL QUIC application must specify the target address of the server that +is being connected to. In "Creating the socket and BIO" above we saved that +address away for future use. Now we need to use it via the +\&\fBSSL_set1_initial_peer_addr\fR\|(3) function. +.PP +.Vb 5 +\& /* Set the IP address of the remote peer */ +\& if (!SSL_set1_initial_peer_addr(ssl, peer_addr)) { +\& printf("Failed to set the initial peer address\en"); +\& goto end; +\& } +.Ve +.PP +Note that we will need to free the \fBpeer_addr\fR value that we allocated via +\&\fBBIO_ADDR_dup\fR\|(3) earlier: +.PP +.Vb 1 +\& BIO_ADDR_free(peer_addr); +.Ve +.SS "The handshake and application data transfer" +.IX Subsection "The handshake and application data transfer" +Once initial setup of the \fBSSL\fR object is complete then we perform the +handshake via \fBSSL_connect\fR\|(3) in exactly the same way as we did for the TLS +client, so we won't repeat it here. +.PP +We can also perform data transfer using a default QUIC stream that is +automatically associated with the \fBSSL\fR object for us. We can transmit data +using \fBSSL_write_ex\fR\|(3), and receive data using \fBSSL_read_ex\fR\|(3) in the same +way as for TLS. The main difference is that we have to account for failures +slightly differently. With QUIC the stream can be reset by the peer (which is +fatal for that stream), but the underlying connection itself may still be +healthy. +.PP +.Vb 10 +\& /* +\& * Get up to sizeof(buf) bytes of the response. We keep reading until the +\& * server closes the connection. +\& */ +\& while (SSL_read_ex(ssl, buf, sizeof(buf), &readbytes)) { +\& /* +\& * OpenSSL does not guarantee that the returned data is a string or +\& * that it is NUL terminated so we use fwrite() to write the exact +\& * number of bytes that we read. The data could be non\-printable or +\& * have NUL characters in the middle of it. For this simple example +\& * we\*(Aqre going to print it to stdout anyway. +\& */ +\& fwrite(buf, 1, readbytes, stdout); +\& } +\& /* In case the response didn\*(Aqt finish with a newline we add one now */ +\& printf("\en"); +\& +\& /* +\& * Check whether we finished the while loop above normally or as the +\& * result of an error. The 0 argument to SSL_get_error() is the return +\& * code we received from the SSL_read_ex() call. It must be 0 in order +\& * to get here. Normal completion is indicated by SSL_ERROR_ZERO_RETURN. In +\& * QUIC terms this means that the peer has sent FIN on the stream to +\& * indicate that no further data will be sent. +\& */ +\& switch (SSL_get_error(ssl, 0)) { +\& case SSL_ERROR_ZERO_RETURN: +\& /* Normal completion of the stream */ +\& break; +\& +\& case SSL_ERROR_SSL: +\& /* +\& * Some stream fatal error occurred. This could be because of a stream +\& * reset \- or some failure occurred on the underlying connection. +\& */ +\& switch (SSL_get_stream_read_state(ssl)) { +\& case SSL_STREAM_STATE_RESET_REMOTE: +\& printf("Stream reset occurred\en"); +\& /* The stream has been reset but the connection is still healthy. */ +\& break; +\& +\& case SSL_STREAM_STATE_CONN_CLOSED: +\& printf("Connection closed\en"); +\& /* Connection is already closed. Skip SSL_shutdown() */ +\& goto end; +\& +\& default: +\& printf("Unknown stream failure\en"); +\& break; +\& } +\& break; +\& +\& default: +\& /* Some other unexpected error occurred */ +\& printf ("Failed reading remaining data\en"); +\& break; +\& } +.Ve +.PP +In the above code example you can see that \fBSSL_ERROR_SSL\fR indicates a stream +fatal error. We can use \fBSSL_get_stream_read_state\fR\|(3) to determine whether the +stream has been reset, or if some other fatal error has occurred. +.SS "Shutting down the connection" +.IX Subsection "Shutting down the connection" +In the TLS tutorial we knew that the server had finished sending data because +\&\fBSSL_read_ex\fR\|(3) returned 0, and \fBSSL_get_error\fR\|(3) returned +\&\fBSSL_ERROR_ZERO_RETURN\fR. The same is true with QUIC except that +\&\fBSSL_ERROR_ZERO_RETURN\fR should be interpreted slightly differently. With TLS +we knew that this meant that the server had sent a "close_notify" alert. No +more data will be sent from the server on that connection. +.PP +With QUIC it means that the server has indicated "FIN" on the stream, meaning +that it will no longer send any more data on that stream. However this only +gives us information about the stream itself and does not tell us anything about +the underlying connection. More data could still be sent from the server on some +other stream. Additionally, although the server will not send any more data to +the client, it does not prevent the client from sending more data to the server. +.PP +In this tutorial, once we have finished reading data from the server on the one +stream that we are using, we will close the connection down. As before we do +this via the \fBSSL_shutdown\fR\|(3) function. This example for QUIC is very similar +to the TLS version. However the \fBSSL_shutdown\fR\|(3) function will need to be +called more than once: +.PP +.Vb 11 +\& /* +\& * Repeatedly call SSL_shutdown() until the connection is fully +\& * closed. +\& */ +\& do { +\& ret = SSL_shutdown(ssl); +\& if (ret < 0) { +\& printf("Error shutting down: %d\en", ret); +\& goto end; +\& } +\& } while (ret != 1); +.Ve +.PP +The shutdown process is in two stages. In the first stage we wait until all the +data we have buffered for sending on any stream has been successfully sent and +acknowledged by the peer, and then we send a CONNECTION_CLOSE to the peer to +indicate that the connection is no longer usable. This immediately closes the +connection and no more data can be sent or received. \fBSSL_shutdown\fR\|(3) returns +0 once the first stage has been completed. +.PP +In the second stage the connection enters a "closing" state. Application data +cannot be sent or received in this state, but late arriving packets coming from +the peer will be handled appropriately. Once this stage has completed +successfully \fBSSL_shutdown\fR\|(3) will return 1 to indicate success. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-quic\-multi\-stream\fR\|(7) to read a tutorial on how to modify the +client developed on this page to support multiple streams. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7), +\&\fBossl\-guide\-tls\-client\-block\fR\|(7), \fBossl\-guide\-quic\-introduction\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/ossl-guide-quic-client-non-block.7ssl b/upstream/debian-unstable/man7/ossl-guide-quic-client-non-block.7ssl new file mode 100644 index 00000000..8428c83c --- /dev/null +++ b/upstream/debian-unstable/man7/ossl-guide-quic-client-non-block.7ssl @@ -0,0 +1,521 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-QUIC-CLIENT-NON-BLOCK 7SSL" +.TH OSSL-GUIDE-QUIC-CLIENT-NON-BLOCK 7SSL 2024-04-04 3.2.2-dev 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 +ossl\-guide\-quic\-client\-non\-block +\&\- OpenSSL Guide: Writing a simple nonblocking QUIC client +.SH "SIMPLE NONBLOCKING QUIC CLIENT EXAMPLE" +.IX Header "SIMPLE NONBLOCKING QUIC CLIENT EXAMPLE" +This page will build on the example developed on the +\&\fBossl\-guide\-quic\-client\-block\fR\|(7) page which demonstrates how to write a simple +blocking QUIC client. On this page we will amend that demo code so that it +supports nonblocking functionality. +.PP +The complete source code for this example nonblocking QUIC client is available +in the \fBdemos/guide\fR directory of the OpenSSL source distribution in the file +\&\fBquic\-client\-non\-block.c\fR. It is also available online at +<https://github.com/openssl/openssl/blob/master/demos/guide/quic\-client\-non\-block.c>. +.PP +As we saw in the previous example an OpenSSL QUIC application always uses a +nonblocking socket. However, despite this, the \fBSSL\fR object still has blocking +behaviour. When the \fBSSL\fR object has blocking behaviour then this means that +it waits (blocks) until data is available to read if you attempt to read from +it when there is no data yet. Similarly it waits when writing if the \fBSSL\fR +object is currently unable to write at the moment. This can simplify the +development of code because you do not have to worry about what to do in these +cases. The execution of the code will simply stop until it is able to continue. +However in many cases you do not want this behaviour. Rather than stopping and +waiting your application may need to go and do other tasks whilst the \fBSSL\fR +object is unable to read/write, for example updating a GUI or performing +operations on some other connection or stream. +.PP +We will see later in this tutorial how to change the \fBSSL\fR object so that it +has nonblocking behaviour. With a nonblocking \fBSSL\fR object, functions such as +\&\fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(3) will return immediately with a non-fatal +error if they are currently unable to read or write respectively. +.PP +Since this page is building on the example developed on the +\&\fBossl\-guide\-quic\-client\-block\fR\|(7) page we assume that you are familiar with it +and we only explain how this example differs. +.SS "Performing work while waiting for the socket" +.IX Subsection "Performing work while waiting for the socket" +In a nonblocking application you will need work to perform in the event that +we want to read or write to the \fBSSL\fR object but we are currently unable to. +In fact this is the whole point of using a nonblocking \fBSSL\fR object, i.e. to +give the application the opportunity to do something else. Whatever it is that +the application has to do, it must also be prepared to come back and retry the +operation that it previously attempted periodically to see if it can now +complete. Ideally it would only do this in the event that something has changed +such that it might succeed on the retry attempt, but this does not have to be +the case. It can retry at any time. +.PP +Note that it is important that you retry exactly the same operation that you +tried last time. You cannot start something new. For example if you were +attempting to write the text "Hello World" and the operation failed because the +\&\fBSSL\fR object is currently unable to write, then you cannot then attempt to +write some other text when you retry the operation. +.PP +In this demo application we will create a helper function which simulates doing +other work. In fact, for the sake of simplicity, it will do nothing except wait +for the state of the underlying socket to change or until a timeout expires +after which the state of the \fBSSL\fR object might have changed. We will call our +function \f(CWwait_for_activity()\fR. +.PP +.Vb 6 +\& static void wait_for_activity(SSL *ssl) +\& { +\& fd_set wfds, rfds; +\& int width, sock, isinfinite; +\& struct timeval tv; +\& struct timeval *tvp = NULL; +\& +\& /* Get hold of the underlying file descriptor for the socket */ +\& sock = SSL_get_fd(ssl); +\& +\& FD_ZERO(&wfds); +\& FD_ZERO(&rfds); +\& +\& /* +\& * Find out if we would like to write to the socket, or read from it (or +\& * both) +\& */ +\& if (SSL_net_write_desired(ssl)) +\& FD_SET(sock, &wfds); +\& if (SSL_net_read_desired(ssl)) +\& FD_SET(sock, &rfds); +\& width = sock + 1; +\& +\& /* +\& * Find out when OpenSSL would next like to be called, regardless of +\& * whether the state of the underlying socket has changed or not. +\& */ +\& if (SSL_get_event_timeout(ssl, &tv, &isinfinite) && !isinfinite) +\& tvp = &tv; +\& +\& /* +\& * Wait until the socket is writeable or readable. We use select here +\& * for the sake of simplicity and portability, but you could equally use +\& * poll/epoll or similar functions +\& * +\& * NOTE: For the purposes of this demonstration code this effectively +\& * makes this demo block until it has something more useful to do. In a +\& * real application you probably want to go and do other work here (e.g. +\& * update a GUI, or service other connections). +\& * +\& * Let\*(Aqs say for example that you want to update the progress counter on +\& * a GUI every 100ms. One way to do that would be to use the timeout in +\& * the last parameter to "select" below. If the tvp value is greater +\& * than 100ms then use 100ms instead. Then, when select returns, you +\& * check if it did so because of activity on the file descriptors or +\& * because of the timeout. If the 100ms GUI timeout has expired but the +\& * tvp timeout has not then go and update the GUI and then restart the +\& * "select" (with updated timeouts). +\& */ +\& +\& select(width, &rfds, &wfds, NULL, tvp); +\&} +.Ve +.PP +If you are familiar with how to write nonblocking applications in OpenSSL for +TLS (see \fBossl\-guide\-tls\-client\-non\-block\fR\|(7)) then you should note that there +is an important difference here between the way a QUIC application and a TLS +application works. With a TLS application if we try to read or write something +to the \fBSSL\fR object and we get a "retry" response (\fBSSL_ERROR_WANT_READ\fR or +\&\fBSSL_ERROR_WANT_WRITE\fR) then we can assume that is because OpenSSL attempted to +read or write to the underlying socket and the socket signalled the "retry". +With QUIC that is not the case. OpenSSL may signal retry as a result of an +\&\fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(3) (or similar) call which indicates the +state of the stream. This is entirely independent of whether the underlying +socket needs to retry or not. +.PP +To determine whether OpenSSL currently wants to read or write to the underlying +socket for a QUIC application we must call the \fBSSL_net_read_desired\fR\|(3) and +\&\fBSSL_net_write_desired\fR\|(3) functions. +.PP +It is also important with QUIC that we periodically call an I/O function (or +otherwise call the \fBSSL_handle_events\fR\|(3) function) to ensure that the QUIC +connection remains healthy. This is particularly important with a nonblocking +application because you are likely to leave the \fBSSL\fR object idle for a while +while the application goes off to do other work. The \fBSSL_get_event_timeout\fR\|(3) +function can be used to determine what the deadline is for the next time we need +to call an I/O function (or call \fBSSL_handle_events\fR\|(3)). +.PP +An alternative to using \fBSSL_get_event_timeout\fR\|(3) to find the next deadline +that OpenSSL must be called again by is to use "thread assisted" mode. In +"thread assisted" mode OpenSSL spawns an additional thread which will +periodically call \fBSSL_handle_events\fR\|(3) automatically, meaning that the +application can leave the connection idle safe in the knowledge that the +connection will still be maintained in a healthy state. See +"Creating the SSL_CTX and SSL objects" below for further details about this. +.PP +In this example we are using the \f(CW\*(C`select\*(C'\fR function to check the +readability/writeability of the socket because it is very simple to use and is +available on most Operating Systems. However you could use any other similar +function to do the same thing. \f(CW\*(C`select\*(C'\fR waits for the state of the underlying +socket(s) to become readable/writeable or until the timeout has expired before +returning. +.SS "Handling errors from OpenSSL I/O functions" +.IX Subsection "Handling errors from OpenSSL I/O functions" +A QUIC application that has been configured for nonblocking behaviour will need +to be prepared to handle errors returned from OpenSSL I/O functions such as +\&\fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(3). Errors may be fatal for the stream (for +example because the stream has been reset or because the underlying connection +has failed), or non-fatal (for example because we are trying to read from the +stream but no data has not yet arrived from the peer for that stream). +.PP +\&\fBSSL_read_ex\fR\|(3) and \fBSSL_write_ex\fR\|(3) will return 0 to indicate an error and +\&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) will return 0 or a negative value to indicate +an error. \fBSSL_shutdown\fR\|(3) will return a negative value to incidate an error. +.PP +In the event of an error an application should call \fBSSL_get_error\fR\|(3) to find +out what type of error has occurred. If the error is non-fatal and can be +retried then \fBSSL_get_error\fR\|(3) will return \fBSSL_ERROR_WANT_READ\fR or +\&\fBSSL_ERROR_WANT_WRITE\fR depending on whether OpenSSL wanted to read to or write +from the stream but was unable to. Note that a call to \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_read\fR\|(3) can still generate \fBSSL_ERROR_WANT_WRITE\fR. Similarly calls to +\&\fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) might generate \fBSSL_ERROR_WANT_READ\fR. +.PP +Another type of non-fatal error that may occur is \fBSSL_ERROR_ZERO_RETURN\fR. This +indicates an EOF (End-Of-File) which can occur if you attempt to read data from +an \fBSSL\fR object but the peer has indicated that it will not send any more data +on the stream. In this case you may still want to write data to the stream but +you will not receive any more data. +.PP +Fatal errors that may occur are \fBSSL_ERROR_SYSCALL\fR and \fBSSL_ERROR_SSL\fR. These +indicate that the stream is no longer usable. For example, this could be because +the stream has been reset by the peer, or because the underlying connection has +failed. You can consult the OpenSSL error stack for further details (for example +by calling \fBERR_print_errors\fR\|(3) to print out details of errors that have +occurred). You can also consult the return value of +\&\fBSSL_get_stream_read_state\fR\|(3) to determine whether the error is local to the +stream, or whether the underlying connection has also failed. A return value +of \fBSSL_STREAM_STATE_RESET_REMOTE\fR tells you that the stream has been reset by +the peer and \fBSSL_STREAM_STATE_CONN_CLOSED\fR tells you that the underlying +connection has closed. +.PP +In our demo application we will write a function to handle these errors from +OpenSSL I/O functions: +.PP +.Vb 8 +\& static int handle_io_failure(SSL *ssl, int res) +\& { +\& switch (SSL_get_error(ssl, res)) { +\& case SSL_ERROR_WANT_READ: +\& case SSL_ERROR_WANT_WRITE: +\& /* Temporary failure. Wait until we can read/write and try again */ +\& wait_for_activity(ssl); +\& return 1; +\& +\& case SSL_ERROR_ZERO_RETURN: +\& /* EOF */ +\& return 0; +\& +\& case SSL_ERROR_SYSCALL: +\& return \-1; +\& +\& case SSL_ERROR_SSL: +\& /* +\& * Some stream fatal error occurred. This could be because of a +\& * stream reset \- or some failure occurred on the underlying +\& * connection. +\& */ +\& switch (SSL_get_stream_read_state(ssl)) { +\& case SSL_STREAM_STATE_RESET_REMOTE: +\& printf("Stream reset occurred\en"); +\& /* +\& * The stream has been reset but the connection is still +\& * healthy. +\& */ +\& break; +\& +\& case SSL_STREAM_STATE_CONN_CLOSED: +\& printf("Connection closed\en"); +\& /* Connection is already closed. */ +\& break; +\& +\& default: +\& printf("Unknown stream failure\en"); +\& break; +\& } +\& /* +\& * If the failure is due to a verification error we can get more +\& * information about it from SSL_get_verify_result(). +\& */ +\& if (SSL_get_verify_result(ssl) != X509_V_OK) +\& printf("Verify error: %s\en", +\& X509_verify_cert_error_string(SSL_get_verify_result(ssl))); +\& return \-1; +\& +\& default: +\& return \-1; +\& } +\& } +.Ve +.PP +This function takes as arguments the \fBSSL\fR object that represents the +connection, as well as the return code from the I/O function that failed. In +the event of a non-fatal failure, it waits until a retry of the I/O operation +might succeed (by using the \f(CWwait_for_activity()\fR function that we developed +in the previous section). It returns 1 in the event of a non-fatal error +(except EOF), 0 in the event of EOF, or \-1 if a fatal error occurred. +.SS "Creating the SSL_CTX and SSL objects" +.IX Subsection "Creating the SSL_CTX and SSL objects" +In order to connect to a server we must create \fBSSL_CTX\fR and \fBSSL\fR objects for +this. Most of the steps to do this are the same as for a blocking client and are +explained on the \fBossl\-guide\-quic\-client\-block\fR\|(7) page. We won't repeat that +information here. +.PP +One key difference is that we must put the \fBSSL\fR object into nonblocking mode +(the default is blocking mode). To do that we use the +\&\fBSSL_set_blocking_mode\fR\|(3) function: +.PP +.Vb 9 +\& /* +\& * The underlying socket is always nonblocking with QUIC, but the default +\& * behaviour of the SSL object is still to block. We set it for nonblocking +\& * mode in this demo. +\& */ +\& if (!SSL_set_blocking_mode(ssl, 0)) { +\& printf("Failed to turn off blocking mode\en"); +\& goto end; +\& } +.Ve +.PP +Although the demo application that we are developing here does not use it, it is +possible to use "thread assisted mode" when developing QUIC applications. +Normally, when writing an OpenSSL QUIC application, it is important that +\&\fBSSL_handle_events\fR\|(3) (or alternatively any I/O function) is called on the +connection \fBSSL\fR object periodically to maintain the connection in a healthy +state. See "Performing work while waiting for the socket" for more discussion +on this. This is particularly important to keep in mind when writing a +nonblocking QUIC application because it is common to leave the \fBSSL\fR connection +object idle for some time when using nonblocking mode. By using "thread assisted +mode" a separate thread is created by OpenSSL to do this automatically which +means that the application developer does not need to handle this aspect. To do +this we must use \fBOSSL_QUIC_client_thread_method\fR\|(3) when we construct the +\&\fBSSL_CTX\fR as shown below: +.PP +.Vb 5 +\& ctx = SSL_CTX_new(OSSL_QUIC_client_thread_method()); +\& if (ctx == NULL) { +\& printf("Failed to create the SSL_CTX\en"); +\& goto end; +\& } +.Ve +.SS "Performing the handshake" +.IX Subsection "Performing the handshake" +As in the demo for a blocking QUIC client we use the \fBSSL_connect\fR\|(3) function +to perform the handshake with the server. Since we are using a nonblocking +\&\fBSSL\fR object it is very likely that calls to this function will fail with a +non-fatal error while we are waiting for the server to respond to our handshake +messages. In such a case we must retry the same \fBSSL_connect\fR\|(3) call at a +later time. In this demo we do this in a loop: +.PP +.Vb 7 +\& /* Do the handshake with the server */ +\& while ((ret = SSL_connect(ssl)) != 1) { +\& if (handle_io_failure(ssl, ret) == 1) +\& continue; /* Retry */ +\& printf("Failed to connect to server\en"); +\& goto end; /* Cannot retry: error */ +\& } +.Ve +.PP +We continually call \fBSSL_connect\fR\|(3) until it gives us a success response. +Otherwise we use the \f(CWhandle_io_failure()\fR function that we created earlier to +work out what we should do next. Note that we do not expect an EOF to occur at +this stage, so such a response is treated in the same way as a fatal error. +.SS "Sending and receiving data" +.IX Subsection "Sending and receiving data" +As with the blocking QUIC client demo we use the \fBSSL_write_ex\fR\|(3) function to +send data to the server. As with \fBSSL_connect\fR\|(3) above, because we are using +a nonblocking \fBSSL\fR object, this call could fail with a non-fatal error. In +that case we should retry exactly the same \fBSSL_write_ex\fR\|(3) call again. Note +that the parameters must be \fIexactly\fR the same, i.e. the same pointer to the +buffer to write with the same length. You must not attempt to send different +data on a retry. An optional mode does exist +(\fBSSL_MODE_ACCEPT_MOVING_WRITE_BUFFER\fR) which will configure OpenSSL to allow +the buffer being written to change from one retry to the next. However, in this +case, you must still retry exactly the same data \- even though the buffer that +contains that data may change location. See \fBSSL_CTX_set_mode\fR\|(3) for further +details. As in the TLS tutorials (\fBossl\-guide\-tls\-client\-block\fR\|(7)) we write +the request in three chunks. +.PP +.Vb 10 +\& /* Write an HTTP GET request to the peer */ +\& while (!SSL_write_ex(ssl, request_start, strlen(request_start), &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write start of HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& while (!SSL_write_ex(ssl, hostname, strlen(hostname), &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write hostname in HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& while (!SSL_write_ex(ssl, request_end, strlen(request_end), &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write end of HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +.Ve +.PP +On a write we do not expect to see an EOF response so we treat that case in the +same way as a fatal error. +.PP +Reading a response back from the server is similar: +.PP +.Vb 10 +\& do { +\& /* +\& * Get up to sizeof(buf) bytes of the response. We keep reading until +\& * the server closes the connection. +\& */ +\& while (!eof && !SSL_read_ex(ssl, buf, sizeof(buf), &readbytes)) { +\& switch (handle_io_failure(ssl, 0)) { +\& case 1: +\& continue; /* Retry */ +\& case 0: +\& eof = 1; +\& continue; +\& case \-1: +\& default: +\& printf("Failed reading remaining data\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& } +\& /* +\& * OpenSSL does not guarantee that the returned data is a string or +\& * that it is NUL terminated so we use fwrite() to write the exact +\& * number of bytes that we read. The data could be non\-printable or +\& * have NUL characters in the middle of it. For this simple example +\& * we\*(Aqre going to print it to stdout anyway. +\& */ +\& if (!eof) +\& fwrite(buf, 1, readbytes, stdout); +\& } while (!eof); +\& /* In case the response didn\*(Aqt finish with a newline we add one now */ +\& printf("\en"); +.Ve +.PP +The main difference this time is that it is valid for us to receive an EOF +response when trying to read data from the server. This will occur when the +server closes down the connection after sending all the data in its response. +.PP +In this demo we just print out all the data we've received back in the response +from the server. We continue going around the loop until we either encounter a +fatal error, or we receive an EOF (indicating a graceful finish). +.SS "Shutting down the connection" +.IX Subsection "Shutting down the connection" +As in the QUIC blocking example we must shutdown the connection when we are +finished with it. +.PP +Even though we have received EOF on the stream that we were reading from above, +this tell us nothing about the state of the underlying connection. Our demo +application will initiate the connection shutdown process via +\&\fBSSL_shutdown\fR\|(3). +.PP +Since our application is initiating the shutdown then we might expect to see +\&\fBSSL_shutdown\fR\|(3) give a return value of 0, and then we should continue to call +it until we receive a return value of 1 (meaning we have successfully completed +the shutdown). Since we are using a nonblocking \fBSSL\fR object we might expect to +have to retry this operation several times. If \fBSSL_shutdown\fR\|(3) returns a +negative result then we must call \fBSSL_get_error\fR\|(3) to work out what to do +next. We use our \fBhandle_io_failure()\fR function that we developed earlier for +this: +.PP +.Vb 8 +\& /* +\& * Repeatedly call SSL_shutdown() until the connection is fully +\& * closed. +\& */ +\& while ((ret = SSL_shutdown(ssl)) != 1) { +\& if (ret < 0 && handle_io_failure(ssl, ret) == 1) +\& continue; /* Retry */ +\& } +.Ve +.SS "Final clean up" +.IX Subsection "Final clean up" +As with the blocking QUIC client example, once our connection is finished with +we must free it. The steps to do this for this example are the same as for the +blocking example, so we won't repeat it here. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-quic\-client\-block\fR\|(7) to read a tutorial on how to write a +blocking QUIC client. See \fBossl\-guide\-quic\-multi\-stream\fR\|(7) to see how to write +a multi-stream QUIC client. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-quic\-introduction\fR\|(7), +\&\fBossl\-guide\-quic\-client\-block\fR\|(7), \fBossl\-guide\-quic\-multi\-stream\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/ossl-guide-quic-introduction.7ssl b/upstream/debian-unstable/man7/ossl-guide-quic-introduction.7ssl new file mode 100644 index 00000000..016b9187 --- /dev/null +++ b/upstream/debian-unstable/man7/ossl-guide-quic-introduction.7ssl @@ -0,0 +1,226 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-QUIC-INTRODUCTION 7SSL" +.TH OSSL-GUIDE-QUIC-INTRODUCTION 7SSL 2024-04-04 3.2.2-dev 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 +ossl\-guide\-quic\-introduction +\&\- OpenSSL Guide: An introduction to QUIC in OpenSSL +.SH INTRODUCTION +.IX Header "INTRODUCTION" +This page will provide an introduction to some basic QUIC concepts and +background and how it is used within OpenSSL. It assumes that you have a basic +understanding of UDP/IP and sockets. It also assumes that you are familiar with +some OpenSSL and TLS fundamentals (see \fBossl\-guide\-libraries\-introduction\fR\|(7) +and \fBossl\-guide\-tls\-introduction\fR\|(7)). +.SH "WHAT IS QUIC?" +.IX Header "WHAT IS QUIC?" +QUIC is a general purpose protocol for enabling applications to securely +communicate over a network. It is defined in RFC9000 (see +<https://datatracker.ietf.org/doc/rfc9000/>). QUIC integrates parts of the +TLS protocol for connection establishment but independently protects packets. +It provides similar security guarantees to TLS such as confidentiality, +integrity and authentication (see \fBossl\-guide\-tls\-introduction\fR\|(7)). +.PP +QUIC delivers a number of advantages: +.IP "Multiple streams" 4 +.IX Item "Multiple streams" +It supports multiple streams of communication (see "QUIC STREAMS" below), +allowing application protocols built on QUIC to create arbitrarily many +bytestreams for communication between a client and server. This allows an +application protocol to avoid problems where one packet of data is held up +waiting on another packet being delivered (commonly referred to as +"head-of-line blocking"). It also enables an application to open additional +logical streams without requiring a round-trip exchange of packets between the +client and server as is required when opening an additional TLS/TCP +connection. +.IP HTTP/3 4 +.IX Item "HTTP/3" +Since QUIC is the basis of HTTP/3, support for QUIC also enables applications +to use HTTP/3 using a suitable third-party library. +.IP "Fast connection initiation" 4 +.IX Item "Fast connection initiation" +Future versions of OpenSSL will offer support for 0\-RTT connection initiation, +allowing a connection to be initiated to a server and application data to be +transmitted without any waiting time. This is similar to TLS 1.3's 0\-RTT +functionality but also avoids the round trip needed to open a TCP socket; thus, +it is similar to a combination of TLS 1.3 0\-RTT and TCP Fast Open. +.IP "Connection migration" 4 +.IX Item "Connection migration" +Future versions of OpenSSL will offer support for connection migration, allowing +connections to seamlessly survive IP address changes. +.IP "Datagram based use cases" 4 +.IX Item "Datagram based use cases" +Future versions of OpenSSL will offer support for the QUIC datagram extension, +allowing support for both TLS and DTLS-style use cases on a single connection. +.IP "Implemented as application library" 4 +.IX Item "Implemented as application library" +Because most QUIC implementations, including OpenSSL's implementation, are +implemented as an application library rather than by an operating system, an +application can gain the benefit of QUIC without needing to wait for an OS +update to be deployed. Future evolutions and enhancements to the QUIC protocol +can be delivered as quickly as an application can be updated without dependency +on an OS update cadence. +.IP "Multiplexing over a single UDP socket" 4 +.IX Item "Multiplexing over a single UDP socket" +Because QUIC is UDP-based, it is possible to multiplex a QUIC connection on the +same UDP socket as some other UDP-based protocols, such as RTP. +.SH "QUIC TIME BASED EVENTS" +.IX Header "QUIC TIME BASED EVENTS" +A key difference between the TLS implementation and the QUIC implementation in +OpenSSL is how time is handled. The QUIC protocol requires various actions to be +performed on a regular basis regardless of whether application data is being +transmitted or received. +.PP +OpenSSL introduces a new function \fBSSL_handle_events\fR\|(3) that will +automatically process any outstanding time based events that must be handled. +Alternatively calling any I/O function such as \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_write_ex\fR\|(3) will also process these events. There is also +\&\fBSSL_get_event_timeout\fR\|(3) which tells an application the amount of time that +remains until \fBSSL_handle_events\fR\|(3) (or any I/O function) must be called. +.PP +Fortunately a blocking application that does not leave the QUIC connection idle, +and is regularly calling I/O functions does not typically need to worry about +this. However if you are developing a nonblocking application or one that may +leave the QUIC connection idle for a period of time then you will need to +arrange to call these functions. +.PP +OpenSSL provides an optional "thread assisted mode" that will automatically +create a background thread and will regularly call \fBSSL_handle_events\fR\|(3) in a +thread safe manner. This provides a simple way for an application to satisfy the +QUIC requirements for time based events without having to implement special +logic to accomplish it. +.SH "QUIC AND TLS" +.IX Header "QUIC AND TLS" +QUIC reuses parts of the TLS protocol in its implementation. Specifically the +TLS handshake also exists in QUIC. The TLS handshake messages are wrapped up in +QUIC protocol messages in order to send them to the peer. Once the TLS handshake +is complete all application data is sent entirely using QUIC protocol messages +without using TLS \- although some TLS handshake messages may still be sent in +some circumstances. +.PP +This relationship between QUIC and TLS means that many of the API functions in +OpenSSL that apply to TLS connections also apply to QUIC connections and +applications can use them in exactly the same way. Some functions do not apply +to QUIC at all, and others have altered semantics. You should refer to the +documentation pages for each function for information on how it applies to QUIC. +Typically if QUIC is not mentioned in the manual pages then the functions apply +to both TLS and QUIC. +.SH "QUIC STREAMS" +.IX Header "QUIC STREAMS" +QUIC introduces the concept of "streams". A stream provides a reliable +mechanism for sending and receiving application data between the endpoints. The +bytes transmitted are guaranteed to be received in the same order they were sent +without any loss of data or reordering of the bytes. A TLS application +effectively has one bi-directional stream available to it per TLS connection. A +QUIC application can have multiple uni-directional or bi-directional streams +available to it for each connection. +.PP +In OpenSSL an \fBSSL\fR object is used to represent both connections and streams. +A QUIC application creates an initial \fBSSL\fR object to represent the connection +(known as the connection \fBSSL\fR object). Once the connection is complete +additional \fBSSL\fR objects can be created to represent streams (known as stream +\&\fBSSL\fR objects). Unless configured otherwise, a "default" stream is also +associated with the connection \fBSSL\fR object so you can still write data and +read data to/from it. Some OpenSSL API functions can only be used with +connection \fBSSL\fR objects, and some can only be used with stream \fBSSL\fR objects. +Check the documentation for each function to confirm what type of \fBSSL\fR object +can be used in any particular context. A connection \fBSSL\fR object that has a +default stream attached to it can be used in contexts that require a connection +\&\fBSSL\fR object or in contexts that require a stream \fBSSL\fR object. +.SH "SOCKETS AND BLOCKING" +.IX Header "SOCKETS AND BLOCKING" +TLS assumes "stream" type semantics for its underlying transport layer protocol +(usually achieved by using TCP). However QUIC assumes "datagram" type semantics +by using UDP. An OpenSSL application using QUIC is responsible for creating a +BIO to represent the underlying transport layer. This BIO must support datagrams +and is typically \fBBIO_s_datagram\fR\|(3), but other \fBBIO\fR choices are available. +See \fBbio\fR\|(7) for an introduction to OpenSSL's \fBBIO\fR concept. +.PP +A significant difference between OpenSSL TLS applications and OpenSSL QUIC +applications is the way that blocking is implemented. In TLS if your application +expects blocking behaviour then you configure the underlying socket for +blocking. Conversely if your application wants nonblocking behaviour then the +underlying socket is configured to be nonblocking. +.PP +With an OpenSSL QUIC application the underlying socket must always be configured +to be nonblocking. Howevever the \fBSSL\fR object will, by default, still operate +in blocking mode. So, from an application's perspective, calls to functions such +as \fBSSL_read_ex\fR\|(3), \fBSSL_write_ex\fR\|(3) and other I/O functions will still +block. OpenSSL itself provides that blocking capability for QUIC instead of the +socket. If nonblocking behaviour is desired then the application must call +\&\fBSSL_set_blocking_mode\fR\|(3). +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-quic\-client\-block\fR\|(7) to see an example of applying these +concepts in order to write a simple blocking QUIC client. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7), +\&\fBossl\-guide\-tls\-client\-block\fR\|(7), \fBossl\-guide\-quic\-client\-block\fR\|(7), \fBbio\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/ossl-guide-quic-multi-stream.7ssl b/upstream/debian-unstable/man7/ossl-guide-quic-multi-stream.7ssl new file mode 100644 index 00000000..e3169803 --- /dev/null +++ b/upstream/debian-unstable/man7/ossl-guide-quic-multi-stream.7ssl @@ -0,0 +1,453 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-QUIC-MULTI-STREAM 7SSL" +.TH OSSL-GUIDE-QUIC-MULTI-STREAM 7SSL 2024-04-04 3.2.2-dev 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 +ossl\-guide\-quic\-multi\-stream +\&\- OpenSSL Guide: Writing a simple multi\-stream QUIC client +.SH INTRODUCTION +.IX Header "INTRODUCTION" +This page will introduce some important concepts required to write a simple +QUIC multi-stream application. It assumes a basic understanding of QUIC and how +it is used in OpenSSL. See \fBossl\-guide\-quic\-introduction\fR\|(7) and +\&\fBossl\-guide\-quic\-client\-block\fR\|(7). +.SH "QUIC STREAMS" +.IX Header "QUIC STREAMS" +In a QUIC multi-stream application we separate out the concepts of a QUIC +"connection" and a QUIC "stream". A connection object represents the overarching +details of the connection between a client and a server including all its +negotiated and configured parameters. We use the \fBSSL\fR object for that in an +OpenSSL application (known as the connection \fBSSL\fR object). It is created by an +application calling \fBSSL_new\fR\|(3). +.PP +Separately a connection can have zero or more streams associated with it +(although a connection with zero streams is probably not very useful, so +normally you would have at least one). A stream is used to send and receive +data between the two peers. Each stream is also represented by an \fBSSL\fR +object. A stream is logically independent of all the other streams associated +with the same connection. Data sent on a stream is guaranteed to be delivered +in the order that it was sent within that stream. The same is not true across +streams, e.g. if an application sends data on stream 1 first and then sends some +more data on stream 2 second, then the remote peer may receive the data sent on +stream 2 before it receives the data sent on stream 1. +.PP +Once the connection \fBSSL\fR object has completed its handshake (i.e. +\&\fBSSL_connect\fR\|(3) has returned 1), stream \fBSSL\fR objects are created by the +application calling \fBSSL_new_stream\fR\|(3) or \fBSSL_accept_stream\fR\|(3) (see +"CREATING NEW STREAMS" below). +.PP +The same threading rules apply to \fBSSL\fR objects as for most OpenSSL objects +(see \fBossl\-guide\-libraries\-introduction\fR\|(7)). In particular most OpenSSL +functions are thread safe, but the \fBSSL\fR object is not. This means that you can +use an \fBSSL\fR object representing one stream at the same time as another thread +is using a different \fBSSL\fR object for a different stream on the same +connection. But you cannot use the same \fBSSL\fR object on two different threads +at the same time (without additional application level locking). +.SH "THE DEFAULT STREAM" +.IX Header "THE DEFAULT STREAM" +A connection \fBSSL\fR object may also (optionally) be associated with a stream. +This stream is known as the default stream. The default stream is automatically +created and associated with the \fBSSL\fR object when the application calls +\&\fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3), \fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) and +passes the connection \fBSSL\fR object as a parameter. +.PP +If a client application calls \fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) first then +(by default) the default stream will be a client-initiated bi-directional +stream. If a client application calls \fBSSL_read_ex\fR\|(3) or \fBSSL_read\fR\|(3) +first then the first stream initiated by the server will be used as the default +stream (whether it is bi-directional or uni-directional). +.PP +This behaviour can be controlled via the default stream mode. See +\&\fBSSL_set_default_stream_mode\fR\|(3) for further details. +.PP +It is recommended that new multi-stream applications should not use a default +stream at all and instead should use a separate stream \fBSSL\fR object for each +stream that is used. This requires calling \fBSSL_set_default_stream_mode\fR\|(3) +and setting the mode to \fBSSL_DEFAULT_STREAM_MODE_NONE\fR. +.SH "CREATING NEW STREAMS" +.IX Header "CREATING NEW STREAMS" +An endpoint can create a new stream by calling \fBSSL_new_stream\fR\|(3). This +creates a locally initiated stream. In order to do so you must pass the QUIC +connection \fBSSL\fR object as a parameter. You can also specify whether you want a +bi-directional or a uni-directional stream. +.PP +The function returns a new QUIC stream \fBSSL\fR object for sending and receiving +data on that stream. +.PP +The peer may also initiate streams. An application can use the function +\&\fBSSL_get_accept_stream_queue_len\fR\|(3) to determine the number of streams that +the peer has initiated that are waiting for the application to handle. An +application can call \fBSSL_accept_stream\fR\|(3) to create a new \fBSSL\fR object for +a remotely initiated stream. If the peer has not initiated any then this call +will block until one is available if the connection object is in blocking mode +(see \fBSSL_set_blocking_mode\fR\|(3)). +.PP +When using a default stream OpenSSL will prevent new streams from being +accepted. To override this behaviour you must call +\&\fBSSL_set_incoming_stream_policy\fR\|(3) to set the policy to +\&\fBSSL_INCOMING_STREAM_POLICY_ACCEPT\fR. See the man page for further details. This +is not relevant if the default stream has been disabled as described in +"THE DEFAULT STREAM" above. +.PP +Any stream may be bi-directional or uni-directional. If it is uni-directional +then the initiator can write to it but not read from it, and vice-versa for the +peer. You can determine what type of stream an \fBSSL\fR object represents by +calling \fBSSL_get_stream_type\fR\|(3). See the man page for further details. +.SH "USING A STREAM TO SEND AND RECEIVE DATA" +.IX Header "USING A STREAM TO SEND AND RECEIVE DATA" +Once you have a stream \fBSSL\fR object (which includes the connection \fBSSL\fR +object if a default stream is in use) then you can send and receive data over it +using the \fBSSL_write_ex\fR\|(3), \fBSSL_write\fR\|(3), \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_read\fR\|(3) functions. See the man pages for further details. +.PP +In the event of one of these functions not returning a success code then +you should call \fBSSL_get_error\fR\|(3) to find out further details about the error. +In blocking mode this will either be a fatal error (e.g. \fBSSL_ERROR_SYSCALL\fR +or \fBSSL_ERROR_SSL\fR), or it will be \fBSSL_ERROR_ZERO_RETURN\fR which can occur +when attempting to read data from a stream and the peer has indicated that the +stream is concluded (i.e. "FIN" has been signalled on the stream). This means +that the peer will send no more data on that stream. Note that the +interpretation of \fBSSL_ERROR_ZERO_RETURN\fR is slightly different for a QUIC +application compared to a TLS application. In TLS it occurs when the connection +has been shutdown by the peer. In QUIC this only tells you that the current +stream has been concluded by the peer. It tells you nothing about the underlying +connection. If the peer has concluded the stream then no more data will be +received on it, however an application can still send data to the peer until +the send side of the stream has also been concluded. This can happen by the +application calling \fBSSL_stream_conclude\fR\|(3). It is an error to attempt to +send more data on a stream after \fBSSL_stream_conclude\fR\|(3) has been called. +.PP +It is also possible to abandon a stream abnormally by calling +\&\fBSSL_stream_reset\fR\|(3). +.PP +Once a stream object is no longer needed it should be freed via a call to +\&\fBSSL_free\fR\|(3). An application should not call \fBSSL_shutdown\fR\|(3) on it since +this is only meaningful for connection level \fBSSL\fR objects. Freeing the stream +will automatically signal STOP_SENDING to the peer. +.SH "STREAMS AND CONNECTIONS" +.IX Header "STREAMS AND CONNECTIONS" +Given a stream object it is possible to get the \fBSSL\fR object corresponding to +the connection via a call to \fBSSL_get0_connection\fR\|(3). Multi-threaded +restrictions apply so care should be taken when using the returned connection +object. Specifically, if you are handling each of your stream objects in a +different thread and call \fBSSL_get0_connection\fR\|(3) from within that thread then +you must be careful to not to call any function that uses the connection object +at the same time as one of the other threads is also using that connection +object (with the exception of \fBSSL_accept_stream\fR\|(3) and +\&\fBSSL_get_accept_stream_queue_len\fR\|(3) which are thread-safe). +.PP +A stream object does not inherit all its settings and values from its parent +\&\fBSSL\fR connection object. Therefore certain function calls that are relevant to +the connection as a whole will not work on a stream. For example the function +\&\fBSSL_get_certificate\fR\|(3) can be used to obtain a handle on the peer certificate +when called with a connection \fBSSL\fR object. When called with a stream \fBSSL\fR +object it will return NULL. +.SH "SIMPLE MULTI-STREAM QUIC CLIENT EXAMPLE" +.IX Header "SIMPLE MULTI-STREAM QUIC CLIENT EXAMPLE" +This section will present various source code samples demonstrating how to write +a simple multi-stream QUIC client application which connects to a server, send +some HTTP/1.0 requests to it, and read back the responses. Note that HTTP/1.0 +over QUIC is non-standard and will not be supported by real world servers. This +is for demonstration purposes only. +.PP +We will build on the example code for the simple blocking QUIC client that is +covered on the \fBossl\-guide\-quic\-client\-block\fR\|(7) page and we assume that you +are familiar with it. We will only describe the differences between the simple +blocking QUIC client and the multi-stream QUIC client. Although the example code +uses blocking \fBSSL\fR objects, you can equally use nonblocking \fBSSL\fR objects. +See \fBossl\-guide\-quic\-client\-non\-block\fR\|(7) for more information about writing a +nonblocking QUIC client. +.PP +The complete source code for this example multi-stream QUIC client is available +in the \f(CW\*(C`demos/guide\*(C'\fR directory of the OpenSSL source distribution in the file +\&\f(CW\*(C`quic\-multi\-stream.c\*(C'\fR. It is also available online at +<https://github.com/openssl/openssl/blob/master/demos/guide/quic\-multi\-stream.c>. +.SS "Disabling the default stream" +.IX Subsection "Disabling the default stream" +As discussed above in "THE DEFAULT STREAM" we will follow the recommendation +to disable the default stream for our multi-stream client. To do this we call +the \fBSSL_set_default_stream_mode\fR\|(3) function and pass in our connection \fBSSL\fR +object and the value \fBSSL_DEFAULT_STREAM_MODE_NONE\fR. +.PP +.Vb 8 +\& /* +\& * We will use multiple streams so we will disable the default stream mode. +\& * This is not a requirement for using multiple streams but is recommended. +\& */ +\& if (!SSL_set_default_stream_mode(ssl, SSL_DEFAULT_STREAM_MODE_NONE)) { +\& printf("Failed to disable the default stream mode\en"); +\& goto end; +\& } +.Ve +.SS "Creating the request streams" +.IX Subsection "Creating the request streams" +For the purposes of this example we will create two different streams to send +two different HTTP requests to the server. For the purposes of demonstration the +first of these will be a bi-directional stream and the second one will be a +uni-directional one: +.PP +.Vb 10 +\& /* +\& * We create two new client initiated streams. The first will be +\& * bi\-directional, and the second will be uni\-directional. +\& */ +\& stream1 = SSL_new_stream(ssl, 0); +\& stream2 = SSL_new_stream(ssl, SSL_STREAM_FLAG_UNI); +\& if (stream1 == NULL || stream2 == NULL) { +\& printf("Failed to create streams\en"); +\& goto end; +\& } +.Ve +.SS "Writing data to the streams" +.IX Subsection "Writing data to the streams" +Once the streams are successfully created we can start writing data to them. In +this example we will be sending a different HTTP request on each stream. To +avoid repeating too much code we write a simple helper function to send an HTTP +request to a stream: +.PP +.Vb 5 +\& int write_a_request(SSL *stream, const char *request_start, +\& const char *hostname) +\& { +\& const char *request_end = "\er\en\er\en"; +\& size_t written; +\& +\& if (!SSL_write_ex(stream, request_start, strlen(request_start), &written)) +\& return 0; +\& if (!SSL_write_ex(stream, hostname, strlen(hostname), &written)) +\& return 0; +\& if (!SSL_write_ex(stream, request_end, strlen(request_end), &written)) +\& return 0; +\& +\& return 1; +\& } +.Ve +.PP +We assume the strings \fBrequest1_start\fR and \fBrequest2_start\fR hold the +appropriate HTTP requests. We can then call our helper function above to send +the requests on the two streams. For the sake of simplicity this example does +this sequentially, writing to \fBstream1\fR first and, when this is successful, +writing to \fBstream2\fR second. Remember that our client is blocking so these +calls will only return once they have been successfully completed. A real +application would not need to do these writes sequentially or in any particular +order. For example we could start two threads (one for each stream) and write +the requests to each stream simultaneously. +.PP +.Vb 5 +\& /* Write an HTTP GET request on each of our streams to the peer */ +\& if (!write_a_request(stream1, request1_start, hostname)) { +\& printf("Failed to write HTTP request on stream 1\en"); +\& goto end; +\& } +\& +\& if (!write_a_request(stream2, request2_start, hostname)) { +\& printf("Failed to write HTTP request on stream 2\en"); +\& goto end; +\& } +.Ve +.SS "Reading data from a stream" +.IX Subsection "Reading data from a stream" +In this example \fBstream1\fR is a bi-directional stream so, once we have sent the +request on it, we can attempt to read the response from the server back. Here +we just repeatedly call \fBSSL_read_ex\fR\|(3) until that function fails (indicating +either that there has been a problem, or that the peer has signalled the stream +as concluded). +.PP +.Vb 10 +\& printf("Stream 1 data:\en"); +\& /* +\& * Get up to sizeof(buf) bytes of the response from stream 1 (which is a +\& * bidirectional stream). We keep reading until the server closes the +\& * connection. +\& */ +\& while (SSL_read_ex(stream1, buf, sizeof(buf), &readbytes)) { +\& /* +\& * OpenSSL does not guarantee that the returned data is a string or +\& * that it is NUL terminated so we use fwrite() to write the exact +\& * number of bytes that we read. The data could be non\-printable or +\& * have NUL characters in the middle of it. For this simple example +\& * we\*(Aqre going to print it to stdout anyway. +\& */ +\& fwrite(buf, 1, readbytes, stdout); +\& } +\& /* In case the response didn\*(Aqt finish with a newline we add one now */ +\& printf("\en"); +.Ve +.PP +In a blocking application like this one calls to \fBSSL_read_ex\fR\|(3) will either +succeed immediately returning data that is already available, or they will block +waiting for more data to become available and return it when it is, or they will +fail with a 0 response code. +.PP +Once we exit the while loop above we know that the last call to +\&\fBSSL_read_ex\fR\|(3) gave a 0 response code so we call the \fBSSL_get_error\fR\|(3) +function to find out more details. Since this is a blocking application this +will either return \fBSSL_ERROR_SYSCALL\fR or \fBSSL_ERROR_SSL\fR indicating a +fundamental problem, or it will return \fBSSL_ERROR_ZERO_RETURN\fR indicating that +the stream is concluded and there will be no more data available to read from +it. Care must be taken to distinguish between an error at the stream level (i.e. +a stream reset) and an error at the connection level (i.e. a connection closed). +The \fBSSL_get_stream_read_state\fR\|(3) function can be used to distinguish between +these different cases. +.PP +.Vb 12 +\& /* +\& * Check whether we finished the while loop above normally or as the +\& * result of an error. The 0 argument to SSL_get_error() is the return +\& * code we received from the SSL_read_ex() call. It must be 0 in order +\& * to get here. Normal completion is indicated by SSL_ERROR_ZERO_RETURN. In +\& * QUIC terms this means that the peer has sent FIN on the stream to +\& * indicate that no further data will be sent. +\& */ +\& switch (SSL_get_error(stream1, 0)) { +\& case SSL_ERROR_ZERO_RETURN: +\& /* Normal completion of the stream */ +\& break; +\& +\& case SSL_ERROR_SSL: +\& /* +\& * Some stream fatal error occurred. This could be because of a stream +\& * reset \- or some failure occurred on the underlying connection. +\& */ +\& switch (SSL_get_stream_read_state(stream1)) { +\& case SSL_STREAM_STATE_RESET_REMOTE: +\& printf("Stream reset occurred\en"); +\& /* The stream has been reset but the connection is still healthy. */ +\& break; +\& +\& case SSL_STREAM_STATE_CONN_CLOSED: +\& printf("Connection closed\en"); +\& /* Connection is already closed. Skip SSL_shutdown() */ +\& goto end; +\& +\& default: +\& printf("Unknown stream failure\en"); +\& break; +\& } +\& break; +\& +\& default: +\& /* Some other unexpected error occurred */ +\& printf ("Failed reading remaining data\en"); +\& break; +\& } +.Ve +.SS "Accepting an incoming stream" +.IX Subsection "Accepting an incoming stream" +Our \fBstream2\fR object that we created above was a uni-directional stream so it +cannot be used to receive data from the server. In this hypothetical example +we assume that the server initiates a new stream to send us back the data that +we requested. To do that we call \fBSSL_accept_stream\fR\|(3). Since this is a +blocking application this will wait indefinitely until the new stream has +arrived and is available for us to accept. In the event of an error it will +return \fBNULL\fR. +.PP +.Vb 10 +\& /* +\& * In our hypothetical HTTP/1.0 over QUIC protocol that we are using we +\& * assume that the server will respond with a server initiated stream +\& * containing the data requested in our uni\-directional stream. This doesn\*(Aqt +\& * really make sense to do in a real protocol, but its just for +\& * demonstration purposes. +\& * +\& * We\*(Aqre using blocking mode so this will block until a stream becomes +\& * available. We could override this behaviour if we wanted to by setting +\& * the SSL_ACCEPT_STREAM_NO_BLOCK flag in the second argument below. +\& */ +\& stream3 = SSL_accept_stream(ssl, 0); +\& if (stream3 == NULL) { +\& printf("Failed to accept a new stream\en"); +\& goto end; +\& } +.Ve +.PP +We can now read data from the stream in the same way that we did for \fBstream1\fR +above. We won't repeat that here. +.SS "Cleaning up the streams" +.IX Subsection "Cleaning up the streams" +Once we have finished using our streams we can simply free them by calling +\&\fBSSL_free\fR\|(3). Optionally we could call \fBSSL_stream_conclude\fR\|(3) on them if +we want to indicate to the peer that we won't be sending them any more data, but +we don't do that in this example because we assume that the HTTP application +protocol supplies sufficient information for the peer to know when we have +finished sending request data. +.PP +We should not call \fBSSL_shutdown\fR\|(3) or \fBSSL_shutdown_ex\fR\|(3) on the stream +objects since those calls should not be used for streams. +.PP +.Vb 3 +\& SSL_free(stream1); +\& SSL_free(stream2); +\& SSL_free(stream3); +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7) \fBossl\-guide\-quic\-introduction\fR\|(7), +\&\fBossl\-guide\-quic\-client\-block\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/ossl-guide-tls-client-block.7ssl b/upstream/debian-unstable/man7/ossl-guide-tls-client-block.7ssl new file mode 100644 index 00000000..5f3829ee --- /dev/null +++ b/upstream/debian-unstable/man7/ossl-guide-tls-client-block.7ssl @@ -0,0 +1,649 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-TLS-CLIENT-BLOCK 7SSL" +.TH OSSL-GUIDE-TLS-CLIENT-BLOCK 7SSL 2024-04-04 3.2.2-dev 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 +ossl\-guide\-tls\-client\-block +\&\- OpenSSL Guide: Writing a simple blocking TLS client +.SH "SIMPLE BLOCKING TLS CLIENT EXAMPLE" +.IX Header "SIMPLE BLOCKING TLS CLIENT EXAMPLE" +This page will present various source code samples demonstrating how to write +a simple TLS client application which connects to a server, sends an HTTP/1.0 +request to it, and reads back the response. +.PP +We use a blocking socket for the purposes of this example. This means that +attempting to read data from a socket that has no data available on it to read +will block (and the function will not return), until data becomes available. +For example, this can happen if we have sent our request, but we are still +waiting for the server's response. Similarly any attempts to write to a socket +that is not able to write at the moment will block until writing is possible. +.PP +This blocking behaviour simplifies the implementation of a client because you do +not have to worry about what happens if data is not yet available. The +application will simply wait until it is available. +.PP +The complete source code for this example blocking TLS client is available in +the \fBdemos/guide\fR directory of the OpenSSL source distribution in the file +\&\fBtls\-client\-block.c\fR. It is also available online at +<https://github.com/openssl/openssl/blob/master/demos/guide/tls\-client\-block.c>. +.PP +We assume that you already have OpenSSL installed on your system; that you +already have some fundamental understanding of OpenSSL concepts and TLS (see +\&\fBossl\-guide\-libraries\-introduction\fR\|(7) and \fBossl\-guide\-tls\-introduction\fR\|(7)); +and that you know how to write and build C code and link it against the +libcrypto and libssl libraries that are provided by OpenSSL. It also assumes +that you have a basic understanding of TCP/IP and sockets. +.SS "Creating the SSL_CTX and SSL objects" +.IX Subsection "Creating the SSL_CTX and SSL objects" +The first step is to create an \fBSSL_CTX\fR object for our client. We use the +\&\fBSSL_CTX_new\fR\|(3) function for this purpose. We could alternatively use +\&\fBSSL_CTX_new_ex\fR\|(3) if we want to associate the \fBSSL_CTX\fR with a particular +\&\fBOSSL_LIB_CTX\fR (see \fBossl\-guide\-libraries\-introduction\fR\|(7) to learn about +\&\fBOSSL_LIB_CTX\fR). We pass as an argument the return value of the function +\&\fBTLS_client_method\fR\|(3). You should use this method whenever you are writing a +TLS client. This method will automatically use TLS version negotiation to select +the highest version of the protocol that is mutually supported by both the +client and the server. +.PP +.Vb 10 +\& /* +\& * Create an SSL_CTX which we can use to create SSL objects from. We +\& * want an SSL_CTX for creating clients so we use TLS_client_method() +\& * here. +\& */ +\& ctx = SSL_CTX_new(TLS_client_method()); +\& if (ctx == NULL) { +\& printf("Failed to create the SSL_CTX\en"); +\& goto end; +\& } +.Ve +.PP +Since we are writing a client we must ensure that we verify the server's +certificate. We do this by calling the \fBSSL_CTX_set_verify\fR\|(3) function and +pass the \fBSSL_VERIFY_PEER\fR value to it. The final argument to this function +is a callback that you can optionally supply to override the default handling +for certificate verification. Most applications do not need to do this so this +can safely be set to NULL to get the default handling. +.PP +.Vb 6 +\& /* +\& * Configure the client to abort the handshake if certificate +\& * verification fails. Virtually all clients should do this unless you +\& * really know what you are doing. +\& */ +\& SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, NULL); +.Ve +.PP +In order for certificate verification to be successful you must have configured +where the trusted certificate store to be used is located (see +\&\fBossl\-guide\-tls\-introduction\fR\|(7)). In most cases you just want to use the +default store so we call \fBSSL_CTX_set_default_verify_paths\fR\|(3). +.PP +.Vb 5 +\& /* Use the default trusted certificate store */ +\& if (!SSL_CTX_set_default_verify_paths(ctx)) { +\& printf("Failed to set the default trusted certificate store\en"); +\& goto end; +\& } +.Ve +.PP +We would also like to restrict the TLS versions that we are willing to accept to +TLSv1.2 or above. TLS protocol versions earlier than that are generally to be +avoided where possible. We can do that using +\&\fBSSL_CTX_set_min_proto_version\fR\|(3): +.PP +.Vb 8 +\& /* +\& * TLSv1.1 or earlier are deprecated by IETF and are generally to be +\& * avoided if possible. We require a minimum TLS version of TLSv1.2. +\& */ +\& if (!SSL_CTX_set_min_proto_version(ctx, TLS1_2_VERSION)) { +\& printf("Failed to set the minimum TLS protocol version\en"); +\& goto end; +\& } +.Ve +.PP +That is all the setup that we need to do for the \fBSSL_CTX\fR, so next we need to +create an \fBSSL\fR object to represent the TLS connection. In a real application +we might expect to be creating more than one TLS connection over time. In that +case we would expect to reuse the \fBSSL_CTX\fR that we already created each time. +There is no need to repeat those steps. In fact it is best not to since certain +internal resources are cached in the \fBSSL_CTX\fR. You will get better performance +by reusing an existing \fBSSL_CTX\fR instead of creating a new one each time. +.PP +Creating the \fBSSL\fR object is a simple matter of calling the \fBSSL_new\|(3)\fR +function and passing the \fBSSL_CTX\fR we created as an argument. +.PP +.Vb 6 +\& /* Create an SSL object to represent the TLS connection */ +\& ssl = SSL_new(ctx); +\& if (ssl == NULL) { +\& printf("Failed to create the SSL object\en"); +\& goto end; +\& } +.Ve +.SS "Creating the socket and BIO" +.IX Subsection "Creating the socket and BIO" +TLS data is transmitted over an underlying transport layer. Normally a TCP +socket. It is the application's responsibility for ensuring that the socket is +created and associated with an SSL object (via a BIO). +.PP +Socket creation for use by a client is typically a 2 step process, i.e. +constructing the socket; and connecting the socket. +.PP +How to construct a socket is platform specific \- but most platforms (including +Windows) provide a POSIX compatible interface via the \fIsocket\fR function, e.g. +to create an IPv4 TCP socket: +.PP +.Vb 1 +\& int sock; +\& +\& sock = socket(AF_INET, SOCK_STREAM, 0); +\& if (sock == \-1) +\& return NULL; +.Ve +.PP +Once the socket is constructed it must be connected to the remote server. Again +the details are platform specific but most platforms (including Windows) +provide the POSIX compatible \fIconnect\fR function. For example: +.PP +.Vb 2 +\& struct sockaddr_in serveraddr; +\& struct hostent *server; +\& +\& server = gethostbyname("www.openssl.org"); +\& if (server == NULL) { +\& close(sock); +\& return NULL; +\& } +\& +\& memset(&serveraddr, 0, sizeof(serveraddr)); +\& serveraddr.sin_family = server\->h_addrtype; +\& serveraddr.sin_port = htons(443); +\& memcpy(&serveraddr.sin_addr.s_addr, server\->h_addr, server\->h_length); +\& +\& if (connect(sock, (struct sockaddr *)&serveraddr, +\& sizeof(serveraddr)) == \-1) { +\& close(sock); +\& return NULL; +\& } +.Ve +.PP +OpenSSL provides portable helper functions to do these tasks which also +integrate into the OpenSSL error system to log error data, e.g. +.PP +.Vb 3 +\& int sock = \-1; +\& BIO_ADDRINFO *res; +\& const BIO_ADDRINFO *ai = NULL; +\& +\& /* +\& * Lookup IP address info for the server. +\& */ +\& if (!BIO_lookup_ex(hostname, port, BIO_LOOKUP_CLIENT, family, SOCK_STREAM, 0, +\& &res)) +\& return NULL; +\& +\& /* +\& * Loop through all the possible addresses for the server and find one +\& * we can connect to. +\& */ +\& for (ai = res; ai != NULL; ai = BIO_ADDRINFO_next(ai)) { +\& /* +\& * Create a TCP socket. We could equally use non\-OpenSSL calls such +\& * as "socket" here for this and the subsequent connect and close +\& * functions. But for portability reasons and also so that we get +\& * errors on the OpenSSL stack in the event of a failure we use +\& * OpenSSL\*(Aqs versions of these functions. +\& */ +\& sock = BIO_socket(BIO_ADDRINFO_family(ai), SOCK_STREAM, 0, 0); +\& if (sock == \-1) +\& continue; +\& +\& /* Connect the socket to the server\*(Aqs address */ +\& if (!BIO_connect(sock, BIO_ADDRINFO_address(ai), BIO_SOCK_NODELAY)) { +\& BIO_closesocket(sock); +\& sock = \-1; +\& continue; +\& } +\& +\& /* We have a connected socket so break out of the loop */ +\& break; +\& } +\& +\& /* Free the address information resources we allocated earlier */ +\& BIO_ADDRINFO_free(res); +.Ve +.PP +See \fBBIO_lookup_ex\fR\|(3), \fBBIO_socket\fR\|(3), \fBBIO_connect\fR\|(3), +\&\fBBIO_closesocket\fR\|(3), \fBBIO_ADDRINFO_next\fR\|(3), \fBBIO_ADDRINFO_address\fR\|(3) and +\&\fBBIO_ADDRINFO_free\fR\|(3) for further information on the functions used here. In +the above example code the \fBhostname\fR and \fBport\fR variables are strings, e.g. +"www.example.com" and "443". Note also the use of the family variable, which +can take the values of AF_INET or AF_INET6 based on the command line \-6 option, +to allow specific connections to an ipv4 or ipv6 enabled host. +.PP +Sockets created using the methods described above will automatically be blocking +sockets \- which is exactly what we want for this example. +.PP +Once the socket has been created and connected we need to associate it with a +BIO object: +.PP +.Vb 1 +\& BIO *bio; +\& +\& /* Create a BIO to wrap the socket */ +\& bio = BIO_new(BIO_s_socket()); +\& if (bio == NULL) { +\& BIO_closesocket(sock); +\& return NULL; +\& } +\& +\& /* +\& * Associate the newly created BIO with the underlying socket. By +\& * passing BIO_CLOSE here the socket will be automatically closed when +\& * the BIO is freed. Alternatively you can use BIO_NOCLOSE, in which +\& * case you must close the socket explicitly when it is no longer +\& * needed. +\& */ +\& BIO_set_fd(bio, sock, BIO_CLOSE); +.Ve +.PP +See \fBBIO_new\fR\|(3), \fBBIO_s_socket\fR\|(3) and \fBBIO_set_fd\fR\|(3) for further +information on these functions. +.PP +Finally we associate the \fBSSL\fR object we created earlier with the \fBBIO\fR using +the \fBSSL_set_bio\fR\|(3) function. Note that this passes ownership of the \fBBIO\fR +object to the \fBSSL\fR object. Once ownership is passed the SSL object is +responsible for its management and will free it automatically when the \fBSSL\fR is +freed. So, once \fBSSL_set_bio\fR\|(3) has been been called, you should not call +\&\fBBIO_free\fR\|(3) on the \fBBIO\fR. +.PP +.Vb 1 +\& SSL_set_bio(ssl, bio, bio); +.Ve +.SS "Setting the server's hostname" +.IX Subsection "Setting the server's hostname" +We have already connected our underlying socket to the server, but the client +still needs to know the server's hostname. It uses this information for 2 key +purposes and we need to set the hostname for each one. +.PP +Firstly, the server's hostname is included in the initial ClientHello message +sent by the client. This is known as the Server Name Indication (SNI). This is +important because it is common for multiple hostnames to be fronted by a single +server that handles requests for all of them. In other words a single server may +have multiple hostnames associated with it and it is important to indicate which +one we want to connect to. Without this information we may get a handshake +failure, or we may get connected to the "default" server which may not be the +one we were expecting. +.PP +To set the SNI hostname data we call the \fBSSL_set_tlsext_host_name\fR\|(3) function +like this: +.PP +.Vb 8 +\& /* +\& * Tell the server during the handshake which hostname we are attempting +\& * to connect to in case the server supports multiple hosts. +\& */ +\& if (!SSL_set_tlsext_host_name(ssl, hostname)) { +\& printf("Failed to set the SNI hostname\en"); +\& goto end; +\& } +.Ve +.PP +Here the \f(CW\*(C`hostname\*(C'\fR argument is a string representing the hostname of the +server, e.g. "www.example.com". +.PP +Secondly, we need to tell OpenSSL what hostname we expect to see in the +certificate coming back from the server. This is almost always the same one that +we asked for in the original request. This is important because, without this, +we do not verify that the hostname in the certificate is what we expect it to be +and any certificate is acceptable unless your application explicitly checks this +itself. We do this via the \fBSSL_set1_host\fR\|(3) function: +.PP +.Vb 10 +\& /* +\& * Ensure we check during certificate verification that the server has +\& * supplied a certificate for the hostname that we were expecting. +\& * Virtually all clients should do this unless you really know what you +\& * are doing. +\& */ +\& if (!SSL_set1_host(ssl, hostname)) { +\& printf("Failed to set the certificate verification hostname"); +\& goto end; +\& } +.Ve +.PP +All of the above steps must happen before we attempt to perform the handshake +otherwise they will have no effect. +.SS "Performing the handshake" +.IX Subsection "Performing the handshake" +Before we can start sending or receiving application data over a TLS connection +the TLS handshake must be performed. We can do this explicitly via the +\&\fBSSL_connect\fR\|(3) function. +.PP +.Vb 12 +\& /* Do the handshake with the server */ +\& if (SSL_connect(ssl) < 1) { +\& printf("Failed to connect to the server\en"); +\& /* +\& * If the failure is due to a verification error we can get more +\& * information about it from SSL_get_verify_result(). +\& */ +\& if (SSL_get_verify_result(ssl) != X509_V_OK) +\& printf("Verify error: %s\en", +\& X509_verify_cert_error_string(SSL_get_verify_result(ssl))); +\& goto end; +\& } +.Ve +.PP +The \fBSSL_connect\fR\|(3) function can return 1, 0 or less than 0. Only a return +value of 1 is considered a success. For a simple blocking client we only need +to concern ourselves with whether the call was successful or not. Anything else +indicates that we have failed to connect to the server. +.PP +A common cause of failures at this stage is due to a problem verifying the +server's certificate. For example if the certificate has expired, or it is not +signed by a CA in our trusted certificate store. We can use the +\&\fBSSL_get_verify_result\fR\|(3) function to find out more information about the +verification failure. A return value of \fBX509_V_OK\fR indicates that the +verification was successful (so the connection error must be due to some other +cause). Otherwise we use the \fBX509_verify_cert_error_string\fR\|(3) function to get +a human readable error message. +.SS "Sending and receiving data" +.IX Subsection "Sending and receiving data" +Once the handshake is complete we are able to send and receive application data. +Exactly what data is sent and in what order is usually controlled by some +application level protocol. In this example we are using HTTP 1.0 which is a +very simple request and response protocol. The client sends a request to the +server. The server sends the response data and then immediately closes down the +connection. +.PP +To send data to the server we use the \fBSSL_write_ex\fR\|(3) function and to receive +data from the server we use the \fBSSL_read_ex\fR\|(3) function. In HTTP 1.0 the +client always writes data first. Our HTTP request will include the hostname that +we are connecting to. For simplicity, we write the HTTP request in three +chunks. First we write the start of the request. Secondly we write the hostname +we are sending the request to. Finally we send the end of the request. +.PP +.Vb 3 +\& size_t written; +\& const char *request_start = "GET / HTTP/1.0\er\enConnection: close\er\enHost: "; +\& const char *request_end = "\er\en\er\en"; +\& +\& /* Write an HTTP GET request to the peer */ +\& if (!SSL_write_ex(ssl, request_start, strlen(request_start), &written)) { +\& printf("Failed to write start of HTTP request\en"); +\& goto end; +\& } +\& if (!SSL_write_ex(ssl, hostname, strlen(hostname), &written)) { +\& printf("Failed to write hostname in HTTP request\en"); +\& goto end; +\& } +\& if (!SSL_write_ex(ssl, request_end, strlen(request_end), &written)) { +\& printf("Failed to write end of HTTP request\en"); +\& goto end; +\& } +.Ve +.PP +The \fBSSL_write_ex\fR\|(3) function returns 0 if it fails and 1 if it is successful. +If it is successful then we can proceed to waiting for a response from the +server. +.PP +.Vb 2 +\& size_t readbytes; +\& char buf[160]; +\& +\& /* +\& * Get up to sizeof(buf) bytes of the response. We keep reading until the +\& * server closes the connection. +\& */ +\& while (SSL_read_ex(ssl, buf, sizeof(buf), &readbytes)) { +\& /* +\& * OpenSSL does not guarantee that the returned data is a string or +\& * that it is NUL terminated so we use fwrite() to write the exact +\& * number of bytes that we read. The data could be non\-printable or +\& * have NUL characters in the middle of it. For this simple example +\& * we\*(Aqre going to print it to stdout anyway. +\& */ +\& fwrite(buf, 1, readbytes, stdout); +\& } +\& /* In case the response didn\*(Aqt finish with a newline we add one now */ +\& printf("\en"); +.Ve +.PP +We use the \fBSSL_read_ex\fR\|(3) function to read the response. We don't know +exactly how much data we are going to receive back so we enter a loop reading +blocks of data from the server and printing each block that we receive to the +screen. The loop ends as soon as \fBSSL_read_ex\fR\|(3) returns 0 \- meaning that it +failed to read any data. +.PP +A failure to read data could mean that there has been some error, or it could +simply mean that server has sent all the data that it wants to send and has +indicated that it has finished by sending a "close_notify" alert. This alert is +a TLS protocol level message indicating that the endpoint has finished sending +all of its data and it will not send any more. Both of these conditions result +in a 0 return value from \fBSSL_read_ex\fR\|(3) and we need to use the function +\&\fBSSL_get_error\fR\|(3) to determine the cause of the 0 return value. +.PP +.Vb 10 +\& /* +\& * Check whether we finished the while loop above normally or as the +\& * result of an error. The 0 argument to SSL_get_error() is the return +\& * code we received from the SSL_read_ex() call. It must be 0 in order +\& * to get here. Normal completion is indicated by SSL_ERROR_ZERO_RETURN. +\& */ +\& if (SSL_get_error(ssl, 0) != SSL_ERROR_ZERO_RETURN) { +\& /* +\& * Some error occurred other than a graceful close down by the +\& * peer +\& */ +\& printf ("Failed reading remaining data\en"); +\& goto end; +\& } +.Ve +.PP +If \fBSSL_get_error\fR\|(3) returns \fBSSL_ERROR_ZERO_RETURN\fR then we know that the +server has finished sending its data. Otherwise an error has occurred. +.SS "Shutting down the connection" +.IX Subsection "Shutting down the connection" +Once we have finished reading data from the server then we are ready to close +the connection down. We do this via the \fBSSL_shutdown\fR\|(3) function which has +the effect of sending a TLS protocol level message (a "close_notify" alert) to +the server saying that we have finished writing data: +.PP +.Vb 10 +\& /* +\& * The peer already shutdown gracefully (we know this because of the +\& * SSL_ERROR_ZERO_RETURN above). We should do the same back. +\& */ +\& ret = SSL_shutdown(ssl); +\& if (ret < 1) { +\& /* +\& * ret < 0 indicates an error. ret == 0 would be unexpected here +\& * because that means "we\*(Aqve sent a close_notify and we\*(Aqre waiting +\& * for one back". But we already know we got one from the peer +\& * because of the SSL_ERROR_ZERO_RETURN above. +\& */ +\& printf("Error shutting down\en"); +\& goto end; +\& } +.Ve +.PP +The \fBSSL_shutdown\fR\|(3) function will either return 1, 0, or less than 0. A +return value of 1 is a success, and a return value less than 0 is an error. More +precisely a return value of 1 means that we have sent a "close_notify" alert to +the server, and that we have also received one back. A return value of 0 means +that we have sent a "close_notify" alert to the server, but we have not yet +received one back. Usually in this scenario you would call \fBSSL_shutdown\fR\|(3) +again which (with a blocking socket) would block until the "close_notify" is +received. However in this case we already know that the server has sent us a +"close_notify" because of the SSL_ERROR_ZERO_RETURN that we received from the +call to \fBSSL_read_ex\fR\|(3). So this scenario should never happen in practice. We +just treat it as an error in this example. +.SS "Final clean up" +.IX Subsection "Final clean up" +Before the application exits we have to clean up some memory that we allocated. +If we are exiting due to an error we might also want to display further +information about that error if it is available to the user: +.PP +.Vb 10 +\& /* Success! */ +\& res = EXIT_SUCCESS; +\& end: +\& /* +\& * If something bad happened then we will dump the contents of the +\& * OpenSSL error stack to stderr. There might be some useful diagnostic +\& * information there. +\& */ +\& if (res == EXIT_FAILURE) +\& ERR_print_errors_fp(stderr); +\& +\& /* +\& * Free the resources we allocated. We do not free the BIO object here +\& * because ownership of it was immediately transferred to the SSL object +\& * via SSL_set_bio(). The BIO will be freed when we free the SSL object. +\& */ +\& SSL_free(ssl); +\& SSL_CTX_free(ctx); +\& return res; +.Ve +.PP +To display errors we make use of the \fBERR_print_errors_fp\fR\|(3) function which +simply dumps out the contents of any errors on the OpenSSL error stack to the +specified location (in this case \fIstderr\fR). +.PP +We need to free up the \fBSSL\fR object that we created for the connection via the +\&\fBSSL_free\fR\|(3) function. Also, since we are not going to be creating any more +TLS connections we must also free up the \fBSSL_CTX\fR via a call to +\&\fBSSL_CTX_free\fR\|(3). +.SH TROUBLESHOOTING +.IX Header "TROUBLESHOOTING" +There are a number of things that might go wrong when running the demo +application. This section describes some common things you might encounter. +.SS "Failure to connect the underlying socket" +.IX Subsection "Failure to connect the underlying socket" +This could occur for numerous reasons. For example if there is a problem in the +network route between the client and the server; or a firewall is blocking the +communication; or the server is not in DNS. Check the network configuration. +.SS "Verification failure of the server certificate" +.IX Subsection "Verification failure of the server certificate" +A verification failure of the server certificate would result in a failure when +running the \fBSSL_connect\fR\|(3) function. \fBERR_print_errors_fp\fR\|(3) would display +an error which would look something like this: +.PP +.Vb 2 +\& Verify error: unable to get local issuer certificate +\& 40E74AF1F47F0000:error:0A000086:SSL routines:tls_post_process_server_certificate:certificate verify failed:ssl/statem/statem_clnt.c:2069: +.Ve +.PP +A server certificate verification failure could be caused for a number of +reasons. For example +.IP "Failure to correctly setup the trusted certificate store" 4 +.IX Item "Failure to correctly setup the trusted certificate store" +See the page \fBossl\-guide\-tls\-introduction\fR\|(7) and check that your trusted +certificate store is correctly configured +.IP "Unrecognised CA" 4 +.IX Item "Unrecognised CA" +If the CA used by the server's certificate is not in the trusted certificate +store for the client then this will cause a verification failure during +connection. Often this can occur if the server is using a self-signed +certificate (i.e. a test certificate that has not been signed by a CA at all). +.IP "Missing intermediate CAs" 4 +.IX Item "Missing intermediate CAs" +This is a server misconfiguration where the client has the relevant root CA in +its trust store, but the server has not supplied all of the intermediate CA +certificates between that root CA and the server's own certificate. Therefore +a trust chain cannot be established. +.IP "Mismatched hostname" 4 +.IX Item "Mismatched hostname" +If for some reason the hostname of the server that the client is expecting does +not match the hostname in the certificate then this will cause verification to +fail. +.IP "Expired certificate" 4 +.IX Item "Expired certificate" +The date that the server's certificate is valid to has passed. +.PP +The "unable to get local issuer certificate" we saw in the example above means +that we have been unable to find the issuer of the server's certificate (or one +of its intermediate CA certificates) in our trusted certificate store (e.g. +because the trusted certificate store is misconfigured, or there are missing +intermediate CAs, or the issuer is simply unrecognised). +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-tls\-client\-non\-block\fR\|(7) to read a tutorial on how to modify +the client developed on this page to support a nonblocking socket. +.PP +See \fBossl\-guide\-quic\-client\-block\fR\|(7) to read a tutorial on how to modify the +client developed on this page to support QUIC instead of TLS. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7), +\&\fBossl\-guide\-tls\-client\-non\-block\fR\|(7), \fBossl\-guide\-quic\-client\-block\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/ossl-guide-tls-client-non-block.7ssl b/upstream/debian-unstable/man7/ossl-guide-tls-client-non-block.7ssl new file mode 100644 index 00000000..507feb6d --- /dev/null +++ b/upstream/debian-unstable/man7/ossl-guide-tls-client-non-block.7ssl @@ -0,0 +1,435 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-TLS-CLIENT-NON-BLOCK 7SSL" +.TH OSSL-GUIDE-TLS-CLIENT-NON-BLOCK 7SSL 2024-04-04 3.2.2-dev 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 +ossl\-guide\-tls\-client\-non\-block +\&\- OpenSSL Guide: Writing a simple nonblocking TLS client +.SH "SIMPLE NONBLOCKING TLS CLIENT EXAMPLE" +.IX Header "SIMPLE NONBLOCKING TLS CLIENT EXAMPLE" +This page will build on the example developed on the +\&\fBossl\-guide\-tls\-client\-block\fR\|(7) page which demonstrates how to write a simple +blocking TLS client. On this page we will amend that demo code so that it +supports a nonblocking socket. +.PP +The complete source code for this example nonblocking TLS client is available +in the \fBdemos/guide\fR directory of the OpenSSL source distribution in the file +\&\fBtls\-client\-non\-block.c\fR. It is also available online at +<https://github.com/openssl/openssl/blob/master/demos/guide/tls\-client\-non\-block.c>. +.PP +As we saw in the previous example a blocking socket is one which waits (blocks) +until data is available to read if you attempt to read from it when there is no +data yet. Similarly it waits when writing if the socket is currently unable to +write at the moment. This can simplify the development of code because you do +not have to worry about what to do in these cases. The execution of the code +will simply stop until it is able to continue. However in many cases you do not +want this behaviour. Rather than stopping and waiting your application may need +to go and do other tasks whilst the socket is unable to read/write, for example +updating a GUI or performing operations on some other socket. +.PP +With a nonblocking socket attempting to read or write to a socket that is +currently unable to read or write will return immediately with a non-fatal +error. Although OpenSSL does the reading/writing to the socket this nonblocking +behaviour is propagated up to the application so that OpenSSL I/O functions such +as \fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(3) will not block. +.PP +Since this page is building on the example developed on the +\&\fBossl\-guide\-tls\-client\-block\fR\|(7) page we assume that you are familiar with it +and we only explain how this example differs. +.SS "Setting the socket to be nonblocking" +.IX Subsection "Setting the socket to be nonblocking" +The first step in writing an application that supports nonblocking is to set +the socket into nonblocking mode. A socket will be default be blocking. The +exact details on how to do this can differ from one platform to another. +Fortunately OpenSSL offers a portable function that will do this for you: +.PP +.Vb 5 +\& /* Set to nonblocking mode */ +\& if (!BIO_socket_nbio(sock, 1)) { +\& sock = \-1; +\& continue; +\& } +.Ve +.PP +You do not have to use OpenSSL's function for this. You can of course directly +call whatever functions that your Operating System provides for this purpose on +your platform. +.SS "Performing work while waiting for the socket" +.IX Subsection "Performing work while waiting for the socket" +In a nonblocking application you will need work to perform in the event that +we want to read or write to the socket, but we are currently unable to. In fact +this is the whole point of using a nonblocking socket, i.e. to give the +application the opportunity to do something else. Whatever it is that the +application has to do, it must also be prepared to come back and retry the +operation that it previously attempted periodically to see if it can now +complete. Ideally it would only do this in the event that the state of the +underlying socket has actually changed (e.g. become readable where it wasn't +before), but this does not have to be the case. It can retry at any time. +.PP +Note that it is important that you retry exactly the same operation that you +tried last time. You cannot start something new. For example if you were +attempting to write the text "Hello World" and the operation failed because the +socket is currently unable to write, then you cannot then attempt to write +some other text when you retry the operation. +.PP +In this demo application we will create a helper function which simulates doing +other work. In fact, for the sake of simplicity, it will do nothing except wait +for the state of the socket to change. +.PP +We call our function \f(CWwait_for_activity()\fR because all it does is wait until +the underlying socket has become readable or writeable when it wasn't before. +.PP +.Vb 4 +\& static void wait_for_activity(SSL *ssl, int write) +\& { +\& fd_set fds; +\& int width, sock; +\& +\& /* Get hold of the underlying file descriptor for the socket */ +\& sock = SSL_get_fd(ssl); +\& +\& FD_ZERO(&fds); +\& FD_SET(sock, &fds); +\& width = sock + 1; +\& +\& /* +\& * Wait until the socket is writeable or readable. We use select here +\& * for the sake of simplicity and portability, but you could equally use +\& * poll/epoll or similar functions +\& * +\& * NOTE: For the purposes of this demonstration code this effectively +\& * makes this demo block until it has something more useful to do. In a +\& * real application you probably want to go and do other work here (e.g. +\& * update a GUI, or service other connections). +\& * +\& * Let\*(Aqs say for example that you want to update the progress counter on +\& * a GUI every 100ms. One way to do that would be to add a 100ms timeout +\& * in the last parameter to "select" below. Then, when select returns, +\& * you check if it did so because of activity on the file descriptors or +\& * because of the timeout. If it is due to the timeout then update the +\& * GUI and then restart the "select". +\& */ +\& if (write) +\& select(width, NULL, &fds, NULL, NULL); +\& else +\& select(width, &fds, NULL, NULL, NULL); +\& } +.Ve +.PP +In this example we are using the \f(CW\*(C`select\*(C'\fR function because it is very simple +to use and is available on most Operating Systems. However you could use any +other similar function to do the same thing. \f(CW\*(C`select\*(C'\fR waits for the state of +the underlying socket(s) to become readable/writeable before returning. It also +supports a "timeout" (as do most other similar functions) so in your own +applications you can make use of this to periodically wake up and perform work +while waiting for the socket state to change. But we don't use that timeout +capability in this example for the sake of simplicity. +.SS "Handling errors from OpenSSL I/O functions" +.IX Subsection "Handling errors from OpenSSL I/O functions" +An application that uses a nonblocking socket will need to be prepared to +handle errors returned from OpenSSL I/O functions such as \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_write_ex\fR\|(3). Errors may be fatal (for example because the underlying +connection has failed), or non-fatal (for example because we are trying to read +from the underlying socket but the data has not yet arrived from the peer). +.PP +\&\fBSSL_read_ex\fR\|(3) and \fBSSL_write_ex\fR\|(3) will return 0 to indicate an error and +\&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) will return 0 or a negative value to indicate +an error. \fBSSL_shutdown\fR\|(3) will return a negative value to incidate an error. +.PP +In the event of an error an application should call \fBSSL_get_error\fR\|(3) to find +out what type of error has occurred. If the error is non-fatal and can be +retried then \fBSSL_get_error\fR\|(3) will return \fBSSL_ERROR_WANT_READ\fR or +\&\fBSSL_ERROR_WANT_WRITE\fR depending on whether OpenSSL wanted to read to or write +from the socket but was unable to. Note that a call to \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_read\fR\|(3) can still generate \fBSSL_ERROR_WANT_WRITE\fR because OpenSSL +may need to write protocol messages (such as to update cryptographic keys) even +if the application is only trying to read data. Similarly calls to +\&\fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) might generate \fBSSL_ERROR_WANT_READ\fR. +.PP +Another type of non-fatal error that may occur is \fBSSL_ERROR_ZERO_RETURN\fR. This +indicates an EOF (End-Of-File) which can occur if you attempt to read data from +an \fBSSL\fR object but the peer has indicated that it will not send any more data +on it. In this case you may still want to write data to the connection but you +will not receive any more data. +.PP +Fatal errors that may occur are \fBSSL_ERROR_SYSCALL\fR and \fBSSL_ERROR_SSL\fR. These +indicate that the underlying connection has failed. You should not attempt to +shut it down with \fBSSL_shutdown\fR\|(3). \fBSSL_ERROR_SYSCALL\fR indicates that +OpenSSL attempted to make a syscall that failed. You can consult \fBerrno\fR for +further details. \fBSSL_ERROR_SSL\fR indicates that some OpenSSL error occurred. You +can consult the OpenSSL error stack for further details (for example by calling +\&\fBERR_print_errors\fR\|(3) to print out details of errors that have occurred). +.PP +In our demo application we will write a function to handle these errors from +OpenSSL I/O functions: +.PP +.Vb 7 +\& static int handle_io_failure(SSL *ssl, int res) +\& { +\& switch (SSL_get_error(ssl, res)) { +\& case SSL_ERROR_WANT_READ: +\& /* Temporary failure. Wait until we can read and try again */ +\& wait_for_activity(ssl, 0); +\& return 1; +\& +\& case SSL_ERROR_WANT_WRITE: +\& /* Temporary failure. Wait until we can write and try again */ +\& wait_for_activity(ssl, 1); +\& return 1; +\& +\& case SSL_ERROR_ZERO_RETURN: +\& /* EOF */ +\& return 0; +\& +\& case SSL_ERROR_SYSCALL: +\& return \-1; +\& +\& case SSL_ERROR_SSL: +\& /* +\& * If the failure is due to a verification error we can get more +\& * information about it from SSL_get_verify_result(). +\& */ +\& if (SSL_get_verify_result(ssl) != X509_V_OK) +\& printf("Verify error: %s\en", +\& X509_verify_cert_error_string(SSL_get_verify_result(ssl))); +\& return \-1; +\& +\& default: +\& return \-1; +\& } +\& } +.Ve +.PP +This function takes as arguments the \fBSSL\fR object that represents the +connection, as well as the return code from the I/O function that failed. In +the event of a non-fatal failure, it waits until a retry of the I/O operation +might succeed (by using the \f(CWwait_for_activity()\fR function that we developed +in the previous section). It returns 1 in the event of a non-fatal error +(except EOF), 0 in the event of EOF, or \-1 if a fatal error occurred. +.SS "Creating the SSL_CTX and SSL objects" +.IX Subsection "Creating the SSL_CTX and SSL objects" +In order to connect to a server we must create \fBSSL_CTX\fR and \fBSSL\fR objects for +this. The steps do this are the same as for a blocking client and are explained +on the \fBossl\-guide\-tls\-client\-block\fR\|(7) page. We won't repeat that information +here. +.SS "Performing the handshake" +.IX Subsection "Performing the handshake" +As in the demo for a blocking TLS client we use the \fBSSL_connect\fR\|(3) function +to perform the TLS handshake with the server. Since we are using a nonblocking +socket it is very likely that calls to this function will fail with a non-fatal +error while we are waiting for the server to respond to our handshake messages. +In such a case we must retry the same \fBSSL_connect\fR\|(3) call at a later time. +In this demo we this in a loop: +.PP +.Vb 7 +\& /* Do the handshake with the server */ +\& while ((ret = SSL_connect(ssl)) != 1) { +\& if (handle_io_failure(ssl, ret) == 1) +\& continue; /* Retry */ +\& printf("Failed to connect to server\en"); +\& goto end; /* Cannot retry: error */ +\& } +.Ve +.PP +We continually call \fBSSL_connect\fR\|(3) until it gives us a success response. +Otherwise we use the \f(CWhandle_io_failure()\fR function that we created earlier to +work out what we should do next. Note that we do not expect an EOF to occur at +this stage, so such a response is treated in the same way as a fatal error. +.SS "Sending and receiving data" +.IX Subsection "Sending and receiving data" +As with the blocking TLS client demo we use the \fBSSL_write_ex\fR\|(3) function to +send data to the server. As with \fBSSL_connect\fR\|(3) above, because we are using +a nonblocking socket, this call could fail with a non-fatal error. In that case +we should retry exactly the same \fBSSL_write_ex\fR\|(3) call again. Note that the +parameters must be \fIexactly\fR the same, i.e. the same pointer to the buffer to +write with the same length. You must not attempt to send different data on a +retry. An optional mode does exist (\fBSSL_MODE_ACCEPT_MOVING_WRITE_BUFFER\fR) +which will configure OpenSSL to allow the buffer being written to change from +one retry to the next. However, in this case, you must still retry exactly the +same data \- even though the buffer that contains that data may change location. +See \fBSSL_CTX_set_mode\fR\|(3) for further details. As in the TLS client +blocking tutorial (\fBossl\-guide\-tls\-client\-block\fR\|(7)) we write the request +in three chunks. +.PP +.Vb 10 +\& /* Write an HTTP GET request to the peer */ +\& while (!SSL_write_ex(ssl, request_start, strlen(request_start), &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write start of HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& while (!SSL_write_ex(ssl, hostname, strlen(hostname), &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write hostname in HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& while (!SSL_write_ex(ssl, request_end, strlen(request_end), &written)) { +\& if (handle_io_failure(ssl, 0) == 1) +\& continue; /* Retry */ +\& printf("Failed to write end of HTTP request\en"); +\& goto end; /* Cannot retry: error */ +\& } +.Ve +.PP +On a write we do not expect to see an EOF response so we treat that case in the +same way as a fatal error. +.PP +Reading a response back from the server is similar: +.PP +.Vb 10 +\& do { +\& /* +\& * Get up to sizeof(buf) bytes of the response. We keep reading until +\& * the server closes the connection. +\& */ +\& while (!eof && !SSL_read_ex(ssl, buf, sizeof(buf), &readbytes)) { +\& switch (handle_io_failure(ssl, 0)) { +\& case 1: +\& continue; /* Retry */ +\& case 0: +\& eof = 1; +\& continue; +\& case \-1: +\& default: +\& printf("Failed reading remaining data\en"); +\& goto end; /* Cannot retry: error */ +\& } +\& } +\& /* +\& * OpenSSL does not guarantee that the returned data is a string or +\& * that it is NUL terminated so we use fwrite() to write the exact +\& * number of bytes that we read. The data could be non\-printable or +\& * have NUL characters in the middle of it. For this simple example +\& * we\*(Aqre going to print it to stdout anyway. +\& */ +\& if (!eof) +\& fwrite(buf, 1, readbytes, stdout); +\& } while (!eof); +\& /* In case the response didn\*(Aqt finish with a newline we add one now */ +\& printf("\en"); +.Ve +.PP +The main difference this time is that it is valid for us to receive an EOF +response when trying to read data from the server. This will occur when the +server closes down the connection after sending all the data in its response. +.PP +In this demo we just print out all the data we've received back in the response +from the server. We continue going around the loop until we either encounter a +fatal error, or we receive an EOF (indicating a graceful finish). +.SS "Shutting down the connection" +.IX Subsection "Shutting down the connection" +As in the TLS blocking example we must shutdown the connection when we are +finished with it. +.PP +If our application was initiating the shutdown then we would expect to see +\&\fBSSL_shutdown\fR\|(3) give a return value of 0, and then we would continue to call +it until we received a return value of 1 (meaning we have successfully completed +the shutdown). In this particular example we don't expect \fBSSL_shutdown()\fR to +return 0 because we have already received EOF from the server indicating that it +has shutdown already. So we just keep calling it until \fBSSL_shutdown()\fR returns 1. +Since we are using a nonblocking socket we might expect to have to retry this +operation several times. If \fBSSL_shutdown\fR\|(3) returns a negative result then we +must call \fBSSL_get_error\fR\|(3) to work out what to do next. We use our +\&\fBhandle_io_failure()\fR function that we developed earlier for this: +.PP +.Vb 10 +\& /* +\& * The peer already shutdown gracefully (we know this because of the +\& * SSL_ERROR_ZERO_RETURN (i.e. EOF) above). We should do the same back. +\& */ +\& while ((ret = SSL_shutdown(ssl)) != 1) { +\& if (ret < 0 && handle_io_failure(ssl, ret) == 1) +\& continue; /* Retry */ +\& /* +\& * ret == 0 is unexpected here because that means "we\*(Aqve sent a +\& * close_notify and we\*(Aqre waiting for one back". But we already know +\& * we got one from the peer because of the SSL_ERROR_ZERO_RETURN +\& * (i.e. EOF) above. +\& */ +\& printf("Error shutting down\en"); +\& goto end; /* Cannot retry: error */ +\& } +.Ve +.SS "Final clean up" +.IX Subsection "Final clean up" +As with the blocking TLS client example, once our connection is finished with we +must free it. The steps to do this for this example are the same as for the +blocking example, so we won't repeat it here. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-tls\-client\-block\fR\|(7) to read a tutorial on how to write a +blocking TLS client. See \fBossl\-guide\-quic\-client\-block\fR\|(7) to see how to do the +same thing for a QUIC client. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7), +\&\fBossl\-guide\-tls\-client\-block\fR\|(7), \fBossl\-guide\-quic\-client\-block\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/ossl-guide-tls-introduction.7ssl b/upstream/debian-unstable/man7/ossl-guide-tls-introduction.7ssl new file mode 100644 index 00000000..970f1174 --- /dev/null +++ b/upstream/debian-unstable/man7/ossl-guide-tls-introduction.7ssl @@ -0,0 +1,372 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OSSL-GUIDE-TLS-INTRODUCTION 7SSL" +.TH OSSL-GUIDE-TLS-INTRODUCTION 7SSL 2024-04-04 3.2.2-dev 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 +ossl\-guide\-tls\-introduction +\&\- OpenSSL Guide: An introduction to SSL/TLS in OpenSSL +.SH INTRODUCTION +.IX Header "INTRODUCTION" +This page will provide an introduction to some basic SSL/TLS concepts and +background and how it is used within OpenSSL. It assumes that you have a basic +understanding of TCP/IP and sockets. +.SH "WHAT IS TLS?" +.IX Header "WHAT IS TLS?" +TLS stands for Transport Layer Security. TLS allows applications to securely +communicate with each other across a network such that the confidentiality of +the information exchanged is protected (i.e. it prevents eavesdroppers from +listening in to the communication). Additionally it protects the integrity of +the information exchanged to prevent an attacker from changing it. Finally it +provides authentication so that one or both parties can be sure that they are +talking to who they think they are talking to and not some imposter. +.PP +Sometimes TLS is referred to by its predecessor's name SSL (Secure Sockets +Layer). OpenSSL dates from a time when the SSL name was still in common use and +hence many of the functions and names used by OpenSSL contain the "SSL" +abbreviation. Nonetheless OpenSSL contains a fully fledged TLS implementation. +.PP +TLS is based on a client/server model. The application that initiates a +communication is known as the client. The application that responds to a +remotely initiated communication is the server. The term "endpoint" refers to +either of the client or the server in a communication. The term "peer" refers to +the endpoint at the other side of the communication that we are currently +referring to. So if we are currently talking about the client then the peer +would be the server. +.PP +TLS is a standardised protocol and there are numerous different implementations +of it. Due to the standards an OpenSSL client or server is able to communicate +seamlessly with an application using some different implementation of TLS. TLS +(and its predecessor SSL) have been around for a significant period of time and +the protocol has undergone various changes over the years. Consequently there +are different versions of the protocol available. TLS includes the ability to +perform version negotiation so that the highest protocol version that the client +and server share in common is used. +.PP +TLS acts as a security layer over some lower level transport protocol. Typically +the transport layer will be TCP. +.SH "SSL AND TLS VERSIONS" +.IX Header "SSL AND TLS VERSIONS" +SSL was initially developed by Netscape Communications and its first publicly +released version was SSLv2 in 1995. Note that SSLv1 was never publicly released. +SSLv3 came along quickly afterwards in 1996. Subsequently development of the +protocol moved to the IETF which released the first version of TLS (TLSv1.0) in +1999 as RFC2246. TLSv1.1 was released in 2006 as RFC4346 and TLSv1.2 came along +in 2008 as RFC5246. The most recent version of the standard is TLSv1.3 which +was released in 2018 as RFC8446. +.PP +Today TLSv1.3 and TLSv1.2 are the most commonly deployed versions of the +protocol. The IETF have formally deprecated TLSv1.1 and TLSv1.0, so anything +below TLSv1.2 should be avoided since the older protocol versions are +susceptible to security problems. +.PP +OpenSSL does not support SSLv2 (it was removed in OpenSSL 1.1.0). Support for +SSLv3 is available as a compile time option \- but it is not built by default. +Support for TLSv1.0, TLSv1.1, TLSv1.2 and TLSv1.3 are all available by default +in a standard build of OpenSSL. However special run-time configuration is +required in order to make TLSv1.0 and TLSv1.1 work successfully. +.PP +OpenSSL will always try to negotiate the highest protocol version that it has +been configured to support. In most cases this will mean either TLSv1.3 or +TLSv1.2 is chosen. +.SH CERTIFICATES +.IX Header "CERTIFICATES" +In order for a client to establish a connection to a server it must authenticate +the identify of that server, i.e. it needs to confirm that the server is really +the server that it claims to be and not some imposter. In order to do this the +server will send to the client a digital certificate (also commonly referred to +as an X.509 certificate). The certificate contains various information about the +server including its full DNS hostname. Also within the certificate is the +server's public key. The server operator will have a private key which is +linked to the public key and must not be published. +.PP +Along with the certificate the server will also send to the client proof that it +knows the private key associated with the public key in the certificate. It does +this by digitally signing a message to the client using that private key. The +client can verify the signature using the public key from the certificate. If +the signature verifies successfully then the client knows that the server is in +possession of the correct private key. +.PP +The certificate that the server sends will also be signed by a Certificate +Authority. The Certificate Authority (commonly known as a CA) is a third party +organisation that is responsible for verifying the information in the server's +certificate (including its DNS hostname). The CA should only sign the +certificate if it has been able to confirm that the server operator does indeed +have control of the server associated with its DNS hostname and that the server +operator has control of the private key. +.PP +In this way, if the client trusts the CA that has signed the server's +certificate and it can verify that the server has the right private key then it +can trust that the server truly does represent the DNS hostname given in the +certificate. The client must also verify that the hostname given in the +certificate matches the hostname that it originally sent the request to. +.PP +Once all of these checks have been done the client has successfully verified the +identify of the server. OpenSSL can perform all of these checks automatically +but it must be provided with certain information in order to do so, i.e. the set +of CAs that the client trusts as well as the DNS hostname for the server that +this client is trying to connect to. +.PP +Note that it is common for certificates to be built up into a chain. For example +a server's certificate may be signed by a key owned by a an intermediate CA. +That intermediate CA also has a certificate containing its public key which is +in turn signed by a key owned by a root CA. The client may only trust the root +CA, but if the server sends both its own certificate and the certificate for the +intermediate CA then the client can still successfully verify the identity of +the server. There is a chain of trust between the root CA and the server. +.PP +By default it is only the client that authenticates the server using this +method. However it is also possible to set things up such that the server +additionally authenticates the client. This is known as "client authentication". +In this approach the client will still authenticate the server in the same way, +but the server will request a certificate from the client. The client sends the +server its certificate and the server authenticates it in the same way that the +client does. +.SH "TRUSTED CERTIFICATE STORE" +.IX Header "TRUSTED CERTIFICATE STORE" +The system described above only works if a chain of trust can be built between +the set of CAs that the endpoint trusts and the certificate that the peer is +using. The endpoint must therefore have a set of certificates for CAs that it +trusts before any communication can take place. OpenSSL itself does not provide +such a set of certificates. Therefore you will need to make sure you have them +before you start if you are going to be verifying certificates (i.e. always if +the endpoint is a client, and only if client authentication is in use for a +server). +.PP +Fortunately other organisations do maintain such a set of certificates. If you +have obtained your copy of OpenSSL from an Operating System (OS) vendor (e.g. a +Linux distribution) then normally the set of CA certificates will also be +distributed with that copy. +.PP +You can check this by running the OpenSSL command line application like this: +.PP +.Vb 1 +\& openssl version \-d +.Ve +.PP +This will display a value for \fBOPENSSLDIR\fR. Look in the \fBcerts\fR sub directory +of \fBOPENSSLDIR\fR and check its contents. For example if \fBOPENSSLDIR\fR is +"/usr/local/ssl", then check the contents of the "/usr/local/ssl/certs" +directory. +.PP +You are expecting to see a list of files, typically with the suffix ".pem" or +".0". If they exist then you already have a suitable trusted certificate store. +.PP +If you are running your version of OpenSSL on Windows then OpenSSL (from version +3.2 onwards) will use the default Windows set of trusted CAs. +.PP +If you have built your version of OpenSSL from source, or obtained it from some +other location and it does not have a set of trusted CA certificates then you +will have to obtain them yourself. One such source is the Curl project. See the +page <https://curl.se/docs/caextract.html> where you can download trusted +certificates in a single file. Rename the file to "cert.pem" and store it +directly in \fBOPENSSLDIR\fR. For example if \fBOPENSSLDIR\fR is "/usr/local/ssl", +then save it as "/usr/local/ssl/cert.pem". +.PP +You can also use environment variables to override the default location that +OpenSSL will look for its trusted certificate store. Set the \fBSSL_CERT_PATH\fR +environment variable to give the directory where OpenSSL should looks for its +certificates or the \fBSSL_CERT_FILE\fR environment variable to give the name of +a single file containing all of the certificates. See \fBopenssl\-env\fR\|(7) for +further details about OpenSSL environment variables. For example you could use +this capability to have multiple versions of OpenSSL all installed on the same +system using different values for \fBOPENSSLDIR\fR but all using the same +trusted certificate store. +.PP +You can test that your trusted certificate store is setup correctly by using it +via the OpenSSL command line. Use the following command to connect to a TLS +server: +.PP +.Vb 1 +\& openssl s_client www.openssl.org:443 +.Ve +.PP +Once the command has connected type the letter "Q" followed by "<enter>" to exit +the session. This will print a lot of information on the screen about the +connection. Look for a block of text like this: +.PP +.Vb 2 +\& SSL handshake has read 4584 bytes and written 403 bytes +\& Verification: OK +.Ve +.PP +Hopefully if everything has worked then the "Verification" line will say "OK". +If its not working as expected then you might see output like this instead: +.PP +.Vb 2 +\& SSL handshake has read 4584 bytes and written 403 bytes +\& Verification error: unable to get local issuer certificate +.Ve +.PP +The "unable to get local issuer certificate" error means that OpenSSL has been +unable to find a trusted CA for the chain of certificates provided by the server +in its trusted certificate store. Check your trusted certificate store +configuration again. +.PP +Note that s_client is a testing tool and will still allow you to connect to the +TLS server regardless of the verification error. Most applications should not do +this and should abort the connection in the event of a verification error. +.SH "IMPORTANT OBJECTS FOR AN OPENSSL TLS APPLICATION" +.IX Header "IMPORTANT OBJECTS FOR AN OPENSSL TLS APPLICATION" +A TLS connection is represented by the \fBSSL\fR object in an OpenSSL based +application. Once a connection with a remote peer has been established an +endpoint can "write" data to the \fBSSL\fR object to send data to the peer, or +"read" data from it to receive data from the server. +.PP +A new \fBSSL\fR object is created from an \fBSSL_CTX\fR object. Think of an \fBSSL_CTX\fR +as a "factory" for creating \fBSSL\fR objects. You can create a single \fBSSL_CTX\fR +object and then create multiple connections (i.e. \fBSSL\fR objects) from it. +Typically you can set up common configuration options on the \fBSSL_CTX\fR so that +all the \fBSSL\fR object created from it inherit the same configuration options. +.PP +Note that internally to OpenSSL various items that are shared between multiple +\&\fBSSL\fR objects are cached in the \fBSSL_CTX\fR for performance reasons. Therefore +it is considered best practice to create one \fBSSL_CTX\fR for use by multiple +\&\fBSSL\fR objects instead of having one \fBSSL_CTX\fR for each \fBSSL\fR object that you +create. +.PP +Each \fBSSL\fR object is also associated with two \fBBIO\fR objects. A \fBBIO\fR object +is used for sending or receiving data from the underlying transport layer. For +example you might create a \fBBIO\fR to represent a TCP socket. The \fBSSL\fR object +uses one \fBBIO\fR for reading data and one \fBBIO\fR for writing data. In most cases +you would use the same \fBBIO\fR for each direction but there could be some +circumstances where you want them to be different. +.PP +It is up to the application programmer to create the \fBBIO\fR objects that are +needed and supply them to the \fBSSL\fR object. See +\&\fBossl\-guide\-tls\-client\-block\fR\|(7) for further information. +.PP +Finally, an endpoint can establish a "session" with its peer. The session holds +various TLS parameters about the connection between the client and the server. +The session details can then be reused in a subsequent connection attempt to +speed up the process of connecting. This is known as "resumption". Sessions are +represented in OpenSSL by the \fBSSL_SESSION\fR object. In TLSv1.2 there is always +exactly one session per connection. In TLSv1.3 there can be any number per +connection including none. +.SH "PHASES OF A TLS CONNECTION" +.IX Header "PHASES OF A TLS CONNECTION" +A TLS connection starts with an initial "set up" phase. The endpoint creates the +\&\fBSSL_CTX\fR (if one has not already been created) and configures it. +.PP +A client then creates an \fBSSL\fR object to represent the new TLS connection. Any +connection specific configuration parameters are then applied and the underlying +socket is created and associated with the \fBSSL\fR via \fBBIO\fR objects. +.PP +A server will create a socket for listening for incoming connection attempts +from clients. Once a connection attempt is made the server will create an \fBSSL\fR +object in the same way as for a client and associate it with a \fBBIO\fR for the +newly created incoming socket. +.PP +After set up is complete the TLS "handshake" phase begins. A TLS handshake +consists of the client and server exchanging a series of TLS handshake messages +to establish the connection. The client starts by sending a "ClientHello" +handshake message and the server responds with a "ServerHello". The handshake is +complete once an endpoint has sent its last message (known as the "Finished" +message) and received a Finished message from its peer. Note that this might +occur at slightly different times for each peer. For example in TLSv1.3 the +server always sends its Finished message before the client. The client later +responds with its Finished message. At this point the client has completed the +handshake because it has both sent and received a Finished message. The server +has sent its Finished message but the Finished message from the client may still +be in-flight, so the server is still in the handshake phase. It is even possible +that the server will fail to complete the handshake (if it considers there is +some problem with the messages sent from the client), even though the client may +have already progressed to sending application data. In TLSv1.2 this can happen +the other way around, i.e. the server finishes first and the client finishes +second. +.PP +Once the handshake is complete the application data transfer phase begins. +Strictly speaking there are some situations where the client can start sending +application data even earlier (using the TLSv1.3 "early data" capability) \- but +we're going to skip over that for this basic introduction. +.PP +During application data transfer the client and server can read and write data +to the connection freely. The details of this are typically left to some higher +level application protocol (for example HTTP). Not all information exchanged +during this phase is application data. Some protocol level messages may still +be exchanged \- so it is not necessarily the case that, just because the +underlying socket is "readable", that application data will be available to read. +.PP +When the connection is no longer required then it should be shutdown. A shutdown +may be initiated by either the client or the server via a message known as a +"close_notify" alert. The client or server that receives a close_notify may +respond with one and then the connection is fully closed and application data +can no longer be sent or received. +.PP +Once shutdown is complete a TLS application must clean up by freeing the SSL +object. +.SH "FURTHER READING" +.IX Header "FURTHER READING" +See \fBossl\-guide\-tls\-client\-block\fR\|(7) to see an example of applying these +concepts in order to write a simple TLS client based on a blocking socket. +See \fBossl\-guide\-quic\-introduction\fR\|(7) for an introduction to QUIC in OpenSSL. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7), +\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-client\-block\fR\|(7), +\&\fBossl\-guide\-quic\-introduction\fR\|(7) +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/ossl_store-file.7ssl b/upstream/debian-unstable/man7/ossl_store-file.7ssl index 7d51cb58..1659ef03 100644 --- a/upstream/debian-unstable/man7/ossl_store-file.7ssl +++ b/upstream/debian-unstable/man7/ossl_store-file.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OSSL_STORE-FILE 7SSL" -.TH OSSL_STORE-FILE 7SSL 2024-02-03 3.1.5 OpenSSL +.TH OSSL_STORE-FILE 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/ossl_store.7ssl b/upstream/debian-unstable/man7/ossl_store.7ssl index 14ce1f81..2dc3b367 100644 --- a/upstream/debian-unstable/man7/ossl_store.7ssl +++ b/upstream/debian-unstable/man7/ossl_store.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "OSSL_STORE 7SSL" -.TH OSSL_STORE 7SSL 2024-02-03 3.1.5 OpenSSL +.TH OSSL_STORE 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -129,7 +129,7 @@ other encoding is undefined. \&\fBOSSL_STORE_SEARCH\fR\|(3) .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2016\-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/packet.7 b/upstream/debian-unstable/man7/packet.7 index b2a264ca..1f75c580 100644 --- a/upstream/debian-unstable/man7/packet.7 +++ b/upstream/debian-unstable/man7/packet.7 @@ -4,7 +4,7 @@ .\" .\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $ .\" -.TH packet 7 2023-07-15 "Linux man-pages 6.05.01" +.TH packet 7 2024-05-02 "Linux man-pages 6.8" .SH NAME packet \- packet interface on device level .SH SYNOPSIS @@ -12,7 +12,7 @@ packet \- packet interface on device level .B #include <sys/socket.h> .B #include <linux/if_packet.h> .B #include <net/ethernet.h> /* the L2 protocols */ -.PP +.P .BI "packet_socket = socket(AF_PACKET, int " socket_type ", int "protocol ); .fi .SH DESCRIPTION @@ -20,7 +20,7 @@ Packet sockets are used to receive or send raw packets at the device driver (OSI Layer 2) level. They allow the user to implement protocol modules in user space on top of the physical layer. -.PP +.P The .I socket_type is either @@ -50,11 +50,11 @@ no packets are received. can optionally be called with a nonzero .I sll_protocol to start receiving packets for the protocols specified. -.PP +.P In order to create a packet socket, a process must have the .B CAP_NET_RAW capability in the user namespace that governs its network namespace. -.PP +.P .B SOCK_RAW packets are passed to and from the device driver without any changes in the packet data. @@ -72,7 +72,7 @@ Some device drivers always add other headers. is similar to but not compatible with the obsolete .B AF_INET/SOCK_PACKET of Linux 2.0. -.PP +.P .B SOCK_DGRAM operates on a slightly higher level. The physical header is removed before the packet is passed to the user. @@ -82,7 +82,7 @@ packet socket get a suitable physical-layer header based on the information in the .I sockaddr_ll destination address before they are queued. -.PP +.P By default, all packets of the specified protocol type are passed to a packet socket. To get packets only from a specific interface use @@ -97,11 +97,11 @@ Fields used for binding are .IR sll_protocol , and .IR sll_ifindex . -.PP +.P The .BR connect (2) operation is not supported on packet sockets. -.PP +.P When the .B MSG_TRUNC flag is passed to @@ -115,7 +115,7 @@ even when it is longer than the buffer. The .I sockaddr_ll structure is a device-independent physical-layer address. -.PP +.P .in +4n .EX struct sockaddr_ll { @@ -129,7 +129,7 @@ struct sockaddr_ll { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I sll_protocol @@ -171,7 +171,7 @@ These types make sense only for receiving. .I sll_halen contain the physical-layer (e.g., IEEE 802.3) address and its length. The exact interpretation depends on the device. -.PP +.P When you send packets, it is enough to specify .IR sll_family , .IR sll_addr , @@ -502,7 +502,7 @@ Argument is a .I struct timeval variable. .\" FIXME Document SIOCGSTAMPNS -.PP +.P In addition, all standard ioctls defined in .BR netdevice (7) and @@ -546,7 +546,7 @@ Interface address contained an invalid interface index. .TP .B EPERM User has insufficient privileges to carry out this operation. -.PP +.P In addition, other errors may be generated by the low-level driver. .SH VERSIONS .B AF_PACKET @@ -561,7 +561,7 @@ via although this covers only a subset of the .B AF_PACKET features. -.PP +.P The .B SOCK_DGRAM packet sockets make no attempt to create or parse the IEEE 802.2 LLC @@ -582,17 +582,17 @@ bind to instead and do the protocol multiplex yourself. The default for sending is the standard Ethernet DIX encapsulation with the protocol filled in. -.PP +.P Packet sockets are not subject to the input or output firewall chains. .SS Compatibility In Linux 2.0, the only way to get a packet socket was with the call: -.PP +.P .in +4n .EX socket(AF_INET, SOCK_PACKET, protocol) .EE .in -.PP +.P This is still supported, but deprecated and strongly discouraged. The main difference between the two methods is that .B SOCK_PACKET @@ -600,7 +600,7 @@ uses the old .I struct sockaddr_pkt to specify an interface, which doesn't provide physical-layer independence. -.PP +.P .in +4n .EX struct sockaddr_pkt { @@ -610,7 +610,7 @@ struct sockaddr_pkt { }; .EE .in -.PP +.P .I spkt_family contains the device type, @@ -620,7 +620,7 @@ is the IEEE 802.3 protocol type as defined in and .I spkt_device is the device name as a null-terminated string, for example, eth0. -.PP +.P This structure is obsolete and should not be used in new code. .SH BUGS .SS LLC header handling @@ -648,12 +648,12 @@ This means the names of network devices longer than 14 bytes will be truncated to fit into .IR spkt_device . All these lengths include the terminating null byte (\[aq]\e0\[aq])). -.PP +.P Issues from this with old code typically show up with very long interface names used by the .B Predictable Network Interface Names feature enabled by default in many modern Linux distributions. -.PP +.P The preferred solution is to rewrite code to avoid .BR SOCK_PACKET . Possible user solutions are to disable @@ -676,14 +676,14 @@ Socket filters are not documented. .BR raw (7), .BR socket (7), .BR ip (8), -.PP +.P RFC\ 894 for the standard IP Ethernet encapsulation. RFC\ 1700 for the IEEE 802.3 IP encapsulation. -.PP +.P The .I <linux/if_ether.h> include file for physical-layer protocols. -.PP +.P The Linux kernel source tree. .I Documentation/networking/filter.rst describes how to apply Berkeley Packet Filters to packet sockets. diff --git a/upstream/debian-unstable/man7/passphrase-encoding.7ssl b/upstream/debian-unstable/man7/passphrase-encoding.7ssl index aeffac00..384a56e7 100644 --- a/upstream/debian-unstable/man7/passphrase-encoding.7ssl +++ b/upstream/debian-unstable/man7/passphrase-encoding.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PASSPHRASE-ENCODING 7SSL" -.TH PASSPHRASE-ENCODING 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PASSPHRASE-ENCODING 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/path_resolution.7 b/upstream/debian-unstable/man7/path_resolution.7 index 17046031..7569dec1 100644 --- a/upstream/debian-unstable/man7/path_resolution.7 +++ b/upstream/debian-unstable/man7/path_resolution.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH path_resolution 7 2023-02-05 "Linux man-pages 6.05.01" +.TH path_resolution 7 2024-05-02 "Linux man-pages 6.8" .SH NAME path_resolution \- how a pathname is resolved to a file .SH DESCRIPTION @@ -20,7 +20,7 @@ system call, or may temporarily use a different root directory by using with the .B RESOLVE_IN_ROOT flag set. -.PP +.P A process may get an entirely private mount namespace in case it\[em]or one of its ancestors\[em]was started by an invocation of the .BR clone (2) @@ -28,7 +28,7 @@ system call that had the .B CLONE_NEWNS flag set. This handles the \[aq]/\[aq] part of the pathname. -.PP +.P If the pathname does not start with the \[aq]/\[aq] character, the starting lookup directory of the resolution process is the current working directory of the process \[em] or in the case of @@ -44,7 +44,7 @@ The current working directory is inherited from the parent, and can be changed by use of the .BR chdir (2) system call. -.PP +.P Pathnames starting with a \[aq]/\[aq] character are called absolute pathnames. Pathnames not starting with a \[aq]/\[aq] are called relative pathnames. .SS Step 2: walk along the path @@ -52,27 +52,27 @@ Set the current lookup directory to the starting lookup directory. Now, for each nonfinal component of the pathname, where a component is a substring delimited by \[aq]/\[aq] characters, this component is looked up in the current lookup directory. -.PP +.P If the process does not have search permission on the current lookup directory, an .B EACCES error is returned ("Permission denied"). -.PP +.P If the component is not found, an .B ENOENT error is returned ("No such file or directory"). -.PP +.P If the component is found, but is neither a directory nor a symbolic link, an .B ENOTDIR error is returned ("Not a directory"). -.PP +.P If the component is found and is a directory, we set the current lookup directory to that directory, and go to the next component. -.PP +.P If the component is found and is a symbolic link, we first resolve this symbolic link (with the current lookup directory @@ -96,7 +96,7 @@ An .B ELOOP error is returned when the maximum is exceeded ("Too many levels of symbolic links"). -.PP +.P .\" .\" presently: max recursion depth during symlink resolution: 5 .\" max total number of symbolic links followed: 40 @@ -114,7 +114,7 @@ the kernel's pathname-resolution code was reworked to eliminate the use of recursion, so that the only limit that remains is the maximum of 40 resolutions for the entire pathname. -.PP +.P The resolution of symbolic links during this stage can be blocked by using .BR openat2 (2), with the @@ -132,15 +132,15 @@ we are just creating it. The details on the treatment of the final entry are described in the manual pages of the specific system calls. -.SS . and .. +.SS "\&. and .." By convention, every directory has the entries "." and "..", which refer to the directory itself and to its parent directory, respectively. -.PP +.P The path resolution process will assume that these entries have their conventional meanings, regardless of whether they are actually present in the physical filesystem. -.PP +.P One cannot walk up past the root: "/.." is the same as "/". .SS Mount points After a @@ -148,11 +148,11 @@ After a command, the pathname "path" refers to the root of the filesystem hierarchy on the device "dev", and no longer to whatever it referred to earlier. -.PP +.P One can walk out of a mounted filesystem: "path/.." refers to the parent directory of "path", outside of the filesystem hierarchy on "dev". -.PP +.P Traversal of mount points can be blocked by using .BR openat2 (2), with the @@ -202,16 +202,16 @@ effective group ID of the calling process, or is one of the supplementary group IDs of the calling process (as set by .BR setgroups (2)). When neither holds, the third group is used. -.PP +.P Of the three bits used, the first bit determines read permission, the second write permission, and the last execute permission in case of ordinary files, or search permission in case of directories. -.PP +.P Linux uses the fsuid instead of the effective user ID in permission checks. Ordinarily the fsuid will equal the effective user ID, but the fsuid can be changed by the system call .BR setfsuid (2). -.PP +.P (Here "fsuid" stands for something like "filesystem user ID". The concept was required for the implementation of a user space NFS server at a time when processes could send a signal to a process @@ -219,7 +219,7 @@ with the same effective user ID. It is obsolete now. Nobody should use .BR setfsuid (2).) -.PP +.P Similarly, Linux uses the fsgid ("filesystem group ID") instead of the effective group ID. See @@ -236,7 +236,7 @@ when accessing files. .\" on some implementations (e.g., Solaris, FreeBSD), .\" access(X_OK) by superuser will report success, regardless .\" of the file's execute permission bits. -- MTK (Oct 05) -.PP +.P On Linux, superuser privileges are divided into capabilities (see .BR capabilities (7)). Two capabilities are relevant for file permissions checks: @@ -244,13 +244,13 @@ Two capabilities are relevant for file permissions checks: and .BR CAP_DAC_READ_SEARCH . (A process has these capabilities if its fsuid is 0.) -.PP +.P The .B CAP_DAC_OVERRIDE capability overrides all permission checking, but grants execute permission only when at least one of the file's three execute permission bits is set. -.PP +.P The .B CAP_DAC_READ_SEARCH capability grants read and search permission diff --git a/upstream/debian-unstable/man7/pcilib.7 b/upstream/debian-unstable/man7/pcilib.7 index 71041c0c..6df46c18 100644 --- a/upstream/debian-unstable/man7/pcilib.7 +++ b/upstream/debian-unstable/man7/pcilib.7 @@ -1,4 +1,4 @@ -.TH pcilib 7 "01 May 2023" "pciutils-3.10.0" "The PCI Utilities" +.TH pcilib 7 "05 April 2024" "pciutils-3.12.0" "The PCI Utilities" .SH NAME pcilib \- a library for accessing PCI devices @@ -146,6 +146,9 @@ Archived download links of previous WinDbg versions: https://web.archive.org/web/20110221133326/https://www.microsoft.com/whdc/devtools/debugging/installx86.mspx .br https://web.archive.org/web/20110214012715/https://www.microsoft.com/whdc/devtools/debugging/install64bit.mspx +.TP +.B aos-expansion +Access method used on PowerPC Amiga running OS4+. Access is made through Expansion.library. It offers read and write access to configuration space. .SH PARAMETERS @@ -234,7 +237,9 @@ Configuration Manager. DNS domain containing the ID database. .TP .B net.cache_name -Name of the file used for caching of resolved ID's. +Name of the file used for caching of resolved ID's. An initial +.B ~/ +is expanded to the user's home directory. .SS Parameters for resolving of ID's via UDEV's HWDB .TP diff --git a/upstream/debian-unstable/man7/persistent-keyring.7 b/upstream/debian-unstable/man7/persistent-keyring.7 index 472782ab..5ac853a7 100644 --- a/upstream/debian-unstable/man7/persistent-keyring.7 +++ b/upstream/debian-unstable/man7/persistent-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH persistent-keyring 7 2023-02-08 "Linux man-pages 6.05.01" +.TH persistent-keyring 7 2024-05-02 "Linux man-pages 6.8" .SH NAME persistent-keyring \- per-user persistent keyring .SH DESCRIPTION @@ -15,7 +15,7 @@ The persistent keyring has a name (description) of the form where .I <UID> is the user ID of the corresponding user. -.PP +.P The persistent keyring may not be accessed directly, even by processes with the appropriate UID. .\" FIXME The meaning of the preceding sentence isn't clear. What is meant? @@ -25,34 +25,34 @@ by virtue of its possessor permits. This linking is done with the .BR keyctl_get_persistent (3) function. -.PP +.P If a persistent keyring does not exist when it is accessed by the .BR keyctl_get_persistent (3) operation, it will be automatically created. -.PP +.P Each time the .BR keyctl_get_persistent (3) operation is performed, the persistent keyring's expiration timer is reset to the value in: -.PP +.P .in +4n .EX /proc/sys/kernel/keys/persistent_keyring_expiry .EE .in -.PP +.P Should the timeout be reached, the persistent keyring will be removed and everything it pins can then be garbage collected. The keyring will then be re-created on a subsequent call to .BR keyctl_get_persistent (3). -.PP +.P The persistent keyring is not directly searched by .BR request_key (2); it is searched only if it is linked into one of the keyrings that is searched by .BR request_key (2). -.PP +.P The persistent keyring is independent of .BR clone (2), .BR fork (2), @@ -72,7 +72,7 @@ The persistent keyring can thus be used to hold authentication tokens for processes that run without user interaction, such as programs started by .BR cron (8). -.PP +.P The persistent keyring is used to store UID-specific objects that themselves have limited lifetimes (e.g., kerberos tokens). If those tokens cease to be used diff --git a/upstream/debian-unstable/man7/pid_namespaces.7 b/upstream/debian-unstable/man7/pid_namespaces.7 index b154fb4c..b757e7ae 100644 --- a/upstream/debian-unstable/man7/pid_namespaces.7 +++ b/upstream/debian-unstable/man7/pid_namespaces.7 @@ -4,20 +4,20 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH pid_namespaces 7 2023-03-30 "Linux man-pages 6.05.01" +.TH pid_namespaces 7 2024-05-02 "Linux man-pages 6.8" .SH NAME pid_namespaces \- overview of Linux PID namespaces .SH DESCRIPTION For an overview of namespaces, see .BR namespaces (7). -.PP +.P PID namespaces isolate the process ID number space, meaning that processes in different PID namespaces can have the same PID. PID namespaces allow containers to provide functionality such as suspending/resuming the set of processes in the container and migrating the container to a new host while the processes inside the container maintain the same PIDs. -.PP +.P PIDs in a new PID namespace start at 1, somewhat like a standalone system, and calls to .BR fork (2), @@ -25,7 +25,7 @@ somewhat like a standalone system, and calls to or .BR clone (2) will produce processes with PIDs that are unique within the namespace. -.PP +.P Use of PID namespaces requires a kernel that is configured with the .B CONFIG_PID_NS option. @@ -47,7 +47,7 @@ flag) has the PID 1, and is the "init" process for the namespace (see This process becomes the parent of any child processes that are orphaned because a process that resides in this PID namespace terminated (see below for further details). -.PP +.P If the "init" process of a PID namespace terminates, the kernel terminates all of the processes in the namespace via a .B SIGKILL @@ -74,13 +74,13 @@ terminates, then subsequent calls to .BR fork (2) fail with .BR ENOMEM . -.PP +.P Only signals for which the "init" process has established a signal handler can be sent to the "init" process by other members of the PID namespace. This restriction applies even to privileged processes, and prevents other members of the PID namespace from accidentally killing the "init" process. -.PP +.P Likewise, a process in an ancestor namespace can\[em]subject to the usual permission checks described in .BR kill (2)\[em]send @@ -100,7 +100,7 @@ these signals are forcibly delivered when sent from an ancestor PID namespace. Neither of these signals can be caught by the "init" process, and so will result in the usual actions associated with those signals (respectively, terminating and stopping the process). -.PP +.P Starting with Linux 3.4, the .BR reboot (2) system call causes a signal to be sent to the namespace "init" process. @@ -125,7 +125,7 @@ Since Linux 3.7, .\" commit f2302505775fd13ba93f034206f1e2a587017929 .\" The kernel constant MAX_PID_NS_LEVEL the kernel limits the maximum nesting depth for PID namespaces to 32. -.PP +.P A process is visible to other processes in its PID namespace, and to the processes in each direct ancestor PID namespace going back to the root PID namespace. @@ -140,7 +140,7 @@ set nice values with .BR setpriority (2), etc.) only processes contained in its own PID namespace and in descendants of that namespace. -.PP +.P A process has one process ID in each of the layers of the PID namespace hierarchy in which is visible, and walking back though each direct ancestor namespace @@ -152,7 +152,7 @@ A call to .BR getpid (2) always returns the PID associated with the namespace in which the process was created. -.PP +.P Some processes in a PID namespace may have parents that are outside of the namespace. For example, the parent of the initial process in the namespace @@ -167,7 +167,7 @@ PID namespace from the caller of Calls to .BR getppid (2) for such processes return 0. -.PP +.P While processes may freely descend into child PID namespaces (e.g., using .BR setns (2) @@ -176,7 +176,7 @@ they may not move in the other direction. That is to say, processes may not enter any ancestor namespaces (parent, grandparent, etc.). Changing PID namespaces is a one-way operation. -.PP +.P The .B NS_GET_PARENT .BR ioctl (2) @@ -206,7 +206,7 @@ because doing so would change the caller's idea of its own PID (as reported by .BR getpid ()), which would break many applications and libraries. -.PP +.P To put things another way: a process's PID namespace membership is determined when the process is created and cannot be changed thereafter. @@ -214,7 +214,7 @@ Among other things, this means that the parental relationship between processes mirrors the parental relationship between PID namespaces: the parent of a process is either in the same namespace or resides in the immediate parent PID namespace. -.PP +.P A process may call .BR unshare (2) with the @@ -268,7 +268,7 @@ type in Since this is computed when a signal is enqueued, a signal queue shared by processes in multiple PID namespaces would defeat that. -.PP +.P .\" Note these restrictions were all introduced in .\" 8382fcac1b813ad0a4e68a838fc7ae93fa39eda0 .\" when CLONE_NEWPID|CLONE_VM was disallowed @@ -297,7 +297,7 @@ directories) only processes visible in the PID namespace of the process that performed the mount, even if the .I /proc filesystem is viewed from processes in other namespaces. -.PP +.P After creating a new PID namespace, it is useful for the child to change its root directory and mount a new procfs instance at @@ -316,17 +316,17 @@ or then it isn't necessary to change the root directory: a new procfs instance can be mounted directly over .IR /proc . -.PP +.P From a shell, the command to mount .I /proc is: -.PP +.P .in +4n .EX $ mount \-t proc proc /proc .EE .in -.PP +.P Calling .BR readlink (2) on the path diff --git a/upstream/debian-unstable/man7/pipe.7 b/upstream/debian-unstable/man7/pipe.7 index baf05bc4..bc7f0e7c 100644 --- a/upstream/debian-unstable/man7/pipe.7 +++ b/upstream/debian-unstable/man7/pipe.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pipe 7 2023-07-16 "Linux man-pages 6.05.01" +.TH pipe 7 2024-05-02 "Linux man-pages 6.8" .SH NAME pipe \- overview of pipes and FIFOs .SH DESCRIPTION @@ -14,7 +14,7 @@ and a .IR "write end" . Data written to the write end of a pipe can be read from the read end of the pipe. -.PP +.P A pipe is created using .BR pipe (2), which creates a new pipe and returns two file descriptors, @@ -24,7 +24,7 @@ Pipes can be used to create a communication channel between related processes; see .BR pipe (2) for an example. -.PP +.P A FIFO (short for First In First Out) has a name within the filesystem (created using .BR mkfifo (3)), @@ -48,7 +48,7 @@ The only difference between pipes and FIFOs is the manner in which they are created and opened. Once these tasks have been accomplished, I/O on pipes and FIFOs has exactly the same semantics. -.PP +.P If a process attempts to read from an empty pipe, then .BR read (2) will block until data is available. @@ -56,7 +56,7 @@ If a process attempts to write to a full pipe (see below), then .BR write (2) blocks until sufficient data has been read from the pipe to allow the write to complete. -.PP +.P Nonblocking I/O is possible by using the .BR fcntl (2) .B F_SETFL @@ -69,11 +69,11 @@ with If any process has the pipe open for writing, reads fail with .BR EAGAIN ; otherwise\[em]with no potential writers\[em]reads succeed and return empty. -.PP +.P The communication channel provided by a pipe is a .IR "byte stream" : there is no concept of message boundaries. -.PP +.P If all file descriptors referring to the write end of a pipe have been closed, then an attempt to .BR read (2) @@ -100,7 +100,7 @@ calls to close unnecessary duplicate file descriptors; this ensures that end-of-file and .BR SIGPIPE / EPIPE are delivered when appropriate. -.PP +.P It is not possible to apply .BR lseek (2) to a pipe. @@ -116,7 +116,7 @@ Applications should not rely on a particular capacity: an application should be designed so that a reading process consumes data as soon as it is available, so that a writing process does not remain blocked. -.PP +.P Before Linux 2.6.11, the capacity of a pipe was the same as the system page size (e.g., 4096 bytes on i386). Since Linux 2.6.11, the pipe capacity is 16 pages @@ -131,7 +131,7 @@ operations. See .BR fcntl (2) for more information. -.PP +.P The following .BR ioctl (2) operation, which can be applied to a file descriptor @@ -139,13 +139,13 @@ that refers to either end of a pipe, places a count of the number of unread bytes in the pipe in the .I int buffer pointed to by the final argument of the call: -.PP +.P .in +4n .EX ioctl(fd, FIONREAD, &nbytes); .EE .in -.PP +.P The .B FIONREAD operation is not specified in any standard, @@ -227,7 +227,7 @@ and attempts to increase a pipe's capacity will be denied. When the value of this limit is zero, no soft limit is applied. The default value for this file is 16384, which permits creating up to 1024 pipes with the default capacity. -.PP +.P Before Linux 4.9, some bugs affected the handling of the .I pipe\-user\-pages\-soft and @@ -310,7 +310,7 @@ a pipe or FIFO are .B O_NONBLOCK and .BR O_ASYNC . -.PP +.P Setting the .B O_ASYNC flag for the read end of a pipe causes a signal @@ -383,7 +383,7 @@ allocation could be pushed over the limit. Starting with Linux 4.9, the accounting step is performed before doing the allocation, and the operation fails if the limit would be exceeded. -.PP +.P Before Linux 4.9, bugs similar to points (a) and (c) could also occur when the kernel allocated memory for a new pipe buffer; that is, when calling diff --git a/upstream/debian-unstable/man7/pkeys.7 b/upstream/debian-unstable/man7/pkeys.7 index 4f96f1e5..15dee30a 100644 --- a/upstream/debian-unstable/man7/pkeys.7 +++ b/upstream/debian-unstable/man7/pkeys.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pkeys 7 2023-05-03 "Linux man-pages 6.05.01" +.TH pkeys 7 2024-05-02 "Linux man-pages 6.8" .SH NAME pkeys \- overview of Memory Protection Keys .SH DESCRIPTION @@ -14,13 +14,13 @@ when changing permissions. Memory Protection Keys provide a mechanism for changing protections without requiring modification of the page tables on every permission change. -.PP +.P To use pkeys, software must first "tag" a page in the page tables with a pkey. After this tag is in place, an application only has to change the contents of a register in order to remove write access, or all access to a tagged page. -.PP +.P Protection keys work in conjunction with the existing .BR PROT_READ , .BR PROT_WRITE , @@ -32,7 +32,7 @@ and .BR mmap (2), but always act to further restrict these traditional permission mechanisms. -.PP +.P If a process performs an access that violates pkey restrictions, it receives a .B SIGSEGV @@ -40,7 +40,7 @@ signal. See .BR sigaction (2) for details of the information available with that signal. -.PP +.P To use the pkeys feature, the processor must support it, and the kernel must contain support for the feature on a given processor. As of early 2016 only future Intel x86 processors are supported, @@ -50,7 +50,7 @@ are available for actual application use. The default key is assigned to any memory region for which a pkey has not been explicitly assigned via .BR pkey_mprotect (2). -.PP +.P Protection keys have the potential to add a layer of security and reliability to applications. But they have not been primarily designed as @@ -58,7 +58,7 @@ a security feature. For instance, WRPKRU is a completely unprivileged instruction, so pkeys are useless in any case that an attacker controls the PKRU register or can execute arbitrary instructions. -.PP +.P Applications should be very careful to ensure that they do not "leak" protection keys. For instance, before calling @@ -77,7 +77,7 @@ Applications may implement these checks by searching the file for memory regions with the pkey assigned. Further details can be found in .BR proc (5). -.PP +.P Any application wanting to use protection keys needs to be able to function without them. They might be unavailable because the hardware that the @@ -91,7 +91,7 @@ keys should simply call and test whether the call succeeds, instead of attempting to detect support for the feature in any other way. -.PP +.P Although unnecessary, hardware support for protection keys may be enumerated with the .I cpuid @@ -104,7 +104,7 @@ under the "flags" field. The string "pku" in this field indicates hardware support for protection keys and the string "ospke" indicates that the kernel contains and has enabled protection keys support. -.PP +.P Applications using threads and protection keys should be especially careful. Threads inherit the protection key rights of the parent at the time @@ -126,7 +126,7 @@ key rights upon entering a signal handler if the desired rights differ from the defaults. The rights of any interrupted context are restored when the signal handler returns. -.PP +.P This signal behavior is unusual and is due to the fact that the x86 PKRU register (which stores protection key access rights) is managed with the same hardware mechanism (XSAVE) that manages floating-point registers. @@ -138,7 +138,7 @@ The Linux kernel implements the following pkey-related system calls: .BR pkey_alloc (2), and .BR pkey_free (2). -.PP +.P The Linux pkey system calls are available only if the kernel was configured and built with the .B CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS @@ -151,7 +151,7 @@ After that, it attempts to allocate a protection key and disallows access to the page by using the WRPKRU instruction. It then tries to access the page, which we now expect to cause a fatal signal to the application. -.PP +.P .in +4n .EX .RB "$" " ./a.out" diff --git a/upstream/debian-unstable/man7/posixoptions.7 b/upstream/debian-unstable/man7/posixoptions.7 index b0dea3de..8ab56463 100644 --- a/upstream/debian-unstable/man7/posixoptions.7 +++ b/upstream/debian-unstable/man7/posixoptions.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH posixoptions 7 2022-10-30 "Linux man-pages 6.05.01" +.TH posixoptions 7 2024-05-02 "Linux man-pages 6.8" .SH NAME posixoptions \- optional parts of the POSIX standard .SH DESCRIPTION @@ -19,7 +19,7 @@ From shell scripts one can use .BR getconf (1). For more detail, see .BR sysconf (3). -.PP +.P We give the name of the POSIX abbreviation, the option, the name of the .BR sysconf (3) parameter used to inquire about the option, and possibly @@ -28,7 +28,7 @@ Much more precise detail can be found in the POSIX standard itself, versions of which can nowadays be accessed freely on the web. .SS ADV - _POSIX_ADVISORY_INFO - _SC_ADVISORY_INFO The following advisory functions are present: -.PP +.P .nf .in +4n .IR posix_fadvise () @@ -42,7 +42,7 @@ The header .I <aio.h> is present. The following functions are present: -.PP +.P .nf .in +4n .IR aio_cancel () @@ -62,7 +62,7 @@ and .B _POSIX_THREAD_SAFE_FUNCTIONS options. The following functions are present: -.PP +.P .nf .in +4n .IR pthread_barrier_destroy () @@ -80,8 +80,8 @@ The following functions are present: If this option is in effect (as it always is under POSIX.1-2001), then only root may change the owner of a file, and nonroot can set the group of a file only to one of the groups it belongs to. -This affects the following functions -.PP +This affects the following functions: +.P .nf .in +4n .IR chown () @@ -94,7 +94,7 @@ This option implies the .B _POSIX_TIMERS option. The following functions are present: -.PP +.P .nf .in +4n .IR pthread_condattr_getclock () @@ -102,7 +102,7 @@ The following functions are present: .IR clock_nanosleep () .in .fi -.PP +.P If .B CLOCK_REALTIME is changed by the function @@ -136,7 +136,7 @@ Internet Protocol Version 6 is supported. If this option is in effect (as it always is under POSIX.1-2001), then the system implements POSIX-style job control, and the following functions are present: -.PP +.P .nf .in +4n .IR setpgid () @@ -154,7 +154,7 @@ The include file .I <sys/mman.h> is present. The following functions are present: -.PP +.P .nf .in +4n .IR mmap () @@ -165,7 +165,7 @@ The following functions are present: .SS ML - _POSIX_MEMLOCK - _SC_MEMLOCK Shared memory can be locked into core. The following functions are present: -.PP +.P .nf .in +4n .IR mlockall () @@ -175,7 +175,7 @@ The following functions are present: .SS MR/MLR - _POSIX_MEMLOCK_RANGE - _SC_MEMLOCK_RANGE More precisely, ranges can be locked into core. The following functions are present: -.PP +.P .nf .in +4n .IR mlock () @@ -191,7 +191,7 @@ The include file .I <mqueue.h> is present. The following functions are present: -.PP +.P .nf .in +4n .IR mq_close () @@ -211,7 +211,7 @@ This option implies the .B _POSIX_TIMERS option. The following functions are affected: -.PP +.P .nf .in +4n .IR aio_suspend () @@ -236,7 +236,7 @@ This property may be dependent on the path prefix of the component. .SS PIO - _POSIX_PRIORITIZED_IO - _SC_PRIORITIZED_IO This option says that one can specify priorities for asynchronous I/O. This affects the functions -.PP +.P .nf .in +4n .IR aio_read () @@ -248,7 +248,7 @@ The include file .I <sched.h> is present. The following functions are present: -.PP +.P .nf .in +4n .IR sched_get_priority_max () @@ -261,11 +261,11 @@ The following functions are present: .IR sched_yield () .in .fi -.PP +.P If also .B _POSIX_SPAWN is in effect, then the following functions are present: -.PP +.P .nf .in +4n .IR posix_spawnattr_getschedparam () @@ -277,7 +277,7 @@ is in effect, then the following functions are present: .SS RS - _POSIX_RAW_SOCKETS Raw sockets are supported. The following functions are affected: -.PP +.P .nf .in +4n .IR getsockopt () @@ -292,9 +292,9 @@ Conversely, under POSIX.1-2001 the .B _POSIX_THREADS option implies this option. -.PP +.P The following functions are present: -.PP +.P .in +4n .nf .IR pthread_rwlock_destroy () @@ -311,7 +311,7 @@ The following functions are present: .SS RTS - _POSIX_REALTIME_SIGNALS - _SC_REALTIME_SIGNALS Realtime signals are supported. The following functions are present: -.PP +.P .nf .in +4n .IR sigqueue () @@ -323,7 +323,7 @@ The following functions are present: If this option is in effect (as it always is under POSIX.1-2001), then POSIX regular expressions are supported and the following functions are present: -.PP +.P .nf .in +4n .IR regcomp () @@ -336,7 +336,7 @@ and the following functions are present: If this option is in effect (as it always is under POSIX.1-2001), then a process has a saved set-user-ID and a saved set-group-ID. The following functions are affected: -.PP +.P .nf .in +4n .IR exec () @@ -354,7 +354,7 @@ The include file .I <semaphore.h> is present. The following functions are present: -.PP +.P .nf .in +4n .IR sem_close () @@ -370,7 +370,7 @@ The following functions are present: .fi .SS SHM - _POSIX_SHARED_MEMORY_OBJECTS - _SC_SHARED_MEMORY_OBJECTS The following functions are present: -.PP +.P .nf .in +4n .IR mmap () @@ -389,13 +389,13 @@ This option describes support for process creation in a context where it is difficult or impossible to use .IR fork (), for example, because no MMU is present. -.PP +.P If .B _POSIX_SPAWN is in effect, then the include file .I <spawn.h> and the following functions are present: -.PP +.P .nf .in +4n .IR posix_spawn () @@ -417,12 +417,12 @@ and the following functions are present: .IR posix_spawnp () .in .fi -.PP +.P If also .B _POSIX_PRIORITY_SCHEDULING is in effect, then the following functions are present: -.PP +.P .nf .in +4n .IR posix_spawnattr_getschedparam () @@ -438,7 +438,7 @@ and .B _POSIX_THREAD_SAFE_FUNCTIONS options. The following functions are present: -.PP +.P .nf .in +4n .IR pthread_spin_destroy () @@ -456,7 +456,7 @@ This option implies the .B _POSIX_PRIORITY_SCHEDULING option. The following functions are affected: -.PP +.P .nf .in +4n .IR sched_setparam () @@ -465,7 +465,7 @@ The following functions are affected: .fi .SS SIO - _POSIX_SYNCHRONIZED_IO - _SC_SYNCHRONIZED_IO The following functions are affected: -.PP +.P .nf .in +4n .IR open () @@ -476,7 +476,7 @@ The following functions are affected: .fi .SS TSA - _POSIX_THREAD_ATTR_STACKADDR - _SC_THREAD_ATTR_STACKADDR The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_attr_getstack () @@ -487,7 +487,7 @@ The following functions are affected: .fi .SS TSS - _POSIX_THREAD_ATTR_STACKSIZE - _SC_THREAD_ATTR_STACKSIZE The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_attr_getstack () @@ -502,7 +502,7 @@ This option implies the .B _POSIX_TIMERS option. The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_getcpuclockid () @@ -514,7 +514,7 @@ The following functions are affected: .fi .SS TPI - _POSIX_THREAD_PRIO_INHERIT - _SC_THREAD_PRIO_INHERIT The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_mutexattr_getprotocol () @@ -523,7 +523,7 @@ The following functions are affected: .fi .SS TPP - _POSIX_THREAD_PRIO_PROTECT - _SC_THREAD_PRIO_PROTECT The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_mutex_getprioceiling () @@ -538,7 +538,7 @@ The following functions are affected: If this option is in effect, the different threads inside a process can run with different priorities and/or different schedulers. The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_attr_getinheritsched () @@ -554,7 +554,7 @@ The following functions are affected: .fi .SS TSH - _POSIX_THREAD_PROCESS_SHARED - _SC_THREAD_PROCESS_SHARED The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_barrierattr_getpshared () @@ -569,7 +569,7 @@ The following functions are affected: .fi .SS TSF - _POSIX_THREAD_SAFE_FUNCTIONS - _SC_THREAD_SAFE_FUNCTIONS The following functions are affected: -.PP +.P .nf .in +4n .IR readdir_r () @@ -598,7 +598,7 @@ This option implies the .B _POSIX_THREAD_PRIORITY_SCHEDULING option. The following functions are affected: -.PP +.P .nf .in +4n .IR sched_getparam () @@ -609,7 +609,7 @@ The following functions are affected: .SS THR - _POSIX_THREADS - _SC_THREADS Basic support for POSIX threads is available. The following functions are present: -.PP +.P .nf .in +4n .IR pthread_atfork () @@ -664,7 +664,7 @@ The following functions are present: .fi .SS TMO - _POSIX_TIMEOUTS - _SC_TIMEOUTS The following functions are present: -.PP +.P .nf .in +4n .IR mq_timedreceive () @@ -678,7 +678,7 @@ The following functions are present: .fi .SS TMR - _POSIX_TIMERS - _SC_TIMERS The following functions are present: -.PP +.P .nf .in +4n .IR clock_getres () @@ -695,7 +695,7 @@ The following functions are present: .SS TRC - _POSIX_TRACE - _SC_TRACE POSIX tracing is available. The following functions are present: -.PP +.P .nf .in +4n .IR posix_trace_attr_destroy () @@ -736,7 +736,7 @@ This option implies the .B _POSIX_TRACE option. The following functions are present: -.PP +.P .nf .in +4n .IR posix_trace_eventset_add () @@ -755,7 +755,7 @@ This option implies the .B _POSIX_TRACE option. The following functions are present: -.PP +.P .nf .in +4n .IR posix_trace_attr_getinherited () @@ -767,7 +767,7 @@ This option implies the .B _POSIX_TRACE option. The following functions are present: -.PP +.P .nf .in +4n .IR posix_trace_attr_getlogfullpolicy () @@ -782,7 +782,7 @@ The following functions are present: .fi .SS TYM - _POSIX_TYPED_MEMORY_OBJECTS - _SC_TYPED_MEMORY_OBJECT The following functions are present: -.PP +.P .nf .in +4n .IR posix_mem_offset () @@ -797,7 +797,7 @@ character to indicate that it is disabled. .SH X/OPEN SYSTEM INTERFACE EXTENSIONS .SS XSI - _XOPEN_CRYPT - _SC_XOPEN_CRYPT The following functions are present: -.PP +.P .nf .in +4n .IR crypt () @@ -806,7 +806,7 @@ The following functions are present: .fi .SS XSI - _XOPEN_REALTIME - _SC_XOPEN_REALTIME This option implies the following options: -.PP +.P .PD 0 .TP .BR _POSIX_ASYNCHRONOUS_IO == 200112L @@ -841,7 +841,7 @@ This option implies the following options: .SS ADV - --- - --- The Advanced Realtime option group implies that the following options are all defined to 200112L: -.PP +.P .PD 0 .TP .B _POSIX_ADVISORY_INFO @@ -872,7 +872,7 @@ are all defined to 200112L: .SS XSI - _XOPEN_REALTIME_THREADS - _SC_XOPEN_REALTIME_THREADS This option implies that the following options are all defined to 200112L: -.PP +.P .PD 0 .TP .B _POSIX_THREAD_PRIO_INHERIT @@ -884,7 +884,7 @@ are all defined to 200112L: .SS ADVANCED REALTIME THREADS - --- - --- This option implies that the following options are all defined to 200112L: -.PP +.P .PD 0 .TP .B _POSIX_BARRIERS @@ -909,7 +909,7 @@ are all defined to 200112L: .SS TRACING - --- - --- This option implies that the following options are all defined to 200112L: -.PP +.P .PD 0 .TP .B _POSIX_TRACE @@ -922,7 +922,7 @@ are all defined to 200112L: .PD .SS STREAMS - _XOPEN_STREAMS - _SC_XOPEN_STREAMS The following functions are present: -.PP +.P .nf .in +4n .IR fattach () @@ -939,7 +939,7 @@ The following functions are present: Functions included in the legacy option group were previously mandatory, but are now optional in this version. The following functions are present: -.PP +.P .nf .in +4n .IR bcmp () @@ -959,7 +959,7 @@ The following functions are present: .fi .SS XSI - _XOPEN_UNIX - _SC_XOPEN_UNIX The following functions are present: -.PP +.P .nf .in +4n .IR mmap () @@ -967,9 +967,9 @@ The following functions are present: .IR msync () .in .fi -.PP +.P This option implies the following options: -.PP +.P .PD 0 .TP .B _POSIX_FSYNC @@ -988,9 +988,9 @@ This option implies the following options: .TP .B _POSIX_THREADS .PD -.PP +.P This option may imply the following options from the XSI option groups: -.PP +.P .PD 0 .TP .RB "Encryption (" _XOPEN_CRYPT ) diff --git a/upstream/debian-unstable/man7/process-keyring.7 b/upstream/debian-unstable/man7/process-keyring.7 index 53557a0f..9d00e026 100644 --- a/upstream/debian-unstable/man7/process-keyring.7 +++ b/upstream/debian-unstable/man7/process-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH process-keyring 7 2022-10-30 "Linux man-pages 6.05.01" +.TH process-keyring 7 2024-05-02 "Linux man-pages 6.8" .SH NAME process-keyring \- per-process shared keyring .SH DESCRIPTION @@ -11,19 +11,19 @@ The process keyring is a keyring used to anchor keys on behalf of a process. It is created only when a process requests it. The process keyring has the name (description) .IR _pid . -.PP +.P A special serial number value, .BR KEY_SPEC_PROCESS_KEYRING , is defined that can be used in lieu of the actual serial number of the calling process's process keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@p\fP' can be used instead of a numeric key ID in much the same way, but since .BR keyctl (1) is a program run after forking, this is of no utility. -.PP +.P A thread created using the .BR clone (2) .B CLONE_THREAD @@ -36,7 +36,7 @@ A process's process keyring is cleared on .BR execve (2). The process keyring is destroyed when the last thread that refers to it terminates. -.PP +.P If a process doesn't have a process keyring when it is accessed, then the process keyring will be created if the keyring is to be modified; otherwise, the error diff --git a/upstream/debian-unstable/man7/property.7ssl b/upstream/debian-unstable/man7/property.7ssl index 1a6e7934..6067151f 100644 --- a/upstream/debian-unstable/man7/property.7ssl +++ b/upstream/debian-unstable/man7/property.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROPERTY 7SSL" -.TH PROPERTY 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROPERTY 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/provider-asym_cipher.7ssl b/upstream/debian-unstable/man7/provider-asym_cipher.7ssl index ddcd6000..3ccaf5b1 100644 --- a/upstream/debian-unstable/man7/provider-asym_cipher.7ssl +++ b/upstream/debian-unstable/man7/provider-asym_cipher.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-ASYM_CIPHER 7SSL" -.TH PROVIDER-ASYM_CIPHER 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-ASYM_CIPHER 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -277,6 +277,14 @@ The TLS protocol version first requested by the client. .IP """tls-negotiated-version"" (\fBOSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION\fR) <unsigned integer>" 4 .IX Item """tls-negotiated-version"" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) <unsigned integer>" The negotiated TLS protocol version. +.IP """implicit-rejection"" (\fBOSSL_PKEY_PARAM_IMPLICIT_REJECTION\fR) <unsigned integer>" 4 +.IX Item """implicit-rejection"" (OSSL_PKEY_PARAM_IMPLICIT_REJECTION) <unsigned integer>" +Gets of sets the use of the implicit rejection mechanism for RSA PKCS#1 v1.5 +decryption. When set (non zero value), the decryption API will return +a deterministically random value if the PKCS#1 v1.5 padding check fails. +This makes exploitation of the Bleichenbacher significantly harder, even +if the code using the RSA decryption API is not implemented in side-channel +free manner. Set by default. .PP \&\fBOSSL_FUNC_asym_cipher_gettable_ctx_params()\fR and \fBOSSL_FUNC_asym_cipher_settable_ctx_params()\fR get a constant \fBOSSL_PARAM\fR\|(3) array that describes the gettable and settable diff --git a/upstream/debian-unstable/man7/provider-base.7ssl b/upstream/debian-unstable/man7/provider-base.7ssl index 004c5a95..565f6ce7 100644 --- a/upstream/debian-unstable/man7/provider-base.7ssl +++ b/upstream/debian-unstable/man7/provider-base.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-BASE 7SSL" -.TH PROVIDER-BASE 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-BASE 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -659,6 +659,116 @@ versions supported by the group. The values equate to the on-the-wire encoding of the various TLS versions. For example TLSv1.3 is 0x0304 (772 decimal), and TLSv1.2 is 0x0303 (771 decimal). A 0 indicates that there is no defined minimum or maximum. A \-1 indicates that the group should not be used in that protocol. +.PP +\fI"TLS-SIGALG" Capability\fR +.IX Subsection """TLS-SIGALG"" Capability" +.PP +The "TLS-SIGALG" capability can be queried by libssl to discover the list of +TLS signature algorithms that a provider can support. Each signature supported +can be used for client\- or server-authentication in addition to the built-in +signature algorithms. +TLS1.3 clients can advertise the list of TLS signature algorithms they support +in the signature_algorithms extension, and TLS servers can select an algorithm +from the offered list that they also support. In this way a provider can add +to the list of signature algorithms that libssl already supports with +additional ones. +.PP +Each TLS signature algorithm that a provider supports should be described via +the callback passed in through the provider_get_capabilities function. Each +algorithm can have the following details supplied: +.IP """iana-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_IANA_NAME\fR) <UTF8 string>" 4 +.IX Item """iana-name"" (OSSL_CAPABILITY_TLS_SIGALG_IANA_NAME) <UTF8 string>" +The name of the signature algorithm as given in the IANA TLS Signature Scheme +registry as "Description": +<https://www.iana.org/assignments/tls\-parameters/tls\-parameters.xhtml#tls\-signaturescheme>. +This value must be supplied. +.IP """iana-code-point"" (\fBOSSL_CAPABILITY_TLS_SIGALG_CODE_POINT\fR) <unsigned integer>" 4 +.IX Item """iana-code-point"" (OSSL_CAPABILITY_TLS_SIGALG_CODE_POINT) <unsigned integer>" +The TLS algorithm ID value as given in the IANA TLS SignatureScheme registry. +This value must be supplied. +.IP """sigalg-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_NAME\fR) <UTF8 string>" 4 +.IX Item """sigalg-name"" (OSSL_CAPABILITY_TLS_SIGALG_NAME) <UTF8 string>" +A name for the full (possibly composite hash-and-signature) signature +algorithm. +The provider may, but is not obligated to, provide a signature implementation +with this name; if it doesn't, this is assumed to be a composite of a pure +signature algorithm and a hash algorithm, which must be given with the +parameters "sig-name" and "hash-name". +This value must be supplied. +.IP """sigalg-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_OID\fR) <UTF8 string>" 4 +.IX Item """sigalg-oid"" (OSSL_CAPABILITY_TLS_SIGALG_OID) <UTF8 string>" +The OID of the "sigalg-name" algorithm in canonical numeric text form. If +this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and +a NID for this OID, using the "sigalg-name" parameter for its (short) name. +Otherwise, it's assumed to already exist in the object database, possibly +done by the provider with the \fBcore_obj_create()\fR upcall. +This value is optional. +.IP """sig-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SIG_NAME\fR) <UTF8 string>" 4 +.IX Item """sig-name"" (OSSL_CAPABILITY_TLS_SIGALG_SIG_NAME) <UTF8 string>" +The name of the pure signature algorithm that is part of a composite +"sigalg-name". If "sigalg-name" is implemented by the provider, this +parameter is redundant and must not be given. +This value is optional. +.IP """sig-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SIG_OID\fR) <UTF8 string>" 4 +.IX Item """sig-oid"" (OSSL_CAPABILITY_TLS_SIGALG_SIG_OID) <UTF8 string>" +The OID of the "sig-name" algorithm in canonical numeric text form. If +this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and +a NID for this OID, using the "sig-name" parameter for its (short) name. +Otherwise, it is assumed to already exist in the object database. This +can be done by the provider using the \fBcore_obj_create()\fR upcall. +This value is optional. +.IP """hash-name"" (\fBOSSL_CAPABILITY_TLS_SIGALG_HASH_NAME\fR) <UTF8 string>" 4 +.IX Item """hash-name"" (OSSL_CAPABILITY_TLS_SIGALG_HASH_NAME) <UTF8 string>" +The name of the hash algorithm that is part of a composite "sigalg-name". +If "sigalg-name" is implemented by the provider, this parameter is redundant +and must not be given. +This value is optional. +.IP """hash-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_HASH_OID\fR) <UTF8 string>" 4 +.IX Item """hash-oid"" (OSSL_CAPABILITY_TLS_SIGALG_HASH_OID) <UTF8 string>" +The OID of the "hash-name" algorithm in canonical numeric text form. If +this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and +a NID for this OID, using the "hash-name" parameter for its (short) name. +Otherwise, it's assumed to already exist in the object database, possibly +done by the provider with the \fBcore_obj_create()\fR upcall. +This value is optional. +.IP """key-type"" (\fBOSSL_CAPABILITY_TLS_SIGALG_KEYTYPE\fR) <UTF8 string>" 4 +.IX Item """key-type"" (OSSL_CAPABILITY_TLS_SIGALG_KEYTYPE) <UTF8 string>" +The key type of the public key of applicable certificates. If this parameter +isn't present, it's assumed to be the same as "sig-name" if that's present, +otherwise "sigalg-name". +This value is optional. +.IP """key-type-oid"" (\fBOSSL_CAPABILITY_TLS_SIGALG_KEYTYPE_OID\fR) <UTF8 string>" 4 +.IX Item """key-type-oid"" (OSSL_CAPABILITY_TLS_SIGALG_KEYTYPE_OID) <UTF8 string>" +The OID of the "key-type" in canonical numeric text form. If +this parameter is given, \fBOBJ_create()\fR will be used to create an OBJ and +a NID for this OID, using the "key-type" parameter for its (short) name. +Otherwise, it's assumed to already exist in the object database, possibly +done by the provider with the \fBcore_obj_create()\fR upcall. +This value is optional. +.IP """sec-bits"" (\fBOSSL_CAPABILITY_TLS_SIGALG_SECURITY_BITS\fR) <unsigned integer>" 4 +.IX Item """sec-bits"" (OSSL_CAPABILITY_TLS_SIGALG_SECURITY_BITS) <unsigned integer>" +The number of bits of security offered by keys of this algorithm. The number +of bits should be comparable with the ones given in table 2 and 3 of the NIST +SP800\-57 document. This number is used to determine the security strength of +the algorithm if no digest algorithm has been registered that otherwise +defines the security strength. If the signature algorithm implements its own +digest internally, this value needs to be set to properly reflect the overall +security strength. +This value must be supplied. +.IP """tls-min-tls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MIN_TLS\fR) <integer>" 4 +.IX Item """tls-min-tls"" (OSSL_CAPABILITY_TLS_SIGALG_MIN_TLS) <integer>" +.PD 0 +.IP """tls-max-tls"" (\fBOSSL_CAPABILITY_TLS_SIGALG_MAX_TLS\fR) <integer>" 4 +.IX Item """tls-max-tls"" (OSSL_CAPABILITY_TLS_SIGALG_MAX_TLS) <integer>" +.PD +These parameters can be used to describe the minimum and maximum TLS +versions supported by the signature algorithm. The values equate to the +on-the-wire encoding of the various TLS versions. For example TLSv1.3 is +0x0304 (772 decimal), and TLSv1.2 is 0x0303 (771 decimal). A 0 indicates that +there is no defined minimum or maximum. A \-1 indicates that the signature +algorithm should not be used in that protocol. +Presently values representing anything other than TLS1.3 mean that the +complete algorithm is ignored. .SH NOTES .IX Header "NOTES" The \fBcore_obj_create()\fR and \fBcore_obj_add_sigid()\fR functions were not thread safe @@ -680,7 +790,7 @@ operation \f(CW\*(C`BAR\*(C'\fR. \& \& static const OSSL_ITEM reasons[] = { \& { E_MALLOC, "memory allocation failure" }. -\& { 0, NULL } /* Termination */ +\& OSSL_DISPATCH_END \& }; \& \& /* @@ -760,7 +870,7 @@ operation \f(CW\*(C`BAR\*(C'\fR. \& { OSSL_FUNC_BAR_INIT, (void (*)(void))foo_init }, \& { OSSL_FUNC_BAR_UPDATE, (void (*)(void))foo_update }, \& { OSSL_FUNC_BAR_FINAL, (void (*)(void))foo_final }, -\& { 0, NULL } +\& OSSL_DISPATCH_END \& }; \& \& static const OSSL_ALGORITHM bars[] = { @@ -792,7 +902,7 @@ operation \f(CW\*(C`BAR\*(C'\fR. \& { OSSL_FUNC_PROVIDER_TEARDOWN, (void (*)(void))p_teardown }, \& { OSSL_FUNC_PROVIDER_QUERY_OPERATION, (void (*)(void))p_query }, \& { OSSL_FUNC_PROVIDER_GET_REASON_STRINGS, (void (*)(void))p_reasons }, -\& { 0, NULL } +\& OSSL_DISPATCH_END \& }; \& \& int OSSL_provider_init(const OSSL_CORE_HANDLE *handle, diff --git a/upstream/debian-unstable/man7/provider-cipher.7ssl b/upstream/debian-unstable/man7/provider-cipher.7ssl index 238b90d2..0bce2e80 100644 --- a/upstream/debian-unstable/man7/provider-cipher.7ssl +++ b/upstream/debian-unstable/man7/provider-cipher.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-CIPHER 7SSL" -.TH PROVIDER-CIPHER 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-CIPHER 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/provider-decoder.7ssl b/upstream/debian-unstable/man7/provider-decoder.7ssl index 1b01f09f..5b58983a 100644 --- a/upstream/debian-unstable/man7/provider-decoder.7ssl +++ b/upstream/debian-unstable/man7/provider-decoder.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-DECODER 7SSL" -.TH PROVIDER-DECODER 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-DECODER 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/provider-digest.7ssl b/upstream/debian-unstable/man7/provider-digest.7ssl index 7c352d98..79682d55 100644 --- a/upstream/debian-unstable/man7/provider-digest.7ssl +++ b/upstream/debian-unstable/man7/provider-digest.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-DIGEST 7SSL" -.TH PROVIDER-DIGEST 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-DIGEST 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -308,8 +308,8 @@ produces larger digests is unusable with those API calls. \&\fBEVP_MD\-common\fR\|(7), \fBEVP_MD\-BLAKE2\fR\|(7), \fBEVP_MD\-MD2\fR\|(7), \&\fBEVP_MD\-MD4\fR\|(7), \fBEVP_MD\-MD5\fR\|(7), \fBEVP_MD\-MD5\-SHA1\fR\|(7), \&\fBEVP_MD\-MDC2\fR\|(7), \fBEVP_MD\-RIPEMD160\fR\|(7), \fBEVP_MD\-SHA1\fR\|(7), -\&\fBEVP_MD\-SHA2\fR\|(7), \fBEVP_MD\-SHA3\fR\|(7), \fBEVP_MD\-SHAKE\fR\|(7), -\&\fBEVP_MD\-SM3\fR\|(7), \fBEVP_MD\-WHIRLPOOL\fR\|(7), +\&\fBEVP_MD\-SHA2\fR\|(7), \fBEVP_MD\-SHA3\fR\|(7), \fBEVP_MD\-KECCAK\fR\|(7) +\&\fBEVP_MD\-SHAKE\fR\|(7), \fBEVP_MD\-SM3\fR\|(7), \fBEVP_MD\-WHIRLPOOL\fR\|(7), \&\fBEVP_MD\-NULL\fR\|(7), \&\fBlife_cycle\-digest\fR\|(7), \fBEVP_DigestInit\fR\|(3) .SH HISTORY diff --git a/upstream/debian-unstable/man7/provider-encoder.7ssl b/upstream/debian-unstable/man7/provider-encoder.7ssl index f56f173a..8eaa8402 100644 --- a/upstream/debian-unstable/man7/provider-encoder.7ssl +++ b/upstream/debian-unstable/man7/provider-encoder.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-ENCODER 7SSL" -.TH PROVIDER-ENCODER 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-ENCODER 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -340,7 +340,7 @@ supports any of the \fIselection\fR bits, otherwise 0. The ENCODER interface was introduced in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2019\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/provider-kdf.7ssl b/upstream/debian-unstable/man7/provider-kdf.7ssl index b16d925a..68a52aac 100644 --- a/upstream/debian-unstable/man7/provider-kdf.7ssl +++ b/upstream/debian-unstable/man7/provider-kdf.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-KDF 7SSL" -.TH PROVIDER-KDF 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-KDF 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/provider-kem.7ssl b/upstream/debian-unstable/man7/provider-kem.7ssl index 32e1e6b1..e9339022 100644 --- a/upstream/debian-unstable/man7/provider-kem.7ssl +++ b/upstream/debian-unstable/man7/provider-kem.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-KEM 7SSL" -.TH PROVIDER-KEM 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-KEM 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -80,13 +80,19 @@ provider\-kem \- The kem library <\-> provider functions \& void *OSSL_FUNC_kem_dupctx(void *ctx); \& \& /* Encapsulation */ -\& int OSSL_FUNC_kem_encapsulate_init(void *ctx, void *provkey, const char *name, +\& int OSSL_FUNC_kem_encapsulate_init(void *ctx, void *provkey, \& const OSSL_PARAM params[]); +\& int OSSL_FUNC_kem_auth_encapsulate_init(void *ctx, void *provkey, +\& void *provauthkey, +\& const OSSL_PARAM params[]); \& int OSSL_FUNC_kem_encapsulate(void *ctx, unsigned char *out, size_t *outlen, \& unsigned char *secret, size_t *secretlen); \& \& /* Decapsulation */ -\& int OSSL_FUNC_kem_decapsulate_init(void *ctx, void *provkey, const char *name); +\& int OSSL_FUNC_kem_decapsulate_init(void *ctx, void *provkey); +\& int OSSL_FUNC_kem_auth_decapsulate_init(void *ctx, void *provkey, +\& void *provauthkey, +\& const OSSL_PARAM params[]); \& int OSSL_FUNC_kem_decapsulate(void *ctx, unsigned char *out, size_t *outlen, \& const unsigned char *in, size_t inlen); \& @@ -128,20 +134,22 @@ For example, the "function" \fBOSSL_FUNC_kem_newctx()\fR has these: macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: .PP .Vb 3 -\& OSSL_FUNC_kem_newctx OSSL_FUNC_KEM_NEWCTX -\& OSSL_FUNC_kem_freectx OSSL_FUNC_KEM_FREECTX -\& OSSL_FUNC_kem_dupctx OSSL_FUNC_KEM_DUPCTX +\& OSSL_FUNC_kem_newctx OSSL_FUNC_KEM_NEWCTX +\& OSSL_FUNC_kem_freectx OSSL_FUNC_KEM_FREECTX +\& OSSL_FUNC_kem_dupctx OSSL_FUNC_KEM_DUPCTX \& -\& OSSL_FUNC_kem_encapsulate_init OSSL_FUNC_KEM_ENCAPSULATE_INIT -\& OSSL_FUNC_kem_encapsulate OSSL_FUNC_KEM_ENCAPSULATE +\& OSSL_FUNC_kem_encapsulate_init OSSL_FUNC_KEM_ENCAPSULATE_INIT +\& OSSL_FUNC_kem_auth_encapsulate_init OSSL_FUNC_KEM_AUTH_ENCAPSULATE_INIT +\& OSSL_FUNC_kem_encapsulate OSSL_FUNC_KEM_ENCAPSULATE \& -\& OSSL_FUNC_kem_decapsulate_init OSSL_FUNC_KEM_DECAPSULATE_INIT -\& OSSL_FUNC_kem_decapsulate OSSL_FUNC_KEM_DECAPSULATE +\& OSSL_FUNC_kem_decapsulate_init OSSL_FUNC_KEM_DECAPSULATE_INIT +\& OSSL_FUNC_kem_auth_decapsulate_init OSSL_FUNC_KEM_AUTH_DECAPSULATE_INIT +\& OSSL_FUNC_kem_decapsulate OSSL_FUNC_KEM_DECAPSULATE \& -\& OSSL_FUNC_kem_get_ctx_params OSSL_FUNC_KEM_GET_CTX_PARAMS -\& OSSL_FUNC_kem_gettable_ctx_params OSSL_FUNC_KEM_GETTABLE_CTX_PARAMS -\& OSSL_FUNC_kem_set_ctx_params OSSL_FUNC_KEM_SET_CTX_PARAMS -\& OSSL_FUNC_kem_settable_ctx_params OSSL_FUNC_KEM_SETTABLE_CTX_PARAMS +\& OSSL_FUNC_kem_get_ctx_params OSSL_FUNC_KEM_GET_CTX_PARAMS +\& OSSL_FUNC_kem_gettable_ctx_params OSSL_FUNC_KEM_GETTABLE_CTX_PARAMS +\& OSSL_FUNC_kem_set_ctx_params OSSL_FUNC_KEM_SET_CTX_PARAMS +\& OSSL_FUNC_kem_settable_ctx_params OSSL_FUNC_KEM_SETTABLE_CTX_PARAMS .Ve .PP An asymmetric kem algorithm implementation may not implement all of these @@ -151,10 +159,12 @@ OSSL_FUNC_kem_newctx and OSSL_FUNC_kem_freectx. It must also implement both of OSSL_FUNC_kem_encapsulate_init and OSSL_FUNC_kem_encapsulate, or both of OSSL_FUNC_kem_decapsulate_init and OSSL_FUNC_kem_decapsulate. +OSSL_FUNC_kem_auth_encapsulate_init is optional but if it is present then so +must OSSL_FUNC_kem_auth_decapsulate_init. OSSL_FUNC_kem_get_ctx_params is optional but if it is present then so must OSSL_FUNC_kem_gettable_ctx_params. Similarly, OSSL_FUNC_kem_set_ctx_params is optional but if it is present then -so must OSSL_FUNC_kem_settable_ctx_params. +OSSL_FUNC_kem_settable_ctx_params must also be present. .PP An asymmetric kem algorithm must also implement some mechanism for generating, loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation. @@ -186,6 +196,10 @@ The key object should have been previously generated, loaded or imported into the provider using the key management (OSSL_OP_KEYMGMT) operation (see \&\fBprovider\-keymgmt\fR\|(7)>. .PP +\&\fBOSSL_FUNC_kem_auth_encapsulate_init()\fR is similar to +\&\fBOSSL_FUNC_kem_encapsulate_init()\fR, but also passes an additional authentication +key \fIprovauthkey\fR which cannot be NULL. +.PP \&\fBOSSL_FUNC_kem_encapsulate()\fR performs the actual encapsulation itself. A previously initialised asymmetric kem context is passed in the \fIctx\fR parameter. @@ -209,6 +223,10 @@ The key object should have been previously generated, loaded or imported into the provider using the key management (OSSL_OP_KEYMGMT) operation (see \&\fBprovider\-keymgmt\fR\|(7)>. .PP +\&\fBOSSL_FUNC_kem_auth_decapsulate_init()\fR is similar to +\&\fBOSSL_FUNC_kem_decapsulate_init()\fR, but also passes an additional authentication +key \fIprovauthkey\fR which cannot be NULL. +.PP \&\fBOSSL_FUNC_kem_decapsulate()\fR performs the actual decapsulation itself. A previously initialised asymmetric kem context is passed in the \fIctx\fR parameter. @@ -253,9 +271,12 @@ All other functions should return 1 for success or 0 on error. .SH HISTORY .IX Header "HISTORY" The provider KEM interface was introduced in OpenSSL 3.0. +.PP +\&\fBOSSL_FUNC_kem_auth_encapsulate_init()\fR and \fBOSSL_FUNC_kem_auth_decapsulate_init()\fR +were added in OpenSSL 3.2. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/provider-keyexch.7ssl b/upstream/debian-unstable/man7/provider-keyexch.7ssl index 735ef2ad..e2e6f331 100644 --- a/upstream/debian-unstable/man7/provider-keyexch.7ssl +++ b/upstream/debian-unstable/man7/provider-keyexch.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-KEYEXCH 7SSL" -.TH PROVIDER-KEYEXCH 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-KEYEXCH 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/provider-keymgmt.7ssl b/upstream/debian-unstable/man7/provider-keymgmt.7ssl index e582229d..a5cd3c41 100644 --- a/upstream/debian-unstable/man7/provider-keymgmt.7ssl +++ b/upstream/debian-unstable/man7/provider-keymgmt.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-KEYMGMT 7SSL" -.TH PROVIDER-KEYMGMT 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-KEYMGMT 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -107,9 +107,11 @@ provider\-keymgmt \- The KEYMGMT library <\-> provider functions \& /* Key object import and export functions */ \& int OSSL_FUNC_keymgmt_import(void *keydata, int selection, const OSSL_PARAM params[]); \& const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types(int selection); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types_ex(void *provctx, int selection); \& int OSSL_FUNC_keymgmt_export(void *keydata, int selection, \& OSSL_CALLBACK *param_cb, void *cbarg); \& const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types(int selection); +\& const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types_ex(void *provctx, int selection); \& \& /* Key object duplication, a constructor */ \& void *OSSL_FUNC_keymgmt_dup(const void *keydata_from, int selection); @@ -177,8 +179,10 @@ macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: \& \& OSSL_FUNC_keymgmt_import OSSL_FUNC_KEYMGMT_IMPORT \& OSSL_FUNC_keymgmt_import_types OSSL_FUNC_KEYMGMT_IMPORT_TYPES +\& OSSL_FUNC_keymgmt_import_types_ex OSSL_FUNC_KEYMGMT_IMPORT_TYPES_EX \& OSSL_FUNC_keymgmt_export OSSL_FUNC_KEYMGMT_EXPORT \& OSSL_FUNC_keymgmt_export_types OSSL_FUNC_KEYMGMT_EXPORT_TYPES +\& OSSL_FUNC_keymgmt_export_types_ex OSSL_FUNC_KEYMGMT_EXPORT_TYPES_EX \& \& OSSL_FUNC_keymgmt_dup OSSL_FUNC_KEYMGMT_DUP .Ve @@ -366,13 +370,25 @@ by the implementation of this function. from \fIkeydata\fR, create an \fBOSSL_PARAM\fR\|(3) array with them and call \&\fIparam_cb\fR with that array as well as the given \fIcbarg\fR. .PP -\&\fBOSSL_FUNC_keymgmt_import_types()\fR should return a constant array of descriptor +\&\fBOSSL_FUNC_keymgmt_import_types()\fR and \fBOSSL_FUNC_keymgmt_import_types_ex()\fR +should return a constant array of descriptor \&\fBOSSL_PARAM\fR\|(3) for data indicated by \fIselection\fR, for parameters that \&\fBOSSL_FUNC_keymgmt_import()\fR can handle. -.PP -\&\fBOSSL_FUNC_keymgmt_export_types()\fR should return a constant array of descriptor +Either \fBOSSL_FUNC_keymgmt_import_types()\fR or \fBOSSL_FUNC_keymgmt_import_types_ex()\fR, +must be implemented, if \fBOSSL_FUNC_keymgmt_import_types_ex()\fR is implemented, then +it is preferred over \fBOSSL_FUNC_keymgmt_import_types()\fR. +Providers that are supposed to be backward compatible with OpenSSL 3.0 or 3.1 +must continue to implement \fBOSSL_FUNC_keymgmt_import_types()\fR. +.PP +\&\fBOSSL_FUNC_keymgmt_export_types()\fR and \fBOSSL_FUNC_keymgmt_export_types_ex()\fR +should return a constant array of descriptor \&\fBOSSL_PARAM\fR\|(3) for data indicated by \fIselection\fR, that the \&\fBOSSL_FUNC_keymgmt_export()\fR callback can expect to receive. +Either \fBOSSL_FUNC_keymgmt_export_types()\fR or \fBOSSL_FUNC_keymgmt_export_types_ex()\fR, +must be implemented, if \fBOSSL_FUNC_keymgmt_export_types_ex()\fR is implemented, then +it is preferred over \fBOSSL_FUNC_keymgmt_export_types()\fR. +Providers that are supposed to be backward compatible with OpenSSL 3.0 or 3.1 +must continue to implement \fBOSSL_FUNC_keymgmt_export_types()\fR. .PP \&\fBOSSL_FUNC_keymgmt_dup()\fR should duplicate data subsets indicated by \&\fIselection\fR or the whole key data \fIkeydata_from\fR and create a new @@ -396,6 +412,9 @@ the result of asymmetric encryption / decryption (\fIout\fR in \&\fBprovider\-asym_cipher\fR\|(7), a derived secret (\fIsecret\fR in \&\fBprovider\-keyexch\fR\|(7), and similar data). .Sp +Providers need to implement this parameter +in order to properly support various use cases such as CMS signing. +.Sp Because an EVP_KEYMGMT method is always tightly bound to another method (signature, asymmetric cipher, key exchange, ...) and must be of the same provider, this number only needs to be synchronised with the @@ -451,11 +470,15 @@ the requested operation, or NULL if the same name used to fetch the keymgmt applies. .PP \&\fBOSSL_FUNC_keymgmt_gettable_params()\fR and \fBOSSL_FUNC_keymgmt_settable_params()\fR -\&\fBOSSL_FUNC_keymgmt_import_types()\fR, \fBOSSL_FUNC_keymgmt_export_types()\fR +\&\fBOSSL_FUNC_keymgmt_import_types()\fR, \fBOSSL_FUNC_keymgmt_import_types_ex()\fR, +\&\fBOSSL_FUNC_keymgmt_export_types()\fR, \fBOSSL_FUNC_keymgmt_export_types_ex()\fR should always return a constant \fBOSSL_PARAM\fR\|(3) array. .SH "SEE ALSO" .IX Header "SEE ALSO" +\&\fBEVP_PKEY_get_size\fR\|(3), +\&\fBEVP_PKEY_get_bits\fR\|(3), +\&\fBEVP_PKEY_get_security_bits\fR\|(3), \&\fBprovider\fR\|(7), \&\fBEVP_PKEY\-X25519\fR\|(7), \fBEVP_PKEY\-X448\fR\|(7), \fBEVP_PKEY\-ED25519\fR\|(7), \&\fBEVP_PKEY\-ED448\fR\|(7), \fBEVP_PKEY\-EC\fR\|(7), \fBEVP_PKEY\-RSA\fR\|(7), @@ -463,6 +486,9 @@ always return a constant \fBOSSL_PARAM\fR\|(3) array. .SH HISTORY .IX Header "HISTORY" The KEYMGMT interface was introduced in OpenSSL 3.0. +.PP +Functions \fBOSSL_FUNC_keymgmt_import_types_ex()\fR, and \fBOSSL_FUNC_keymgmt_export_types_ex()\fR +were added with OpenSSL 3.2. .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. diff --git a/upstream/debian-unstable/man7/provider-mac.7ssl b/upstream/debian-unstable/man7/provider-mac.7ssl index 30e4178c..ce95370d 100644 --- a/upstream/debian-unstable/man7/provider-mac.7ssl +++ b/upstream/debian-unstable/man7/provider-mac.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-MAC 7SSL" -.TH PROVIDER-MAC 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-MAC 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -274,7 +274,7 @@ array, or NULL if none is offered. The provider MAC interface was introduced in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2019\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/provider-object.7ssl b/upstream/debian-unstable/man7/provider-object.7ssl index 8ce5736c..437c6769 100644 --- a/upstream/debian-unstable/man7/provider-object.7ssl +++ b/upstream/debian-unstable/man7/provider-object.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-OBJECT 7SSL" -.TH PROVIDER-OBJECT 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-OBJECT 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/provider-rand.7ssl b/upstream/debian-unstable/man7/provider-rand.7ssl index 99b3598e..b48752c2 100644 --- a/upstream/debian-unstable/man7/provider-rand.7ssl +++ b/upstream/debian-unstable/man7/provider-rand.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-RAND 7SSL" -.TH PROVIDER-RAND 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-RAND 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -327,7 +327,7 @@ the EVP layer will begin enforcing the listed transitions. The provider RAND interface was introduced in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/provider-signature.7ssl b/upstream/debian-unstable/man7/provider-signature.7ssl index b950db32..1b5c0cdd 100644 --- a/upstream/debian-unstable/man7/provider-signature.7ssl +++ b/upstream/debian-unstable/man7/provider-signature.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-SIGNATURE 7SSL" -.TH PROVIDER-SIGNATURE 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-SIGNATURE 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -408,6 +408,17 @@ The length of the "digest-size" parameter should not exceed that of a \fBsize_t\ .IX Item """algorithm-id"" (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <octet string>" Gets the DER encoded AlgorithmIdentifier that corresponds to the combination of signature algorithm and digest algorithm for the signature operation. +.IP """nonce-type"" (\fBOSSL_SIGNATURE_PARAM_NONCE_TYPE\fR) <unsigned integer>" 4 +.IX Item """nonce-type"" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) <unsigned integer>" +Set this to 1 to use deterministic digital signature generation with +ECDSA or DSA, as defined in RFC 6979 (see Section 3.2 "Generation of +k"). In this case, the "digest" parameter must be explicitly set +(otherwise, deterministic nonce generation will fail). Before using +deterministic digital signature generation, please read RFC 6979 +Section 4 "Security Considerations". The default value for +"nonce-type" is 0 and results in a random value being used for the +nonce \fBk\fR as defined in FIPS 186\-4 Section 6.3 "Secret Number +Generation". .IP """kat"" (\fBOSSL_SIGNATURE_PARAM_KAT\fR) <unsigned integer>" 4 .IX Item """kat"" (OSSL_SIGNATURE_PARAM_KAT) <unsigned integer>" Sets a flag to modify the sign operation to return an error if the initial @@ -467,7 +478,7 @@ All other functions should return 1 for success or 0 on error. The provider SIGNATURE interface was introduced in OpenSSL 3.0. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2019\-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019\-2024 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/provider-storemgmt.7ssl b/upstream/debian-unstable/man7/provider-storemgmt.7ssl index 9ed00b6e..42fdfe16 100644 --- a/upstream/debian-unstable/man7/provider-storemgmt.7ssl +++ b/upstream/debian-unstable/man7/provider-storemgmt.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER-STOREMGMT 7SSL" -.TH PROVIDER-STOREMGMT 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER-STOREMGMT 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -86,6 +86,14 @@ provider\-storemgmt \- The OSSL_STORE library <\-> provider functions \& int OSSL_FUNC_store_export_object \& (void *loaderctx, const void *objref, size_t objref_sz, \& OSSL_CALLBACK *export_cb, void *export_cbarg); +\& void *OSSL_FUNC_store_open_ex(void *provctx, const char *uri, +\& const OSSL_PARAM params[], +\& OSSL_PASSPHRASE_CALLBACK *pw_cb, +\& void *pw_cbarg); +\& +\& int OSSL_FUNC_store_delete(void *provctx, const char *uri, +\& const OSSL_PARAM params[], +\& OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" @@ -123,7 +131,7 @@ For example, the "function" \fBOSSL_FUNC_store_attach()\fR has these: \&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: .PP -.Vb 8 +.Vb 10 \& OSSL_FUNC_store_open OSSL_FUNC_STORE_OPEN \& OSSL_FUNC_store_attach OSSL_FUNC_STORE_ATTACH \& OSSL_FUNC_store_settable_ctx_params OSSL_FUNC_STORE_SETTABLE_CTX_PARAMS @@ -132,6 +140,8 @@ in \fBopenssl\-core_dispatch.h\fR\|(7), as follows: \& OSSL_FUNC_store_eof OSSL_FUNC_STORE_EOF \& OSSL_FUNC_store_close OSSL_FUNC_STORE_CLOSE \& OSSL_FUNC_store_export_object OSSL_FUNC_STORE_EXPORT_OBJECT +\& OSSL_FUNC_store_delete OSSL_FUNC_STORE_DELETE +\& OSSL_FUNC_store_open_ex OSSL_FUNC_STORE_OPEN_EX .Ve .SS Functions .IX Subsection "Functions" @@ -175,6 +185,18 @@ supports the type of the object and provides an import function. \&\fBOSSL_FUNC_store_export_object()\fR should export the object of size \fIobjref_sz\fR referenced by \fIobjref\fR as an \fBOSSL_PARAM\fR\|(3) array and pass that to the \&\fIexport_cb\fR as well as the given \fIexport_cbarg\fR. +.PP +\&\fBOSSL_FUNC_store_delete()\fR deletes the object identified by the \fIuri\fR. The +implementation is entirely responsible for the interpretation of the URI. In +case a passphrase needs to be prompted to remove an object, \fIpw_cb\fR should be +called. +.PP +\&\fBOSSL_FUNC_store_open_ex()\fR is an extended variant of \fBOSSL_FUNC_store_open()\fR. If +the provider does not implement this function the code internally falls back to +use the original \fBOSSL_FUNC_store_open()\fR. +This variant additionally accepts an \fBOSSL_PARAM\fR\|(3) object and a \fIpw_cb\fR +callback that can be used to request a passphrase in cases where the whole +store needs to be unlocked before performing any load operation. .SS "Load Parameters" .IX Subsection "Load Parameters" .IP """expect"" (\fBOSSL_STORE_PARAM_EXPECT\fR) <integer>" 4 @@ -235,9 +257,11 @@ search for a certificate by issuer+serial, both the "issuer" and the .SH HISTORY .IX Header "HISTORY" The STORE interface was introduced in OpenSSL 3.0. +.PP +\&\fBOSSL_FUNC_store_delete()\fR callback was added in OpenSSL 3.2 .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2020\-2022 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2020\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/provider.7ssl b/upstream/debian-unstable/man7/provider.7ssl index ef55e5d5..232a0335 100644 --- a/upstream/debian-unstable/man7/provider.7ssl +++ b/upstream/debian-unstable/man7/provider.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROVIDER 7SSL" -.TH PROVIDER 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROVIDER 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/proxy-certificates.7ssl b/upstream/debian-unstable/man7/proxy-certificates.7ssl index 7d541ec0..e704e710 100644 --- a/upstream/debian-unstable/man7/proxy-certificates.7ssl +++ b/upstream/debian-unstable/man7/proxy-certificates.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "PROXY-CERTIFICATES 7SSL" -.TH PROXY-CERTIFICATES 7SSL 2024-02-03 3.1.5 OpenSSL +.TH PROXY-CERTIFICATES 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -390,7 +390,7 @@ the same as the issuer, with one commonName added on. RFC 3820 <https://tools.ietf.org/html/rfc3820> .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2019\-2020 The OpenSSL Project Authors. All Rights Reserved. .PP 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 diff --git a/upstream/debian-unstable/man7/pthreads.7 b/upstream/debian-unstable/man7/pthreads.7 index 2c007980..66957602 100644 --- a/upstream/debian-unstable/man7/pthreads.7 +++ b/upstream/debian-unstable/man7/pthreads.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthreads 7 2023-03-18 "Linux man-pages 6.05.01" +.TH pthreads 7 2024-05-02 "Linux man-pages 6.8" .SH NAME pthreads \- POSIX threads .SH DESCRIPTION @@ -12,7 +12,7 @@ A single process can contain multiple threads, all of which are executing the same program. These threads share the same global memory (data and heap segments), but each thread has its own stack (automatic variables). -.PP +.P POSIX.1 also requires that threads share a range of other attributes (i.e., these attributes are process-wide rather than per-thread): .IP \[bu] 3 @@ -57,7 +57,7 @@ measurements of the consumption of CPU time .RB ( times (2)) and resources .RB ( getrusage (2)) -.PP +.P As well as the stack, POSIX.1 specifies that various other attributes are distinct for each thread, including: .IP \[bu] 3 @@ -77,7 +77,7 @@ alternate signal stack .IP \[bu] real-time scheduling policy and priority .RB ( sched (7)) -.PP +.P The following Linux-specific features are also per-thread: .IP \[bu] 3 capabilities (see @@ -104,12 +104,12 @@ This identifier is returned to the caller of .BR pthread_create (3), and a thread can obtain its own thread identifier using .BR pthread_self (3). -.PP +.P Thread IDs are guaranteed to be unique only within a process. (In all pthreads functions that accept a thread ID as an argument, that ID by definition refers to a thread in the same process as the caller.) -.PP +.P The system may reuse a thread ID after a terminated thread has been joined, or a detached thread has terminated. POSIX says: "If an application attempts to use a thread ID whose @@ -118,11 +118,11 @@ lifetime has ended, the behavior is undefined." A thread-safe function is one that can be safely (i.e., it will deliver the same results regardless of whether it is) called from multiple threads at the same time. -.PP +.P POSIX.1-2001 and POSIX.1-2008 require that all functions specified in the standard shall be thread-safe, except for the following functions: -.PP +.P .in +4n .EX asctime() @@ -224,10 +224,10 @@ wctomb() An async-cancel-safe function is one that can be safely called in an application where asynchronous cancelability is enabled (see .BR pthread_setcancelstate (3)). -.PP +.P Only the following functions are required to be async-cancel-safe by POSIX.1-2001 and POSIX.1-2008: -.PP +.P .in +4n .EX pthread_cancel() @@ -242,10 +242,10 @@ If a thread is cancelable, its cancelability type is deferred, and a cancelation request is pending for the thread, then the thread is canceled when it calls a function that is a cancelation point. -.PP +.P The following functions are required to be cancelation points by POSIX.1-2001 and/or POSIX.1-2008: -.PP +.P .\" FIXME .\" Document the list of all functions that are cancelation points in glibc .in +4n @@ -310,10 +310,10 @@ write() writev() .EE .in -.PP +.P The following functions may be cancelation points according to POSIX.1-2001 and/or POSIX.1-2008: -.PP +.P .in +4n .EX access() @@ -545,13 +545,13 @@ wprintf() wscanf() .EE .in -.PP +.P An implementation may also mark other functions not specified in the standard as cancelation points. In particular, an implementation is likely to mark any nonstandard function that may block as a cancelation point. (This includes most functions that can touch files.) -.PP +.P It should be noted that even if an application is not using asynchronous cancelation, that calling a function from the above list from an asynchronous signal handler may cause the equivalent of @@ -669,7 +669,7 @@ the requirements of the POSIX.1 specification and better performance when creating large numbers of threads. NPTL is available since glibc 2.3.2, and requires features that are present in the Linux 2.6 kernel. -.PP +.P Both of these are so-called 1:1 implementations, meaning that each thread maps to a kernel scheduling entity. Both threading implementations employ the Linux @@ -707,7 +707,7 @@ more information than usual, but which do not share a common process ID.) LinuxThreads threads (including the manager thread) are visible as separate processes using .BR ps (1). -.PP +.P The LinuxThreads implementation deviates from the POSIX.1 specification in a number of ways, including the following: .IP \[bu] 3 @@ -789,13 +789,13 @@ With NPTL, all of the threads in a process are placed in the same thread group; all members of a thread group share the same PID. NPTL does not employ a manager thread. -.PP +.P NPTL makes internal use of the first two real-time signals; these signals cannot be used in applications. See .BR nptl (7) for further details. -.PP +.P NPTL still has at least one nonconformance with POSIX.1: .IP \[bu] 3 Threads do not share a common nice value. @@ -804,7 +804,7 @@ Threads do not share a common nice value. .\" Sep 08: there is a patch by Denys Vlasenko to address this .\" "make setpriority POSIX compliant; introduce PRIO_THREAD extension" .\" Monitor this to see if it makes it into mainline. -.PP +.P Some NPTL nonconformances occur only with older kernels: .IP \[bu] 3 The information returned by @@ -831,7 +831,7 @@ However, a new thread's alternate signal stack settings are copied from the thread that created it, so that the threads initially share an alternate signal stack (fixed in Linux 2.6.16). -.PP +.P Note the following further points about the NPTL implementation: .IP \[bu] 3 If the stack size soft resource limit (see the description of @@ -852,17 +852,17 @@ Since glibc 2.3.2, the .BR getconf (1) command can be used to determine the system's threading implementation, for example: -.PP +.P .in +4n .EX bash$ getconf GNU_LIBPTHREAD_VERSION NPTL 2.3.4 .EE .in -.PP +.P With older glibc versions, a command such as the following should be sufficient to determine the default threading implementation: -.PP +.P .in +4n .EX bash$ $( ldd /bin/ls | grep libc.so | awk \[aq]{print $3}\[aq] ) | \e @@ -885,7 +885,7 @@ of LinuxThreads. (broken) application that depends on some nonconformant behavior in LinuxThreads.) For example: -.PP +.P .in +4n .EX bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \e @@ -904,9 +904,9 @@ bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \e .BR attributes (7), .BR futex (7), .BR nptl (7), -.BR sigevent (7), +.BR sigevent (3type), .BR signal (7) -.PP +.P Various Pthreads manual pages, for example: .BR pthread_atfork (3), .BR pthread_attr_init (3), diff --git a/upstream/debian-unstable/man7/pty.7 b/upstream/debian-unstable/man7/pty.7 index 5d9b429c..4444d95c 100644 --- a/upstream/debian-unstable/man7/pty.7 +++ b/upstream/debian-unstable/man7/pty.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pty 7 2022-12-04 "Linux man-pages 6.05.01" +.TH pty 7 2024-05-02 "Linux man-pages 6.8" .SH NAME pty \- pseudoterminal interfaces .SH DESCRIPTION @@ -13,7 +13,7 @@ One end of the channel is called the .IR master ; the other end is called the .IR slave . -.PP +.P The slave end of the pseudoterminal provides an interface that behaves exactly like a classical terminal. A process that expects to be connected to a terminal, @@ -29,24 +29,24 @@ that is connected to the slave. Conversely, anything that is written to the slave end of the pseudoterminal can be read by the process that is connected to the master end. -.PP +.P Data flow between master and slave is handled asynchronously, much like data flow with a physical terminal. Data written to the slave will be available at the master promptly, but may not be available immediately. Similarly, there may be a small processing delay between a write to the master, and the effect being visible at the slave. -.PP +.P Historically, two pseudoterminal APIs have evolved: BSD and System V. SUSv1 standardized a pseudoterminal API based on the System V API, and this API should be employed in all new programs that use pseudoterminals. -.PP +.P Linux provides both BSD-style and (standardized) System V-style pseudoterminals. System V-style terminals are commonly called UNIX 98 pseudoterminals on Linux systems. -.PP +.P Since Linux 2.6.4, BSD-style pseudoterminals are considered deprecated: support can be disabled when building the kernel by disabling the .B CONFIG_LEGACY_PTYS @@ -71,7 +71,7 @@ the name returned by .BR ptsname (3) in a call to .BR open (2). -.PP +.P The Linux kernel imposes a limit on the number of available UNIX 98 pseudoterminals. Up to and including Linux 2.6.3, this limit is configured @@ -122,7 +122,10 @@ BSD master devices BSD slave devices .SH NOTES Pseudoterminals are used by applications such as network login services -.RB ( ssh "(1), " rlogin "(1), " telnet (1)), +(\c +.BR ssh (1), +.BR rlogin (1), +.BR telnet (1)), terminal emulators such as .BR xterm (1), .BR script (1), @@ -131,13 +134,13 @@ terminal emulators such as .BR unbuffer (1), and .BR expect (1). -.PP +.P A description of the .B TIOCPKT .BR ioctl (2), which controls packet mode operation, can be found in .BR ioctl_tty (2). -.PP +.P The BSD .BR ioctl (2) operations diff --git a/upstream/debian-unstable/man7/queue.7 b/upstream/debian-unstable/man7/queue.7 index 6f2d5ab2..404cc3f8 100644 --- a/upstream/debian-unstable/man7/queue.7 +++ b/upstream/debian-unstable/man7/queue.7 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: BSD-3-Clause .\" .\" -.TH queue 7 2023-03-30 "Linux man-pages 6.05.01" +.TH queue 7 2024-05-02 "Linux man-pages 6.8" .SH NAME queue \- implementations of linked lists and queues .SH DESCRIPTION @@ -28,7 +28,7 @@ doubly linked tail queues .TP CIRCLEQ doubly linked circular queues -.PP +.P All structures support the following functionality: .IP \[bu] 3 Insertion of a new entry at the head of the list. @@ -38,9 +38,9 @@ Insertion of a new entry after any element in the list. O(1) removal of an entry from the head of the list. .IP \[bu] Forward traversal through the list. -.\".IP * +.\".IP \[bu] .\" Swapping the contents of two lists. -.PP +.P Code size and execution time depend on the complexity of the data structure being used, so programmers should take care to choose the appropriate one. @@ -61,13 +61,13 @@ Entries can be added at the end of a list. O(n) removal of any entry in the list. .IP \[bu] They may be concatenated. -.PP +.P However: .IP \[bu] 3 All list insertions must specify the head of the list. .IP \[bu] Each head entry requires two pointers rather than one. -.PP +.P Singly linked tail queues are ideal for applications with large datasets and few or no removals, or for implementing a FIFO queue. @@ -78,7 +78,7 @@ additionally allow: Insertion of a new entry before any element in the list. .IP \[bu] O(1) removal of any entry in the list. -.PP +.P However: .IP \[bu] 3 Each element requires two pointers rather than one. @@ -87,7 +87,7 @@ Linked lists are the simplest of the doubly linked data structures. They add the following functionality over the above: .IP \[bu] 3 They may be traversed backwards. -.PP +.P However: .IP \[bu] 3 To traverse backwards, an entry to begin the traversal and the list in @@ -100,7 +100,7 @@ Entries can be added at the end of a list. They may be traversed backwards, from tail to head. .IP \[bu] They may be concatenated. -.PP +.P However: .IP \[bu] 3 All list insertions and removals must specify the head of the list. @@ -110,7 +110,7 @@ Each head entry requires two pointers rather than one. Circular queues add the following functionality over the above: .IP \[bu] 3 The first and last entries are connected. -.PP +.P However: .IP \[bu] 3 The termination condition for traversal is more complex. diff --git a/upstream/debian-unstable/man7/random.7 b/upstream/debian-unstable/man7/random.7 index bca67cef..d4e2df93 100644 --- a/upstream/debian-unstable/man7/random.7 +++ b/upstream/debian-unstable/man7/random.7 @@ -9,7 +9,7 @@ .\" The following web page is quite informative: .\" http://www.2uo.de/myths-about-urandom/ .\" -.TH random 7 2023-02-10 "Linux man-pages 6.05.01" +.TH random 7 2024-05-02 "Linux man-pages 6.8" .SH NAME random \- overview of interfaces for obtaining randomness .SH DESCRIPTION @@ -17,7 +17,7 @@ The kernel random-number generator relies on entropy gathered from device drivers and other sources of environmental noise to seed a cryptographically secure pseudorandom number generator (CSPRNG). It is designed for security, rather than speed. -.PP +.P The following interfaces provide access to output from the kernel CSPRNG: .IP \[bu] 3 The @@ -77,7 +77,7 @@ flag. The cryptographic algorithms used for the .I urandom source are quite conservative, and so should be sufficient for all purposes. -.PP +.P The disadvantage of .B GRND_RANDOM and reads from @@ -194,7 +194,7 @@ or Diffie-Hellman private key has an effective key size of 128 bits (it requires about 2\[ha]128 operations to break) so a key generator needs only 128 bits (16 bytes) of seed material from .IR /dev/random . -.PP +.P While some safety margin above that minimum is reasonable, as a guard against flaws in the CSPRNG algorithm, no cryptographic primitive available today can hope to promise more than 256 bits of security, diff --git a/upstream/debian-unstable/man7/raw.7 b/upstream/debian-unstable/man7/raw.7 index ab43dd4a..13a09a76 100644 --- a/upstream/debian-unstable/man7/raw.7 +++ b/upstream/debian-unstable/man7/raw.7 @@ -5,7 +5,7 @@ .\" .\" $Id: raw.7,v 1.6 1999/06/05 10:32:08 freitag Exp $ .\" -.TH raw 7 2023-07-15 "Linux man-pages 6.05.01" +.TH raw 7 2024-05-02 "Linux man-pages 6.8" .SH NAME raw \- Linux IPv4 raw sockets .SH SYNOPSIS @@ -18,17 +18,17 @@ raw \- Linux IPv4 raw sockets Raw sockets allow new IPv4 protocols to be implemented in user space. A raw socket receives or sends the raw datagram not including link level headers. -.PP +.P The IPv4 layer generates an IP header when sending a packet unless the .B IP_HDRINCL socket option is enabled on the socket. When it is enabled, the packet must contain an IP header. For receiving, the IP header is always included in the packet. -.PP +.P In order to create a raw socket, a process must have the .B CAP_NET_RAW capability in the user namespace that governs its network namespace. -.PP +.P All packets or errors matching the .I protocol number specified @@ -39,7 +39,7 @@ see the IANA list of assigned protocol numbers at .UE and .BR getprotobyname (3). -.PP +.P A protocol of .B IPPROTO_RAW implies enabled @@ -61,7 +61,7 @@ Packet ID:Filled in when zero Total Length:Always filled in .TE .RE -.PP +.P If .B IP_HDRINCL is specified and the IP header has a nonzero destination address, then @@ -71,7 +71,7 @@ When is specified, the destination address should refer to a local interface, otherwise a routing table lookup is done anyway but gatewayed routes are ignored. -.PP +.P If .B IP_HDRINCL isn't set, then IP header options can be set on raw sockets with @@ -79,12 +79,12 @@ isn't set, then IP header options can be set on raw sockets with see .BR ip (7) for more information. -.PP +.P Starting with Linux 2.2, all IP header fields and options can be set using IP socket options. This means raw sockets are usually needed only for new protocols or protocols with no user interface (like ICMP). -.PP +.P When a packet is received, it is passed to any raw sockets which have been bound to its protocol before it is passed to other protocol handlers (e.g., kernel protocol modules). @@ -123,7 +123,7 @@ protocol. The value has a bit set for each ICMP message type which should be filtered out. The default is to filter no ICMP messages. -.PP +.P In addition, all .BR ip (7) .B IPPROTO_IP @@ -178,7 +178,7 @@ and .B ICMP_FILTER are new in Linux 2.2. They are Linux extensions and should not be used in portable programs. -.PP +.P Linux 2.0 enabled some bug-to-bug compatibility with BSD in the raw socket code when the .B SO_BSDCOMPAT @@ -202,7 +202,7 @@ When turned off, raw sockets will fragment outgoing packets that exceed the interface MTU. However, disabling it is not recommended for performance and reliability reasons. -.PP +.P A raw socket can be bound to a specific local address using the .BR bind (2) call. @@ -211,7 +211,7 @@ In addition, a raw socket can be bound to a specific network device using .BR SO_BINDTODEVICE ; see .BR socket (7). -.PP +.P An .B IPPROTO_RAW socket is send only. @@ -222,28 +222,28 @@ socket with the protocol. Note that packet sockets don't reassemble IP fragments, unlike raw sockets. -.PP +.P If you want to receive all ICMP packets for a datagram socket, it is often better to use .B IP_RECVERR on that particular socket; see .BR ip (7). -.PP +.P Raw sockets may tap all IP protocols in Linux, even protocols like ICMP or TCP which have a protocol module in the kernel. In this case, the packets are passed to both the kernel module and the raw socket(s). This should not be relied upon in portable programs, many other BSD socket implementation have limitations here. -.PP +.P Linux never changes headers passed from the user (except for filling in some zeroed fields as described for .BR IP_HDRINCL ). This differs from many other implementations of raw sockets. -.PP +.P Raw sockets are generally rather unportable and should be avoided in programs intended to be portable. -.PP +.P Sending on raw sockets should take the IP protocol from .IR sin_port ; this ability was lost in Linux 2.2. @@ -251,12 +251,12 @@ The workaround is to use .BR IP_HDRINCL . .SH BUGS Transparent proxy extensions are not described. -.PP +.P When the .B IP_HDRINCL option is set, datagrams will not be fragmented and are limited to the interface MTU. -.PP +.P Setting the IP protocol for sending in .I sin_port got lost in Linux 2.2. @@ -272,7 +272,7 @@ call is always used. .BR capabilities (7), .BR ip (7), .BR socket (7) -.PP +.P .B RFC\ 1191 for path MTU discovery. .B RFC\ 791 diff --git a/upstream/debian-unstable/man7/regex.7 b/upstream/debian-unstable/man7/regex.7 index 7a5b2d85..97a3fe33 100644 --- a/upstream/debian-unstable/man7/regex.7 +++ b/upstream/debian-unstable/man7/regex.7 @@ -35,14 +35,14 @@ .\" .ie t .ds dg \(dg .el .ds dg (!) -.TH regex 7 2023-03-08 "Linux man-pages 6.05.01" +.TH regex 7 2024-05-02 "Linux man-pages 6.8" .SH NAME regex \- POSIX.2 regular expressions .SH DESCRIPTION Regular expressions ("RE"s), as defined in POSIX.2, come in two forms: modern REs (roughly those of -.IR egrep ; +.BR egrep (1); POSIX.2 calls these "extended" REs) and obsolete REs (roughly those of .BR ed (1); @@ -52,15 +52,15 @@ they will be discussed at the end. POSIX.2 leaves some aspects of RE syntax and semantics open; "\*(dg" marks decisions on these aspects that may not be fully portable to other POSIX.2 implementations. -.PP +.P A (modern) RE is one\*(dg or more nonempty\*(dg \fIbranches\fR, separated by \[aq]|\[aq]. It matches anything that matches one of the branches. -.PP +.P A branch is one\*(dg or more \fIpieces\fR, concatenated. It matches a match for the first, followed by a match for the second, and so on. -.PP +.P A piece is an \fIatom\fR possibly followed by a single\*(dg \[aq]*\[aq], \[aq]+\[aq], \[aq]?\[aq], or \fIbound\fR. An atom followed by \[aq]*\[aq] @@ -69,7 +69,7 @@ An atom followed by \[aq]+\[aq] matches a sequence of 1 or more matches of the atom. An atom followed by \[aq]?\[aq] matches a sequence of 0 or 1 matches of the atom. -.PP +.P A \fIbound\fR is \[aq]{\[aq] followed by an unsigned decimal integer, possibly followed by \[aq],\[aq] possibly followed by another unsigned decimal integer, @@ -87,7 +87,7 @@ a sequence of \fIi\fR or more matches of the atom. An atom followed by a bound containing two integers \fIi\fR and \fIj\fR matches a sequence of \fIi\fR through \fIj\fR (inclusive) matches of the atom. -.PP +.P An atom is a regular expression enclosed in "\fI()\fP" (matching a match for the regular expression), an empty set of "\fI()\fP" (matching the null string)\*(dg, @@ -105,7 +105,7 @@ A \[aq]{\[aq] followed by a character other than a digit is an ordinary character, not the beginning of a bound\*(dg. It is illegal to end an RE with \[aq]\e\[aq]. -.PP +.P A \fIbracket expression\fR is a list of characters enclosed in "\fI[]\fP". It normally matches any single character from the list (but see below). If the list begins with \[aq]\[ha]\[aq], @@ -119,7 +119,7 @@ It is illegal\*(dg for two ranges to share an endpoint, for example, "\fIa\-c\-e\fP". Ranges are very collating-sequence-dependent, and portable programs should avoid relying on them. -.PP +.P To include a literal \[aq]]\[aq] in the list, make it the first character (following a possible \[aq]\[ha]\[aq]). To include a literal \[aq]\-\[aq], make it the first or last character, @@ -130,7 +130,7 @@ to make it a collating element (see below). With the exception of these and some combinations using \[aq][\[aq] (see next paragraphs), all other special characters, including \[aq]\e\[aq], lose their special significance within a bracket expression. -.PP +.P Within a bracket expression, a collating element (a character, a multicharacter sequence that collates as if it were a single character, or a collating-sequence name for either) @@ -142,7 +142,7 @@ can thus match more than one character, for example, if the collating sequence includes a "ch" collating element, then the RE "\fI[[.ch.]]*c\fP" matches the first five characters of "chchcc". -.PP +.P Within a bracket expression, a collating element enclosed in "\fI[=\fP" and "\fI=]\fP" is an equivalence class, standing for the sequences of characters of all collating elements equivalent to that one, including itself. @@ -154,13 +154,13 @@ then "\fI[[=o=]]\fP", "\fI[[=\(^o=]]\fP", and "\fI[o\(^o]\fP" are all synonymous. An equivalence class may not\*(dg be an endpoint of a range. -.PP +.P Within a bracket expression, the name of a \fIcharacter class\fR enclosed in "\fI[:\fP" and "\fI:]\fP" stands for the list of all characters belonging to that class. Standard character class names are: -.PP +.P .RS .TS l l l. @@ -170,14 +170,14 @@ blank lower upper cntrl print xdigit .TE .RE -.PP +.P These stand for the character classes defined in .BR wctype (3). A locale may provide others. A character class may not be used as an endpoint of a range. .\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666 .\" The following does not seem to apply in the glibc implementation -.\" .PP +.\" .P .\" There are two special cases\*(dg of bracket expressions: .\" the bracket expressions "\fI[[:<:]]\fP" and "\fI[[:>:]]\fP" match .\" the null string at the beginning and end of a word respectively. @@ -194,7 +194,7 @@ A character class may not be used as an endpoint of a range. .\" compatible with but not specified by POSIX.2, .\" and should be used with .\" caution in software intended to be portable to other systems. -.PP +.P In the event that an RE could match more than one substring of a given string, the RE matches the one starting earliest in the string. @@ -206,7 +206,7 @@ with subexpressions starting earlier in the RE taking priority over ones starting later. Note that higher-level subexpressions thus take priority over their lower-level component subexpressions. -.PP +.P Match lengths are measured in characters, not collating elements. A null string is considered longer than no match at all. For example, @@ -218,7 +218,7 @@ matches all three characters, and when "\fI(a*)*\fP" is matched against "bc" both the whole RE and the parenthesized subexpression match the null string. -.PP +.P If case-independent matching is specified, the effect is much as if all case distinctions had vanished from the alphabet. @@ -229,13 +229,13 @@ for example, \[aq]x\[aq] becomes "\fI[xX]\fP". When it appears inside a bracket expression, all case counterparts of it are added to the bracket expression, so that, for example, "\fI[x]\fP" becomes "\fI[xX]\fP" and "\fI[\[ha]x]\fP" becomes "\fI[\[ha]xX]\fP". -.PP +.P No particular limit is imposed on the length of REs\*(dg. Programs intended to be portable should not employ REs longer than 256 bytes, as an implementation can refuse to accept such REs and remain POSIX-compliant. -.PP +.P Obsolete ("basic") regular expressions differ in several respects. \[aq]|\[aq], \[aq]+\[aq], and \[aq]?\[aq] are ordinary characters and there is no equivalent @@ -251,7 +251,7 @@ RE or\*(dg the end of a parenthesized subexpression, and \[aq]*\[aq] is an ordinary character if it appears at the beginning of the RE or the beginning of a parenthesized subexpression (after a possible leading \[aq]\[ha]\[aq]). -.PP +.P Finally, there is one new type of atom, a \fIback reference\fR: \[aq]\e\[aq] followed by a nonzero decimal digit \fId\fR matches the same sequence of characters @@ -261,26 +261,26 @@ left to right), so that, for example, "\fI\e([bc]\e)\e1\fP" matches "bb" or "cc" but not "bc". .SH BUGS Having two kinds of REs is a botch. -.PP +.P The current POSIX.2 spec says that \[aq])\[aq] is an ordinary character in the absence of an unmatched \[aq](\[aq]; this was an unintentional result of a wording error, and change is likely. Avoid relying on it. -.PP +.P Back references are a dreadful botch, posing major problems for efficient implementations. They are also somewhat vaguely defined (does "\fIa\e(\e(b\e)*\e2\e)*d\fP" match "abbbd"?). Avoid using them. -.PP +.P POSIX.2's specification of case-independent matching is vague. The "one case implies all cases" definition given above is current consensus among implementors as to the right interpretation. .\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666 .\" The following does not seem to apply in the glibc implementation -.\" .PP +.\" .P .\" The syntax for word boundaries is incredibly ugly. .SH AUTHOR .\" Sigh... The page license means we must have the author's name @@ -289,5 +289,5 @@ This page was taken from Henry Spencer's regex package. .SH SEE ALSO .BR grep (1), .BR regex (3) -.PP +.P POSIX.2, section 2.8 (Regular Expression Notation). diff --git a/upstream/debian-unstable/man7/roff.7 b/upstream/debian-unstable/man7/roff.7 index 0610b868..49883c45 100644 --- a/upstream/debian-unstable/man7/roff.7 +++ b/upstream/debian-unstable/man7/roff.7 @@ -1,5 +1,5 @@ '\" t -.TH roff 7 "16 October 2023" "groff 1.23.0" +.TH roff 7 "30 April 2024" "groff 1.23.0" .SH Name roff \- concepts and history of .I roff diff --git a/upstream/debian-unstable/man7/rtld-audit.7 b/upstream/debian-unstable/man7/rtld-audit.7 index df04a8cd..931dc30c 100644 --- a/upstream/debian-unstable/man7/rtld-audit.7 +++ b/upstream/debian-unstable/man7/rtld-audit.7 @@ -5,7 +5,7 @@ .\" .\" 2009-01-12, mtk, Created .\" -.TH RTLD-AUDIT 7 2023-05-03 "Linux man-pages 6.05.01" +.TH RTLD-AUDIT 7 2024-05-02 "Linux man-pages 6.8" .SH NAME rtld\-audit \- auditing API for the dynamic linker .SH SYNOPSIS @@ -21,14 +21,14 @@ This API is very similar to the auditing interface provided by the Solaris run-time linker. The necessary constants and prototypes are defined by including .IR <link.h> . -.PP +.P To use this interface, the programmer creates a shared library that implements a standard set of function names. Not all of the functions need to be implemented: in most cases, if the programmer is not interested in a particular class of auditing event, then no implementation needs to be provided for the corresponding auditing function. -.PP +.P To employ the auditing interface, the environment variable .B LD_AUDIT must be defined to contain a colon-separated list of shared libraries, @@ -41,7 +41,7 @@ in the order that the libraries are listed. .nf .BI "unsigned int la_version(unsigned int " version ); .fi -.PP +.P This is the only function that .I must be defined by an auditing library: @@ -50,7 +50,7 @@ the auditing library. When invoking this function, the dynamic linker passes, in .IR version , the highest version of the auditing interface that the linker supports. -.PP +.P A typical implementation of this function simply returns the constant .BR LAV_CURRENT , which indicates the version of @@ -61,7 +61,7 @@ not support this version of the audit interface, it will refuse to activate this audit module. If the function returns zero, the dynamic linker also does not activate this audit module. -.PP +.P In order to enable backwards compatibility with older dynamic linkers, an audit module can examine the .I version @@ -83,7 +83,7 @@ definitions used to build the audit module. .BI "char *la_objsearch(const char *" name ", uintptr_t *" cookie , .BI " unsigned int " flag ); .fi -.PP +.P The dynamic linker invokes this function to inform the auditing library that it is about to search for a shared object. The @@ -130,7 +130,7 @@ was found via a search of one of the default directories. .B LA_SER_SECURE .I name is specific to a secure object (unused on Linux). -.PP +.P As its function result, .BR la_objsearch () returns the pathname that the dynamic linker should use @@ -144,7 +144,7 @@ should be returned. .nf .BI "void la_activity( uintptr_t *" cookie ", unsigned int "flag ); .fi -.PP +.P The dynamic linker calls this function to inform the auditing library that link-map activity is occurring. .I cookie @@ -167,7 +167,7 @@ Link-map activity has been completed: the map is once again consistent. .BI "unsigned int la_objopen(struct link_map *" map ", Lmid_t " lmid , .BI " uintptr_t *" cookie ); .fi -.PP +.P The dynamic linker calls this function when a new shared object is loaded. The .I map @@ -182,7 +182,7 @@ Link map is part of the initial namespace. .B LM_ID_NEWLM Link map is part of a new namespace requested via .BR dlmopen (3). -.PP +.P .I cookie is a pointer to an identifier for this object. The identifier is provided to later calls to functions @@ -190,7 +190,7 @@ in the auditing library in order to identify this object. This identifier is initialized to point to object's link map, but the audit library can change the identifier to some other value that it may prefer to use to identify the object. -.PP +.P As its return value, .BR la_objopen () returns a bit mask created by ORing zero or more of the @@ -203,7 +203,7 @@ Audit symbol bindings to this object. .TP .B LA_FLG_BINDFROM Audit symbol bindings from this object. -.PP +.P A return value of 0 from .BR la_objopen () indicates that no symbol bindings should be audited for this object. @@ -212,7 +212,7 @@ indicates that no symbol bindings should be audited for this object. .nf .BI "unsigned int la_objclose(uintptr_t *" cookie ); .fi -.PP +.P The dynamic linker invokes this function after any finalization code for the object has been executed, before the object is unloaded. @@ -220,7 +220,7 @@ The .I cookie argument is the identifier obtained from a previous invocation of .BR la_objopen (). -.PP +.P In the current implementation, the value returned by .BR la_objclose () is ignored. @@ -229,7 +229,7 @@ is ignored. .nf .BI "void la_preinit(uintptr_t *" cookie ); .fi -.PP +.P The dynamic linker invokes this function after all shared objects have been loaded, before control is passed to the application (i.e., before calling @@ -248,7 +248,7 @@ may still later dynamically load objects using .BI " uintptr_t *" refcook ", uintptr_t *" defcook , .BI " unsigned int *" flags ", const char *" symname ); .fi -.PP +.P The dynamic linker invokes one of these functions when a symbol binding occurs between two shared objects that have been marked for auditing notification by @@ -259,7 +259,7 @@ function is employed on 32-bit platforms; the .BR la_symbind64 () function is employed on 64-bit platforms. -.PP +.P The .I sym argument is a pointer to a structure @@ -269,12 +269,12 @@ The structure definition is shown in Among the fields of this structure, .I st_value indicates the address to which the symbol is bound. -.PP +.P The .I ndx argument gives the index of the symbol in the symbol table of the bound shared object. -.PP +.P The .I refcook argument identifies the shared object that is making the symbol reference; @@ -289,11 +289,11 @@ this is the same identifier that is provided to the .BR la_objopen () function that returned .BR LA_FLG_BINDTO . -.PP +.P The .I symname argument points a string containing the name of the symbol. -.PP +.P The .I flags argument is a bit mask that both provides information about the symbol @@ -310,7 +310,7 @@ The binding resulted from a call to A previous .BR la_symbind* () call returned an alternate value for this symbol. -.PP +.P By default, if the auditing library implements .BR la_pltenter () and @@ -334,7 +334,7 @@ for this symbol. Don't call .BR la_pltexit () for this symbol. -.PP +.P The return value of .BR la_symbind32 () and @@ -351,17 +351,17 @@ depend on the hardware platform. (The appropriate definition is supplied by .IR <link.h> .) Here is the definition for x86-32: -.PP +.P .nf .BI "Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *" sym ", unsigned int " ndx , .BI " uintptr_t *" refcook ", uintptr_t *" defcook , .BI " La_i86_regs *" regs ", unsigned int *" flags , .BI " const char *" symname ", long *" framesizep ); .fi -.PP +.P This function is invoked just before a PLT entry is called, between two shared objects that have been marked for binding notification. -.PP +.P The .IR sym , .IR ndx , @@ -371,20 +371,20 @@ and .I symname are as for .BR la_symbind* (). -.PP +.P The .I regs argument points to a structure (defined in .IR <link.h> ) containing the values of registers to be used for the call to this PLT entry. -.PP +.P The .I flags argument points to a bit mask that conveys information about, and can be used to modify subsequent auditing of, this PLT entry, as for .BR la_symbind* (). -.PP +.P .\" FIXME . Is the following correct? The .I framesizep @@ -400,7 +400,7 @@ The .BR la_pltexit () function is called only if this buffer is explicitly set to a suitable value. -.PP +.P The return value of .BR la_pltenter () is as for @@ -411,20 +411,20 @@ depend on the hardware platform. (The appropriate definition is supplied by .IR <link.h> .) Here is the definition for x86-32: -.PP +.P .nf .BI "unsigned int la_i86_gnu_pltexit(Elf32_Sym *" sym ", unsigned int " ndx , .BI " uintptr_t *" refcook ", uintptr_t *" defcook , .BI " const La_i86_regs *" inregs ", La_i86_retval *" outregs , .BI " const char *" symname ); .fi -.PP +.P This function is called when a PLT entry, made between two shared objects that have been marked for binding notification, returns. The function is called just before control returns to the caller of the PLT entry. -.PP +.P The .IR sym , .IR ndx , @@ -434,7 +434,7 @@ and .I symname are as for .BR la_symbind* (). -.PP +.P The .I inregs argument points to a structure (defined in @@ -447,7 +447,7 @@ argument points to a structure (defined in containing return values for the call to this PLT entry. These values can be modified by the caller, and the changes will be visible to the caller of the PLT entry. -.PP +.P In the current GNU implementation, the return value of .BR la_pltexit () is ignored. diff --git a/upstream/debian-unstable/man7/rtnetlink.7 b/upstream/debian-unstable/man7/rtnetlink.7 index f710bbea..36c57a60 100644 --- a/upstream/debian-unstable/man7/rtnetlink.7 +++ b/upstream/debian-unstable/man7/rtnetlink.7 @@ -7,7 +7,7 @@ .\" help from Matthew Wilcox. .\" $Id: rtnetlink.7,v 1.8 2000/01/22 01:55:04 freitag Exp $ .\" -.TH rtnetlink 7 2023-07-15 "Linux man-pages 6.05.01" +.TH rtnetlink 7 2024-05-02 "Linux man-pages 6.8" .SH NAME rtnetlink \- Linux routing socket .SH SYNOPSIS @@ -17,7 +17,7 @@ rtnetlink \- Linux routing socket .B #include <linux/netlink.h> .B #include <linux/rtnetlink.h> .B #include <sys/socket.h> -.PP +.P .BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type ", NETLINK_ROUTE);" .fi .SH DESCRIPTION @@ -36,7 +36,7 @@ for more information. .\" FIXME . ? all these macros could be moved to rtnetlink(3) .SS Routing attributes Some rtnetlink messages have optional attributes after the initial header: -.PP +.P .in +4n .EX struct rtattr { @@ -46,7 +46,7 @@ struct rtattr { }; .EE .in -.PP +.P These attributes should be manipulated using only the RTA_* macros or libnetlink, see .BR rtnetlink (3). @@ -54,7 +54,11 @@ or libnetlink, see Rtnetlink consists of these message types (in addition to standard netlink messages): .TP -.BR RTM_NEWLINK ", " RTM_DELLINK ", " RTM_GETLINK +.B RTM_NEWLINK +.TQ +.B RTM_DELLINK +.TQ +.B RTM_GETLINK Create, remove, or get information about a specific network interface. These messages contain an .I ifinfomsg @@ -113,7 +117,11 @@ is .RI ( "struct net_device_stats" in Linux 2.4 and earlier). .TP -.BR RTM_NEWADDR ", " RTM_DELADDR ", " RTM_GETADDR +.B RTM_NEWADDR +.TQ +.B RTM_DELADDR +.TQ +.B RTM_GETADDR Add, remove, or receive information about an IP address associated with an interface. In Linux 2.2, an interface can carry multiple IP addresses, @@ -171,7 +179,11 @@ IFA_CACHEINFO:struct ifa_cacheinfo:Address information .TE .\" FIXME Document struct ifa_cacheinfo .TP -.BR RTM_NEWROUTE ", " RTM_DELROUTE ", " RTM_GETROUTE +.B RTM_NEWROUTE +.TQ +.B RTM_DELROUTE +.TQ +.B RTM_GETROUTE Create, remove, or receive information about a network route. These messages contain an .I rtmsg @@ -243,7 +255,7 @@ RTPROT_KERNEL:by the kernel RTPROT_BOOT:during boot RTPROT_STATIC:by the administrator .TE -.sp 1 +.IP Values larger than .B RTPROT_STATIC are not interpreted by the kernel, they are just for user information. @@ -266,7 +278,7 @@ RT_SCOPE_LINK:route on this link RT_SCOPE_HOST:route on the local host RT_SCOPE_NOWHERE:destination doesn't exist .TE -.sp 1 +.IP The values between .B RT_SCOPE_UNIVERSE and @@ -285,7 +297,7 @@ T} RTM_F_CLONED:route is cloned from another route RTM_F_EQUALIZE:a multipath equalizer (not yet implemented) .TE -.sp 1 +.IP .I rtm_table specifies the routing table .TS @@ -296,7 +308,7 @@ RT_TABLE_DEFAULT:the default table RT_TABLE_MAIN:the main table RT_TABLE_LOCAL:the local table .TE -.sp 1 +.IP The user may assign arbitrary values between .B RT_TABLE_UNSPEC and @@ -424,7 +436,11 @@ defined in .IP .B Fill these values in! .TP -.BR RTM_NEWNEIGH ", " RTM_DELNEIGH ", " RTM_GETNEIGH +.B RTM_NEWNEIGH +.TQ +.B RTM_DELNEIGH +.TQ +.B RTM_GETNEIGH Add, remove, or receive information about a neighbor table entry (e.g., an ARP entry). The message contains an @@ -462,7 +478,7 @@ NUD_FAILED:an invalid cache entry NUD_NOARP:a device with no destination cache NUD_PERMANENT:a static entry .TE -.sp 1 +.IP Valid .I ndm_flags are: @@ -472,7 +488,7 @@ lb l. NTF_PROXY:a proxy arp entry NTF_ROUTER:an IPv6 router .TE -.sp 1 +.IP .\" FIXME . .\" document the members of the struct better The @@ -488,7 +504,7 @@ NDA_DST:a neighbor cache n/w layer destination address NDA_LLADDR:a neighbor cache link layer address NDA_CACHEINFO:cache statistics .TE -.sp 1 +.IP If the .I rta_type field is @@ -497,12 +513,20 @@ then a .I struct nda_cacheinfo header follows. .TP -.BR RTM_NEWRULE ", " RTM_DELRULE ", " RTM_GETRULE +.B RTM_NEWRULE +.TQ +.B RTM_DELRULE +.TQ +.B RTM_GETRULE Add, delete, or retrieve a routing rule. Carries a .I struct rtmsg .TP -.BR RTM_NEWQDISC ", " RTM_DELQDISC ", " RTM_GETQDISC +.B RTM_NEWQDISC +.TQ +.B RTM_DELQDISC +.TQ +.B RTM_GETQDISC Add, remove, or get a queueing discipline. The message contains a .I struct tcmsg @@ -532,17 +556,25 @@ TCA_STATS:struct tc_stats:Qdisc statistics TCA_XSTATS:qdisc-specific:Module-specific statistics TCA_RATE:struct tc_estimator:Rate limit .TE -.sp 1 +.IP In addition, various other qdisc-module-specific attributes are allowed. For more information see the appropriate include files. .TP -.BR RTM_NEWTCLASS ", " RTM_DELTCLASS ", " RTM_GETTCLASS +.B RTM_NEWTCLASS +.TQ +.B RTM_DELTCLASS +.TQ +.B RTM_GETTCLASS Add, remove, or get a traffic class. These messages contain a .I struct tcmsg as described above. .TP -.BR RTM_NEWTFILTER ", " RTM_DELTFILTER ", " RTM_GETTFILTER +.B RTM_NEWTFILTER +.TQ +.B RTM_DELTFILTER +.TQ +.B RTM_GETTFILTER Add, remove, or receive information about a traffic filter. These messages contain a .I struct tcmsg diff --git a/upstream/debian-unstable/man7/samba.7 b/upstream/debian-unstable/man7/samba.7 index a9fed89b..c691f384 100644 --- a/upstream/debian-unstable/man7/samba.7 +++ b/upstream/debian-unstable/man7/samba.7 @@ -2,12 +2,12 @@ .\" Title: samba .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> -.\" Date: 02/19/2024 +.\" Date: 05/29/2024 .\" Manual: Miscellanea -.\" Source: Samba 4.19.5-Debian +.\" Source: Samba 4.20.1-Debian .\" Language: English .\" -.TH "SAMBA" "7" "02/19/2024" "Samba 4\&.19\&.5\-Debian" "Miscellanea" +.TH "SAMBA" "7" "05/29/2024" "Samba 4\&.20\&.1\-Debian" "Miscellanea" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -231,7 +231,7 @@ https://lists\&.samba\&.org you can find a lot of information in the archives and you can subscribe to the samba list and ask for help or discuss things\&. .SH "VERSION" .PP -This man page is part of version 4\&.19\&.5\-Debian of the Samba suite\&. +This man page is part of version 4\&.20\&.1\-Debian of the Samba suite\&. .SH "CONTRIBUTIONS" .PP If you wish to contribute to the Samba project, then I suggest you join the Samba mailing list at diff --git a/upstream/debian-unstable/man7/sane.7 b/upstream/debian-unstable/man7/sane.7 index f9ab73e0..9698072c 100644 --- a/upstream/debian-unstable/man7/sane.7 +++ b/upstream/debian-unstable/man7/sane.7 @@ -61,7 +61,7 @@ homepage. .SH "GENERAL INFORMATION" The following sections provide short descriptions and links to more information about several aspects of -.B SANE. +.BR SANE . A name with a number in parenthesis (e.g. .BR sane\-dll (5)) points to a manual page. In this case @@ -367,6 +367,11 @@ Supports the Lexmark X1100 series of USB scanners. See .BR sane\-lexmark (5) for details. .TP +.B lexmark_x2600 +Supports the Lexmark X2600 series of USB scanners. See +.BR sane\-lexmark_x2600 (5) +for details. +.TP .B ma1509 Supports the Mustek BearPaw 1200F USB flatbed scanner. See .BR sane\-ma1509 (5) @@ -818,7 +823,7 @@ So now scanning with works and you want to use one of the graphical frontends like .BR xsane (1) , .BR xscanimage (1) ", or" -.B quiteinsane (1) +.BR quiteinsane (1) but those frontends don't detect your scanner? One reason may be that you installed two versions of .BR SANE . @@ -905,6 +910,7 @@ for details). .BR sane\-kodak (5), .BR sane\-leo (5), .BR sane\-lexmark (5), +.BR sane\-lexmark_x2600 (5), .BR sane\-ma1509 (5), .BR sane\-matsushita (5), .BR sane\-microtek2 (5), diff --git a/upstream/debian-unstable/man7/sched.7 b/upstream/debian-unstable/man7/sched.7 index 78545053..82c7ae31 100644 --- a/upstream/debian-unstable/man7/sched.7 +++ b/upstream/debian-unstable/man7/sched.7 @@ -10,7 +10,7 @@ .\" .\" Worth looking at: http://rt.wiki.kernel.org/index.php .\" -.TH sched 7 2023-02-10 "Linux man-pages 6.05.01" +.TH sched 7 2024-05-02 "Linux man-pages 6.8" .SH NAME sched \- overview of CPU scheduling .SH DESCRIPTION @@ -91,12 +91,12 @@ scheduling priority, .IR sched_priority . The scheduler makes its decisions based on knowledge of the scheduling policy and static priority of all threads on the system. -.PP +.P For threads scheduled under one of the normal scheduling policies (\fBSCHED_OTHER\fP, \fBSCHED_IDLE\fP, \fBSCHED_BATCH\fP), \fIsched_priority\fP is not used in scheduling decisions (it must be specified as 0). -.PP +.P Processes scheduled under one of the real-time policies (\fBSCHED_FIFO\fP, \fBSCHED_RR\fP) have a \fIsched_priority\fP value in the range 1 (low) to 99 (high). @@ -110,17 +110,17 @@ Portable programs should use and .BR sched_get_priority_max (2) to find the range of priorities supported for a particular policy. -.PP +.P Conceptually, the scheduler maintains a list of runnable threads for each possible \fIsched_priority\fP value. In order to determine which thread runs next, the scheduler looks for the nonempty list with the highest static priority and selects the thread at the head of this list. -.PP +.P A thread's scheduling policy determines where it will be inserted into the list of threads with equal static priority and how it will move inside this list. -.PP +.P All scheduling is preemptive: if a thread with a higher static priority becomes ready to run, the currently running thread will be preempted and @@ -158,7 +158,7 @@ changes the priority of the running or runnable thread identified by .I pid the effect on the thread's position in the list depends on -the direction of the change to threads priority: +the direction of the change to the thread's priority: .RS .IP (a) 5 If the thread's priority is raised, @@ -184,11 +184,11 @@ the list for its priority. A thread calling .BR sched_yield (2) will be put at the end of the list. -.PP +.P No other events will move a thread scheduled under the \fBSCHED_FIFO\fP policy in the wait list of runnable threads with equal static priority. -.PP +.P A \fBSCHED_FIFO\fP thread runs until either it is blocked by an I/O request, it is preempted by a higher priority thread, or it calls @@ -224,7 +224,7 @@ one must use the Linux-specific and .BR sched_getattr (2) system calls. -.PP +.P A sporadic task is one that has a sequence of jobs, where each job is activated at most once per period. Each job also has a @@ -242,9 +242,9 @@ is the time at which a task starts its execution. The .I absolute deadline is thus obtained by adding the relative deadline to the arrival time. -.PP +.P The following diagram clarifies these terms: -.PP +.P .in +4n .EX arrival/wakeup absolute deadline @@ -257,7 +257,7 @@ arrival/wakeup absolute deadline |<-------------- period ------------------->| .EE .in -.PP +.P When setting a .B SCHED_DEADLINE policy for a thread using @@ -274,7 +274,7 @@ Deadline to the relative deadline, and Period to the period of the task. Thus, for .B SCHED_DEADLINE scheduling, we have: -.PP +.P .in +4n .EX arrival/wakeup absolute deadline @@ -287,7 +287,7 @@ arrival/wakeup absolute deadline |<-------------- Period ------------------->| .EE .in -.PP +.P The three deadline-scheduling parameters correspond to the .IR sched_runtime , .IR sched_deadline , @@ -305,15 +305,15 @@ If .I sched_period is specified as 0, then it is made the same as .IR sched_deadline . -.PP +.P The kernel requires that: -.PP +.P .in +4n .EX sched_runtime <= sched_deadline <= sched_period .EE .in -.PP +.P .\" See __checkparam_dl in kernel/sched/core.c In addition, under the current implementation, all of the parameter values must be at least 1024 @@ -323,10 +323,10 @@ If any of these checks fails, .BR sched_setattr (2) fails with the error .BR EINVAL . -.PP +.P The CBS guarantees non-interference between tasks, by throttling threads that attempt to over-run their specified Runtime. -.PP +.P To ensure deadline scheduling guarantees, the kernel must prevent situations where the set of .B SCHED_DEADLINE @@ -339,13 +339,13 @@ if it is not, .BR sched_setattr (2) fails with the error .BR EBUSY . -.PP +.P For example, it is required (but not necessarily sufficient) for the total utilization to be less than or equal to the total number of CPUs available, where, since each thread can maximally run for Runtime per Period, that thread's utilization is its Runtime divided by its Period. -.PP +.P In order to fulfill the guarantees that are made when a thread is admitted to the .B SCHED_DEADLINE @@ -356,7 +356,7 @@ system; if any .B SCHED_DEADLINE thread is runnable, it will preempt any thread scheduled under one of the other policies. -.PP +.P A call to .BR fork (2) by a thread scheduled under the @@ -364,7 +364,7 @@ by a thread scheduled under the policy fails with the error .BR EAGAIN , unless the thread has its reset-on-fork flag set (see below). -.PP +.P A .B SCHED_DEADLINE thread that calls @@ -383,7 +383,7 @@ processes). \fBSCHED_OTHER\fP is the standard Linux time-sharing scheduler that is intended for all threads that do not require the special real-time mechanisms. -.PP +.P The thread to run is chosen from the static priority 0 list based on a \fIdynamic\fP priority that is determined only inside this list. @@ -391,7 +391,7 @@ The dynamic priority is based on the nice value (see below) and is increased for each time quantum the thread is ready to run, but denied to run by the scheduler. This ensures fair progress among all \fBSCHED_OTHER\fP threads. -.PP +.P In the Linux kernel source code, the .B SCHED_OTHER policy is actually named @@ -411,12 +411,12 @@ The nice value can be modified using .BR setpriority (2), or .BR sched_setattr (2). -.PP +.P According to POSIX.1, the nice value is a per-process attribute; that is, the threads in a process should share a nice value. However, on Linux, the nice value is a per-thread attribute: different threads in the same process may have different nice values. -.PP +.P The range of the nice value varies across UNIX systems. On modern Linux, the range is \-20 (high priority) to +19 (low priority). @@ -424,12 +424,12 @@ On some other systems, the range is \-20..20. Very early Linux kernels (before Linux 2.0) had the range \-infinity..15. .\" Linux before 1.3.36 had \-infinity..15. .\" Since Linux 1.3.43, Linux has the range \-20..19. -.PP +.P The degree to which the nice value affects the relative scheduling of .B SCHED_OTHER processes likewise varies across UNIX systems and across Linux kernel versions. -.PP +.P With the advent of the CFS scheduler in Linux 2.6.23, Linux adopted an algorithm that causes relative differences in nice values to have a much stronger effect. @@ -441,14 +441,14 @@ to a process whenever there is any other higher priority load on the system, and makes high nice values (\-20) deliver most of the CPU to applications that require it (e.g., some audio applications). -.PP +.P On Linux, the .B RLIMIT_NICE resource limit can be used to define a limit to which an unprivileged process's nice value can be raised; see .BR setrlimit (2) for details. -.PP +.P For further details on the nice value, see the subsections on the autogroup feature and group scheduling, below. .\" @@ -464,7 +464,7 @@ that the thread is CPU-intensive. Consequently, the scheduler will apply a small scheduling penalty with respect to wakeup behavior, so that this thread is mildly disfavored in scheduling decisions. -.PP +.P .\" The following paragraph is drawn largely from the text that .\" accompanied Ingo Molnar's patch for the implementation of .\" SCHED_BATCH. @@ -478,7 +478,7 @@ interactivity causing extra preemptions (between the workload's tasks). (Since Linux 2.6.23.) \fBSCHED_IDLE\fP can be used only at static priority 0; the process nice value has no influence for this policy. -.PP +.P This policy is intended for running jobs at extremely low priority (lower even than a +19 nice value with the .B SCHED_OTHER @@ -508,20 +508,20 @@ flag in .I attr.sched_flags when calling .BR sched_setattr (2). -.PP +.P Note that the constants used with these two APIs have different names. The state of the reset-on-fork flag can analogously be retrieved using .BR sched_getscheduler (2) and .BR sched_getattr (2). -.PP +.P The reset-on-fork feature is intended for media-playback applications, and can be used to prevent applications evading the .B RLIMIT_RTTIME resource limit (see .BR getrlimit (2)) by creating multiple child processes. -.PP +.P More precisely, if the reset-on-fork flag is set, the following rules apply for subsequently created children: .IP \[bu] 3 @@ -535,7 +535,7 @@ in child processes. .IP \[bu] If the calling process has a negative nice value, the nice value is reset to zero in child processes. -.PP +.P After the reset-on-fork flag has been enabled, it can be reset only if the thread has the .B CAP_SYS_NICE @@ -555,13 +555,13 @@ matches the real or effective user ID of the target thread (i.e., the thread specified by .IR pid ) whose policy is being changed. -.PP +.P A thread must be privileged .RB ( CAP_SYS_NICE ) in order to set or modify a .B SCHED_DEADLINE policy. -.PP +.P Since Linux 2.6.12, the .B RLIMIT_RTPRIO resource limit defines a ceiling on an unprivileged thread's @@ -608,7 +608,7 @@ policy so long as its nice value falls within the range permitted by its .B RLIMIT_NICE resource limit (see .BR getrlimit (2)). -.PP +.P Privileged .RB ( CAP_SYS_NICE ) threads ignore the @@ -632,7 +632,7 @@ process from freezing the system was to run (at the console) a shell scheduled under a higher static priority than the tested application. This allows an emergency kill of tested real-time applications that do not block or terminate as expected. -.PP +.P Since Linux 2.6.25, there are other techniques for dealing with runaway real-time and deadline processes. One of these is to use the @@ -642,7 +642,7 @@ a real-time process may consume. See .BR getrlimit (2) for details. -.PP +.P Since Linux 2.6.25, Linux also provides two .I /proc files that can be used to reserve a certain amount of CPU time @@ -684,7 +684,7 @@ Child processes inherit the scheduling policy and parameters across a .BR fork (2). The scheduling policy and parameters are preserved across .BR execve (2). -.PP +.P Memory locking is usually needed for real-time processes to avoid paging delays; this can be done with .BR mlock (2) @@ -701,7 +701,7 @@ parallel build processes (i.e., the .BR make (1) .B \-j flag). -.PP +.P This feature operates in conjunction with the CFS scheduler and requires a kernel that is configured with .BR CONFIG_SCHED_AUTOGROUP . @@ -711,7 +711,7 @@ a value of 0 disables the feature, while a value of 1 enables it. The default value in this file is 1, unless the kernel was booted with the .I noautogroup parameter. -.PP +.P A new autogroup is created when a new session is created via .BR setsid (2); this happens, for example, when a new terminal window is started. @@ -721,14 +721,14 @@ inherits its parent's autogroup membership. Thus, all of the processes in a session are members of the same autogroup. An autogroup is automatically destroyed when the last process in the group terminates. -.PP +.P When autogrouping is enabled, all of the members of an autogroup are placed in the same kernel scheduler "task group". The CFS scheduler employs an algorithm that equalizes the distribution of CPU cycles across task groups. The benefits of this for interactive desktop performance can be described via the following example. -.PP +.P Suppose that there are two autogroups competing for the same CPU (i.e., presume either a single CPU system or the use of .BR taskset (1) @@ -759,17 +759,17 @@ the scheduler distributes CPU cycles across task groups such that an autogroup that contains a large number of CPU-bound processes does not end up hogging CPU cycles at the expense of the other jobs on the system. -.PP +.P A process's autogroup (task group) membership can be viewed via the file .IR /proc/ pid /autogroup : -.PP +.P .in +4n .EX $ \fBcat /proc/1/autogroup\fP /autogroup\-1 nice 0 .EE .in -.PP +.P This file can also be used to modify the CPU bandwidth allocated to an autogroup. This is done by writing a number in the "nice" range to the file @@ -791,7 +791,7 @@ to fail with the error .\" A patch was posted on 23 Nov 2016 .\" ("sched/autogroup: Fix 64bit kernel nice adjustment"; .\" check later to see in which kernel version it lands. -.PP +.P The autogroup nice setting has the same meaning as the process nice value, but applies to distribution of CPU cycles to the autogroup as a whole, based on the relative nice values of other autogroups. @@ -800,12 +800,12 @@ will be a product of the autogroup's nice value (compared to other autogroups) and the process's nice value (compared to other processes in the same autogroup. -.PP +.P The use of the .BR cgroups (7) CPU controller to place processes in cgroups other than the root CPU cgroup overrides the effect of autogrouping. -.PP +.P The autogroup feature groups only processes scheduled under non-real-time policies .RB ( SCHED_OTHER , @@ -826,7 +826,7 @@ policies), the CFS scheduler employs a technique known as "group scheduling", if the kernel was configured with the .B CONFIG_FAIR_GROUP_SCHED option (which is typical). -.PP +.P Under group scheduling, threads are scheduled in "task groups". Task groups have a hierarchical relationship, rooted under the initial task group on the system, @@ -856,7 +856,7 @@ If group scheduling was disabled (i.e., the kernel was configured without .BR CONFIG_FAIR_GROUP_SCHED ), then all of the processes on the system are notionally placed in a single task group. -.PP +.P Under group scheduling, a thread's nice value has an effect for scheduling decisions .IR "only relative to other threads in the same task group" . @@ -870,7 +870,7 @@ or on a process has an effect only for scheduling relative to other processes executed in the same session (typically: the same terminal window). -.PP +.P Conversely, for two processes that are (for example) the sole CPU-bound processes in different sessions (e.g., different terminal windows, @@ -886,7 +886,7 @@ A possibly useful workaround here is to use a command such as the following to modify the autogroup nice value for .I all of the processes in a terminal session: -.PP +.P .in +4n .EX $ \fBecho 10 > /proc/self/autogroup\fP @@ -904,17 +904,17 @@ Until the patches have been completely merged into the mainline kernel, they must be installed to achieve the best real-time performance. These patches are named: -.PP +.P .in +4n .EX patch\-\fIkernelversion\fP\-rt\fIpatchversion\fP .EE .in -.PP +.P and can be downloaded from .UR http://www.kernel.org\:/pub\:/linux\:/kernel\:/projects\:/rt/ .UE . -.PP +.P Without the patches and prior to their full inclusion into the mainline kernel, the kernel configuration offers only the three preemption classes .BR CONFIG_PREEMPT_NONE , @@ -923,7 +923,7 @@ and .B CONFIG_PREEMPT_DESKTOP which respectively provide no, some, and considerable reduction of the worst-case scheduling latency. -.PP +.P With the patches applied or after their full inclusion into the mainline kernel, the additional configuration item .B CONFIG_PREEMPT_RT @@ -937,7 +937,7 @@ The .BR cgroups (7) CPU controller can be used to limit the CPU consumption of groups of processes. -.PP +.P Originally, Standard Linux was intended as a general-purpose operating system being able to handle background processes, interactive applications, and less demanding real-time applications (applications that @@ -980,10 +980,10 @@ was not possible up to Linux 2.6.17. .BR capabilities (7), .BR cpuset (7) .ad -.PP +.P .I Programming for the real world \- POSIX.4 by Bill O.\& Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0. -.PP +.P The Linux kernel source files .IR \%Documentation/\:scheduler/\:sched\-deadline\:.txt , .IR \%Documentation/\:scheduler/\:sched\-rt\-group\:.txt , diff --git a/upstream/debian-unstable/man7/sem_overview.7 b/upstream/debian-unstable/man7/sem_overview.7 index c452a1c2..cf87f8fb 100644 --- a/upstream/debian-unstable/man7/sem_overview.7 +++ b/upstream/debian-unstable/man7/sem_overview.7 @@ -2,12 +2,12 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sem_overview 7 2022-12-04 "Linux man-pages 6.05.01" +.TH sem_overview 7 2024-05-02 "Linux man-pages 6.8" .SH NAME sem_overview \- overview of POSIX semaphores .SH DESCRIPTION POSIX semaphores allow processes and threads to synchronize their actions. -.PP +.P A semaphore is an integer whose value is never allowed to fall below zero. Two operations can be performed on semaphores: increment the semaphore value by one @@ -17,7 +17,7 @@ and decrement the semaphore value by one If the value of a semaphore is currently zero, then a .BR sem_wait (3) operation will block until the value becomes greater than zero. -.PP +.P POSIX semaphores come in two forms: named semaphores and unnamed semaphores. .TP @@ -81,7 +81,7 @@ When the semaphore is no longer required, and before the memory in which it is located is deallocated, the semaphore should be destroyed using .BR sem_destroy (3). -.PP +.P The remainder of this section describes some specific details of the Linux implementation of POSIX semaphores. .SS Versions @@ -111,7 +111,7 @@ with names of the form rather than .B NAME_MAX characters.) -.PP +.P Since Linux 2.6.19, ACLs can be placed on files under this directory, to control object permissions on a per-user and per-group basis. .SH NOTES diff --git a/upstream/debian-unstable/man7/session-keyring.7 b/upstream/debian-unstable/man7/session-keyring.7 index d8a950f1..7ed38b59 100644 --- a/upstream/debian-unstable/man7/session-keyring.7 +++ b/upstream/debian-unstable/man7/session-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH session-keyring 7 2023-03-12 "Linux man-pages 6.05.01" +.TH session-keyring 7 2024-05-02 "Linux man-pages 6.8" .SH NAME session-keyring \- session shared process keyring .SH DESCRIPTION @@ -18,17 +18,17 @@ may revoke the session keyring on logout. (In typical configurations, PAM does do this revocation.) The session keyring has the name (description) .IR _ses . -.PP +.P A special serial number value, .BR KEY_SPEC_SESSION_KEYRING , is defined that can be used in lieu of the actual serial number of the calling process's session keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@s\fP' can be used instead of a numeric key ID in much the same way. -.PP +.P A process's session keyring is inherited across .BR clone (2), .BR fork (2), @@ -40,7 +40,7 @@ is preserved across even when the executable is set-user-ID or set-group-ID or has capabilities. The session keyring is destroyed when the last process that refers to it exits. -.PP +.P If a process doesn't have a session keyring when it is accessed, then, under certain circumstances, the .BR user\-session\-keyring (7) @@ -76,11 +76,11 @@ identical security attributes and must be single threaded. .BR keyctl (2) .B KEYCTL_SESSION_TO_PARENT operation.) -.PP +.P These operations are also exposed through the .BR keyctl (1) utility as: -.PP +.P .in +4n .EX keyctl session @@ -88,9 +88,9 @@ keyctl session \- [<prog> <arg1> <arg2> ...] keyctl session <name> [<prog> <arg1> <arg2> ...] .EE .in -.PP +.P and: -.PP +.P .in +4n .EX keyctl new_session diff --git a/upstream/debian-unstable/man7/shm_overview.7 b/upstream/debian-unstable/man7/shm_overview.7 index 9a33ea0c..e8563625 100644 --- a/upstream/debian-unstable/man7/shm_overview.7 +++ b/upstream/debian-unstable/man7/shm_overview.7 @@ -3,13 +3,13 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH shm_overview 7 2022-12-04 "Linux man-pages 6.05.01" +.TH shm_overview 7 2024-05-02 "Linux man-pages 6.8" .SH NAME shm_overview \- overview of POSIX shared memory .SH DESCRIPTION The POSIX shared memory API allows processes to communicate information by sharing a region of memory. -.PP +.P The interfaces employed in the API are: .TP 15 .BR shm_open (3) @@ -80,7 +80,7 @@ to control the permissions of objects in the virtual filesystem. .SH NOTES Typically, processes must synchronize their access to a shared memory object, using, for example, POSIX semaphores. -.PP +.P System V shared memory .RB ( shmget (2), .BR shmop (2), diff --git a/upstream/debian-unstable/man7/sigevent.7 b/upstream/debian-unstable/man7/sigevent.7 deleted file mode 100644 index 1ae860f0..00000000 --- a/upstream/debian-unstable/man7/sigevent.7 +++ /dev/null @@ -1,120 +0,0 @@ -.\" Copyright (C) 2006, 2010 Michael Kerrisk <mtk.manpages@gmail.com> -.\" Copyright (C) 2009 Petr Baudis <pasky@suse.cz> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH sigevent 7 2022-10-30 "Linux man-pages 6.05.01" -.SH NAME -sigevent \- structure for notification from asynchronous routines -.SH SYNOPSIS -.nf -#include <signal.h> -.PP -union sigval { /* Data passed with notification */ - int sival_int; /* Integer value */ - void *sival_ptr; /* Pointer value */ -}; -.PP -struct sigevent { - int sigev_notify; /* Notification method */ - int sigev_signo; /* Notification signal */ - union sigval sigev_value; - /* Data passed with notification */ - void (*sigev_notify_function)(union sigval); - /* Function used for thread - notification (SIGEV_THREAD) */ - void *sigev_notify_attributes; - /* Attributes for notification thread - (SIGEV_THREAD) */ - pid_t sigev_notify_thread_id; - /* ID of thread to signal - (SIGEV_THREAD_ID); Linux-specific */ -}; -.fi -.SH DESCRIPTION -The -.I sigevent -structure is used by various APIs -to describe the way a process is to be notified about an event -(e.g., completion of an asynchronous request, expiration of a timer, -or the arrival of a message). -.PP -The definition shown in the SYNOPSIS is approximate: -some of the fields in the -.I sigevent -structure may be defined as part of a union. -Programs should employ only those fields relevant -to the value specified in -.IR sigev_notify . -.PP -The -.I sigev_notify -field specifies how notification is to be performed. -This field can have one of the following values: -.TP -.B SIGEV_NONE -A "null" notification: don't do anything when the event occurs. -.TP -.B SIGEV_SIGNAL -Notify the process by sending the signal specified in -.IR sigev_signo . -.IP -If the signal is caught with a signal handler that was registered using the -.BR sigaction (2) -.B SA_SIGINFO -flag, then the following fields are set in the -.I siginfo_t -structure that is passed as the second argument of the handler: -.RS -.TP 10 -.I si_code -This field is set to a value that depends on the API -delivering the notification. -.TP -.I si_signo -This field is set to the signal number (i.e., the same value as in -.IR sigev_signo ). -.TP -.I si_value -This field is set to the value specified in -.IR sigev_value . -.RE -.IP -Depending on the API, other fields may also be set in the -.I siginfo_t -structure. -.IP -The same information is also available if the signal is accepted using -.BR sigwaitinfo (2). -.TP -.B SIGEV_THREAD -Notify the process by invoking -.I sigev_notify_function -"as if" it were the start function of a new thread. -(Among the implementation possibilities here are that -each timer notification could result in the creation of a new thread, -or that a single thread is created to receive all notifications.) -The function is invoked with -.I sigev_value -as its sole argument. -If -.I sigev_notify_attributes -is not NULL, it should point to a -.I pthread_attr_t -structure that defines attributes for the new thread (see -.BR pthread_attr_init (3)). -.TP -.BR SIGEV_THREAD_ID " (Linux-specific)" -.\" | SIGEV_SIGNAL vs not? -Currently used only by POSIX timers; see -.BR timer_create (2). -.SH SEE ALSO -.BR timer_create (2), -.BR aio_fsync (3), -.BR aio_read (3), -.BR aio_write (3), -.BR getaddrinfo_a (3), -.BR lio_listio (3), -.BR mq_notify (3), -.BR aio (7), -.BR pthreads (7) diff --git a/upstream/debian-unstable/man7/signal-safety.7 b/upstream/debian-unstable/man7/signal-safety.7 index 4bcb4789..fe76828c 100644 --- a/upstream/debian-unstable/man7/signal-safety.7 +++ b/upstream/debian-unstable/man7/signal-safety.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH signal-safety 7 2023-02-05 "Linux man-pages 6.05.01" +.TH signal-safety 7 2024-05-02 "Linux man-pages 6.8" .SH NAME signal-safety \- async-signal-safe functions .SH DESCRIPTION @@ -15,13 +15,13 @@ Many functions are async-signal-safe. In particular, nonreentrant functions are generally unsafe to call from a signal handler. -.PP +.P The kinds of issues that render a function unsafe can be quickly understood when one considers the implementation of the .I stdio library, all of whose functions are not async-signal-safe. -.PP +.P When performing buffered I/O on a file, the .I stdio functions must maintain a statically allocated data buffer @@ -38,7 +38,7 @@ the program is interrupted by a signal handler that also calls then the second call to .BR printf (3) will operate on inconsistent data, with unpredictable results. -.PP +.P To avoid problems with unsafe functions, there are two possible choices: .IP (a) 5 Ensure that @@ -50,26 +50,26 @@ with respect to global variables in the main program. Block signal delivery in the main program when calling functions that are unsafe or operating on global data that is also accessed by the signal handler. -.PP +.P Generally, the second choice is difficult in programs of any complexity, so the first choice is taken. -.PP +.P POSIX.1 specifies a set of functions that an implementation must make async-signal-safe. (An implementation may provide safe implementations of additional functions, but this is not required by the standard and other implementations may not provide the same guarantees.) -.PP +.P In general, a function is async-signal-safe either because it is reentrant or because it is atomic with respect to signals (i.e., its execution can't be interrupted by a signal handler). -.PP +.P The set of functions required to be async-signal-safe by POSIX.1 is shown in the following table. The functions not otherwise noted were required to be async-signal-safe in POSIX.1-2001; the table details changes in the subsequent standards. -.PP +.P .TS lb lb l l. @@ -272,7 +272,7 @@ T} \fBwmemset\fP(3) Added in POSIX.1-2008 TC2 \fBwrite\fP(2) .TE -.PP +.P Notes: .IP \[bu] 3 POSIX.1-2001 and POSIX.1-2001 TC2 required the functions diff --git a/upstream/debian-unstable/man7/signal.7 b/upstream/debian-unstable/man7/signal.7 index 6f6f9c90..9305cc3a 100644 --- a/upstream/debian-unstable/man7/signal.7 +++ b/upstream/debian-unstable/man7/signal.7 @@ -23,7 +23,7 @@ .\" Added section on stop/cont signals interrupting syscalls. .\" 2008-10-05, mtk: various additions .\" -.TH signal 7 2023-04-03 "Linux man-pages 6.05.01" +.TH signal 7 2024-05-02 "Linux man-pages 6.8" .SH NAME signal \- overview of signals .SH DESCRIPTION @@ -34,7 +34,7 @@ Each signal has a current .IR disposition , which determines how the process behaves when it is delivered the signal. -.PP +.P The entries in the "Action" column of the table below specify the default disposition for each signal, as follows: .TP @@ -53,7 +53,7 @@ Default action is to stop the process. .TP Cont Default action is to continue the process if it is currently stopped. -.PP +.P A process can change the disposition of a signal using .BR sigaction (2) or @@ -69,18 +69,18 @@ or catch the signal with a .IR "signal handler" , a programmer-defined function that is automatically invoked when the signal is delivered. -.PP +.P By default, a signal handler is invoked on the normal process stack. It is possible to arrange that the signal handler uses an alternate stack; see .BR sigaltstack (2) for a discussion of how to do this and when it might be useful. -.PP +.P The signal disposition is a per-process attribute: in a multithreaded application, the disposition of a particular signal is the same for all threads. -.PP +.P A child created via .BR fork (2) inherits a copy of its parent's signal dispositions. @@ -164,7 +164,7 @@ which means that it will not be delivered until it is later unblocked. Between the time when it is generated and when it is delivered a signal is said to be .IR pending . -.PP +.P Each thread in a process has an independent .IR "signal mask" , which indicates the set of signals that the thread is currently blocking. @@ -173,13 +173,13 @@ A thread can manipulate its signal mask using In a traditional single-threaded application, .BR sigprocmask (2) can be used to manipulate the signal mask. -.PP +.P A child created via .BR fork (2) inherits a copy of its parent's signal mask; the signal mask is preserved across .BR execve (2). -.PP +.P A signal may be process-directed or thread-directed. A process-directed signal is one that is targeted at (and thus pending for) the process as a whole. @@ -202,7 +202,7 @@ interfaces such as .BR tgkill (2) or .BR pthread_kill (3). -.PP +.P A process-directed signal may be delivered to any one of the threads that does not currently have the signal blocked. .\" Joseph C. Sible notes: @@ -225,14 +225,14 @@ threads that does not currently have the signal blocked. .\" If more than one of the threads has the signal unblocked, then the kernel chooses an arbitrary thread to which to deliver the signal. -.PP +.P A thread can obtain the set of signals that it currently has pending using .BR sigpending (2). This set will consist of the union of the set of pending process-directed signals and the set of signals pending for the calling thread. -.PP +.P A child created via .BR fork (2) initially has an empty pending signal set; @@ -320,7 +320,7 @@ Upon completion of the call to the kernel transfers control back to user space, and the thread recommences execution at the point where it was interrupted by the signal handler. -.PP +.P Note that if the signal handler does not return (e.g., control is transferred out of the handler using .BR siglongjmp (3), @@ -338,7 +338,7 @@ may or may not restore the signal mask, depending on the .I savesigs value that was specified in the corresponding call to .BR sigsetjmp (3).) -.PP +.P From the kernel's point of view, execution of the signal handler code is exactly the same as the execution of any other user-space code. @@ -405,13 +405,13 @@ SIGXFSZ P2001 Core File size limit exceeded (4.2BSD); see \fBsetrlimit\fP(2) SIGWINCH \- Ign Window resize signal (4.3BSD, Sun) .TE -.PP +.P The signals .B SIGKILL and .B SIGSTOP cannot be caught, blocked, or ignored. -.PP +.P Up to and including Linux 2.2, the default behavior for .BR SIGSYS ", " SIGXCPU ", " SIGXFSZ , and (on architectures other than SPARC and MIPS) @@ -422,17 +422,17 @@ was to terminate the process (without a core dump). is to terminate the process without a core dump.) Linux 2.4 conforms to the POSIX.1-2001 requirements for these signals, terminating the process with a core dump. -.PP +.P .B SIGEMT is not specified in POSIX.1-2001, but nevertheless appears on most other UNIX systems, where its default action is typically to terminate the process with a core dump. -.PP +.P .B SIGPWR (which is not specified in POSIX.1-2001) is typically ignored by default on those other UNIX systems where it appears. -.PP +.P .B SIGIO (which is not specified in POSIX.1-2001) is ignored by default on several other UNIX systems. @@ -440,7 +440,7 @@ on several other UNIX systems. .SS Queueing and delivery semantics for standard signals If multiple standard signals are pending for a process, the order in which the signals are delivered is unspecified. -.PP +.P Standard signals do not queue. If multiple instances of a standard signal are generated while that signal is blocked, @@ -510,7 +510,7 @@ SIGLOST \- \-/29 \- \- SIGSYS 31 12 12 31 SIGUNUSED 31 \- \- 31 .TE -.PP +.P Note the following: .IP \[bu] 3 Where defined, @@ -538,7 +538,7 @@ and POSIX.1-2001 requires that an implementation support at least .B _POSIX_RTSIG_MAX (8) real-time signals. -.PP +.P The Linux kernel supports a range of 33 different real-time signals, numbered 32 to 64. However, the glibc POSIX threads implementation internally uses @@ -560,14 +560,14 @@ and include suitable (run-time) checks that .BR SIGRTMIN +n does not exceed .BR SIGRTMAX . -.PP +.P Unlike standard signals, real-time signals have no predefined meanings: the entire set of real-time signals can be used for application-defined purposes. -.PP +.P The default action for an unhandled real-time signal is to terminate the receiving process. -.PP +.P Real-time signals are distinguished by the following: .IP \[bu] 3 Multiple instances of real-time signals can be queued. @@ -602,12 +602,12 @@ starting with the lowest-numbered signal. (I.e., low-numbered signals have highest priority.) By contrast, if multiple standard signals are pending for a process, the order in which they are delivered is unspecified. -.PP +.P If both standard and real-time signals are pending for a process, POSIX leaves it unspecified which is delivered first. Linux, like many other implementations, gives priority to standard signals in this case. -.PP +.P According to POSIX, an implementation should permit at least .B _POSIX_SIGQUEUE_MAX (32) real-time signals to be queued to @@ -630,7 +630,7 @@ resource limit, which specifies a per-user limit for queued signals; see .BR setrlimit (2) for further details. -.PP +.P The addition of real-time signals required the widening of the signal set structure .RI ( sigset_t ) @@ -658,7 +658,7 @@ the call is automatically restarted after the signal handler returns; or .IP \[bu] the call fails with the error .BR EINTR . -.PP +.P Which of these two behaviors occurs depends on the interface and whether or not the signal handler was established using the .B SA_RESTART @@ -666,7 +666,7 @@ flag (see .BR sigaction (2)). The details vary across UNIX systems; below, the details for Linux. -.PP +.P If a blocked call to one of the following interfaces is interrupted by a signal handler, then the call is automatically restarted after the signal handler returns if the @@ -771,7 +771,7 @@ file descriptor .\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06 beforehand, always failed with .BR EINTR ). -.PP +.P The following interfaces are never restarted after being interrupted by a signal handler, regardless of the use of @@ -838,12 +838,12 @@ and .BR usleep (3). .IP \[bu] .BR io_getevents (2). -.PP +.P The .BR sleep (3) function is also never restarted if interrupted by a handler, but gives a success return: the number of seconds remaining to sleep. -.PP +.P In certain circumstances, the .BR seccomp (2) user-space notification feature can lead to restarting of system calls @@ -861,7 +861,7 @@ and then resumed via .BR SIGCONT . This behavior is not sanctioned by POSIX.1, and doesn't occur on other systems. -.PP +.P The Linux interfaces that display this behavior are: .IP \[bu] 3 "Input" socket interfaces, when a timeout @@ -925,7 +925,7 @@ POSIX.1, except as noted. .SH NOTES For a discussion of async-signal-safe functions, see .BR signal\-safety (7). -.PP +.P The .IR /proc/ pid /task/ tid /status file contains various fields that show the signals @@ -961,13 +961,13 @@ and Which of these signals is delivered, for any given hardware exception, is not documented and does not always make sense. -.PP +.P For example, an invalid memory access that causes delivery of .B SIGSEGV on one CPU architecture may cause delivery of .B SIGBUS on another architecture, or vice versa. -.PP +.P For another example, using the x86 .I int instruction with a forbidden argument @@ -1016,4 +1016,4 @@ because of how the CPU reports the forbidden operation to the kernel. .BR proc (5), .BR nptl (7), .BR pthreads (7), -.BR sigevent (7) +.BR sigevent (3type) diff --git a/upstream/debian-unstable/man7/smbios-type-11.7 b/upstream/debian-unstable/man7/smbios-type-11.7 index b9c52637..5893c76a 100644 --- a/upstream/debian-unstable/man7/smbios-type-11.7 +++ b/upstream/debian-unstable/man7/smbios-type-11.7 @@ -1,5 +1,5 @@ '\" t -.TH "SMBIOS\-TYPE\-11" "7" "" "systemd 255" "smbios-type-11" +.TH "SMBIOS\-TYPE\-11" "7" "" "systemd 256~rc3" "smbios-type-11" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -55,11 +55,18 @@ This allows configuration of additional kernel command line options, and is read .sp Added in version 254\&. .RE +.PP +\fIio\&.systemd\&.boot\&.kernel\-cmdline\-extra=\fR\fICMDLINE\fR +.RS 4 +This allows configuration of additional kernel command line options for Boot Loader Specification Type 1 entries, and is read by +\fBsystemd\-boot\fR\&. For details see +\fBsystemd-boot\fR(1)\&. +.sp +Added in version 256\&. +.RE .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBkernel-command-line\fR(7), -\fBsystemd.system-credentials\fR(7) +\fBsystemd\fR(1), \fBkernel-command-line\fR(7), \fBsystemd.system-credentials\fR(7) .SH "NOTES" .IP " 1." 4 System Management BIOS diff --git a/upstream/debian-unstable/man7/sock_diag.7 b/upstream/debian-unstable/man7/sock_diag.7 index adf47b7b..8b222c8b 100644 --- a/upstream/debian-unstable/man7/sock_diag.7 +++ b/upstream/debian-unstable/man7/sock_diag.7 @@ -2,7 +2,7 @@ .\" Copyright (c) 2016 Dmitry V. Levin <ldv@altlinux.org> .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH sock_diag 7 2023-05-03 "Linux man-pages 6.05.01" +.TH sock_diag 7 2024-05-02 "Linux man-pages 6.8" .SH NAME sock_diag \- obtaining information about sockets .SH SYNOPSIS @@ -11,7 +11,7 @@ sock_diag \- obtaining information about sockets .B #include <linux/sock_diag.h> .BR "#include <linux/unix_diag.h>" " /* for UNIX domain sockets */" .BR "#include <linux/inet_diag.h>" " /* for IPv4 and IPv6 sockets */" -.PP +.P .BI "diag_socket = socket(AF_NETLINK, " socket_type ", NETLINK_SOCK_DIAG);" .fi .SH DESCRIPTION @@ -19,16 +19,16 @@ The sock_diag netlink subsystem provides a mechanism for obtaining information about sockets of various address families from the kernel. This subsystem can be used to obtain information about individual sockets or request a list of sockets. -.PP +.P In the request, the caller can specify additional information it would like to obtain about the socket, for example, memory information or information specific to the address family. -.PP +.P When requesting a list of sockets, the caller can specify filters that would be applied by the kernel to select a subset of sockets to report. For now, there is only the ability to filter sockets by state (connected, listening, and so on.) -.PP +.P Note that sock_diag reports only those sockets that have a name; that is, either sockets bound explicitly with .BR bind (2) @@ -51,7 +51,7 @@ field set to .BR SOCK_DIAG_BY_FAMILY . It is followed by a header specific to the address family that starts with a common part shared by all address families: -.PP +.P .in +4n .EX struct sock_diag_req { @@ -60,7 +60,7 @@ struct sock_diag_req { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I sdiag_family @@ -79,7 +79,7 @@ constant for and .BR AF_INET6 , and to 0 otherwise. -.PP +.P If the .I nlmsg_flags field of the @@ -98,7 +98,7 @@ The array is to be accessed with the standard macros from the .BR netlink (3) API. -.PP +.P Each object is the NLA (netlink attributes) list that is to be accessed with the .B RTA_* @@ -108,7 +108,7 @@ API. .\" .SS UNIX domain sockets For UNIX domain sockets the request is represented in the following structure: -.PP +.P .in +4n .EX struct unix_diag_req { @@ -122,13 +122,13 @@ struct unix_diag_req { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I sdiag_family The address family; it should be set to .BR AF_UNIX . -.PP +.P .I sdiag_protocol .PD 0 .TP @@ -141,11 +141,11 @@ This is a bit mask that defines a filter of sockets states. Only those sockets whose states are in this mask will be reported. Ignored when querying for an individual socket. Supported values are: -.PP +.P .RS 12 1 << .B TCP_ESTABLISHED -.PP +.P 1 << .B TCP_LISTEN .RE @@ -253,7 +253,7 @@ The attribute reported in answer to this request is .BR UNIX_DIAG_MEMINFO . The payload associated with this attribute is an array of __u32 values described below in the subsection "Socket memory information". -.PP +.P The following attributes are reported back without any specific request: .TP .B UNIX_DIAG_SHUTDOWN @@ -269,9 +269,9 @@ This is an array of opaque identifiers that could be used along with to specify an individual socket. It is ignored when querying for a list of sockets, as well as when all its elements are set to \-1. -.PP +.P The response to a query for UNIX domain sockets is represented as an array of -.PP +.P .in +4n .EX struct unix_diag_msg { @@ -284,9 +284,9 @@ struct unix_diag_msg { }; .EE .in -.PP +.P followed by netlink attributes. -.PP +.P The fields of this structure are as follows: .TP .I udiag_family @@ -319,7 +319,7 @@ queries. .SS IPv4 and IPv6 sockets For IPv4 and IPv6 sockets, the request is represented in the following structure: -.PP +.P .in +4n .EX struct inet_diag_req_v2 { @@ -332,11 +332,11 @@ struct inet_diag_req_v2 { }; .EE .in -.PP +.P where .I "struct inet_diag_sockid" is defined as follows: -.PP +.P .in +4n .EX struct inet_diag_sockid { @@ -349,7 +349,7 @@ struct inet_diag_sockid { }; .EE .in -.PP +.P The fields of .I "struct inet_diag_req_v2" are as follows: @@ -447,7 +447,7 @@ about individual sockets, and is reported back in each response. Unlike UNIX domain sockets, IPv4 and IPv6 sockets are identified using addresses and ports. All values are in network byte order. -.PP +.P The fields of .I "struct inet_diag_sockid" are as follows: @@ -472,9 +472,9 @@ This is an array of opaque identifiers that could be used along with other fields of this structure to specify an individual socket. It is ignored when querying for a list of sockets, as well as when all its elements are set to \-1. -.PP +.P The response to a query for IPv4 or IPv6 sockets is represented as an array of -.PP +.P .in +4n .EX struct inet_diag_msg { @@ -493,9 +493,9 @@ struct inet_diag_msg { }; .EE .in -.PP +.P followed by netlink attributes. -.PP +.P The fields of this structure are as follows: .TP .I idiag_family @@ -611,7 +611,7 @@ In Linux 3.3, it was renamed to and extended to support .B AF_UNIX sockets. -.PP +.P .B UNIX_DIAG_MEMINFO and .B INET_DIAG_SKMEMINFO @@ -621,7 +621,7 @@ Linux. .SH EXAMPLES The following example program prints inode number, peer's inode number, and name of all UNIX domain sockets in the current namespace. -.PP +.P .EX #include <errno.h> #include <stdio.h> diff --git a/upstream/debian-unstable/man7/socket.7 b/upstream/debian-unstable/man7/socket.7 index 2cc24d90..85c20430 100644 --- a/upstream/debian-unstable/man7/socket.7 +++ b/upstream/debian-unstable/man7/socket.7 @@ -47,13 +47,13 @@ .\" commit ea02f9411d9faa3553ed09ce0ec9f00ceae9885e .\" Author: Michal Sekletar <msekleta@redhat.com> .\" -.TH socket 7 2023-07-15 "Linux man-pages 6.05.01" +.TH socket 7 2024-05-02 "Linux man-pages 6.8" .SH NAME socket \- Linux socket interface .SH SYNOPSIS .nf .B #include <sys/socket.h> -.PP +.P .IB sockfd " = socket(int " socket_family ", int " socket_type ", int " protocol ); .fi .SH DESCRIPTION @@ -79,7 +79,7 @@ for more information on families and types. These functions are used by the user process to send or receive packets and to do other socket operations. For more information, see their respective manual pages. -.PP +.P .BR socket (2) creates a socket, .BR connect (2) @@ -95,7 +95,7 @@ is used to get a new socket with a new incoming connection. returns two connected anonymous sockets (implemented only for a few local families like .BR AF_UNIX ) -.PP +.P .BR send (2), .BR sendto (2), and @@ -117,7 +117,7 @@ In addition, the standard I/O operations like and .BR readv (2) can be used to read and write data. -.PP +.P .BR getsockname (2) returns the local socket address and .BR getpeername (2) @@ -128,18 +128,18 @@ and are used to set or get socket layer or protocol options. .BR ioctl (2) can be used to set or read some other options. -.PP +.P .BR close (2) is used to close a socket. .BR shutdown (2) closes parts of a full-duplex socket connection. -.PP +.P Seeking, or calling .BR pread (2) or .BR pwrite (2) with a nonzero position is not supported on sockets. -.PP +.P It is possible to do nonblocking I/O on sockets by setting the .B O_NONBLOCK flag on a socket file descriptor using @@ -208,7 +208,7 @@ T} .\" or .\" .BR close (2). .TE -.PP +.P An alternative to .BR poll (2) and @@ -244,7 +244,7 @@ the various system calls (e.g., .BR getpeername (2)), which are generic to all socket domains, to determine the domain of a particular socket address. -.PP +.P To allow any type of socket address to be passed to interfaces in the sockets API, the type @@ -254,7 +254,7 @@ The purpose of this type is purely to allow casting of domain-specific socket address types to a "generic" type, so as to avoid compiler warnings about type mismatches in calls to the sockets API. -.PP +.P In addition, the sockets API provides the data type .IR "struct sockaddr_storage". This type @@ -264,13 +264,13 @@ address structures; it is large enough and is aligned properly. IPv6 socket addresses.) The structure includes the following field, which can be used to identify the type of socket address actually stored in the structure: -.PP +.P .in +4n .EX sa_family_t ss_family; .EE .in -.PP +.P The .I sockaddr_storage structure is useful in programs that must handle socket addresses @@ -303,7 +303,9 @@ The value 0 indicates that this is not a listening socket, the value 1 indicates that this is a listening socket. This socket option is read-only. .TP -.BR SO_ATTACH_FILTER " (since Linux 2.2), " SO_ATTACH_BPF " (since Linux 3.19)" +.BR SO_ATTACH_FILTER " (since Linux 2.2)" +.TQ +.BR SO_ATTACH_BPF " (since Linux 3.19)" Attach a classic BPF .RB ( SO_ATTACH_FILTER ) or an extended BPF @@ -348,7 +350,9 @@ never has more than one filter defined. Both classic and extended BPF are explained in the kernel source file .I Documentation/networking/filter.txt .TP -.BR SO_ATTACH_REUSEPORT_CBPF ", " SO_ATTACH_REUSEPORT_EBPF +.B SO_ATTACH_REUSEPORT_CBPF +.TQ +.B SO_ATTACH_REUSEPORT_EBPF For use with the .B SO_REUSEPORT option, these options allow the user to set a classic BPF @@ -451,7 +455,9 @@ Allowed only for processes with the .B CAP_NET_ADMIN capability or an effective user ID of 0. .TP -.BR SO_DETACH_FILTER " (since Linux 2.2), " SO_DETACH_BPF " (since Linux 3.19)" +.BR SO_DETACH_FILTER " (since Linux 2.2)" +.TQ +.BR SO_DETACH_BPF " (since Linux 3.19)" These two options, which are synonyms, may be used to remove the classic or extended BPF program attached to a socket with either @@ -608,7 +614,9 @@ Changing the mark can be used for mark-based routing without netfilter or for packet filtering. Setting this option requires the .B CAP_NET_ADMIN -capability. +or +.B CAP_NET_RAW +(since Linux 5.17) capability. .TP .B SO_OOBINLINE If this option is enabled, @@ -1054,7 +1062,7 @@ The signal is not sent when the write call specified the .B MSG_NOSIGNAL flag. -.PP +.P When requested with the .B FIOSETOWN .BR fcntl (2) @@ -1079,7 +1087,7 @@ field of its See .BR fcntl (2) for more information. -.PP +.P Under some circumstances (e.g., multiple processes accessing a single socket), the condition that caused the .B SIGIO @@ -1124,7 +1132,7 @@ per socket. .SS Ioctls These operations can be accessed using .BR ioctl (2): -.PP +.P .in +4n .EX .IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");" @@ -1198,7 +1206,7 @@ or signals, or 0 when none is set. -.PP +.P Valid .BR fcntl (2) operations: @@ -1231,7 +1239,7 @@ Linux assumes that half of the send/receive buffer is used for internal kernel structures; thus the values in the corresponding .I /proc files are twice what can be observed on the wire. -.PP +.P Linux will allow port reuse only with the .B SO_REUSEADDR option diff --git a/upstream/debian-unstable/man7/spufs.7 b/upstream/debian-unstable/man7/spufs.7 index fc3b4241..8356b4fc 100644 --- a/upstream/debian-unstable/man7/spufs.7 +++ b/upstream/debian-unstable/man7/spufs.7 @@ -10,14 +10,14 @@ .\" 2007-07-10, quite a lot of polishing by mtk .\" 2007-09-28, updates for newer kernels by Jeremy Kerr <jk@ozlabs.org> .\" -.TH spufs 7 2023-02-05 "Linux man-pages 6.05.01" +.TH spufs 7 2024-05-02 "Linux man-pages 6.8" .SH NAME spufs \- SPU filesystem .SH DESCRIPTION The SPU filesystem is used on PowerPC machines that implement the Cell Broadband Engine Architecture in order to access Synergistic Processor Units (SPUs). -.PP +.P The filesystem provides a name space similar to POSIX shared memory or message queues. Users that have write permissions @@ -26,7 +26,7 @@ on the filesystem can use to establish SPU contexts under the .B spufs root directory. -.PP +.P Every SPU context is represented by a directory containing a predefined set of files. These files can be @@ -58,7 +58,7 @@ supported on regular filesystems. This list details the supported operations and the deviations from the standard behavior described in the respective man pages. -.PP +.P All files that support the .BR read (2) operation also support @@ -80,7 +80,7 @@ structure that contain reliable information are .IR st_uid , and .IR st_gid . -.PP +.P All files support the .BR chmod (2)/\c .BR fchmod (2) @@ -91,7 +91,7 @@ operations, but will not be able to grant permissions that contradict the possible operations (e.g., read access on the .I wbox file). -.PP +.P The current set of files is: .TP .I /capabilities @@ -105,7 +105,7 @@ This context may be scheduled. .TP .B step This context can be run in single-step mode, for debugging. -.PP +.P New capabilities flags may be added in the future. .RE .TP @@ -119,7 +119,15 @@ The possible operations on an open file are: .RS .TP -.BR read "(2), " pread "(2), " write "(2), " pwrite "(2), " lseek (2) +.BR read (2) +.TQ +.BR pread (2) +.TQ +.BR write (2) +.TQ +.BR pwrite (2) +.TQ +.BR lseek (2) These operate as usual, with the exception that .BR lseek (2), .BR write (2), @@ -289,7 +297,11 @@ file returns whenever space is available for writing. .RE .TP -.IR /mbox_stat ", " /ibox_stat ", " /wbox_stat +.I /mbox_stat +.TQ +.I /ibox_stat +.TQ +.I /wbox_stat These are read-only files that contain the length of the current queue of each mailbox\[em]that is, how many words can be read from .IR mbox " or " ibox @@ -324,8 +336,21 @@ the respective mailbox without blocking or returning an error. .RE .TP -.IR /npc ", " /decr ", " /decr_status ", " /spu_tag_mask ", " \ -/event_mask ", " /event_status ", " /srr0 ", " /lslr +.I /npc +.TQ +.I /decr +.TQ +.I /decr_status +.TQ +.I /spu_tag_mask +.TQ +.I /event_mask +.TQ +.I /event_status +.TQ +.I /srr0 +.TQ +.I /lslr Internal registers of the SPU. These files contain an ASCII string representing the hex value of the specified register. @@ -433,7 +458,9 @@ updating the value of the register. .RE .TP -.IR /signal1 ", " /signal2 +.I /signal1 +.TQ +.I /signal2 The files provide access to the two signal notification channels of an SPU. These are read-write files that operate on four-byte words. @@ -484,7 +511,9 @@ or files respectively. .RE .TP -.IR /signal1_type ", " /signal2_type +.I /signal1_type +.TQ +.I /signal2_type These two files change the behavior of the .I signal1 and @@ -524,7 +553,15 @@ Subsequent writes to the same file descriptor overwrite the previous setting. .RE .TP -.IR /mbox_info ", " /ibox_info ", " /wbox_info ", " /dma_into ", " /proxydma_info +.I /mbox_info +.TQ +.I /ibox_info +.TQ +.I /wbox_info +.TQ +.I /dma_into +.TQ +.I /proxydma_info Read-only files that contain the saved state of the SPU mailboxes and DMA queues. This allows the SPU status to be inspected, mainly for debugging. @@ -763,5 +800,5 @@ none /spu spufs gid=spu 0 0 .BR spu_create (2), .BR spu_run (2), .BR capabilities (7) -.PP +.P .I The Cell Broadband Engine Architecture (CBEA) specification diff --git a/upstream/debian-unstable/man7/ssl.7ssl b/upstream/debian-unstable/man7/ssl.7ssl deleted file mode 100644 index dc345e7a..00000000 --- a/upstream/debian-unstable/man7/ssl.7ssl +++ /dev/null @@ -1,151 +0,0 @@ -.\" -*- mode: troff; coding: utf-8 -*- -.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. -.ie n \{\ -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds C` -. ds C' -'br\} -.\" -.\" Escape single quotes in literal strings from groff's Unicode transform. -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.\" -.\" If the F register is >0, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.\" -.\" Avoid warning from groff about undefined register 'F'. -.de IX -.. -.nr rF 0 -.if \n(.g .if rF .nr rF 1 -.if (\n(rF:(\n(.g==0)) \{\ -. if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. if !\nF==2 \{\ -. nr % 0 -. nr F 2 -. \} -. \} -.\} -.rr rF -.\" ======================================================================== -.\" -.IX Title "SSL 7SSL" -.TH SSL 7SSL 2024-02-03 3.1.5 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 -ssl \- OpenSSL SSL/TLS library -.SH SYNOPSIS -.IX Header "SYNOPSIS" -See the individual manual pages for details. -.SH DESCRIPTION -.IX Header "DESCRIPTION" -The OpenSSL \fBssl\fR library implements several versions of the -Secure Sockets Layer, Transport Layer Security, and Datagram Transport Layer -Security protocols. -This page gives a brief overview of the extensive API and data types -provided by the library. -.PP -An \fBSSL_CTX\fR object is created as a framework to establish -TLS/SSL enabled connections (see \fBSSL_CTX_new\fR\|(3)). -Various options regarding certificates, algorithms etc. can be set -in this object. -.PP -When a network connection has been created, it can be assigned to an -\&\fBSSL\fR object. After the \fBSSL\fR object has been created using -\&\fBSSL_new\fR\|(3), \fBSSL_set_fd\fR\|(3) or -\&\fBSSL_set_bio\fR\|(3) can be used to associate the network -connection with the object. -.PP -When the TLS/SSL handshake is performed using -\&\fBSSL_accept\fR\|(3) or \fBSSL_connect\fR\|(3) -respectively. -\&\fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3), \fBSSL_write_ex\fR\|(3) and \fBSSL_write\fR\|(3) are -used to read and write data on the TLS/SSL connection. -\&\fBSSL_shutdown\fR\|(3) can be used to shut down the -TLS/SSL connection. -.SH "DATA STRUCTURES" -.IX Header "DATA STRUCTURES" -Here are some of the main data structures in the library. -.IP "\fBSSL_METHOD\fR (SSL Method)" 4 -.IX Item "SSL_METHOD (SSL Method)" -This is a dispatch structure describing the internal \fBssl\fR library -methods/functions which implement the various protocol versions (SSLv3 -TLSv1, ...). It's needed to create an \fBSSL_CTX\fR. -.IP "\fBSSL_CIPHER\fR (SSL Cipher)" 4 -.IX Item "SSL_CIPHER (SSL Cipher)" -This structure holds the algorithm information for a particular cipher which -are a core part of the SSL/TLS protocol. The available ciphers are configured -on a \fBSSL_CTX\fR basis and the actual ones used are then part of the -\&\fBSSL_SESSION\fR. -.IP "\fBSSL_CTX\fR (SSL Context)" 4 -.IX Item "SSL_CTX (SSL Context)" -This is the global context structure which is created by a server or client -once per program life-time and which holds mainly default values for the -\&\fBSSL\fR structures which are later created for the connections. -.IP "\fBSSL_SESSION\fR (SSL Session)" 4 -.IX Item "SSL_SESSION (SSL Session)" -This is a structure containing the current TLS/SSL session details for a -connection: \fBSSL_CIPHER\fRs, client and server certificates, keys, etc. -.IP "\fBSSL\fR (SSL Connection)" 4 -.IX Item "SSL (SSL Connection)" -This is the main SSL/TLS structure which is created by a server or client per -established connection. This actually is the core structure in the SSL API. -At run-time the application usually deals with this structure which has -links to mostly all other structures. -.SH "HEADER FILES" -.IX Header "HEADER FILES" -Currently the OpenSSL \fBssl\fR library provides the following C header files -containing the prototypes for the data structures and functions: -.IP \fI<openssl/ssl.h>\fR 4 -.IX Item "<openssl/ssl.h>" -This is the common header file for the SSL/TLS API. Include it into your -program to make the API of the \fBssl\fR library available. It internally -includes both more private SSL headers and headers from the \fBcrypto\fR library. -Whenever you need hard-core details on the internals of the SSL API, look -inside this header file. -This file also includes the others listed below. -.IP \fI<openssl/ssl2.h>\fR 4 -.IX Item "<openssl/ssl2.h>" -Unused. Present for backwards compatibility only. -.IP \fI<openssl/ssl3.h>\fR 4 -.IX Item "<openssl/ssl3.h>" -This is the sub header file dealing with the SSLv3 protocol only. -.IP \fI<openssl/tls1.h>\fR 4 -.IX Item "<openssl/tls1.h>" -This is the sub header file dealing with the TLSv1 protocol only. -.SH COPYRIGHT -.IX Header "COPYRIGHT" -Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved. -.PP -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 LICENSE in the source distribution or at -<https://www.openssl.org/source/license.html>. diff --git a/upstream/debian-unstable/man7/standards.7 b/upstream/debian-unstable/man7/standards.7 index c1df6f8a..4dc7aac6 100644 --- a/upstream/debian-unstable/man7/standards.7 +++ b/upstream/debian-unstable/man7/standards.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH standards 7 2023-03-13 "Linux man-pages 6.05.01" +.TH standards 7 2024-05-02 "Linux man-pages 6.8" .SH NAME standards \- C and UNIX Standards .SH DESCRIPTION @@ -183,7 +183,9 @@ See also .UR http://www.unix.org\:/version2/ .UE .) .TP -.B POSIX.1-2001, SUSv3 +.B POSIX.1-2001 +.TQ +.B SUSv3 This was a 2001 revision and consolidation of the POSIX.1, POSIX.2, and SUS standards into a single document, conducted under the auspices of the Austin Group @@ -233,7 +235,9 @@ of the original 2001 standard have occurred: TC1 in 2003 and TC2 in 2004. .TP -.B POSIX.1-2008, SUSv4 +.B POSIX.1-2008 +.TQ +.B SUSv4 Work on the next revision of POSIX.1/SUS was completed and ratified in 2008. The standard is available online at @@ -286,7 +290,7 @@ Technical Corrigenda 1 and 2 applied. .B SUSv4 2018 edition This is equivalent to POSIX.1-2017, with the addition of the XCurses specification. -.PP +.P The interfaces documented in POSIX.1/SUS are available as manual pages under sections 0p (header files), 1p (commands), and 3p (functions); diff --git a/upstream/debian-unstable/man7/string_copying.7 b/upstream/debian-unstable/man7/string_copying.7 index 814eabdd..030f12b4 100644 --- a/upstream/debian-unstable/man7/string_copying.7 +++ b/upstream/debian-unstable/man7/string_copying.7 @@ -2,18 +2,17 @@ .\" .\" SPDX-License-Identifier: BSD-3-Clause .\" -.TH string_copying 7 2023-07-29 "Linux man-pages 6.05.01" +.TH string_copying 7 2024-05-14 "Linux man-pages 6.8" .\" ----- NAME :: -----------------------------------------------------/ .SH NAME stpcpy, strcpy, strcat, stpecpy, +strtcpy, strlcpy, strlcat, stpncpy, strncpy, -zustr2ustp, zustr2stp, -strncat, -ustpcpy, ustr2stp +strncat \- copying strings and character sequences .\" ----- SYNOPSIS :: -------------------------------------------------/ .SH SYNOPSIS @@ -22,63 +21,60 @@ ustpcpy, ustr2stp .nf // Chain-copy a string. .BI "char *stpcpy(char *restrict " dst ", const char *restrict " src ); -.PP +.P // Copy/catenate a string. .BI "char *strcpy(char *restrict " dst ", const char *restrict " src ); .BI "char *strcat(char *restrict " dst ", const char *restrict " src ); -.PP +.P // Chain-copy a string with truncation. .BI "char *stpecpy(char *" dst ", char " end "[0], const char *restrict " src ); -.PP +.P // Copy/catenate a string with truncation. -.BI "size_t strlcpy(char " dst "[restrict ." sz "], \ +.BI "ssize_t strtcpy(char " dst "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " sz ); -.BI "size_t strlcat(char " dst "[restrict ." sz "], \ +.BI " size_t " dsize ); +.BI "size_t strlcpy(char " dst "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " sz ); +.BI " size_t " dsize ); +.BI "size_t strlcat(char " dst "[restrict ." dsize "], \ +const char *restrict " src , +.BI " size_t " dsize ); .fi .\" ----- SYNOPSIS :: Null-padded character sequences --------/ .SS Null-padded character sequences .nf -// Zero a fixed-width buffer, and -// copy a string into a character sequence with truncation. -.BI "char *stpncpy(char " dst "[restrict ." sz "], \ +// Fill a fixed-size buffer with characters from a string +// and pad with null bytes. +.BI "char *strncpy(char " dst "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " sz ); -.PP -// Zero a fixed-width buffer, and -// copy a string into a character sequence with truncation. -.BI "char *strncpy(char " dst "[restrict ." sz "], \ +.BI " size_t " dsize ); +.BI "char *stpncpy(char " dst "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " sz ); -.PP +.BI " size_t " dsize ); +.P // Chain-copy a null-padded character sequence into a character sequence. -.BI "char *zustr2ustp(char *restrict " dst ", \ -const char " src "[restrict ." sz ], -.BI " size_t " sz ); -.PP +.I mempcpy(dst, src, strnlen(src, NITEMS(src))); +.P // Chain-copy a null-padded character sequence into a string. -.BI "char *zustr2stp(char *restrict " dst ", \ -const char " src "[restrict ." sz ], -.BI " size_t " sz ); -.PP +.I stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), \[dq]\[dq]); +.P // Catenate a null-padded character sequence into a string. -.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." sz ], -.BI " size_t " sz ); +.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." ssize ], +.BI " size_t " ssize ); +.P +// Duplicate a null-padded character sequence into a string. +.BI "char *strndup(const char " src [. ssize "], size_t " ssize ); .fi -.\" ----- SYNOPSIS :: Measured character sequences --------------------/ -.SS Measured character sequences +.\" ----- SYNOPSIS :: Known-length character sequences --------------------/ +.SS Known-length character sequences .nf -// Chain-copy a measured character sequence. -.BI "char *ustpcpy(char *restrict " dst ", \ -const char " src "[restrict ." len ], -.BI " size_t " len ); -.PP -// Chain-copy a measured character sequence into a string. -.BI "char *ustr2stp(char *restrict " dst ", \ -const char " src "[restrict ." len ], +// Chain-copy a known-length character sequence. +.BI "void *mempcpy(void " dst "[restrict ." len "], \ +const void " src "[restrict ." len ], .BI " size_t " len ); +.P +// Chain-copy a known-length character sequence into a string. +.I stpcpy(mempcpy(dst, src, len), \[dq]\[dq]); .fi .SH DESCRIPTION .\" ----- DESCRIPTION :: Terms (and abbreviations) :: -----------------/ @@ -86,7 +82,7 @@ const char " src "[restrict ." len ], .\" ----- DESCRIPTION :: Terms (and abbreviations) :: string (str) ----/ .TP .IR "string " ( str ) -is a sequence of zero or more non-null characters followed by a null byte. +is a sequence of zero or more non-null characters followed by a null character. .\" ----- DESCRIPTION :: Terms (and abbreviations) :: null-padded character seq .TP .I character sequence @@ -96,15 +92,18 @@ However, with appropriate care, a string can be used in the place of a character sequence. .RS .TP -.IR "null-padded character sequence " ( zustr ) -Character sequences can be contained in fixed-width buffers, +.I null-padded character sequence +Character sequences can be contained in fixed-size buffers, which contain padding null bytes after the character sequence, to fill the rest of the buffer without affecting the character sequence; however, those padding null bytes are not part of the character sequence. -.\" ----- DESCRIPTION :: Terms (and abbreviations) :: measured character sequence +Don't confuse null-padded with null-terminated: +null-padded means 0 or more padding null bytes, +while null-terminated means exactly 1 terminating null character. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: known-length character sequence .TP -.IR "measured character sequence " ( ustr ) +.I known-length character sequence Character sequence delimited by its length. It may be a slice of a larger character sequence, or even of a string. @@ -116,10 +115,10 @@ is the number of non-null characters in a string or character sequence. It is the return value of .I strlen(str) and of -.IR "strnlen(ustr, sz)" . -.\" ----- DESCRIPTION :: Terms (and abbreviations) :: size (sz) -------/ +.IR "strnlen(buf, size)" . +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: size ------------/ .TP -.IR "size " ( sz ) +.I size refers to the entire buffer where the string or character sequence is contained. .\" ----- DESCRIPTION :: Terms (and abbreviations) :: end -------------/ @@ -127,7 +126,7 @@ where the string or character sequence is contained. .I end is the name of a pointer to one past the last element of a buffer. It is equivalent to -.IR &str[sz] . +.IR &str[size] . It is used as a sentinel value, to be able to truncate strings or character sequences instead of overrunning the containing buffer. @@ -141,7 +140,7 @@ the writing starts at the first element pointed to by .TP .I catenate This term is used when -a function first finds the terminating null byte in +a function first finds the terminating null character in .IR dst , and then starts writing at that position. .\" ----- DESCRIPTION :: Terms (and abbreviations) :: chain -----------/ @@ -149,15 +148,20 @@ and then starts writing at that position. .I chain This term is used when it's the programmer who provides -a pointer to the terminating null byte in the string +a pointer to the terminating null character in the string .I dst (or one after the last character in a character sequence), and the function starts writing at that location. The function returns -a pointer to the new location of the terminating null byte +a pointer to the new location of the terminating null character (or one after the last character in a character sequence) after the call, so that the programmer can use it to chain such calls. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: duplicate -------/ +.TP +.I duplicate +Allocate a new buffer +where a copy is placed. .\" ----- DESCRIPTION :: Copy, catenate, and chain-copy ---------------/ .SS Copy, catenate, and chain-copy Originally, @@ -166,11 +170,11 @@ However, newer functions that copy while allowing chaining cover both use cases with a single API. They are also algorithmically faster, since they don't need to search for -the terminating null byte of the existing string. +the terminating null character of the existing string. However, functions that catenate have a much simpler use, so if performance is not important, it can make sense to use them for improving readability. -.PP +.P The pointer returned by functions that allow chaining is a byproduct of the copy operation, so it has no performance costs. @@ -180,7 +184,7 @@ have names of the form .RB * stp *(), since it's common to name the pointer just .IR p . -.PP +.P Chain-copying functions that truncate should accept a pointer to the end of the destination buffer, and have names of the form @@ -191,14 +195,14 @@ This allows not having to recalculate the remaining size after each call. The first thing to note is that programmers should be careful with buffers, so they always have the correct size, and truncation is not necessary. -.PP +.P In most cases, truncation is not desired, and it is simpler to just do the copy. Simpler code is safer code. Programming against programming mistakes by adding more code just adds more points where mistakes can be made. -.PP +.P Nowadays, compilers can detect most programmer errors with features like compiler warnings, @@ -208,22 +212,25 @@ static analyzers, and .BR ftm (7)). Keeping the code simple helps these overflow-detection features be more precise. -.PP +.P When validating user input, +code should normally not truncate, +but instead fail and prevent the copy at all. +.P +In some cases, however, it makes sense to truncate. -Remember to check the return value of such function calls. -.PP +.P Functions that truncate: .IP \[bu] 3 -.BR stpecpy (3) -is the most efficient string copy function that performs truncation. -It only requires to check for truncation once after all chained calls. +.BR stpecpy () +.IP \[bu] +.BR strtcpy () .IP \[bu] .BR strlcpy (3bsd) and .BR strlcat (3bsd) -are similar, but less efficient when chained. +are similar, but have important performance problems; see BUGS. .IP \[bu] .BR stpncpy (3) and @@ -233,30 +240,31 @@ but rather null-padded character sequences. .\" ----- DESCRIPTION :: Null-padded character sequences --------------/ .SS Null-padded character sequences For historic reasons, -some standard APIs, +some standard APIs and file formats, such as -.BR utmpx (5), -use null-padded character sequences in fixed-width buffers. +.BR utmpx (5) +and +.BR tar (1), +use null-padded character sequences in fixed-size buffers. To interface with them, specialized functions need to be used. -.PP -To copy strings into them, use +.P +To copy bytes from strings into these buffers, use +.BR strncpy (3) +or .BR stpncpy (3). -.PP -To copy from an unterminated string within a fixed-width buffer into a string, -ignoring any trailing null bytes in the source fixed-width buffer, -you should use -.BR zustr2stp (3) +.P +To read a null-padded character sequence, +use +.IR "strnlen(src,\ NITEMS(src))" , +and then you can treat it as a known-length character sequence; +or use +.BR strncat (3) or -.BR strncat (3). -.PP -To copy from an unterminated string within a fixed-width buffer -into a character sequence, -ignoring any trailing null bytes in the source fixed-width buffer, -you should use -.BR zustr2ustp (3). -.\" ----- DESCRIPTION :: Measured character sequences -----------------/ -.SS Measured character sequences +.BR strndup (3) +directly. +.\" ----- DESCRIPTION :: Known-length character sequences -----------------/ +.SS Known-length character sequences The simplest character sequence copying function is .BR mempcpy (3). It requires always knowing the length of your character sequences, @@ -266,39 +274,34 @@ since you always know the length of your character sequences, and can do the minimal copies and length measurements. .BR mempcpy (3) copies character sequences, -so you need to explicitly set the terminating null byte if you need a string. -.PP -However, -for keeping type safety, -it's good to add a wrapper that uses -.I char\~* -instead of -.IR void\~* : -.BR ustpcpy (3). -.PP +so you need to explicitly set the terminating null character +if you need a string. +.P In programs that make considerable use of strings or character sequences, and need the best performance, using overlapping character sequences can make a big difference. It allows holding subsequences of a larger character sequence, while not duplicating memory nor using time to do a copy. -.PP +.P However, this is delicate, since it requires using character sequences. C library APIs use strings, so programs that use character sequences will have to take care of differentiating strings from character sequences. -.PP -To copy a measured character sequence, use -.BR ustpcpy (3). -.PP -To copy a measured character sequence into a string, use -.BR ustr2stp (3). -.PP -Because these functions ask for the length, -and a string is by nature composed of a character sequence of the same length -plus a terminating null byte, -a string is also accepted as input. +.P +To copy a known-length character sequence, use +.BR mempcpy (3). +.P +To copy a known-length character sequence into a string, use +.IR "\%stpcpy(mempcpy(dst,\ src,\ len),\ \[dq]\[dq])" . +.P +A string is also accepted as input, +because +.BR mempcpy (3) +asks for the length, +and a string is composed of a character sequence of the same length +plus a terminating null character. .\" ----- DESCRIPTION :: String vs character sequence -----------------/ .SS String vs character sequence Some functions only operate on strings. @@ -319,12 +322,14 @@ List of functions: .BR strcpy (3), .BR strcat (3) .IP \[bu] -.BR stpecpy (3) +.BR stpecpy () +.IP \[bu] +.BR strtcpy () .IP \[bu] .BR strlcpy (3bsd), .BR strlcat (3bsd) .PD -.PP +.P Other functions require an input string, but create a character sequence as output. These functions have confusing names, @@ -336,7 +341,7 @@ List of functions: .IP \[bu] .BR strncpy (3) .PD -.PP +.P Other functions operate on an input character sequence, and create an output string. Functions that catenate @@ -348,28 +353,22 @@ has an even more misleading name than the functions above. List of functions: .IP \[bu] 3 .PD 0 -.BR zustr2stp (3) -.IP \[bu] .BR strncat (3) .IP \[bu] -.BR ustr2stp (3) +.BR strndup (3) .PD -.PP +.P Other functions operate on an input character sequence to create an output character sequence. List of functions: .IP \[bu] 3 -.PD 0 -.BR ustpcpy (3) -.IP \[bu] -.BR zustr2stp (3) -.PD +.BR mempcpy (3) .\" ----- DESCRIPTION :: Functions :: ---------------------------------/ .SS Functions .\" ----- DESCRIPTION :: Functions :: stpcpy(3) -----------------------/ .TP .BR stpcpy (3) -This function copies the input string into a destination string. +Copy the input string into a destination string. The programmer is responsible for allocating a buffer large enough. It returns a pointer suitable for chaining. .\" ----- DESCRIPTION :: Functions :: strcpy(3), strcat(3) ------------/ @@ -377,16 +376,16 @@ It returns a pointer suitable for chaining. .BR strcpy (3) .TQ .BR strcat (3) -These functions copy and catenate the input string into a destination string. +Copy and catenate the input string into a destination string. The programmer is responsible for allocating a buffer large enough. The return value is useless. .IP .BR stpcpy (3) is a faster alternative to these functions. -.\" ----- DESCRIPTION :: Functions :: stpecpy(3) ----------------------/ +.\" ----- DESCRIPTION :: Functions :: stpecpy() -----------------------/ .TP -.BR stpecpy (3) -This function copies the input string into a destination string. +.BR stpecpy () +Chain-copy the input string into a destination string. If the destination buffer, limited by a pointer to its end, isn't large enough to hold the copy, @@ -397,12 +396,24 @@ Truncation needs to be detected only once after the last chained call. .IP This function is not provided by any library; see EXAMPLES for a reference implementation. +.\" ----- DESCRIPTION :: Functions :: strtcpy() -----------------------/ +.TP +.BR strtcpy () +Copy the input string into a destination string. +If the destination buffer isn't large enough to hold the copy, +the resulting string is truncated +(but it is guaranteed to be null-terminated). +It returns the length of the string, +or \-1 if it truncated. +.IP +This function is not provided by any library; +see EXAMPLES for a reference implementation. .\" ----- DESCRIPTION :: Functions :: strlcpy(3bsd), strlcat(3bsd) ----/ .TP .BR strlcpy (3bsd) .TQ .BR strlcat (3bsd) -These functions copy and catenate the input string into a destination string. +Copy and catenate the input string into a destination string. If the destination buffer, limited by its size, isn't large enough to hold the copy, @@ -410,19 +421,23 @@ the resulting string is truncated (but it is guaranteed to be null-terminated). They return the length of the total string they tried to create. .IP -.BR stpecpy (3) -is a simpler alternative to these functions. +Check BUGS before using these functions. +.IP +.BR strtcpy () +and +.BR stpecpy () +are better alternatives to these functions. .\" ----- DESCRIPTION :: Functions :: stpncpy(3) ----------------------/ .TP .BR stpncpy (3) -This function copies the input string into -a destination null-padded character sequence in a fixed-width buffer. +Copy the input string into +a destination null-padded character sequence in a fixed-size buffer. If the destination buffer, limited by its size, isn't large enough to hold the copy, the resulting character sequence is truncated. Since it creates a character sequence, -it doesn't need to write a terminating null byte. +it doesn't need to write a terminating null character. It's impossible to distinguish truncation by the result of the call, from a character sequence that just fits the destination buffer; truncation should be detected by @@ -437,147 +452,124 @@ except for the useless return value. .IP .BR stpncpy (3) is a more useful alternative to this function. -.\" ----- DESCRIPTION :: Functions :: zustr2ustp(3) --------------------/ -.TP -.BR zustr2ustp (3) -This function copies the input character sequence, -contained in a null-padded fixed-width buffer, -into a destination character sequence. -The programmer is responsible for allocating a buffer large enough. -It returns a pointer suitable for chaining. -.IP -A truncating version of this function doesn't exist, -since the size of the original character sequence is always known, -so it wouldn't be very useful. -.IP -This function is not provided by any library; -see EXAMPLES for a reference implementation. -.\" ----- DESCRIPTION :: Functions :: zustr2stp(3) --------------------/ +.\" ----- DESCRIPTION :: Functions :: strncat(3) ----------------------/ .TP -.BR zustr2stp (3) -This function copies the input character sequence, -contained in a null-padded fixed-width buffer, +.BR strncat (3) +Catenate the input character sequence, +contained in a null-padded fixed-size buffer, into a destination string. The programmer is responsible for allocating a buffer large enough. -It returns a pointer suitable for chaining. -.IP -A truncating version of this function doesn't exist, -since the size of the original character sequence is always known, -so it wouldn't be very useful. +The return value is useless. .IP -This function is not provided by any library; -see EXAMPLES for a reference implementation. -.\" ----- DESCRIPTION :: Functions :: strncat(3) ----------------------/ -.TP -.BR strncat (3) Do not confuse this function with .BR strncpy (3); they are not related at all. .IP -This function catenates the input character sequence, -contained in a null-padded fixed-width buffer, -into a destination string. -The programmer is responsible for allocating a buffer large enough. -The return value is useless. -.IP -.BR zustr2stp (3) +.I \%stpcpy(mempcpy(dst,\ src,\ strnlen(src,\ NITEMS(src))),\ \[dq]\[dq]) is a faster alternative to this function. -.\" ----- DESCRIPTION :: Functions :: ustpcpy(3) ----------------------/ +.\" ----- DESCRIPTION :: Functions :: strndup(3) ----------------------/ .TP -.BR ustpcpy (3) -This function copies the input character sequence, -limited by its length, -into a destination character sequence. -The programmer is responsible for allocating a buffer large enough. -It returns a pointer suitable for chaining. -.\" ----- DESCRIPTION :: Functions :: ustr2stp(3) ---------------------/ +.BR strndup (3) +Duplicate the input character sequence, +contained in a null-padded fixed-size buffer, +into a newly allocated destination string. +.IP +The string must be freed with +.BR free (3). +.\" ----- DESCRIPTION :: Functions :: mempcpy(3) ----------------------/ .TP -.BR ustr2stp (3) -This function copies the input character sequence, +.BR mempcpy (3) +Copy the input character sequence, limited by its length, -into a destination string. +into a destination character sequence. The programmer is responsible for allocating a buffer large enough. It returns a pointer suitable for chaining. .\" ----- RETURN VALUE :: ---------------------------------------------/ .SH RETURN VALUE -The following functions return -a pointer to the terminating null byte in the destination string. -.IP \[bu] 3 -.PD 0 +.TP .BR stpcpy (3) -.IP \[bu] -.BR ustr2stp (3) -.IP \[bu] -.BR zustr2stp (3) -.PD -.PP -The following function returns -a pointer to the terminating null byte in the destination string, -except when truncation occurs; -if truncation occurs, -it returns a pointer to the end of the destination buffer. -.IP \[bu] 3 -.BR stpecpy (3) -.PP -The following function returns -a pointer to one after the last character -in the destination character sequence; -if truncation occurs, -that pointer is equivalent to -a pointer to the end of the destination buffer. -.IP \[bu] 3 +A pointer to the terminating null character in the destination string. +.TP +.BR stpecpy () +A pointer to the terminating null character in the destination string, +on success. +On error, +NULL is returned, +and +.I errno +is set to indicate the error. +.TP +.BR mempcpy (3) +.TQ .BR stpncpy (3) -.PP -The following functions return -a pointer to one after the last character +A pointer to one after the last character in the destination character sequence. -.IP \[bu] 3 -.PD 0 -.BR zustr2ustp (3) -.IP \[bu] -.BR ustpcpy (3) -.PD -.PP -The following functions return -the length of the total string that they tried to create -(as if truncation didn't occur). -.IP \[bu] 3 -.BR strlcpy (3bsd), +.TP +.BR strtcpy () +The length of the string, +on success. +On error, +\-1 is returned, +and +.I errno +is set to indicate the error. +.TP +.BR strlcpy (3bsd) +.TQ .BR strlcat (3bsd) -.PP -The following functions return the -.I dst -pointer, -which is useless. -.IP \[bu] 3 -.PD 0 -.BR strcpy (3), +The length of the total string that they tried to create +(as if truncation didn't occur). +.TP +.BR strcpy (3) +.TQ .BR strcat (3) -.IP \[bu] +.TQ .BR strncpy (3) -.IP \[bu] +.TQ .BR strncat (3) -.PD +The +.I dst +pointer, +which is useless. +.TP +.BR strndup (3) +The newly allocated string. +.\" ----- ERRORS ------------------------------------------------------/ +.SH ERRORS +Most of these functions don't set +.IR errno . +.TP +.BR stpecpy () +.TQ +.BR strtcpy () +.RS +.TP +.B ENOBUFS +.I dsize +was +.BR 0 . +.TP +.B E2BIG +The string has been truncated. +.RE +.TP +.BR strndup (3) +.RS +.TP +.B ENOMEM +Insufficient memory available to allocate duplicate string. +.RE .\" ----- NOTES :: strscpy(9) -----------------------------------------/ .SH NOTES The Linux kernel has an internal function for copying strings, -which is similar to -.BR stpecpy (3), -except that it can't be chained: -.TP -.BR strscpy (9) -This function copies the input string into a destination string. -If the destination buffer, -limited by its size, -isn't large enough to hold the copy, -the resulting string is truncated -(but it is guaranteed to be null-terminated). -It returns the length of the destination string, or +.BR strscpy (9), +which is identical to +.BR strtcpy (), +except that it returns .B \-E2BIG -on truncation. -.IP -.BR stpecpy (3) -is a simpler and faster alternative to this function. +instead of \-1 +and it doesn't set +.IR errno . .\" ----- CAVEATS :: --------------------------------------------------/ .SH CAVEATS Don't mix chain calls to truncating and non-truncating functions. @@ -591,8 +583,28 @@ Calling a non-truncating function after a truncating one is necessarily wrong. .SH BUGS All catenation functions share the same performance problem: .UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/ -Shlemiel the painter +Shlemiel the painter .UE . +As a mitigation, +compilers are able to transform some calls to catenation functions +into normal copy functions, +since +.I strlen(dst) +is usually a byproduct of the previous copy. +.P +.BR strlcpy (3) +and +.BR strlcat (3) +need to read the entire +.I src +string, +even if the destination buffer is small. +This makes them vulnerable to Denial of Service (DoS) attacks +if an attacker can control the length of the +.I src +string. +And if not, +they're still unnecessarily slow. .\" ----- EXAMPLES :: -------------------------------------------------/ .SH EXAMPLES The following are examples of correct use of each of these functions. @@ -619,43 +631,43 @@ strcat(buf, "!"); len = strlen(buf); puts(buf); .EE -.\" ----- EXAMPLES :: stpecpy(3) --------------------------------------/ +.\" ----- EXAMPLES :: stpecpy() ---------------------------------------/ .TP -.BR stpecpy (3) +.BR stpecpy () .EX -end = buf + sizeof(buf); +end = buf + NITEMS(buf); p = buf; p = stpecpy(p, end, "Hello "); p = stpecpy(p, end, "world"); p = stpecpy(p, end, "!"); -if (p == end) { - p\-\-; +if (p == NULL) { + len = NITEMS(buf) \- 1; goto toolong; } len = p \- buf; puts(buf); .EE +.\" ----- EXAMPLES :: strtcpy() ---------------------------------------/ +.TP +.BR strtcpy () +.EX +len = strtcpy(buf, "Hello world!", NITEMS(buf)); +if (len == \-1) + goto toolong; +puts(buf); +.EE .\" ----- EXAMPLES :: strlcpy(3bsd), strlcat(3bsd) --------------------/ .TP .BR strlcpy (3bsd) .TQ .BR strlcat (3bsd) .EX -if (strlcpy(buf, "Hello ", sizeof(buf)) >= sizeof(buf)) +if (strlcpy(buf, "Hello ", NITEMS(buf)) >= NITEMS(buf)) goto toolong; -if (strlcat(buf, "world", sizeof(buf)) >= sizeof(buf)) +if (strlcat(buf, "world", NITEMS(buf)) >= NITEMS(buf)) goto toolong; -len = strlcat(buf, "!", sizeof(buf)); -if (len >= sizeof(buf)) - goto toolong; -puts(buf); -.EE -.\" ----- EXAMPLES :: strscpy(9) --------------------------------------/ -.TP -.BR strscpy (9) -.EX -len = strscpy(buf, "Hello world!", sizeof(buf)); -if (len == \-E2BIG) +len = strlcat(buf, "!", NITEMS(buf)); +if (len >= NITEMS(buf)) goto toolong; puts(buf); .EE @@ -663,43 +675,40 @@ puts(buf); .TP .BR stpncpy (3) .EX -p = stpncpy(buf, "Hello world!", sizeof(buf)); -if (sizeof(buf) < strlen("Hello world!")) +p = stpncpy(u->ut_user, "alx", NITEMS(u->ut_user)); +if (NITEMS(u->ut_user) < strlen("alx")) goto toolong; -len = p \- buf; -for (size_t i = 0; i < sizeof(buf); i++) - putchar(buf[i]); +len = p \- u->ut_user; +fwrite(u->ut_user, 1, len, stdout); .EE .\" ----- EXAMPLES :: strncpy(3) --------------------------------------/ .TP .BR strncpy (3) .EX -strncpy(buf, "Hello world!", sizeof(buf)); -if (sizeof(buf) < strlen("Hello world!")) +strncpy(u->ut_user, "alx", NITEMS(u->ut_user)); +if (NITEMS(u->ut_user) < strlen("alx")) goto toolong; -len = strnlen(buf, sizeof(buf)); -for (size_t i = 0; i < sizeof(buf); i++) - putchar(buf[i]); +len = strnlen(u->ut_user, NITEMS(u->ut_user)); +fwrite(u->ut_user, 1, len, stdout); .EE -.\" ----- EXAMPLES :: zustr2ustp(3) -----------------------------------/ +.\" ----- EXAMPLES :: mempcpy(dst, src, strnlen(src, NITEMS(src))) ----/ .TP -.BR zustr2ustp (3) +.I mempcpy(dst, src, strnlen(src, NITEMS(src))) .EX +char buf[NITEMS(u->ut_user)]; p = buf; -p = zustr2ustp(p, "Hello ", 6); -p = zustr2ustp(p, "world", 42); // Padding null bytes ignored. -p = zustr2ustp(p, "!", 1); +p = mempcpy(p, u->ut_user, strnlen(u->ut_user, NITEMS(u->ut_user))); len = p \- buf; -printf("%.*s\en", (int) len, buf); +fwrite(buf, 1, len, stdout); .EE -.\" ----- EXAMPLES :: zustr2stp(3) ------------------------------------/ +.\" ----- EXAMPLES :: stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), "") .TP -.BR zustr2stp (3) +.I stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), \[dq]\[dq]) .EX +char buf[NITEMS(u->ut_user) + 1]; p = buf; -p = zustr2stp(p, "Hello ", 6); -p = zustr2stp(p, "world", 42); // Padding null bytes ignored. -p = zustr2stp(p, "!", 1); +p = mempcpy(p, u->ut_user, strnlen(u->ut_user, NITEMS(u->ut_user))); +p = stpcpy(p, ""); len = p \- buf; puts(buf); .EE @@ -707,102 +716,86 @@ puts(buf); .TP .BR strncat (3) .EX -buf[0] = \[aq]\e0\[aq]; // There's no 'cpy' function to this 'cat'. -strncat(buf, "Hello ", 6); -strncat(buf, "world", 42); // Padding null bytes ignored. -strncat(buf, "!", 1); +char buf[NITEMS(u->ut_user) + 1]; +strcpy(buf, ""); +strncat(buf, u->ut_user, NITEMS(u->ut_user)); len = strlen(buf); puts(buf); .EE -.\" ----- EXAMPLES :: ustpcpy(3) --------------------------------------/ +.\" ----- EXAMPLES :: strndup(3) --------------------------------------/ .TP -.BR ustpcpy (3) +.BR strndup (3) +.EX +buf = strndup(u->ut_user, NITEMS(u->ut_user)); +len = strlen(buf); +puts(buf); +free(buf); +.EE +.\" ----- EXAMPLES :: mempcpy(3) --------------------------------------/ +.TP +.BR mempcpy (3) .EX p = buf; -p = ustpcpy(p, "Hello ", 6); -p = ustpcpy(p, "world", 5); -p = ustpcpy(p, "!", 1); +p = mempcpy(p, "Hello ", 6); +p = mempcpy(p, "world", 5); +p = mempcpy(p, "!", 1); len = p \- buf; -printf("%.*s\en", (int) len, buf); +fwrite(buf, 1, len, stdout); .EE -.\" ----- EXAMPLES :: ustr2stp(3) -------------------------------------/ +.\" ----- EXAMPLES :: stpcpy(mempcpy(), "") ---------------------------/ .TP -.BR ustr2stp (3) +.I stpcpy(mempcpy(dst, src, len), \[dq]\[dq]) .EX p = buf; -p = ustr2stp(p, "Hello ", 6); -p = ustr2stp(p, "world", 5); -p = ustr2stp(p, "!", 1); +p = mempcpy(p, "Hello ", 6); +p = mempcpy(p, "world", 5); +p = mempcpy(p, "!", 1); +p = stpcpy(p, ""); len = p \- buf; puts(buf); .EE .\" ----- EXAMPLES :: Implementations :: ------------------------------/ .SS Implementations Here are reference implementations for functions not provided by libc. -.PP +.P .in +4n .EX /* This code is in the public domain. */ \& -.\" ----- EXAMPLES :: Implementations :: stpecpy(3) -------------------/ +.\" ----- EXAMPLES :: Implementations :: stpecpy() --------------------/ char * .IR stpecpy "(char *dst, char end[0], const char *restrict src)" { - char *p; + size_t dlen; \& if (dst == NULL) return NULL; - if (dst == end) - return end; -\& - p = memccpy(dst, src, \[aq]\e0\[aq], end \- dst); - if (p != NULL) - return p \- 1; -\& - /* truncation detected */ - end[\-1] = \[aq]\e0\[aq]; - return end; -} -\& -.\" ----- EXAMPLES :: Implementations :: zustr2ustp(3) ----------------/ -char * -.IR zustr2ustp "(char *restrict dst, const char *restrict src, size_t sz)" -{ - return ustpcpy(dst, src, strnlen(src, sz)); -} \& -.\" ----- EXAMPLES :: Implementations :: zustr2stp(3) -----------------/ -char * -.IR zustr2stp "(char *restrict dst, const char *restrict src, size_t sz)" -{ - char *p; -\& - p = zustr2ustp(dst, src, sz); - *p = \[aq]\e0\[aq]; -\& - return p; + dlen = strtcpy(dst, src, end \- dst); + return (dlen == \-1) ? NULL : dst + dlen; } \& -.\" ----- EXAMPLES :: Implementations :: ustpcpy(3) -------------------/ -char * -.IR ustpcpy "(char *restrict dst, const char *restrict src, size_t len)" +.\" ----- EXAMPLES :: Implementations :: strtcpy() --------------------/ +ssize_t +.IR strtcpy "(char *restrict dst, const char *restrict src, size_t dsize)" { - return mempcpy(dst, src, len); -} + bool trunc; + size_t dlen, slen; \& -.\" ----- EXAMPLES :: Implementations :: ustr2stp(3) ------------------/ -char * -.IR ustr2stp "(char *restrict dst, const char *restrict src, size_t len)" -{ - char *p; + if (dsize == 0) { + errno = ENOBUFS; + return \-1; + } \& - p = ustpcpy(dst, src, len); - *p = \[aq]\e0\[aq]; + slen = strnlen(src, dsize); + trunc = (slen == dsize); + dlen = slen \- trunc; \& - return p; + stpcpy(mempcpy(dst, src, dlen), ""); + if (trunc) + errno = E2BIG; + return trunc ? \-1 : slen; } -.EE -.in .\" ----- SEE ALSO :: -------------------------------------------------/ .SH SEE ALSO .BR bzero (3), diff --git a/upstream/debian-unstable/man7/suffixes.7 b/upstream/debian-unstable/man7/suffixes.7 index 5e970f42..33911062 100644 --- a/upstream/debian-unstable/man7/suffixes.7 +++ b/upstream/debian-unstable/man7/suffixes.7 @@ -14,7 +14,7 @@ .\" Modified Thu Nov 16 23:28:25 2000 by David A. Wheeler .\" <dwheeler@dwheeler.com> .\" -.TH SUFFIXES 7 2023-03-17 "Linux man-pages 6.05.01" +.TH SUFFIXES 7 2024-05-02 "Linux man-pages 6.8" .SH NAME suffixes \- list of file suffixes .SH DESCRIPTION @@ -25,10 +25,10 @@ file they are dealing with. The .BR make (1) utility is driven by rules based on file suffix. -.PP +.P Following is a list of suffixes which are likely to be found on a Linux system. -.PP +.P .TS l | l _ | _ diff --git a/upstream/debian-unstable/man7/symlink.7 b/upstream/debian-unstable/man7/symlink.7 index 9c238b2e..dae9da83 100644 --- a/upstream/debian-unstable/man7/symlink.7 +++ b/upstream/debian-unstable/man7/symlink.7 @@ -10,14 +10,14 @@ .\" 2008-06-11, mtk, Taken from FreeBSD 6.2 and heavily edited for .\" specific Linux details, improved readability, and man-pages style. .\" -.TH symlink 7 2023-04-03 "Linux man-pages 6.05.01" +.TH symlink 7 2024-05-02 "Linux man-pages 6.8" .SH NAME symlink \- symbolic link handling .SH DESCRIPTION Symbolic links are files that act as pointers to other files. To understand their behavior, you must first understand how hard links work. -.PP +.P A hard link to a file is indistinguishable from the original file because it is a reference to the object underlying the original filename. (To be precise: each of the hard links to a file is a reference to @@ -33,7 +33,7 @@ Hard links may not refer to directories which would confuse many programs) and may not refer to files on different filesystems (because inode numbers are not unique across filesystems). -.PP +.P A symbolic link is a special type of file whose contents are a string that is the pathname of another file, the file to which the link refers. (The contents of a symbolic link can be read using @@ -42,13 +42,13 @@ In other words, a symbolic link is a pointer to another name, and not to an underlying object. For this reason, symbolic links may refer to directories and may cross filesystem boundaries. -.PP +.P There is no requirement that the pathname referred to by a symbolic link should exist. A symbolic link that refers to a pathname that does not exist is said to be a .IR "dangling link" . -.PP +.P Because a symbolic link and its referenced object coexist in the filesystem name space, confusion can arise in distinguishing between the link itself and the referenced object. @@ -76,7 +76,7 @@ representation of a file handle. As such, these magic links allow users to access files which cannot be referenced with normal paths (such as unlinked files still referenced by a running program ). -.PP +.P Because they can bypass ordinary .BR mount_namespaces (7)-based restrictions, @@ -94,22 +94,22 @@ and when the .I fs.protected_symlinks sysctl is set (see .BR proc (5)). -.PP +.P The last access and last modification timestamps of a symbolic link can be changed using .BR utimensat (2) or .BR lutimes (3). -.PP +.P .\" Linux does not currently implement an lchmod(2). On Linux, the permissions of an ordinary symbolic link are not used in any operations; the permissions are always 0777 (read, write, and execute for all user categories), and can't be changed. -.PP +.P However, magic links do not follow this rule. They can have a non-0777 mode, though this mode is not currently used in any permission checks. -.\" .PP +.\" .P .\" The .\" 4.4BSD .\" system differs from historical @@ -140,7 +140,7 @@ and .BR readlinkat (2), in order to operate on the symbolic link itself (rather than the file to which it refers). -.PP +.P By default (i.e., if the .B AT_SYMLINK_FOLLOW @@ -171,7 +171,7 @@ or a loop is detected. (Loop detection is done by placing an upper limit on the number of links that may be followed, and an error results if this limit is exceeded.) -.PP +.P There are three separate areas that need to be discussed. They are as follows: .IP \[bu] 3 @@ -183,7 +183,7 @@ are not traversing a file tree. Symbolic links encountered by utilities that are traversing a file tree (either specified on the command line or encountered as part of the file hierarchy walk). -.PP +.P Before describing the treatment of symbolic links by system calls and commands, we require some terminology. Given a pathname of the form @@ -201,7 +201,7 @@ component. .SS Treatment of symbolic links in system calls The first area is symbolic links used as filename arguments for system calls. -.PP +.P The treatment of symbolic links within a pathname passed to a system call is as follows: .IP (1) 5 @@ -224,7 +224,7 @@ the system call .I "open(""slink"" ...\&)" would return a file descriptor referring to the file .IR afile . -.PP +.P Various system calls do not follow links in the basename component of a pathname, and operate on the symbolic link itself. @@ -240,7 +240,7 @@ They are: .BR rmdir (2), and .BR unlink (2). -.PP +.P Certain other system calls optionally follow symbolic links in the basename component of a pathname. They are: @@ -265,7 +265,7 @@ When .BR rmdir (2) is applied to a symbolic link, it fails with the error .BR ENOTDIR . -.PP +.P .BR link (2) warrants special discussion. POSIX.1-2001 specifies that @@ -282,7 +282,7 @@ either behavior in an implementation. .SS Commands not traversing a file tree The second area is symbolic links, specified as command-line filename arguments, to commands which are not traversing a file tree. -.PP +.P Except as noted below, commands follow symbolic links named as command-line arguments. For example, if there were a symbolic link @@ -293,7 +293,7 @@ the command .I "cat slink" would display the contents of the file .IR afile . -.PP +.P It is important to realize that this rule includes commands which may optionally traverse file trees; for example, the command .I "chown file" @@ -301,7 +301,7 @@ is included in this rule, while the command .IR "chown\ \-R file" , which performs a tree traversal, is not. (The latter is described in the third area, below.) -.PP +.P If it is explicitly intended that the command operate on the symbolic link instead of following the symbolic link\[em]for example, it is desired that .I "chown slink" @@ -319,7 +319,7 @@ while would change the ownership of .I slink itself. -.PP +.P There are some exceptions to this rule: .IP \[bu] 3 The @@ -392,16 +392,16 @@ The following commands either optionally or always traverse file trees: .BR rm (1), and .BR tar (1). -.PP +.P It is important to realize that the following rules apply equally to symbolic links encountered during the file tree traversal and symbolic links listed as command-line arguments. -.PP +.P The \fIfirst rule\fP applies to symbolic links that reference files other than directories. Operations that apply to symbolic links are performed on the links themselves, but otherwise the links are ignored. -.PP +.P The command .I "rm\ \-r slink directory" will remove @@ -413,12 +413,12 @@ In no case will .BR rm (1) affect the file referred to by .IR slink . -.PP +.P The \fIsecond rule\fP applies to symbolic links that refer to directories. Symbolic links that refer to directories are never followed by default. This is often referred to as a "physical" walk, as opposed to a "logical" walk (where symbolic links that refer to directories are followed). -.PP +.P Certain conventions are (should be) followed as consistently as possible by commands that perform file tree walks: .IP \[bu] 3 @@ -486,7 +486,7 @@ provide the default behavior by specifying the (for "physical") flag. This flag is intended to make the entire name space look like the physical name space. -.PP +.P For commands that do not by default do file tree traversals, the .IR \-H , .IR \-L , @@ -504,7 +504,7 @@ options more than once; the last one specified determines the command's behavior. This is intended to permit you to alias commands to behave one way or the other, and then override that behavior on the command line. -.PP +.P The .BR ls (1) and diff --git a/upstream/debian-unstable/man7/system_data_types.7 b/upstream/debian-unstable/man7/system_data_types.7 index c4b3925c..fc69d467 100644 --- a/upstream/debian-unstable/man7/system_data_types.7 +++ b/upstream/debian-unstable/man7/system_data_types.7 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH system_data_types 7 2023-05-20 "Linux man-pages 6.05.01" +.TH system_data_types 7 2024-05-02 "Linux man-pages 6.8" .SH NAME system_data_types \- overview of system data types .SH DESCRIPTION @@ -62,53 +62,6 @@ system_data_types \- overview of system data types .\"------------------------------------- regmatch_t -------------------/ .\"------------------------------------- regoff_t ---------------------/ .\"------------------------------------- sigevent ---------------------/ -.TP -.I sigevent -.RS -.IR Include : -.IR <signal.h> . -Alternatively, -.IR <aio.h> , -.IR <mqueue.h> , -or -.IR <time.h> . -.PP -.EX -struct sigevent { - int sigev_notify; /* Notification type */ - int sigev_signo; /* Signal number */ - union sigval sigev_value; /* Signal value */ - void (*sigev_notify_function)(union sigval); - /* Notification function */ - pthread_attr_t *sigev_notify_attributes; - /* Notification attributes */ -}; -.EE -.PP -For further details about this type, see -.BR sigevent (7). -.PP -.IR Versions : -.I <aio.h> -and -.I <time.h> -define -.I sigevent -since POSIX.1-2008. -.PP -.IR "Conforming to" : -POSIX.1-2001 and later. -.PP -.IR "See also" : -.BR timer_create (2), -.BR getaddrinfo_a (3), -.BR lio_listio (3), -.BR mq_notify (3) -.PP -See also the -.I aiocb -structure in this page. -.RE .\"------------------------------------- siginfo_t --------------------/ .TP .I siginfo_t @@ -117,27 +70,27 @@ structure in this page. .IR <signal.h> . Alternatively, .IR <sys/wait.h> . -.PP +.P .EX typedef struct { int si_signo; /* Signal number */ int si_code; /* Signal code */ pid_t si_pid; /* Sending process ID */ uid_t si_uid; /* Real user ID of sending process */ - void *si_addr; /* Address of faulting instruction */ + void *si_addr; /* Memory location which caused fault */ int si_status; /* Exit value or signal */ union sigval si_value; /* Signal value */ } siginfo_t; .EE -.PP +.P Information associated with a signal. For further details on this structure (including additional, Linux-specific fields), see .BR sigaction (2). -.PP +.P .IR "Conforming to" : POSIX.1-2001 and later. -.PP +.P .IR "See also" : .BR pidfd_send_signal (2), .BR rt_sigqueueinfo (2), @@ -155,13 +108,13 @@ Alternatively, .IR <spawn.h> , or .IR <sys/select.h> . -.PP +.P This is a type that represents a set of signals. According to POSIX, this shall be an integer or structure type. -.PP +.P .IR "Conforming to" : POSIX.1-2001 and later. -.PP +.P .IR "See also" : .BR epoll_pwait (2), .BR ppoll (2), @@ -175,37 +128,6 @@ POSIX.1-2001 and later. .BR signal (7) .RE .\"------------------------------------- sigval -----------------------/ -.TP -.I sigval -.RS -.IR Include : -.IR <signal.h> . -.PP -.EX -union sigval { - int sival_int; /* Integer value */ - void *sival_ptr; /* Pointer value */ -}; -.EE -.PP -Data passed with a signal. -.PP -.IR "Conforming to" : -POSIX.1-2001 and later. -.PP -.IR "See also" : -.BR pthread_sigqueue (3), -.BR sigqueue (3), -.BR sigevent (7) -.PP -See also the -.I sigevent -structure -and the -.I siginfo_t -type -in this page. -.RE .\"------------------------------------- size_t -----------------------/ .\"------------------------------------- sockaddr ---------------------/ .\"------------------------------------- socklen_t --------------------/ @@ -227,7 +149,7 @@ in this page. .SH NOTES The structures described in this manual page shall contain, at least, the members shown in their definition, in no particular order. -.PP +.P Most of the integer types described in this page don't have a corresponding length modifier for the .BR printf (3) @@ -258,7 +180,7 @@ In "Conforming to" we only concern ourselves with C99 and later and POSIX.1-2001 and later. Some types may be specified in earlier versions of one of these standards, but in the interests of simplicity we omit details from earlier standards. -.PP +.P In "Include", we first note the "primary" header(s) that define the type according to either the C or POSIX.1 standards. Under "Alternatively", we note additional headers that @@ -270,7 +192,7 @@ The appropriate conversions from and to .IR intmax_t , and the appropriate range checks, are used as explained in the notes section above. -.PP +.P .EX #include <stdint.h> #include <stdio.h> diff --git a/upstream/debian-unstable/man7/systemd-boot.7 b/upstream/debian-unstable/man7/systemd-boot.7 index 2aa46c6a..b1feacfb 100644 --- a/upstream/debian-unstable/man7/systemd-boot.7 +++ b/upstream/debian-unstable/man7/systemd-boot.7 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\-BOOT" "7" "" "systemd 255" "systemd-boot" +.TH "SYSTEMD\-BOOT" "7" "" "systemd 256~rc3" "systemd-boot" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -467,7 +467,7 @@ directory of the ESP\&. The files placed there must have an extension of the EFI x64\&.efi)\&. This may be used to automatically load file system drivers and similar, to extend the native firmware support\&. .PP Enrollment of Secure Boot variables can be performed manually or automatically if files are available under -/loader/keys/\fINAME\fR/{db,KEK,PK}\&.auth, +/loader/keys/\fINAME\fR/{db,dbx,KEK,PK}\&.auth, \fINAME\fR being the display name for the set of variables in the menu\&. If one of the sets is named auto @@ -642,6 +642,22 @@ Added in version 243\&. .PP Many of these variables are defined by the \m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[2]\d\s+2\&. +.SH "SMBIOS TYPE 11 STRINGS" +.PP +\fBsystemd\-boot\fR +can be configured using SMBIOS Type 11 strings\&. Applicable strings consist of a name, followed by +"=", followed by the value\&. Unless +\fBsystemd\-boot\fR +detects it is running inside a confidential computing environment, +\fBsystemd\-boot\fR +will search the table for a string with a specific name, and if found, use its value\&. The following strings are read: +.PP +\fIio\&.systemd\&.boot\&.kernel\-cmdline\-extra\fR +.RS 4 +If set, the value of this string is added to the list of kernel command line arguments for Boot Loader Specification Type 1 entries that are measured in PCR12 and passed to the kernel\&. +.sp +Added in version 256\&. +.RE .SH "BOOT COUNTING" .PP \fBsystemd\-boot\fR @@ -724,15 +740,7 @@ on x64: systemd\-boot will detect that it was started directly instead of being loaded from ESP and will search for the ESP in that case, taking into account boot order information from the hypervisor (if available)\&. .SH "SEE ALSO" .PP -\fBbootctl\fR(1), -\fBloader.conf\fR(5), -\fBsystemd-bless-boot.service\fR(8), -\fBsystemd-boot-random-seed.service\fR(8), -\fBkernel-install\fR(8), -\fBsystemd-stub\fR(7), -\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2, -\m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[2]\d\s+2, -\m[blue]\fBTPM2 PCR Measurements Made by systemd\fR\m[]\&\s-2\u[4]\d\s+2 +\fBbootctl\fR(1), \fBloader.conf\fR(5), \fBsystemd-bless-boot.service\fR(8), \fBsystemd-boot-random-seed.service\fR(8), \fBkernel-install\fR(8), \fBsystemd-stub\fR(7), \m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2, \m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[2]\d\s+2, \m[blue]\fBTPM2 PCR Measurements Made by systemd\fR\m[]\&\s-2\u[4]\d\s+2 .SH "NOTES" .IP " 1." 4 Boot Loader Specification diff --git a/upstream/debian-unstable/man7/systemd-stub.7 b/upstream/debian-unstable/man7/systemd-stub.7 index 0a1f9b0b..be784019 100644 --- a/upstream/debian-unstable/man7/systemd-stub.7 +++ b/upstream/debian-unstable/man7/systemd-stub.7 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\-STUB" "7" "" "systemd 255" "systemd-stub" +.TH "SYSTEMD\-STUB" "7" "" "systemd 256~rc3" "systemd-stub" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -23,21 +23,36 @@ systemd-stub, sd-stub, linuxx64.efi.stub, linuxia32.efi.stub, linuxaa64.efi.stub \- A simple UEFI kernel boot stub .SH "SYNOPSIS" .PP +.RS 4 /usr/lib/systemd/boot/efi/linuxx64\&.efi\&.stub -.PP +.RE +.RS 4 /usr/lib/systemd/boot/efi/linuxia32\&.efi\&.stub -.PP +.RE +.RS 4 /usr/lib/systemd/boot/efi/linuxaa64\&.efi\&.stub -.PP +.RE +.RS 4 \fIESP\fR/\&.\&.\&./\fIfoo\fR\&.efi\&.extra\&.d/*\&.addon\&.efi -.PP +.RE +.RS 4 \fIESP\fR/\&.\&.\&./\fIfoo\fR\&.efi\&.extra\&.d/*\&.cred -.PP +.RE +.RS 4 \fIESP\fR/\&.\&.\&./\fIfoo\fR\&.efi\&.extra\&.d/*\&.raw -.PP +.RE +.RS 4 +\fIESP\fR/\&.\&.\&./\fIfoo\fR\&.efi\&.extra\&.d/*\&.sysext\&.raw +.RE +.RS 4 +\fIESP\fR/\&.\&.\&./\fIfoo\fR\&.efi\&.extra\&.d/*\&.confext\&.raw +.RE +.RS 4 \fIESP\fR/loader/addons/*\&.addon\&.efi -.PP +.RE +.RS 4 \fIESP\fR/loader/credentials/*\&.cred +.RE .SH "DESCRIPTION" .PP \fBsystemd\-stub\fR @@ -112,6 +127,19 @@ section with the initrd\&. .IP \(bu 2.3 .\} A +"\&.ucode" +section with an initrd containing microcode, to be handed to the kernel before any other initrd\&. This initrd must not be compressed\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A "\&.splash" section with an image (in the Windows \&.BMP @@ -186,7 +214,7 @@ section with a set of cryptographic signatures for the expected TPM2 PCR values .\} A "\&.pcrpkey" -section with a public key in the PEM format matching the signature data in the the +section with a public key in the PEM format matching the signature data in the "\&.pcrsig" section\&. .RE @@ -277,7 +305,7 @@ archive is measured into TPM PCR 12 (if a TPM is present)\&. .IP \(bu 2.3 .\} Similarly, files -\fIfoo\fR\&.efi\&.extra\&.d/*\&.raw +\fIfoo\fR\&.efi\&.extra\&.d/*\&.sysext\&.raw are packed up in a \fBcpio\fR archive and placed in the @@ -298,12 +326,33 @@ archive containing these system extension images is measured into TPM PCR 13 (if .IP \(bu 2.3 .\} Similarly, files +\fIfoo\fR\&.efi\&.extra\&.d/*\&.confext\&.raw +are packed up in a +\fBcpio\fR +archive and placed in the +/\&.extra/confext/ +directory in the initrd file hierarchy\&. This is supposed to be used to pass additional configuration extension images to the initrd\&. See +\fBsystemd-confext\fR(8) +for details on configuration extension images\&. The generated +\fBcpio\fR +archive containing these system extension images is measured into TPM PCR 12 (if a TPM is present)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Similarly, files \fIfoo\fR\&.efi\&.extra\&.d/*\&.addon\&.efi are loaded and verified as PE binaries, and a "\&.cmdline" section is parsed from them\&. Addons are supposed to be used to pass additional kernel command line parameters or Devicetree blobs, regardless of the kernel image being booted, for example to allow platform vendors to ship platform\-specific configuration\&. .sp -In case Secure Boot is enabled, these files will be validated using keys in UEFI DB, Shim\*(Aqs DB or Shim\*(Aqs MOK, and will be rejected otherwise\&. Additionally, if the both the addon and the UKI contain a a +In case Secure Boot is enabled, these files will be validated using keys in UEFI DB, Shim\*(Aqs DB or Shim\*(Aqs MOK, and will be rejected otherwise\&. Additionally, if both the addon and the UKI contain a "\&.uname" section, the addon will be rejected if they do not match exactly\&. It is recommended to always add a "\&.sbat" @@ -363,7 +412,7 @@ Note that when a unified kernel using \fBsystemd\-stub\fR is invoked the firmware will measure it as a whole to TPM PCR 4, covering all embedded resources, such as the stub code itself, the core kernel, the embedded initrd and kernel command line (see above for a full list)\&. .PP -Also note that the Linux kernel will measure all initrds it receives into TPM PCR 9\&. This means every type of initrd will be measured two or three times: the initrd embedded in the kernel image will be measured to PCR 4, PCR 9 and PCR 11; the initrd synthesized from credentials will be measured to both PCR 9 and PCR 12; the initrd synthesized from system extensions will be measured to both PCR 4 and PCR 9\&. Let\*(Aqs summarize the OS resources and the PCRs they are measured to: +Also note that the Linux kernel will measure all initrds it receives into TPM PCR 9\&. This means every type of initrd will be measured two or three times: the initrds embedded in the kernel image will be measured to PCR 4, PCR 9 and PCR 11; the initrd synthesized from credentials (and the one synthesized from configuration extensions) will be measured to both PCR 9 and PCR 12; the initrd synthesized from system extensions will be measured to both PCR 4 and PCR 9\&. Let\*(Aqs summarize the OS resources and the PCRs they are measured to: .sp .it 1 an-trap .nr an-no-space-flag 1 @@ -389,6 +438,8 @@ l l l l l l l l +l l +l l l l. T{ \fBsystemd\-stub\fR code (the entry point of the unified PE binary) @@ -411,6 +462,11 @@ T}:T{ 4 + 9 + 11 T} T{ +Microcode initrd (embedded in unified PE binary) +T}:T{ +4 + 9 + 11 +T} +T{ Default kernel command line (embedded in unified PE binary) T}:T{ 4 + 11 @@ -445,6 +501,11 @@ System Extensions (synthesized initrd from companion files) T}:T{ 9 + 13 T} +T{ +Configuration Extensions (synthesized initrd from companion files) +T}:T{ +9 + 12 +T} .TE .sp 1 .SH "EFI VARIABLES" @@ -507,12 +568,20 @@ Added in version 252\&. .PP \fIStubPcrInitRDSysExts\fR .RS 4 -The PCR register index the systemd extensions for the initrd, which are picked up from the file system the kernel image is located on\&. Formatted as decimal ASCII string (e\&.g\&. +The PCR register index the system extensions for the initrd, which are picked up from the file system the kernel image is located on\&. Formatted as decimal ASCII string (e\&.g\&. "13")\&. This variable is set if a measurement was successfully completed, and remains unset otherwise\&. .sp Added in version 252\&. .RE .PP +\fIStubPcrInitRDConfExts\fR +.RS 4 +The PCR register index the configuration extensions for the initrd, which are picked up from the file system the kernel image is located on\&. Formatted as decimal ASCII string (e\&.g\&. +"12")\&. This variable is set if a measurement was successfully completed, and remains unset otherwise\&. +.sp +Added in version 255\&. +.RE +.PP Note that some of the variables above may also be set by the boot loader\&. The stub will only set them if they aren\*(Aqt set already\&. Some of these variables are defined by the \m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[4]\d\s+2\&. .SH "INITRD RESOURCES" @@ -549,16 +618,26 @@ directory in the initrd execution environment\&. Added in version 252\&. .RE .PP -/\&.extra/sysext/*\&.raw +/\&.extra/sysext/*\&.sysext\&.raw .RS 4 System extension image files (suffix -"\&.raw") that are placed next to the unified kernel image (as described above) are copied into the +"\&.sysext\&.raw") that are placed next to the unified kernel image (as described above) are copied into the /\&.extra/sysext/ directory in the initrd execution environment\&. .sp Added in version 252\&. .RE .PP +/\&.extra/confext/*\&.confext\&.raw +.RS 4 +Configuration extension image files (suffix +"\&.confext\&.raw") that are placed next to the unified kernel image (as described above) are copied into the +/\&.extra/confext/ +directory in the initrd execution environment\&. +.sp +Added in version 255\&. +.RE +.PP /\&.extra/tpm2\-pcr\-signature\&.json .RS 4 The TPM2 PCR signature JSON object included in the @@ -590,7 +669,9 @@ line\&. By default, this is done for the TPM2 PCR signature and public key files .PP \fBsystemd\-stub\fR can be configured using SMBIOS Type 11 strings\&. Applicable strings consist of a name, followed by -"=", followed by the value\&. +"=", followed by the value\&. Unless +\fBsystemd\-stub\fR +detects it is running inside a confidential computing environment, \fBsystemd\-stub\fR will search the table for a string with a specific name, and if found, use its value\&. The following strings are read: .PP @@ -606,15 +687,7 @@ In order to assemble a bootable Unified Kernel Image from various components as \fBukify\fR(1)\&. .SH "SEE ALSO" .PP -\fBsystemd-boot\fR(7), -\fBsystemd.exec\fR(5), -\fBsystemd-creds\fR(1), -\fBsystemd-sysext\fR(8), -\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[5]\d\s+2, -\m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[4]\d\s+2, -\fBukify\fR(1), -\fBsystemd-measure\fR(1), -\m[blue]\fBTPM2 PCR Measurements Made by systemd\fR\m[]\&\s-2\u[6]\d\s+2 +\fBsystemd-boot\fR(7), \fBsystemd.exec\fR(5), \fBsystemd-creds\fR(1), \fBsystemd-sysext\fR(8), \m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[5]\d\s+2, \m[blue]\fBBoot Loader Interface\fR\m[]\&\s-2\u[4]\d\s+2, \fBukify\fR(1), \fBsystemd-measure\fR(1), \m[blue]\fBTPM2 PCR Measurements Made by systemd\fR\m[]\&\s-2\u[6]\d\s+2 .SH "NOTES" .IP " 1." 4 SBAT diff --git a/upstream/debian-unstable/man7/systemd.directives.7 b/upstream/debian-unstable/man7/systemd.directives.7 index 005b8129..556d452f 100644 --- a/upstream/debian-unstable/man7/systemd.directives.7 +++ b/upstream/debian-unstable/man7/systemd.directives.7 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\&.DIRECTIVES" "7" "" "systemd 255" "systemd.directives" +.TH "SYSTEMD\&.DIRECTIVES" "7" "" "systemd 256~rc3" "systemd.directives" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -1201,6 +1201,11 @@ Directives for configuring units, used in unit files\&. \fBsystemd.resource-control\fR(5) .RE .PP +\fIMemoryZSwapWriteback=\fR +.RS 4 +\fBsystemd.resource-control\fR(5) +.RE +.PP \fIMessageQueueMaxMessages=\fR .RS 4 \fBsystemd.socket\fR(5) @@ -1388,6 +1393,11 @@ Directives for configuring units, used in unit files\&. \fBsystemd.exec\fR(5) .RE .PP +\fIPassFileDescriptorsToExec=\fR +.RS 4 +\fBsystemd.socket\fR(5) +.RE +.PP \fIPassPacketInfo=\fR .RS 4 \fBsystemd.socket\fR(5) @@ -2263,6 +2273,11 @@ Directives for configuring units, used in unit files\&. \fBsystemd.unit\fR(5) .RE .PP +\fIWantsMountsFor=\fR +.RS 4 +\fBsystemd.unit\fR(5) +.RE +.PP \fIWatchdogSec=\fR .RS 4 \fBsystemd.service\fR(5) @@ -2393,6 +2408,7 @@ Kernel boot options for configuring the behaviour of the systemd process\&. .PP \fIifname=\fR .RS 4 +\fBkernel-command-line\fR(7), \fBsystemd-network-generator.service\fR(8) .RE .PP @@ -2557,8 +2573,9 @@ Kernel boot options for configuring the behaviour of the systemd process\&. \fBsystemd-resolved.service\fR(8) .RE .PP -\fInet\&.ifname\-policy=\fR +\fInet\&.ifname_policy=\fR .RS 4 +\fBkernel-command-line\fR(7), \fBsystemd-network-generator.service\fR(8), \fBsystemd-udevd.service\fR(8) .RE @@ -2569,7 +2586,7 @@ Kernel boot options for configuring the behaviour of the systemd process\&. \fBsystemd-udevd.service\fR(8) .RE .PP -\fInet\&.naming\-scheme=\fR +\fInet\&.naming_scheme=\fR .RS 4 \fBkernel-command-line\fR(7), \fBsystemd-udevd.service\fR(8) @@ -2765,6 +2782,7 @@ Kernel boot options for configuring the behaviour of the systemd process\&. .PP \fIresume_offset=\fR .RS 4 +\fBkernel-command-line\fR(7), \fBsystemd-hibernate-resume-generator\fR(8) .RE .PP @@ -2826,22 +2844,28 @@ Kernel boot options for configuring the behaviour of the systemd process\&. \fBsystemd\fR(1) .RE .PP -\fIsystemd\&.battery\-check=\fR +\fIsystemd\&.allow_userspace_verity=\fR +.RS 4 +\fBkernel-command-line\fR(7) +.RE +.PP +\fIsystemd\&.battery_check=\fR .RS 4 +\fBkernel-command-line\fR(7), \fBsystemd-battery-check.service\fR(8) .RE .PP -\fIsystemd\&.clock\-usec=\fR +\fIsystemd\&.clock_usec=\fR .RS 4 \fBkernel-command-line\fR(7) .RE .PP -\fIsystemd\&.condition\-first\-boot=\fR +\fIsystemd\&.condition_first_boot=\fR .RS 4 \fBkernel-command-line\fR(7) .RE .PP -\fIsystemd\&.condition\-needs\-update=\fR +\fIsystemd\&.condition_needs_update=\fR .RS 4 \fBkernel-command-line\fR(7) .RE @@ -2857,13 +2881,13 @@ Kernel boot options for configuring the behaviour of the systemd process\&. \fBkernel-command-line\fR(7) .RE .PP -\fIsystemd\&.crash_chvt\fR +\fIsystemd\&.crash_action=\fR .RS 4 \fBkernel-command-line\fR(7), \fBsystemd\fR(1) .RE .PP -\fIsystemd\&.crash_reboot\fR +\fIsystemd\&.crash_chvt\fR .RS 4 \fBkernel-command-line\fR(7), \fBsystemd\fR(1) @@ -2880,6 +2904,11 @@ Kernel boot options for configuring the behaviour of the systemd process\&. \fBkernel-command-line\fR(7) .RE .PP +\fIsystemd\&.default_debug_tty=\fR +.RS 4 +\fBkernel-command-line\fR(7) +.RE +.PP \fIsystemd\&.default_device_timeout_sec=\fR .RS 4 \fBkernel-command-line\fR(7) @@ -2915,6 +2944,7 @@ Kernel boot options for configuring the behaviour of the systemd process\&. .PP \fIsystemd\&.firstboot=\fR .RS 4 +\fBhomectl\fR(1), \fBkernel-command-line\fR(7), \fBsystemd-firstboot\fR(1) .RE @@ -2976,6 +3006,36 @@ Kernel boot options for configuring the behaviour of the systemd process\&. \fBsystemd-journald.service\fR(8) .RE .PP +\fIsystemd\&.journald\&.max_level_console=\fR +.RS 4 +\fBsystemd-journald.service\fR(8) +.RE +.PP +\fIsystemd\&.journald\&.max_level_kmsg=\fR +.RS 4 +\fBsystemd-journald.service\fR(8) +.RE +.PP +\fIsystemd\&.journald\&.max_level_socket=\fR +.RS 4 +\fBsystemd-journald.service\fR(8) +.RE +.PP +\fIsystemd\&.journald\&.max_level_store=\fR +.RS 4 +\fBsystemd-journald.service\fR(8) +.RE +.PP +\fIsystemd\&.journald\&.max_level_syslog=\fR +.RS 4 +\fBsystemd-journald.service\fR(8) +.RE +.PP +\fIsystemd\&.journald\&.max_level_wall=\fR +.RS 4 +\fBsystemd-journald.service\fR(8) +.RE +.PP \fIsystemd\&.log_color\fR .RS 4 \fBkernel-command-line\fR(7), @@ -3036,7 +3096,7 @@ Kernel boot options for configuring the behaviour of the systemd process\&. \fBsystemd-fstab-generator\fR(8) .RE .PP -\fIsystemd\&.random\-seed=\fR +\fIsystemd\&.random_seed=\fR .RS 4 \fBkernel-command-line\fR(7) .RE @@ -3107,6 +3167,18 @@ Kernel boot options for configuring the behaviour of the systemd process\&. \fBsystemd\fR(1) .RE .PP +\fIsystemd\&.ssh_auto=\fR +.RS 4 +\fBkernel-command-line\fR(7), +\fBsystemd-ssh-generator\fR(8) +.RE +.PP +\fIsystemd\&.ssh_listen=\fR +.RS 4 +\fBkernel-command-line\fR(7), +\fBsystemd-ssh-generator\fR(8) +.RE +.PP \fIsystemd\&.status_unit_format=\fR .RS 4 \fBkernel-command-line\fR(7), @@ -3124,6 +3196,11 @@ Kernel boot options for configuring the behaviour of the systemd process\&. \fBsystemd-gpt-auto-generator\fR(8) .RE .PP +\fIsystemd\&.tpm2_wait=\fR +.RS 4 +\fBkernel-command-line\fR(7) +.RE +.PP \fIsystemd\&.tty\&.columns\&.\fR\fI\fItty\fR\fR\fI=\fR .RS 4 \fBkernel-command-line\fR(7) @@ -3303,6 +3380,11 @@ Kernel boot options for configuring the behaviour of the systemd process\&. .PP Data passed from VMM to system via SMBIOS Type 11\&. .PP +\fIio\&.systemd\&.boot\&.kernel\-cmdline\-extra=\fR +.RS 4 +\fBsmbios-type-11\fR(7) +.RE +.PP \fIio\&.systemd\&.credential\&.binary:\fR .RS 4 \fBsmbios-type-11\fR(7) @@ -3532,6 +3614,7 @@ Environment variables understood by the systemd manager and other programs and e \fI$SYSTEMD_COLORS\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -3605,6 +3688,7 @@ Environment variables understood by the systemd manager and other programs and e \fI$SYSTEMD_LESS\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -3623,6 +3707,7 @@ Environment variables understood by the systemd manager and other programs and e \fI$SYSTEMD_LESSCHARSET\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -3641,6 +3726,7 @@ Environment variables understood by the systemd manager and other programs and e \fI$SYSTEMD_LOG_COLOR\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -3660,6 +3746,7 @@ Environment variables understood by the systemd manager and other programs and e \fI$SYSTEMD_LOG_LEVEL\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -3679,6 +3766,7 @@ Environment variables understood by the systemd manager and other programs and e \fI$SYSTEMD_LOG_LOCATION\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -3698,6 +3786,7 @@ Environment variables understood by the systemd manager and other programs and e \fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -3714,6 +3803,7 @@ Environment variables understood by the systemd manager and other programs and e \fI$SYSTEMD_LOG_TARGET\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -3733,6 +3823,7 @@ Environment variables understood by the systemd manager and other programs and e \fI$SYSTEMD_LOG_TID\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -3749,6 +3840,7 @@ Environment variables understood by the systemd manager and other programs and e \fI$SYSTEMD_LOG_TIME\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -3798,6 +3890,7 @@ Environment variables understood by the systemd manager and other programs and e \fI$SYSTEMD_PAGER\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -3816,6 +3909,7 @@ Environment variables understood by the systemd manager and other programs and e \fI$SYSTEMD_PAGERSECURE\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -3849,6 +3943,7 @@ Environment variables understood by the systemd manager and other programs and e \fI$SYSTEMD_URLIFY\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -4160,6 +4255,66 @@ Environment variables understood by the systemd manager and other programs and e .PP System credentials understood by the system and service manager and various other components: .PP +\fIcryptenroll\&.fido2\-pin\fR +.RS 4 +\fBsystemd-cryptenroll\fR(1) +.RE +.PP +\fIcryptenroll\&.new\-passphrase\fR +.RS 4 +\fBsystemd-cryptenroll\fR(1) +.RE +.PP +\fIcryptenroll\&.new\-tpm2\-pin\fR +.RS 4 +\fBsystemd-cryptenroll\fR(1) +.RE +.PP +\fIcryptenroll\&.passphrase\fR +.RS 4 +\fBsystemd-cryptenroll\fR(1) +.RE +.PP +\fIcryptenroll\&.pkcs11\-pin\fR +.RS 4 +\fBsystemd-cryptenroll\fR(1) +.RE +.PP +\fIcryptenroll\&.tpm2\-pin\fR +.RS 4 +\fBsystemd-cryptenroll\fR(1) +.RE +.PP +\fIcryptsetup\&.fido2\-pin\fR +.RS 4 +\fBsystemd-cryptsetup\fR(8), +\fBsystemd.system-credentials\fR(7) +.RE +.PP +\fIcryptsetup\&.luks2\-pin\fR +.RS 4 +\fBsystemd-cryptsetup\fR(8), +\fBsystemd.system-credentials\fR(7) +.RE +.PP +\fIcryptsetup\&.passphrase\fR +.RS 4 +\fBsystemd-cryptsetup\fR(8), +\fBsystemd.system-credentials\fR(7) +.RE +.PP +\fIcryptsetup\&.pkcs11\-pin\fR +.RS 4 +\fBsystemd-cryptsetup\fR(8), +\fBsystemd.system-credentials\fR(7) +.RE +.PP +\fIcryptsetup\&.tpm2\-pin\fR +.RS 4 +\fBsystemd-cryptsetup\fR(8), +\fBsystemd.system-credentials\fR(7) +.RE +.PP \fIfirstboot\&.keymap\fR .RS 4 \fBsystemd-firstboot\fR(1), @@ -4202,6 +4357,24 @@ System credentials understood by the system and service manager and various othe \fBsystemd.system-credentials\fR(7) .RE .PP +\fIhome\&.create\&.*\fR +.RS 4 +\fBhomectl\fR(1), +\fBsystemd.system-credentials\fR(7) +.RE +.PP +\fIjournal\&.forward_to_socket\fR +.RS 4 +\fBsystemd-journald.service\fR(8), +\fBsystemd.system-credentials\fR(7) +.RE +.PP +\fIjournal\&.storage\fR +.RS 4 +\fBsystemd-journald.service\fR(8), +\fBsystemd.system-credentials\fR(7) +.RE +.PP \fIlogin\&.issue\fR .RS 4 \fBsystemd.system-credentials\fR(7) @@ -4212,6 +4385,12 @@ System credentials understood by the system and service manager and various othe \fBsystemd.system-credentials\fR(7) .RE .PP +\fInetwork\&.conf\&.*\fR +.RS 4 +\fBsystemd-network-generator.service\fR(8), +\fBsystemd.system-credentials\fR(7) +.RE +.PP \fInetwork\&.dns\fR .RS 4 \fBsystemd-resolved.service\fR(8), @@ -4223,12 +4402,35 @@ System credentials understood by the system and service manager and various othe \fBsystemd.system-credentials\fR(7) .RE .PP +\fInetwork\&.link\&.*\fR +.RS 4 +\fBsystemd-network-generator.service\fR(8), +\fBsystemd.system-credentials\fR(7) +.RE +.PP +\fInetwork\&.netdev\&.*\fR +.RS 4 +\fBsystemd-network-generator.service\fR(8), +\fBsystemd.system-credentials\fR(7) +.RE +.PP +\fInetwork\&.network\&.*\fR +.RS 4 +\fBsystemd-network-generator.service\fR(8), +\fBsystemd.system-credentials\fR(7) +.RE +.PP \fInetwork\&.search_domains\fR .RS 4 \fBsystemd-resolved.service\fR(8), \fBsystemd.system-credentials\fR(7) .RE .PP +\fInetwork\&.wireguard\&.*\fR +.RS 4 +\fBsystemd.system-credentials\fR(7) +.RE +.PP \fIpasswd\&.hashed\-password\&.\fR\fI\fIuser\fR\fR .RS 4 \fBsystemd-sysusers\fR(8) @@ -4267,18 +4469,41 @@ System credentials understood by the system and service manager and various othe \fBsystemd.system-credentials\fR(7) .RE .PP +\fIssh\&.listen\fR +.RS 4 +\fBsystemd-ssh-generator\fR(8), +\fBsystemd.system-credentials\fR(7) +.RE +.PP \fIsysctl\&.extra\fR .RS 4 \fBsystemd-sysctl.service\fR(8), \fBsystemd.system-credentials\fR(7) .RE .PP +\fIsystem\&.hostname\fR +.RS 4 +\fBsystemd.system-credentials\fR(7) +.RE +.PP \fIsystem\&.machine_id\fR .RS 4 \fBsystemd\fR(1), \fBsystemd.system-credentials\fR(7) .RE .PP +\fIsystemd\&.extra\-unit\&.*\fR +.RS 4 +\fBsystemd-debug-generator\fR(8), +\fBsystemd.system-credentials\fR(7) +.RE +.PP +\fIsystemd\&.unit\-dropin\&.*\fR +.RS 4 +\fBsystemd-debug-generator\fR(8), +\fBsystemd.system-credentials\fR(7) +.RE +.PP \fIsysusers\&.extra\fR .RS 4 \fBsystemd-sysusers\fR(8), @@ -4291,6 +4516,16 @@ System credentials understood by the system and service manager and various othe \fBsystemd.system-credentials\fR(7) .RE .PP +\fIudev\&.conf\&.*\fR +.RS 4 +\fBsystemd.system-credentials\fR(7) +.RE +.PP +\fIudev\&.rules\&.*\fR +.RS 4 +\fBsystemd.system-credentials\fR(7) +.RE +.PP \fIvconsole\&.font\fR .RS 4 \fBsystemd.system-credentials\fR(7) @@ -4431,6 +4666,11 @@ and other programs\&. \fBsystemd-stub\fR(7) .RE .PP +\fIStubPcrInitRDConfExts\fR +.RS 4 +\fBsystemd-stub\fR(7) +.RE +.PP \fIStubPcrInitRDSysExts\fR .RS 4 \fBsystemd-stub\fR(7) @@ -4876,6 +5116,11 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.netdev\fR(5) .RE .PP +\fIARPMissedMax=\fR +.RS 4 +\fBsystemd.netdev\fR(5) +.RE +.PP \fIARPValidate=\fR .RS 4 \fBsystemd.netdev\fR(5) @@ -5133,6 +5378,11 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.netdev\fR(5) .RE .PP +\fIBroadcastQueueThreshold=\fR +.RS 4 +\fBsystemd.netdev\fR(5) +.RE +.PP \fIBuckets=\fR .RS 4 \fBsystemd.network\fR(5) @@ -5851,11 +6101,6 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.netdev\fR(5) .RE .PP -\fIIPForward=\fR -.RS 4 -\fBsystemd.network\fR(5) -.RE -.PP \fIIPMasquerade=\fR .RS 4 \fBsystemd.network\fR(5) @@ -5891,6 +6136,12 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.network\fR(5) .RE .PP +\fIIPv4Forwarding=\fR +.RS 4 +\fBnetworkd.conf\fR(5), +\fBsystemd.network\fR(5) +.RE +.PP \fIIPv4LLRoute=\fR .RS 4 \fBsystemd.network\fR(5) @@ -5906,6 +6157,11 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.network\fR(5) .RE .PP +\fIIPv4ProxyARPPrivateVLAN=\fR +.RS 4 +\fBsystemd.network\fR(5) +.RE +.PP \fIIPv4ReversePathFilter=\fR .RS 4 \fBsystemd.network\fR(5) @@ -5931,6 +6187,12 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.netdev\fR(5) .RE .PP +\fIIPv6Forwarding=\fR +.RS 4 +\fBnetworkd.conf\fR(5), +\fBsystemd.network\fR(5) +.RE +.PP \fIIPv6HopLimit=\fR .RS 4 \fBsystemd.network\fR(5) @@ -5982,6 +6244,11 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.netdev\fR(5) .RE .PP +\fIIPv6RetransmissionTimeSec=\fR +.RS 4 +\fBsystemd.network\fR(5) +.RE +.PP \fIIPv6SendRA=\fR .RS 4 \fBsystemd.network\fR(5) @@ -6019,6 +6286,11 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.network\fR(5) .RE .PP +\fIImportProperty=\fR +.RS 4 +\fBsystemd.link\fR(5) +.RE +.PP \fIIncomingInterface=\fR .RS 4 \fBsystemd.network\fR(5) @@ -6135,6 +6407,11 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.netdev\fR(5) .RE .PP +\fIL3MasterDevice=\fR +.RS 4 +\fBsystemd.network\fR(5) +.RE +.PP \fIL3MissNotification=\fR .RS 4 \fBsystemd.netdev\fR(5) @@ -6318,6 +6595,11 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.netdev\fR(5) .RE .PP +\fIManageForeignNextHops=\fR +.RS 4 +\fBnetworkd.conf\fR(5) +.RE +.PP \fIManageForeignRoutes=\fR .RS 4 \fBnetworkd.conf\fR(5) @@ -6606,6 +6888,11 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.network\fR(5) .RE .PP +\fIPeerNotifyDelaySec=\fR +.RS 4 +\fBsystemd.netdev\fR(5) +.RE +.PP \fIPeerPort=\fR .RS 4 \fBsystemd.netdev\fR(5) @@ -6627,6 +6914,11 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.network\fR(5) .RE .PP +\fIPersistLeases=\fR +.RS 4 +\fBsystemd.network\fR(5) +.RE +.PP \fIPersistentKeepalive=\fR .RS 4 \fBsystemd.netdev\fR(5) @@ -6850,6 +7142,11 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.network\fR(5) .RE .PP +\fIReachableTimeSec=\fR +.RS 4 +\fBsystemd.network\fR(5) +.RE +.PP \fIReadEtcHosts=\fR .RS 4 \fBresolved.conf\fR(5) @@ -6860,6 +7157,11 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.link\fR(5) .RE .PP +\fIReceivePacketSteeringCPUMask=\fR +.RS 4 +\fBsystemd.link\fR(5) +.RE +.PP \fIReceiveQueues=\fR .RS 4 \fBsystemd.link\fR(5) @@ -7183,6 +7485,11 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.network\fR(5) .RE .PP +\fIServerPort=\fR +.RS 4 +\fBsystemd.network\fR(5) +.RE +.PP \fISessionId=\fR .RS 4 \fBsystemd.netdev\fR(5) @@ -7233,6 +7540,11 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.network\fR(5) .RE .PP +\fISubType=\fR +.RS 4 +\fBsystemd.dnssd\fR(5) +.RE +.PP \fISubnetId=\fR .RS 4 \fBsystemd.network\fR(5) @@ -7288,11 +7600,6 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.netdev\fR(5) .RE .PP -\fITTLPropagate=\fR -.RS 4 -\fBsystemd.network\fR(5) -.RE -.PP \fITable=\fR .RS 4 \fBsystemd.netdev\fR(5), @@ -7493,6 +7800,11 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.network\fR(5) .RE .PP +\fIUnsetProperty=\fR +.RS 4 +\fBsystemd.link\fR(5) +.RE +.PP \fIUpDelaySec=\fR .RS 4 \fBsystemd.netdev\fR(5) @@ -7550,6 +7862,7 @@ Directives for configuring network links through the net\-setup\-link udev built .PP \fIUseDomains=\fR .RS 4 +\fBnetworkd.conf\fR(5), \fBsystemd.network\fR(5) .RE .PP @@ -7573,11 +7886,6 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.network\fR(5) .RE .PP -\fIUseICMP6RateLimit=\fR -.RS 4 -\fBsystemd.network\fR(5) -.RE -.PP \fIUseMTU=\fR .RS 4 \fBsystemd.network\fR(5) @@ -7603,6 +7911,21 @@ Directives for configuring network links through the net\-setup\-link udev built \fBsystemd.network\fR(5) .RE .PP +\fIUseReachableTime=\fR +.RS 4 +\fBsystemd.network\fR(5) +.RE +.PP +\fIUseRedirect=\fR +.RS 4 +\fBsystemd.network\fR(5) +.RE +.PP +\fIUseRetransmissionTime=\fR +.RS 4 +\fBsystemd.network\fR(5) +.RE +.PP \fIUseRoutePrefix=\fR .RS 4 \fBsystemd.network\fR(5) @@ -8008,6 +8331,11 @@ Fields in the journal events with a well known meaning\&. \fBsystemd.journal-fields\fR(7) .RE .PP +\fIOBJECT_SYSTEMD_INVOCATION_ID=\fR +.RS 4 +\fBsystemd.journal-fields\fR(7) +.RE +.PP \fIOBJECT_SYSTEMD_OWNER_UID=\fR .RS 4 \fBsystemd.journal-fields\fR(7) @@ -8480,6 +8808,11 @@ Options which influence mounted filesystems and encrypted volumes\&. \fBcrypttab\fR(5) .RE .PP +\fBlink\-volume\-key=\fR +.RS 4 +\fBcrypttab\fR(5) +.RE +.PP \fBluks\fR .RS 4 \fBcrypttab\fR(5) @@ -8784,6 +9117,11 @@ Options which influence mounted filesystems and encrypted volumes\&. .RS 4 \fBsystemd.mount\fR(5) .RE +.PP +\fBx\-systemd\&.wants\-mounts\-for=\fR +.RS 4 +\fBsystemd.mount\fR(5) +.RE .SH "SYSTEMD.NSPAWN(5) DIRECTIVES" .PP Directives for configuring systemd\-nspawn containers\&. @@ -9132,12 +9470,12 @@ Directives for configuring the behaviour of the systemd process and other tools \fBjournald.conf\fR(5) .RE .PP -\fICrashChangeVT=\fR +\fICrashAction=\fR .RS 4 \fBsystemd-system.conf\fR(5) .RE .PP -\fICrashReboot=\fR +\fICrashChangeVT=\fR .RS 4 \fBsystemd-system.conf\fR(5) .RE @@ -9372,6 +9710,11 @@ Directives for configuring the behaviour of the systemd process and other tools \fBjournald.conf\fR(5) .RE .PP +\fIForwardToSocket=\fR +.RS 4 +\fBjournald.conf\fR(5) +.RE +.PP \fIForwardToSyslog=\fR .RS 4 \fBjournald.conf\fR(5) @@ -9573,6 +9916,11 @@ Directives for configuring the behaviour of the systemd process and other tools \fBjournald.conf\fR(5) .RE .PP +\fIMaxLevelSocket=\fR +.RS 4 +\fBjournald.conf\fR(5) +.RE +.PP \fIMaxLevelStore=\fR .RS 4 \fBjournald.conf\fR(5) @@ -9599,6 +9947,11 @@ Directives for configuring the behaviour of the systemd process and other tools \fBjournal-remote.conf\fR(5) .RE .PP +\fIMemorySleepMode=\fR +.RS 4 +\fBsystemd-sleep.conf\fR(5) +.RE +.PP \fINAutoVTs=\fR .RS 4 \fBlogind.conf\fR(5) @@ -9634,6 +9987,11 @@ Directives for configuring the behaviour of the systemd process and other tools \fBcoredump.conf\fR(5) .RE .PP +\fIProtectSystem=\fR +.RS 4 +\fBsystemd-system.conf\fR(5) +.RE +.PP \fIRateLimitBurst=\fR .RS 4 \fBjournald.conf\fR(5) @@ -9752,6 +10110,11 @@ Directives for configuring the behaviour of the systemd process and other tools \fBsystemd-system.conf\fR(5) .RE .PP +\fISleepOperation=\fR +.RS 4 +\fBlogind.conf\fR(5) +.RE +.PP \fISplitMode=\fR .RS 4 \fBjournal-remote.conf\fR(5), @@ -9974,6 +10337,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBbusctl\fR(1) .RE .PP +\fB\-\-allow\-null\fR +.RS 4 +\fBsystemd-creds\fR(1) +.RE +.PP \fB\-\-ambient\-capability\fR .RS 4 \fBsystemd-nspawn\fR(1) @@ -10059,6 +10427,18 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-mount\fR(1) .RE .PP +\fB\-\-avatar\fR +.RS 4 +\fBhomectl\fR(1) +.RE +.PP +\fB\-\-background\fR +.RS 4 +\fBrun0\fR(1), +\fBsystemd-nspawn\fR(1), +\fBsystemd-run\fR(1) +.RE +.PP \fB\-\-backing\fR .RS 4 \fBudevadm\fR(8) @@ -10075,6 +10455,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-analyze\fR(1) .RE .PP +\fB\-\-basename\fR +.RS 4 +\fBsystemd-vpick\fR(1) +.RE +.PP \fB\-\-batch\fR .RS 4 \fBsystemd-cgtop\fR(1) @@ -10105,6 +10490,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-nspawn\fR(1) .RE .PP +\fB\-\-blob\fR +.RS 4 +\fBhomectl\fR(1) +.RE +.PP \fB\-\-boot\fR\fB[=[\fIID\fR][\fI\(+-offset\fR]|\fBall\fR]\fR .RS 4 \fBjournalctl\fR(1), @@ -10163,6 +10553,13 @@ Command\-line options accepted by programs in the systemd suite\&. \fBhomectl\fR(1) .RE .PP +\fB\-\-capsule\fR +.RS 4 +\fBbusctl\fR(1), +\fBsystemctl\fR(1), +\fBsystemd-run\fR(1) +.RE +.PP \fB\-\-case\-sensitive\fR\fB[=BOOLEAN]\fR .RS 4 \fBjournalctl\fR(1) @@ -10195,6 +10592,7 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-\-certificate\fR .RS 4 +\fBsystemd-measure\fR(1), \fBsystemd-repart\fR(8) .RE .PP @@ -10210,6 +10608,7 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-\-chdir\fR .RS 4 +\fBrun0\fR(1), \fBsystemd-nspawn\fR(1) .RE .PP @@ -10251,11 +10650,13 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-\-class\fR .RS 4 +\fBimportctl\fR(1), \fBresolvectl\fR(1) .RE .PP \fB\-\-clean\fR .RS 4 +\fBportablectl\fR(1), \fBsystemd-tmpfiles\fR(8) .RE .PP @@ -10278,7 +10679,8 @@ Command\-line options accepted by programs in the systemd suite\&. \fB\-\-collect\fR .RS 4 \fBsystemd-mount\fR(1), -\fBsystemd-run\fR(1) +\fBsystemd-run\fR(1), +\fBvarlinkctl\fR(1) .RE .PP \fB\-\-commit\fR @@ -10394,7 +10796,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBhomectl\fR(1) .RE .PP -\fB\-\-crash\-reboot\fR +\fB\-\-crash\-action\fR .RS 4 \fBsystemd\fR(1) .RE @@ -10504,6 +10906,7 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-\-description\fR .RS 4 +\fBrun0\fR(1), \fBsystemd-mount\fR(1), \fBsystemd-run\fR(1) .RE @@ -10602,6 +11005,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-oomd.service\fR(8), \fBsystemd-repart\fR(8), \fBsystemd-sysusers\fR(8), +\fBsystemd-tmpfiles\fR(8), \fBudevadm\fR(8) .RE .PP @@ -10673,7 +11077,8 @@ Command\-line options accepted by programs in the systemd suite\&. \fB\-\-entry\-token\fR .RS 4 \fBbootctl\fR(1), -\fBkernel-install\fR(8) +\fBkernel-install\fR(8), +\fBsystemd-pcrlock\fR(8) .RE .PP \fB\-\-ephemeral\fR @@ -10692,6 +11097,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-udevd.service\fR(8) .RE .PP +\fB\-\-exclude\-identifier\fR +.RS 4 +\fBjournalctl\fR(1) +.RE +.PP \fB\-\-exclude\-partitions\fR .RS 4 \fBsystemd-repart\fR(8) @@ -10865,6 +11275,7 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-\-force\fR .RS 4 +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBmachinectl\fR(1), \fBportablectl\fR(1), @@ -10877,7 +11288,7 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-\-format\fR .RS 4 -\fBmachinectl\fR(1) +\fBimportctl\fR(1) .RE .PP \fB\-\-from\-pattern\fR @@ -10913,6 +11324,16 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-analyze\fR(1) .RE .PP +\fB\-\-generate\-crypttab\fR +.RS 4 +\fBsystemd-repart\fR(8) +.RE +.PP +\fB\-\-generate\-fstab\fR +.RS 4 +\fBsystemd-repart\fR(8) +.RE +.PP \fB\-\-generators\fR .RS 4 \fBsystemd-analyze\fR(1) @@ -10951,6 +11372,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBjournalctl\fR(1) .RE .PP +\fB\-\-group\fR +.RS 4 +\fBrun0\fR(1) +.RE +.PP \fB\-\-growfs\fR .RS 4 \fBsystemd-dissect\fR(1) @@ -10974,6 +11400,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBcoredumpctl\fR(1), \fBhomectl\fR(1), \fBhostnamectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBkernel-install\fR(8), \fBlocalectl\fR(1), @@ -10984,6 +11411,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBportablectl\fR(1), \fBpoweroff\fR(8), \fBresolvectl\fR(1), +\fBrun0\fR(1), \fBrunlevel\fR(8), \fBshutdown\fR(8), \fBsystemctl\fR(1), @@ -11005,7 +11433,6 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-dissect\fR(1), \fBsystemd-escape\fR(1), \fBsystemd-firstboot\fR(1), -\fBsystemd-fsckd.service\fR(8), \fBsystemd-hwdb\fR(8), \fBsystemd-id128\fR(1), \fBsystemd-inhibit\fR(1), @@ -11018,6 +11445,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-networkd-wait-online.service\fR(8), \fBsystemd-notify\fR(1), \fBsystemd-nspawn\fR(1), +\fBsystemd-oomd.service\fR(8), \fBsystemd-path\fR(1), \fBsystemd-pcrlock\fR(8), \fBsystemd-pcrphase.service\fR(8), @@ -11035,6 +11463,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-tmpfiles\fR(8), \fBsystemd-tty-ask-password-agent\fR(1), \fBsystemd-udevd.service\fR(8), +\fBsystemd-vpick\fR(1), \fBtelinit\fR(8), \fBtimedatectl\fR(1), \fBudevadm\fR(8), @@ -11053,6 +11482,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBbusctl\fR(1), \fBhomectl\fR(1), \fBhostnamectl\fR(1), +\fBimportctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), \fBmachinectl\fR(1), @@ -11101,6 +11531,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-networkd-wait-online.service\fR(8) .RE .PP +\fB\-\-ignore\-failure\fR +.RS 4 +\fBsystemd-run\fR(1) +.RE +.PP \fB\-\-image\fR .RS 4 \fBbootctl\fR(1), @@ -11246,12 +11681,15 @@ Command\-line options accepted by programs in the systemd suite\&. \fBcoredumpctl\fR(1), \fBhomectl\fR(1), \fBhostnamectl\fR(1), +\fBimportctl\fR(1), \fBkernel-install\fR(8), +\fBloginctl\fR(1), \fBnetworkctl\fR(1), \fBresolvectl\fR(1), \fBsystemd-analyze\fR(1), \fBsystemd-creds\fR(1), \fBsystemd-dissect\fR(1), +\fBsystemd-id128\fR(1), \fBsystemd-measure\fR(1), \fBsystemd-pcrlock\fR(8), \fBsystemd-repart\fR(8), @@ -11263,6 +11701,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBvarlinkctl\fR(1) .RE .PP +\fB\-\-keep\-download\fR +.RS 4 +\fBimportctl\fR(1) +.RE +.PP \fB\-\-keep\-unit\fR .RS 4 \fBsystemd-nspawn\fR(1) @@ -11408,6 +11851,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-nspawn\fR(1) .RE .PP +\fB\-\-load\-credentials\fR +.RS 4 +\fBudevadm\fR(8) +.RE +.PP \fB\-\-locale\fR .RS 4 \fBsystemd-firstboot\fR(1) @@ -11455,6 +11903,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd\fR(1) .RE .PP +\fB\-\-login\-background\fR +.RS 4 +\fBhomectl\fR(1) +.RE +.PP \fB\-\-loop\-ref\fR .RS 4 \fBsystemd-dissect\fR(1) @@ -11535,11 +11988,13 @@ Command\-line options accepted by programs in the systemd suite\&. \fBbusctl\fR(1), \fBhomectl\fR(1), \fBhostnamectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), \fBmachinectl\fR(1), \fBportablectl\fR(1), +\fBrun0\fR(1), \fBsystemctl\fR(1), \fBsystemd-analyze\fR(1), \fBsystemd-cgls\fR(1), @@ -11558,6 +12013,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-pcrphase.service\fR(8) .RE .PP +\fB\-\-make\-archive\fR +.RS 4 +\fBsystemd-dissect\fR(1) +.RE +.PP \fB\-\-make\-ddi\fR .RS 4 \fBsystemd-repart\fR(8) @@ -11626,6 +12086,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemctl\fR(1) .RE .PP +\fB\-\-microcode\fR +.RS 4 +\fBukify\fR(1) +.RE +.PP \fB\-\-mkdir\fR .RS 4 \fBmachinectl\fR(1), @@ -11673,6 +12138,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBuserdbctl\fR(1) .RE .PP +\fB\-\-mutable\fR +.RS 4 +\fBsystemd-sysext\fR(8) +.RE +.PP \fB\-\-name\fR .RS 4 \fBsystemd-creds\fR(1), @@ -11687,6 +12157,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fB\-\-namespace\fR .RS 4 \fBjournalctl\fR(1), +\fBsystemd-cat\fR(1), \fBsystemd-journal-upload.service\fR(8) .RE .PP @@ -11743,6 +12214,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fB\-\-nice\fR .RS 4 \fBhomectl\fR(1), +\fBrun0\fR(1), \fBsystemd-run\fR(1) .RE .PP @@ -11750,10 +12222,12 @@ Command\-line options accepted by programs in the systemd suite\&. .RS 4 \fBhomectl\fR(1), \fBhostnamectl\fR(1), +\fBimportctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), \fBmachinectl\fR(1), \fBportablectl\fR(1), +\fBrun0\fR(1), \fBsystemctl\fR(1), \fBsystemd-mount\fR(1), \fBsystemd-run\fR(1), @@ -11789,6 +12263,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBbusctl\fR(1), \fBcoredumpctl\fR(1), \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBkernel-install\fR(8), \fBloginctl\fR(1), \fBmachinectl\fR(1), @@ -11797,6 +12272,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-analyze\fR(1), \fBsystemd-creds\fR(1), \fBsystemd-dissect\fR(1), +\fBsystemd-id128\fR(1), \fBsystemd-inhibit\fR(1), \fBsystemd-mount\fR(1), \fBsystemd-repart\fR(8), @@ -11826,6 +12302,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBbusctl\fR(1), \fBcoredumpctl\fR(1), \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBkernel-install\fR(8), \fBlocalectl\fR(1), @@ -11842,6 +12319,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-creds\fR(1), \fBsystemd-delta\fR(1), \fBsystemd-dissect\fR(1), +\fBsystemd-id128\fR(1), \fBsystemd-inhibit\fR(1), \fBsystemd-measure\fR(1), \fBsystemd-mount\fR(1), @@ -11977,6 +12455,7 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-\-offline\fR .RS 4 +\fBhomectl\fR(1), \fBsystemd-analyze\fR(1), \fBsystemd-repart\fR(8) .RE @@ -12267,6 +12746,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fB\-\-print\fR .RS 4 \fBsystemd-machine-id-setup\fR(1), +\fBsystemd-vpick\fR(1), \fBudevadm\fR(8) .RE .PP @@ -12302,6 +12782,12 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-repart\fR(8) .RE .PP +\fB\-\-private\-key\-source\fR +.RS 4 +\fBsystemd-measure\fR(1), +\fBsystemd-repart\fR(8) +.RE +.PP \fB\-\-private\-network\fR .RS 4 \fBsystemd-nspawn\fR(1) @@ -12363,6 +12849,7 @@ Command\-line options accepted by programs in the systemd suite\&. .RS 4 \fBloginctl\fR(1), \fBmachinectl\fR(1), +\fBrun0\fR(1), \fBsystemctl\fR(1), \fBsystemd-mount\fR(1), \fBsystemd-nspawn\fR(1), @@ -12391,6 +12878,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-measure\fR(1) .RE .PP +\fB\-\-purge\fR +.RS 4 +\fBsystemd-tmpfiles\fR(8) +.RE +.PP \fB\-\-query\fR .RS 4 \fBsystemd-tty-ask-password-agent\fR(1), @@ -12402,6 +12894,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBbootctl\fR(1), \fBbusctl\fR(1), \fBcoredumpctl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBmachinectl\fR(1), \fBportablectl\fR(1), @@ -12439,6 +12932,7 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-\-read\-only\fR .RS 4 +\fBimportctl\fR(1), \fBmachinectl\fR(1), \fBsystemctl\fR(1), \fBsystemd-dissect\fR(1), @@ -12504,6 +12998,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-nspawn\fR(1) .RE .PP +\fB\-\-relax\-single\-label\fR +.RS 4 +\fBresolvectl\fR(1) +.RE +.PP \fB\-\-relinquish\-var\fR .RS 4 \fBjournalctl\fR(1) @@ -12555,6 +13054,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-nspawn\fR(1) .RE .PP +\fB\-\-resolve\fR +.RS 4 +\fBsystemd-vpick\fR(1) +.RE +.PP \fB\-\-resolve\-names\fR .RS 4 \fBsystemd-udevd.service\fR(8), @@ -12635,8 +13139,14 @@ Command\-line options accepted by programs in the systemd suite\&. \fBjournalctl\fR(1) .RE .PP +\fB\-\-runner\fR +.RS 4 +\fBmachinectl\fR(1) +.RE +.PP \fB\-\-runtime\fR .RS 4 +\fBnetworkctl\fR(1), \fBportablectl\fR(1), \fBsystemctl\fR(1) .RE @@ -12762,6 +13272,16 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd\fR(1) .RE .PP +\fB\-\-session\-launcher\fR +.RS 4 +\fBhomectl\fR(1) +.RE +.PP +\fB\-\-session\-type\fR +.RS 4 +\fBhomectl\fR(1) +.RE +.PP \fB\-\-set\-credential\fR .RS 4 \fBsystemd-nspawn\fR(1) @@ -12771,6 +13291,7 @@ Command\-line options accepted by programs in the systemd suite\&. .RS 4 \fBhomectl\fR(1), \fBmachinectl\fR(1), +\fBrun0\fR(1), \fBsystemd-nspawn\fR(1), \fBsystemd-run\fR(1), \fBsystemd-socket-activate\fR(1) @@ -12873,12 +13394,14 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-\-slice\fR .RS 4 +\fBrun0\fR(1), \fBsystemd-nspawn\fR(1), \fBsystemd-run\fR(1) .RE .PP \fB\-\-slice\-inherit\fR .RS 4 +\fBrun0\fR(1), \fBsystemd-run\fR(1) .RE .PP @@ -12948,6 +13471,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-cat\fR(1) .RE .PP +\fB\-\-stdin\fR +.RS 4 +\fBsystemctl\fR(1) +.RE +.PP \fB\-\-stop\-delay\fR .RS 4 \fBhomectl\fR(1) @@ -12987,7 +13515,8 @@ Command\-line options accepted by programs in the systemd suite\&. \fB\-\-suffix\fR .RS 4 \fBsystemd-escape\fR(1), -\fBsystemd-path\fR(1) +\fBsystemd-path\fR(1), +\fBsystemd-vpick\fR(1) .RE .PP \fB\-\-summary\fR @@ -13220,15 +13749,26 @@ Command\-line options accepted by programs in the systemd suite\&. \fBresolvectl\fR(1) .RE .PP +\fB\-\-tty\fR +.RS 4 +\fBsystemd-bsod.service\fR(8) +.RE +.PP \fB\-\-type\fR .RS 4 \fBresolvectl\fR(1), \fBsystemctl\fR(1), \fBsystemd-delta\fR(1), \fBsystemd-mount\fR(1), +\fBsystemd-vpick\fR(1), \fBudevadm\fR(8) .RE .PP +\fB\-\-ucode\fR +.RS 4 +\fBsystemd-measure\fR(1) +.RE +.PP \fB\-\-udev\fR .RS 4 \fBudevadm\fR(8) @@ -13238,6 +13778,7 @@ Command\-line options accepted by programs in the systemd suite\&. .RS 4 \fBhomectl\fR(1), \fBmachinectl\fR(1), +\fBsystemd-creds\fR(1), \fBsystemd-notify\fR(1), \fBsystemd-run\fR(1) .RE @@ -13272,6 +13813,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fB\-\-unit\fR .RS 4 \fBjournalctl\fR(1), +\fBrun0\fR(1), \fBsystemd\fR(1), \fBsystemd-analyze\fR(1), \fBsystemd-cgls\fR(1), @@ -13288,6 +13830,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-cryptenroll\fR(1) .RE .PP +\fB\-\-unlock\-tpm2\-device\fR +.RS 4 +\fBsystemd-cryptenroll\fR(1) +.RE +.PP \fB\-\-unregister\fR .RS 4 \fBsystemd-binfmt.service\fR(8) @@ -13314,9 +13861,11 @@ Command\-line options accepted by programs in the systemd suite\&. .RS 4 \fBbusctl\fR(1), \fBjournalctl\fR(1), +\fBrun0\fR(1), \fBsystemctl\fR(1), \fBsystemd\fR(1), \fBsystemd-analyze\fR(1), +\fBsystemd-creds\fR(1), \fBsystemd-journal-gatewayd.service\fR(8), \fBsystemd-journal-upload.service\fR(8), \fBsystemd-mount\fR(1), @@ -13390,8 +13939,8 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-\-verify\fR .RS 4 +\fBimportctl\fR(1), \fBjournalctl\fR(1), -\fBmachinectl\fR(1), \fBsystemd-sysupdate\fR(8) .RE .PP @@ -13413,6 +13962,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBcoredumpctl\fR(1), \fBhomectl\fR(1), \fBhostnamectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBkernel-install\fR(8), \fBlocalectl\fR(1), @@ -13422,6 +13972,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBoomctl\fR(1), \fBportablectl\fR(1), \fBresolvectl\fR(1), +\fBrun0\fR(1), \fBsystemctl\fR(1), \fBsystemd\fR(1), \fBsystemd-ac-power\fR(1), @@ -13440,7 +13991,6 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-dissect\fR(1), \fBsystemd-escape\fR(1), \fBsystemd-firstboot\fR(1), -\fBsystemd-fsckd.service\fR(8), \fBsystemd-id128\fR(1), \fBsystemd-inhibit\fR(1), \fBsystemd-journal-gatewayd.service\fR(8), @@ -13452,6 +14002,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-networkd-wait-online.service\fR(8), \fBsystemd-notify\fR(1), \fBsystemd-nspawn\fR(1), +\fBsystemd-oomd.service\fR(8), \fBsystemd-path\fR(1), \fBsystemd-pcrlock\fR(8), \fBsystemd-pcrphase.service\fR(8), @@ -13469,6 +14020,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-tmpfiles\fR(8), \fBsystemd-tty-ask-password-agent\fR(1), \fBsystemd-udevd.service\fR(8), +\fBsystemd-vpick\fR(1), \fBtimedatectl\fR(1), \fBudevadm\fR(8), \fBukify\fR(1), @@ -13625,12 +14177,22 @@ Command\-line options accepted by programs in the systemd suite\&. .RS 4 \fBcoredumpctl\fR(1), \fBsystemd-mount\fR(1), +\fBsystemd-vpick\fR(1), \fBudevadm\fR(8) .RE .PP +\fB\-B\fR +.RS 4 +\fBsystemd-vpick\fR(1) +.RE +.PP \fB\-C\fR .RS 4 +\fBbusctl\fR(1), +\fBimportctl\fR(1), +\fBsystemctl\fR(1), \fBsystemd-repart\fR(8), +\fBsystemd-run\fR(1), \fBsystemd-sysupdate\fR(8) .RE .PP @@ -13638,6 +14200,7 @@ Command\-line options accepted by programs in the systemd suite\&. .RS 4 \fBcoredumpctl\fR(1), \fBjournalctl\fR(1), +\fBrun0\fR(1), \fBsystemd-journal-gatewayd.service\fR(8), \fBsystemd-journal-upload.service\fR(8), \fBsystemd-nspawn\fR(1), @@ -13678,6 +14241,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBbusctl\fR(1), \fBhomectl\fR(1), \fBhostnamectl\fR(1), +\fBimportctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), \fBmachinectl\fR(1), @@ -13706,11 +14270,13 @@ Command\-line options accepted by programs in the systemd suite\&. \fBbusctl\fR(1), \fBhomectl\fR(1), \fBhostnamectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), \fBmachinectl\fR(1), \fBportablectl\fR(1), +\fBrun0\fR(1), \fBsystemctl\fR(1), \fBsystemd-analyze\fR(1), \fBsystemd-cgls\fR(1), @@ -13725,6 +14291,7 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-N\fR .RS 4 +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBsystemd-udevd.service\fR(8), \fBudevadm\fR(8), @@ -13734,6 +14301,8 @@ Command\-line options accepted by programs in the systemd suite\&. \fB\-P\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), +\fBmachinectl\fR(1), \fBshutdown\fR(8), \fBsystemctl\fR(1), \fBsystemd-cgtop\fR(1), @@ -13741,6 +14310,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-nspawn\fR(1), \fBsystemd-repart\fR(8), \fBsystemd-run\fR(1), +\fBtimedatectl\fR(1), \fBudevadm\fR(8) .RE .PP @@ -13754,15 +14324,18 @@ Command\-line options accepted by programs in the systemd suite\&. \fB\-S\fR .RS 4 \fBcoredumpctl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBsystemd-nspawn\fR(1), \fBsystemd-repart\fR(8), \fBsystemd-run\fR(1), +\fBsystemd-vpick\fR(1), \fBudevadm\fR(8) .RE .PP \fB\-T\fR .RS 4 +\fBjournalctl\fR(1), \fBsystemctl\fR(1), \fBsystemd-creds\fR(1), \fBsystemd-mount\fR(1) @@ -13778,7 +14351,9 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-V\fR .RS 4 -\fBresolvectl\fR(1) +\fBmachinectl\fR(1), +\fBresolvectl\fR(1), +\fBsystemd-vpick\fR(1) .RE .PP \fB\-Z\fR @@ -13805,6 +14380,7 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-b\fR .RS 4 +\fBhomectl\fR(1), \fBjournalctl\fR(1), \fBsystemd-cgtop\fR(1), \fBsystemd-nspawn\fR(1), @@ -13826,7 +14402,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBudevadm\fR(8) .RE .PP -\fB\-d\fR +\fB\-d\fR\fB\fIPATH\fR\fR .RS 4 \fBhomectl\fR(1), \fBpoweroff\fR(8), @@ -13857,6 +14433,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fB\-g\fR .RS 4 \fBjournalctl\fR(1), +\fBrun0\fR(1), \fBudevadm\fR(8) .RE .PP @@ -13867,6 +14444,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBcoredumpctl\fR(1), \fBhomectl\fR(1), \fBhostnamectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBkernel-install\fR(8), \fBlocalectl\fR(1), @@ -13876,6 +14454,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBoomctl\fR(1), \fBportablectl\fR(1), \fBresolvectl\fR(1), +\fBrun0\fR(1), \fBshutdown\fR(8), \fBsystemctl\fR(1), \fBsystemd\fR(1), @@ -13896,7 +14475,6 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-dissect\fR(1), \fBsystemd-escape\fR(1), \fBsystemd-firstboot\fR(1), -\fBsystemd-fsckd.service\fR(8), \fBsystemd-hwdb\fR(8), \fBsystemd-id128\fR(1), \fBsystemd-inhibit\fR(1), @@ -13909,6 +14487,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-networkd-wait-online.service\fR(8), \fBsystemd-notify\fR(1), \fBsystemd-nspawn\fR(1), +\fBsystemd-oomd.service\fR(8), \fBsystemd-path\fR(1), \fBsystemd-pcrlock\fR(8), \fBsystemd-pcrphase.service\fR(8), @@ -13926,6 +14505,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-tmpfiles\fR(8), \fBsystemd-tty-ask-password-agent\fR(1), \fBsystemd-udevd.service\fR(8), +\fBsystemd-vpick\fR(1), \fBtimedatectl\fR(1), \fBudevadm\fR(8), \fBukify\fR(1), @@ -13935,6 +14515,7 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-i\fR .RS 4 +\fBjournalctl\fR(1), \fBresolvectl\fR(1), \fBsystemctl\fR(1), \fBsystemd-cgtop\fR(1), @@ -13946,7 +14527,11 @@ Command\-line options accepted by programs in the systemd suite\&. .RS 4 \fBbusctl\fR(1), \fBhomectl\fR(1), +\fBhostnamectl\fR(1), +\fBimportctl\fR(1), +\fBloginctl\fR(1), \fBresolvectl\fR(1), +\fBsystemd-id128\fR(1), \fBsystemd-nspawn\fR(1), \fBvarlinkctl\fR(1) .RE @@ -13978,6 +14563,7 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fB\-m\fR .RS 4 +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBresolvectl\fR(1), \fBsystemd-cgtop\fR(1), @@ -14035,6 +14621,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-nspawn\fR(1), \fBsystemd-run\fR(1), \fBsystemd-stdio-bridge\fR(1), +\fBsystemd-vpick\fR(1), \fBtimedatectl\fR(1), \fBudevadm\fR(8) .RE @@ -14044,6 +14631,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBbootctl\fR(1), \fBbusctl\fR(1), \fBcoredumpctl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBmachinectl\fR(1), \fBportablectl\fR(1), @@ -14097,6 +14685,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd-mount\fR(1), \fBsystemd-run\fR(1), \fBsystemd-udevd.service\fR(8), +\fBsystemd-vpick\fR(1), \fBudevadm\fR(8) .RE .PP @@ -14104,6 +14693,7 @@ Command\-line options accepted by programs in the systemd suite\&. .RS 4 \fBjournalctl\fR(1), \fBresolvectl\fR(1), +\fBrun0\fR(1), \fBsystemd-cgls\fR(1), \fBsystemd-dissect\fR(1), \fBsystemd-escape\fR(1), @@ -14146,6 +14736,16 @@ Command\-line options accepted by programs in the systemd suite\&. \fBudevadm\fR(8) .RE .PP +\fBBonding\fR +.RS 4 +\fBsystemd.network\fR(5) +.RE +.PP +\fBCAN\fR +.RS 4 +\fBsystemd.network\fR(5) +.RE +.PP \fBIPv4\fR .RS 4 \fBsystemd.link\fR(5), @@ -14161,6 +14761,7 @@ Command\-line options accepted by programs in the systemd suite\&. \fBK\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -14176,9 +14777,20 @@ Command\-line options accepted by programs in the systemd suite\&. \fBuserdbctl\fR(1) .RE .PP +\fBMaster\fR +.RS 4 +\fBsystemd.network\fR(5) +.RE +.PP +\fBOther\fR +.RS 4 +\fBsystemd.network\fR(5) +.RE +.PP \fBX\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -14222,6 +14834,7 @@ Command\-line options accepted by programs in the systemd suite\&. .PP \fBauto\fR .RS 4 +\fBsystemd-sysext\fR(8), \fBsystemd.resource-control\fR(5) .RE .PP @@ -14333,6 +14946,16 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd.network\fR(5) .RE .PP +\fBephemeral\fR +.RS 4 +\fBsystemd-sysext\fR(8) +.RE +.PP +\fBephemeral\-import\fR +.RS 4 +\fBsystemd-sysext\fR(8) +.RE +.PP \fBeui64\fR .RS 4 \fBsystemd.network\fR(5) @@ -14395,6 +15018,11 @@ Command\-line options accepted by programs in the systemd suite\&. \fBloader.conf\fR(5) .RE .PP +\fBimport\fR +.RS 4 +\fBsystemd-sysext\fR(8) +.RE +.PP \fBindeterminate\fR .RS 4 \fBsystemd-bless-boot.service\fR(8) @@ -14523,12 +15151,22 @@ Command\-line options accepted by programs in the systemd suite\&. \fBsystemd.link\fR(5) .RE .PP +\fBno\fR +.RS 4 +\fBsystemd-sysext\fR(8) +.RE +.PP \fBnone\fR .RS 4 \fBsystemd.link\fR(5), \fBsystemd.network\fR(5) .RE .PP +\fBnspawn\fR +.RS 4 +\fBmachinectl\fR(1) +.RE +.PP \fBoff\fR .RS 4 \fBloader.conf\fR(5) @@ -14787,11 +15425,21 @@ Command\-line options accepted by programs in the systemd suite\&. \fBjournalctl\fR(1) .RE .PP +\fBvmspawn\fR +.RS 4 +\fBmachinectl\fR(1) +.RE +.PP \fBwith\-unit\fR .RS 4 \fBjournalctl\fR(1) .RE .PP +\fByes\fR +.RS 4 +\fBsystemd-sysext\fR(8) +.RE +.PP \fBμs\fR .RS 4 \fBsystemctl\fR(1) @@ -15436,6 +16084,7 @@ Various constants used and/or defined by systemd\&. \fBsd_journal_add_match\fR(3), \fBsystemctl\fR(1), \fBsystemd-analyze\fR(1), +\fBsystemd.net-naming-scheme\fR(7), \fBsystemd.netdev\fR(5), \fBsystemd.resource-control\fR(5), \fBtmpfiles.d\fR(5), @@ -15496,6 +16145,7 @@ Various constants used and/or defined by systemd\&. \fBsystemd-analyze\fR(1), \fBsystemd-oomd.service\fR(8), \fBsystemd-tmpfiles\fR(8), +\fBsystemd.net-naming-scheme\fR(7), \fBsystemd.network\fR(5), \fBsystemd.scope\fR(5), \fBsystemd.service\fR(5), @@ -15554,13 +16204,9 @@ Various constants used and/or defined by systemd\&. \fBresolvectl\fR(1) .RE .PP -\fB4a67b082\-0a4c\-41cf\-b6c7\-440b29bb8c4\fR -.RS 4 -\fBsystemd-bless-boot.service\fR(8) -.RE -.PP \fB4a67b082\-0a4c\-41cf\-b6c7\-440b29bb8c4f\fR .RS 4 +\fBsystemd-bless-boot.service\fR(8), \fBsystemd-gpt-auto-generator\fR(8) .RE .PP @@ -15626,6 +16272,7 @@ Various constants used and/or defined by systemd\&. \fBorg.freedesktop.machine1\fR(5), \fBorg.freedesktop.resolve1\fR(5), \fBsd_is_fifo\fR(3), +\fBsystemd-ssh-generator\fR(8), \fBsystemd.exec\fR(5), \fBsystemd.resource-control\fR(5), \fBsystemd.socket\fR(5) @@ -15633,9 +16280,11 @@ Various constants used and/or defined by systemd\&. .PP \fBAF_INET6\fR .RS 4 +\fBjournald.conf\fR(5), \fBorg.freedesktop.machine1\fR(5), \fBorg.freedesktop.resolve1\fR(5), \fBsd_is_fifo\fR(3), +\fBsystemd-ssh-generator\fR(8), \fBsystemd.exec\fR(5), \fBsystemd.resource-control\fR(5), \fBsystemd.socket\fR(5) @@ -15670,6 +16319,8 @@ Various constants used and/or defined by systemd\&. \fBsystemd-journal-gatewayd.service\fR(8), \fBsystemd-journal-remote.service\fR(8), \fBsystemd-repart\fR(8), +\fBsystemd-ssh-generator\fR(8), +\fBsystemd-ssh-proxy\fR(1), \fBsystemd.exec\fR(5), \fBsystemd.link\fR(5), \fBsystemd.netdev\fR(5), @@ -15686,9 +16337,14 @@ Various constants used and/or defined by systemd\&. .PP \fBAF_VSOCK\fR .RS 4 +\fBjournald.conf\fR(5), +\fBorg.freedesktop.hostname1\fR(5), \fBsd_notify\fR(3), \fBsystemd\fR(1), +\fBsystemd-ssh-generator\fR(8), +\fBsystemd-ssh-proxy\fR(1), \fBsystemd.socket\fR(5), +\fBsystemd.special\fR(7), \fBsystemd.system-credentials\fR(7) .RE .PP @@ -16742,6 +17398,7 @@ Various constants used and/or defined by systemd\&. \fBsd_journal_open\fR(3), \fBsd_journal_print\fR(3), \fBsd_journal_query_unique\fR(3), +\fBsd_journal_stream_fd\fR(3), \fBsd_listen_fds\fR(3), \fBsd_login_monitor_new\fR(3), \fBsd_machine_get_class\fR(3), @@ -16918,6 +17575,21 @@ Various constants used and/or defined by systemd\&. \fBsystemd.exec\fR(5) .RE .PP +\fBSCM_CREDENTIALS\fR +.RS 4 +\fBsystemd-socket-proxyd\fR(8) +.RE +.PP +\fBSCM_RIGHTS\fR +.RS 4 +\fBsystemd-socket-proxyd\fR(8) +.RE +.PP +\fBSCM_SECURITY\fR +.RS 4 +\fBsystemd-socket-proxyd\fR(8) +.RE +.PP \fBSD_BUS_ARGS(\fR\fB\fI\&.\&.\&.\fR\fR\fB)\fR .RS 4 \fBsd_bus_add_object\fR(3) @@ -17023,6 +17695,11 @@ Various constants used and/or defined by systemd\&. \fBsd_bus_creds_new_from_pid\fR(3) .RE .PP +\fBSD_BUS_CREDS_PIDFD\fR +.RS 4 +\fBsd_bus_creds_new_from_pid\fR(3) +.RE +.PP \fBSD_BUS_CREDS_PPID\fR .RS 4 \fBsd_bus_creds_new_from_pid\fR(3) @@ -18033,6 +18710,11 @@ Various constants used and/or defined by systemd\&. \fBsystemd-gpt-auto-generator\fR(8) .RE .PP +\fBSD_HOMED_UPDATE_OFFLINE\fR +.RS 4 +\fBorg.freedesktop.home1\fR(5) +.RE +.PP \fBSD_ID128_ALLF\fR .RS 4 \fBsd-id128\fR(3), @@ -18547,6 +19229,7 @@ Various constants used and/or defined by systemd\&. \fBdaemon\fR(7), \fBorg.freedesktop.hostname1\fR(5), \fBsystemd\fR(1), +\fBsystemd-resolved.service\fR(8), \fBsystemd.kill\fR(5), \fBsystemd.service\fR(5) .RE @@ -18801,6 +19484,7 @@ Various constants used and/or defined by systemd\&. .RS 4 \fBsd_is_fifo\fR(3), \fBsystemd-socket-activate\fR(1), +\fBsystemd-ssh-proxy\fR(1), \fBsystemd.socket\fR(5) .RE .PP @@ -18834,6 +19518,26 @@ Various constants used and/or defined by systemd\&. \fBsystemd.socket\fR(5) .RE .PP +\fBSO_PEERCRED\fR +.RS 4 +\fBsystemd-socket-proxyd\fR(8) +.RE +.PP +\fBSO_PEERGROUPS\fR +.RS 4 +\fBsystemd-socket-proxyd\fR(8) +.RE +.PP +\fBSO_PEERPIDFD\fR +.RS 4 +\fBsystemd-socket-proxyd\fR(8) +.RE +.PP +\fBSO_PEERSEC\fR +.RS 4 +\fBsystemd-socket-proxyd\fR(8) +.RE +.PP \fBSO_PRIORITY\fR .RS 4 \fBsystemd.netdev\fR(5), @@ -18871,6 +19575,25 @@ Various constants used and/or defined by systemd\&. \fBudev_device_new_from_syspath\fR(3) .RE .PP +\fBSYSTEMD_LOG_LEVEL=debug,console:info\fR +.RS 4 +\fBhomectl\fR(1), +\fBimportctl\fR(1), +\fBjournalctl\fR(1), +\fBlocalectl\fR(1), +\fBloginctl\fR(1), +\fBmachinectl\fR(1), +\fBportablectl\fR(1), +\fBsystemctl\fR(1), +\fBsystemd\fR(1), +\fBsystemd-analyze\fR(1), +\fBsystemd-inhibit\fR(1), +\fBsystemd-nspawn\fR(1), +\fBsystemd-tmpfiles\fR(8), +\fBtimedatectl\fR(1), +\fBuserdbctl\fR(1) +.RE +.PP \fBS_IFREG\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) @@ -18921,19 +19644,35 @@ Various constants used and/or defined by systemd\&. \fBsystemd.exec\fR(5) .RE .PP +\fBUINT32_MAX\fR +.RS 4 +\fBorg.freedesktop.hostname1\fR(5) +.RE +.PP \fBUINT64_MAX\fR .RS 4 \fBorg.freedesktop.home1\fR(5), +\fBorg.freedesktop.hostname1\fR(5), \fBsd_bus_get_fd\fR(3), \fBsd_bus_wait\fR(3), \fBsd_event_add_time\fR(3) .RE .PP +\fBUNIT64_MAX\fR +.RS 4 +\fBorg.freedesktop.hostname1\fR(5) +.RE +.PP \fBUSER_PROCESS\fR .RS 4 \fBsystemd.exec\fR(5) .RE .PP +\fBVMADDR_CID_ANY\fR +.RS 4 +\fBorg.freedesktop.machine1\fR(5) +.RE +.PP \fBWCONTINUED\fR .RS 4 \fBsd_event_add_child\fR(3) @@ -18993,6 +19732,7 @@ Various constants used and/or defined by systemd\&. \fBalert\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -19064,6 +19804,7 @@ Various constants used and/or defined by systemd\&. \fBsystemd-system.conf\fR(5), \fBsystemd.dnssd\fR(5), \fBsystemd.exec\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -19078,6 +19819,7 @@ Various constants used and/or defined by systemd\&. \fBauto\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -19105,6 +19847,16 @@ Various constants used and/or defined by systemd\&. \fBsystemd-gpt-auto-generator\fR(8) .RE .PP +\fBbackground\fR +.RS 4 +\fBpam_systemd\fR(8) +.RE +.PP +\fBbackground\-light\fR +.RS 4 +\fBpam_systemd\fR(8) +.RE +.PP \fBbad\-setting\fR .RS 4 \fBsystemctl\fR(1) @@ -19185,6 +19937,7 @@ Various constants used and/or defined by systemd\&. \fBconsole\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -19203,6 +19956,7 @@ Various constants used and/or defined by systemd\&. \fBconsole\-prefixed\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -19237,6 +19991,7 @@ Various constants used and/or defined by systemd\&. \fBcrit\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -19266,6 +20021,7 @@ Various constants used and/or defined by systemd\&. \fBdebug\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -19314,6 +20070,7 @@ Various constants used and/or defined by systemd\&. \fBemerg\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -19342,6 +20099,7 @@ Various constants used and/or defined by systemd\&. \fBerr\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -19407,6 +20165,11 @@ Various constants used and/or defined by systemd\&. \fBsystemd.resource-control\fR(5) .RE .PP +\fBgreeter\fR +.RS 4 +\fBpam_systemd\fR(8) +.RE +.PP \fBh\fR .RS 4 \fBtmpfiles.d\fR(5) @@ -19458,6 +20221,7 @@ Various constants used and/or defined by systemd\&. \fBinfo\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -19504,6 +20268,11 @@ Various constants used and/or defined by systemd\&. \fBuserdbctl\fR(1) .RE .PP +\fBio\&.systemd\&.MountFileSystem\fR +.RS 4 +\fBsystemd-mountfsd.service\fR(8) +.RE +.PP \fBio\&.systemd\&.Multiplexer\fR .RS 4 \fBsystemd-userdbd.service\fR(8), @@ -19516,6 +20285,11 @@ Various constants used and/or defined by systemd\&. \fBuserdbctl\fR(1) .RE .PP +\fBio\&.systemd\&.NamespaceResource\fR +.RS 4 +\fBsystemd-nsresourced.service\fR(8) +.RE +.PP \fBipc\fR .RS 4 \fBsystemd.exec\fR(5) @@ -19534,6 +20308,7 @@ Various constants used and/or defined by systemd\&. \fBjournal\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -19552,6 +20327,7 @@ Various constants used and/or defined by systemd\&. \fBjournal\-or\-kmsg\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -19591,6 +20367,7 @@ Various constants used and/or defined by systemd\&. \fBkmsg\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -19797,6 +20574,11 @@ Various constants used and/or defined by systemd\&. \fBsystemd.resource-control\fR(5) .RE .PP +\fBlock\-screen\fR +.RS 4 +\fBpam_systemd\fR(8) +.RE +.PP \fBlogs\fR .RS 4 \fBsystemctl\fR(1) @@ -19818,6 +20600,16 @@ Various constants used and/or defined by systemd\&. \fBsystemd.exec\fR(5) .RE .PP +\fBmanager\fR +.RS 4 +\fBpam_systemd\fR(8) +.RE +.PP +\fBmanager\-early\fR +.RS 4 +\fBpam_systemd\fR(8) +.RE +.PP \fBmasked\fR .RS 4 \fBsystemctl\fR(1) @@ -19937,6 +20729,7 @@ Various constants used and/or defined by systemd\&. \fBnotice\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -19955,6 +20748,7 @@ Various constants used and/or defined by systemd\&. \fBnull\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -20139,6 +20933,11 @@ Various constants used and/or defined by systemd\&. \fBudevadm\fR(8) .RE .PP +\fBphys_port_name\fR +.RS 4 +\fBsystemd.net-naming-scheme\fR(7) +.RE +.PP \fBpid\fR .RS 4 \fBsystemd.exec\fR(5) @@ -20468,7 +21267,21 @@ Various constants used and/or defined by systemd\&. .PP \fBsyslog\fR .RS 4 -\fBsystemctl\fR(1) +\fBhomectl\fR(1), +\fBimportctl\fR(1), +\fBjournalctl\fR(1), +\fBlocalectl\fR(1), +\fBloginctl\fR(1), +\fBmachinectl\fR(1), +\fBportablectl\fR(1), +\fBsystemctl\fR(1), +\fBsystemd\fR(1), +\fBsystemd-analyze\fR(1), +\fBsystemd-inhibit\fR(1), +\fBsystemd-nspawn\fR(1), +\fBsystemd-tmpfiles\fR(8), +\fBtimedatectl\fR(1), +\fBuserdbctl\fR(1) .RE .PP \fBtar\fR @@ -20552,9 +21365,20 @@ Various constants used and/or defined by systemd\&. .PP \fBuser\fR .RS 4 +\fBpam_systemd\fR(8), \fBsystemd.exec\fR(5) .RE .PP +\fBuser\-early\fR +.RS 4 +\fBpam_systemd\fR(8) +.RE +.PP +\fBuser\-incomplete\fR +.RS 4 +\fBpam_systemd\fR(8) +.RE +.PP \fBusr\fR .RS 4 \fBrepart.d\fR(5), @@ -20701,6 +21525,7 @@ Various constants used and/or defined by systemd\&. \fBwarning\fR .RS 4 \fBhomectl\fR(1), +\fBimportctl\fR(1), \fBjournalctl\fR(1), \fBlocalectl\fR(1), \fBloginctl\fR(1), @@ -20742,6 +21567,7 @@ Various constants used and/or defined by systemd\&. \fBsystemd-system.conf\fR(5), \fBsystemd.dnssd\fR(5), \fBsystemd.exec\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -20754,6 +21580,7 @@ Various constants used and/or defined by systemd\&. \fBsystemd-system.conf\fR(5), \fBsystemd.dnssd\fR(5), \fBsystemd.exec\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -20850,6 +21677,26 @@ Other configuration elements which don\*(Aqt fit in any of the above groups\&. \fBsystemd-journal-remote.service\fR(8) .RE .PP +\fI$SUDO_GID\fR +.RS 4 +\fBrun0\fR(1) +.RE +.PP +\fI$SUDO_UID\fR +.RS 4 +\fBrun0\fR(1) +.RE +.PP +\fI$SUDO_USER\fR +.RS 4 +\fBrun0\fR(1) +.RE +.PP +\fI$TERM\fR +.RS 4 +\fBrun0\fR(1) +.RE +.PP \fBA\fR .RS 4 \fBtmpfiles.d\fR(5) @@ -20895,6 +21742,11 @@ Other configuration elements which don\*(Aqt fit in any of the above groups\&. \fBtmpfiles.d\fR(5) .RE .PP +\fIDefaultSubvolume=\fR +.RS 4 +\fBrepart.d\fR(5) +.RE +.PP \fIDeviceTree=\fR .RS 4 \fBukify\fR(1) @@ -20905,6 +21757,11 @@ Other configuration elements which don\*(Aqt fit in any of the above groups\&. \fBrepart.d\fR(5) .RE .PP +\fIEncryptedVolume=\fR +.RS 4 +\fBrepart.d\fR(5) +.RE +.PP \fIExcludeFiles=\fR .RS 4 \fBrepart.d\fR(5) @@ -20945,6 +21802,16 @@ Other configuration elements which don\*(Aqt fit in any of the above groups\&. \fBsystemd.net-naming-scheme\fR(7) .RE .PP +\fIID_NET_NAME_ALLOW=\fR +.RS 4 +\fBsystemd.net-naming-scheme\fR(7) +.RE +.PP +\fIID_NET_NAME_ALLOW_\fR\fI\fIsysfsattr\fR\fR\fI=\fR\fI\fIBOOL\fR\fR +.RS 4 +\fBsystemd.net-naming-scheme\fR(7) +.RE +.PP \fIID_NET_NAME_MAC=\fR .RS 4 \fBsystemd.net-naming-scheme\fR(7) @@ -21010,6 +21877,11 @@ Other configuration elements which don\*(Aqt fit in any of the above groups\&. \fBsysupdate.d\fR(5) .RE .PP +\fIMicrocode=\fR +.RS 4 +\fBukify\fR(1) +.RE +.PP \fIMinVersion=\fR .RS 4 \fBsysupdate.d\fR(5) @@ -21025,6 +21897,11 @@ Other configuration elements which don\*(Aqt fit in any of the above groups\&. \fBsysupdate.d\fR(5) .RE .PP +\fIMountPoint=\fR +.RS 4 +\fBrepart.d\fR(5) +.RE +.PP \fINoAuto=\fR .RS 4 \fBrepart.d\fR(5) @@ -21347,6 +22224,11 @@ Other configuration elements which don\*(Aqt fit in any of the above groups\&. \fBtmpfiles.d\fR(5) .RE .PP +\fIio\&.systemd\&.boot\&.kernel\-cmdline\-extra\fR +.RS 4 +\fBsystemd-boot\fR(7) +.RE +.PP \fIio\&.systemd\&.stub\&.kernel\-cmdline\-extra\fR .RS 4 \fBsystemd-stub\fR(7) @@ -21403,6 +22285,16 @@ Other configuration elements which don\*(Aqt fit in any of the above groups\&. \fBsysusers.d\fR(5) .RE .PP +\fIudev\&.conf\&.*\fR +.RS 4 +\fBudevadm\fR(8) +.RE +.PP +\fIudev\&.rules\&.*\fR +.RS 4 +\fBudevadm\fR(8) +.RE +.PP \fIunchanged\fR .RS 4 \fBsystemd-delta\fR(1) @@ -21500,6 +22392,7 @@ Short strings which are substituted in configuration directives\&. \fBrepart.d\fR(5), \fBsystemd-system.conf\fR(5), \fBsystemd.dnssd\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -21511,6 +22404,7 @@ Short strings which are substituted in configuration directives\&. \fBrepart.d\fR(5), \fBsystemd-system.conf\fR(5), \fBsystemd.dnssd\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -21523,6 +22417,11 @@ Short strings which are substituted in configuration directives\&. \fBtmpfiles.d\fR(5) .RE .PP +"%D" +.RS 4 +\fBsystemd.unit\fR(5) +.RE +.PP "%E" .RS 4 \fBsystemd.unit\fR(5) @@ -21540,6 +22439,7 @@ Short strings which are substituted in configuration directives\&. \fBrepart.d\fR(5), \fBsystemd-system.conf\fR(5), \fBsystemd.dnssd\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -21567,6 +22467,7 @@ Short strings which are substituted in configuration directives\&. \fBrepart.d\fR(5), \fBsystemd-system.conf\fR(5), \fBsystemd.dnssd\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -21593,6 +22494,7 @@ Short strings which are substituted in configuration directives\&. .RS 4 \fBrepart.d\fR(5), \fBsystemd-system.conf\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -21611,6 +22513,7 @@ Short strings which are substituted in configuration directives\&. .RS 4 \fBrepart.d\fR(5), \fBsystemd-system.conf\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -21622,6 +22525,7 @@ Short strings which are substituted in configuration directives\&. \fBrepart.d\fR(5), \fBsystemd-system.conf\fR(5), \fBsystemd.dnssd\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -21638,6 +22542,7 @@ Short strings which are substituted in configuration directives\&. \fBrepart.d\fR(5), \fBsystemd-system.conf\fR(5), \fBsystemd.dnssd\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -21649,6 +22554,7 @@ Short strings which are substituted in configuration directives\&. \fBrepart.d\fR(5), \fBsystemd-system.conf\fR(5), \fBsystemd.dnssd\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -21693,6 +22599,7 @@ Short strings which are substituted in configuration directives\&. .RS 4 \fBrepart.d\fR(5), \fBsystemd-system.conf\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -21704,6 +22611,7 @@ Short strings which are substituted in configuration directives\&. \fBrepart.d\fR(5), \fBsystemd-system.conf\fR(5), \fBsystemd.dnssd\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -21721,6 +22629,7 @@ Short strings which are substituted in configuration directives\&. \fBrepart.d\fR(5), \fBsystemd-system.conf\fR(5), \fBsystemd.dnssd\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -21734,6 +22643,7 @@ Short strings which are substituted in configuration directives\&. .PP "%q" .RS 4 +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5) .RE .PP @@ -21762,6 +22672,7 @@ Short strings which are substituted in configuration directives\&. \fBrepart.d\fR(5), \fBsystemd-system.conf\fR(5), \fBsystemd.dnssd\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -21773,6 +22684,7 @@ Short strings which are substituted in configuration directives\&. \fBrepart.d\fR(5), \fBsystemd-system.conf\fR(5), \fBsystemd.dnssd\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -21862,6 +22774,16 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd.special\fR(7) .RE .PP +/\&.extra/confext/ +.RS 4 +\fBsystemd-stub\fR(7) +.RE +.PP +/\&.extra/confext/*\&.confext\&.raw +.RS 4 +\fBsystemd-stub\fR(7) +.RE +.PP /\&.extra/credentials/ .RS 4 \fBsystemd-stub\fR(7) @@ -21888,7 +22810,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-sysext\fR(8) .RE .PP -/\&.extra/sysext/*\&.raw +/\&.extra/sysext/*\&.sysext\&.raw .RS 4 \fBsystemd-stub\fR(7) .RE @@ -21954,6 +22876,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf /bin/sh .RS 4 \fBmachinectl\fR(1), +\fBrun0\fR(1), \fBsysusers.d\fR(5) .RE .PP @@ -22071,6 +22994,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf .RS 4 \fBcrypttab\fR(5), \fBintegritytab\fR(5), +\fBrepart.d\fR(5), \fBveritytab\fR(5) .RE .PP @@ -22136,6 +23060,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBkernel-install\fR(8), \fBlogind.conf\fR(5), \fBmodules-load.d\fR(5), +\fBnetworkctl\fR(1), \fBnetworkd.conf\fR(5), \fBoomd.conf\fR(5), \fBorg.freedesktop.systemd1\fR(5), @@ -22215,7 +23140,8 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-cryptenroll\fR(1), \fBsystemd-measure\fR(1), \fBsystemd-pcrphase.service\fR(8), -\fBsystemd.exec\fR(5) +\fBsystemd.exec\fR(5), +\fBsystemd.special\fR(7) .RE .PP /dev/tty7 @@ -22296,6 +23222,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-machine-id-commit.service\fR(8), \fBsystemd-machine-id-setup\fR(1), \fBsystemd-modules-load.service\fR(8), +\fBsystemd-mountfsd.service\fR(8), \fBsystemd-nspawn\fR(1), \fBsystemd-sleep.conf\fR(5), \fBsystemd-sysext\fR(8), @@ -22443,7 +23370,8 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBkernel-command-line\fR(7), \fBmachine-info\fR(5), \fBorg.freedesktop.hostname1\fR(5), -\fBsystemd-hostnamed.service\fR(8) +\fBsystemd-hostnamed.service\fR(8), +\fBsystemd.system-credentials\fR(7) .RE .PP /etc/hosts @@ -22507,6 +23435,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBkernel-install\fR(8) .RE .PP +/etc/kernel/install\&.conf\&.d/*\&.conf +.RS 4 +\fBkernel-install\fR(8) +.RE +.PP /etc/kernel/install\&.d/ .RS 4 \fBkernel-install\fR(8) @@ -22566,6 +23499,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBmachine-info\fR(5), \fBorg.freedesktop.hostname1\fR(5), \fBsystemd-hostnamed.service\fR(8), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5) .RE .PP @@ -22611,6 +23545,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-system.conf\fR(5), \fBsystemd-sysupdate\fR(8), \fBsystemd.dnssd\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), \fBsysusers.d\fR(5), @@ -22692,6 +23627,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBhomectl\fR(1) .RE .PP +/etc/ssh/ssh_config\&.d/20\-systemd\-ssh\-proxy\&.conf\&.in +.RS 4 +\fBsystemd-ssh-proxy\fR(1) +.RE +.PP /etc/ssl/ca/trusted\&.pem .RS 4 \fBsystemd-journal-remote.service\fR(8), @@ -22823,7 +23763,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf .PP /etc/systemd/import\-pubring\&.gpg .RS 4 -\fBmachinectl\fR(1), +\fBimportctl\fR(1), \fBsysupdate.d\fR(5) .RE .PP @@ -22938,13 +23878,9 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-pstore.service\fR(8) .RE .PP -/etc/systemd/pstore\&.conf\&.d/ -.RS 4 -\fBpstore.conf\fR(5) -.RE -.PP /etc/systemd/pstore\&.conf\&.d/*\&.conf .RS 4 +\fBpstore.conf\fR(5), \fBsystemd-pstore.service\fR(8) .RE .PP @@ -23142,6 +24078,16 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBhwdb\fR(7) .RE .PP +/etc/udev/hwdb\&.d/50\-net\-naming\-allowlist\&.hwdb +.RS 4 +\fBsystemd.net-naming-scheme\fR(7) +.RE +.PP +/etc/udev/hwdb\&.d/50\-net\-naming\-denylist\&.hwdb +.RS 4 +\fBsystemd.net-naming-scheme\fR(7) +.RE +.PP /etc/udev/rules\&.d .RS 4 \fBudev\fR(7) @@ -23157,6 +24103,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBudev.conf\fR(5) .RE .PP +/etc/udev/udev\&.conf\&.d/*\&.conf +.RS 4 +\fBudev.conf\fR(5) +.RE +.PP /etc/userdb/ .RS 4 \fBnss-systemd\fR(8), @@ -23170,6 +24121,12 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-firstboot\fR(1) .RE .PP +/etc/verity\&.d/ +.RS 4 +\fBkernel-command-line\fR(7), +\fBsystemd-mountfsd.service\fR(8) +.RE +.PP /etc/veritytab .RS 4 \fBveritytab\fR(5) @@ -23192,6 +24149,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf .PP /home/ .RS 4 +\fBcapsule@.service\fR(5), \fBfile-hierarchy\fR(7), \fBhomectl\fR(1), \fBhomed.conf\fR(5), @@ -23255,6 +24213,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf .PP /loader/credentials/ .RS 4 +\fBsystemd-pcrlock\fR(8), \fBsystemd-stub\fR(7) .RE .PP @@ -23448,6 +24407,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf .PP /proc/sys/kernel/random/boot_id .RS 4 +\fBorg.freedesktop.hostname1\fR(5), \fBsd_id128_get_machine\fR(3) .RE .PP @@ -23496,11 +24456,23 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf /run/ .RS 4 \fBbinfmt.d\fR(5), +\fBcoredump.conf\fR(5), \fBcrypttab\fR(5), \fBenvironment.d\fR(5), \fBfile-hierarchy\fR(7), +\fBhomed.conf\fR(5), +\fBiocost.conf\fR(5), +\fBjournal-remote.conf\fR(5), +\fBjournal-upload.conf\fR(5), +\fBjournald.conf\fR(5), +\fBlogind.conf\fR(5), \fBmodules-load.d\fR(5), +\fBnetworkctl\fR(1), +\fBnetworkd.conf\fR(5), +\fBoomd.conf\fR(5), \fBorg.freedesktop.systemd1\fR(5), +\fBpstore.conf\fR(5), +\fBresolved.conf\fR(5), \fBsd-login\fR(3), \fBsd_notify\fR(3), \fBsysctl.d\fR(5), @@ -23508,9 +24480,12 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-delta\fR(1), \fBsystemd-journald.service\fR(8), \fBsystemd-modules-load.service\fR(8), +\fBsystemd-mountfsd.service\fR(8), \fBsystemd-nspawn\fR(1), \fBsystemd-poweroff.service\fR(8), +\fBsystemd-sleep.conf\fR(5), \fBsystemd-soft-reboot.service\fR(8), +\fBsystemd-system.conf\fR(5), \fBsystemd-timedated.service\fR(8), \fBsystemd.dnssd\fR(5), \fBsystemd.environment-generator\fR(7), @@ -23522,6 +24497,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd.preset\fR(5), \fBsystemd.service\fR(5), \fBsystemd.unit\fR(5), +\fBtimesyncd.conf\fR(5), \fBtmpfiles.d\fR(5), \fBudev\fR(7) .RE @@ -23531,6 +24507,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBbinfmt.d\fR(5) .RE .PP +/run/capsules/\fINAME\fR/ +.RS 4 +\fBcapsule@.service\fR(5) +.RE +.PP /run/confexts/ .RS 4 \fBsystemd-sysext\fR(8) @@ -23598,6 +24579,16 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd.exec\fR(5) .RE .PP +/run/host/unix\-export/ +.RS 4 +\fBsystemd-ssh-generator\fR(8) +.RE +.PP +/run/host/unix\-export/ssh +.RS 4 +\fBsystemd-ssh-generator\fR(8) +.RE +.PP /run/host/userdb/ .RS 4 \fBnss-systemd\fR(8), @@ -23605,6 +24596,16 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBuserdbctl\fR(1) .RE .PP +/run/kernel/install\&.conf +.RS 4 +\fBkernel-install\fR(8) +.RE +.PP +/run/kernel/install\&.conf\&.d/*\&.conf +.RS 4 +\fBkernel-install\fR(8) +.RE +.PP /run/log/ .RS 4 \fBfile-hierarchy\fR(7), @@ -23683,6 +24684,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBtmpfiles.d\fR(5) .RE .PP +/run/ssh\-unix\-local/socket +.RS 4 +\fBsystemd-ssh-generator\fR(8) +.RE +.PP /run/sysctl\&.d/*\&.conf .RS 4 \fBsysctl.d\fR(5) @@ -23700,9 +24706,28 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf .PP /run/systemd/ .RS 4 +\fBcoredump.conf\fR(5), \fBcrypttab\fR(5), +\fBhomed.conf\fR(5), +\fBiocost.conf\fR(5), +\fBjournal-remote.conf\fR(5), +\fBjournal-upload.conf\fR(5), +\fBjournald.conf\fR(5), +\fBlogind.conf\fR(5), +\fBnetworkd.conf\fR(5), +\fBoomd.conf\fR(5), +\fBpstore.conf\fR(5), +\fBresolved.conf\fR(5), \fBsystemd-creds\fR(1), -\fBsystemd-cryptenroll\fR(1) +\fBsystemd-cryptenroll\fR(1), +\fBsystemd-sleep.conf\fR(5), +\fBsystemd-system.conf\fR(5), +\fBtimesyncd.conf\fR(5) +.RE +.PP +/run/systemd/coredump\&.conf +.RS 4 +\fBcoredump.conf\fR(5) .RE .PP /run/systemd/coredump\&.conf\&.d/*\&.conf @@ -23733,16 +24758,31 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd.unit\fR(5) .RE .PP +/run/systemd/homed\&.conf +.RS 4 +\fBhomed.conf\fR(5) +.RE +.PP /run/systemd/homed\&.conf\&.d/*\&.conf .RS 4 \fBhomed.conf\fR(5) .RE .PP +/run/systemd/journal\-remote\&.conf +.RS 4 +\fBjournal-remote.conf\fR(5) +.RE +.PP /run/systemd/journal\-remote\&.conf\&.d/*\&.conf .RS 4 \fBjournal-remote.conf\fR(5) .RE .PP +/run/systemd/journal\-upload\&.conf +.RS 4 +\fBjournal-upload.conf\fR(5) +.RE +.PP /run/systemd/journal\-upload\&.conf\&.d/*\&.conf .RS 4 \fBjournal-upload.conf\fR(5) @@ -23768,6 +24808,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBjournald.conf\fR(5) .RE .PP +/run/systemd/journald\&.conf +.RS 4 +\fBjournald.conf\fR(5) +.RE +.PP /run/systemd/journald\&.conf\&.d/*\&.conf .RS 4 \fBjournald.conf\fR(5) @@ -23778,6 +24823,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBjournald.conf\fR(5) .RE .PP +/run/systemd/logind\&.conf +.RS 4 +\fBlogind.conf\fR(5) +.RE +.PP /run/systemd/logind\&.conf\&.d/*\&.conf .RS 4 \fBlogind.conf\fR(5) @@ -23792,6 +24842,16 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd.network\fR(5) .RE .PP +/run/systemd/networkd\&.conf +.RS 4 +\fBnetworkd.conf\fR(5) +.RE +.PP +/run/systemd/networkd\&.conf\&.d/*\&.conf +.RS 4 +\fBnetworkd.conf\fR(5) +.RE +.PP /run/systemd/notify .RS 4 \fBsystemd\fR(1) @@ -23803,6 +24863,16 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd.nspawn\fR(5) .RE .PP +/run/systemd/oomd\&.conf +.RS 4 +\fBoomd.conf\fR(5) +.RE +.PP +/run/systemd/oomd\&.conf\&.d/*\&.conf +.RS 4 +\fBoomd.conf\fR(5) +.RE +.PP /run/systemd/portables/ .RS 4 \fBportablectl\fR(1) @@ -23818,9 +24888,20 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd.exec\fR(5) .RE .PP +/run/systemd/pstore\&.conf +.RS 4 +\fBpstore.conf\fR(5) +.RE +.PP +/run/systemd/pstore\&.conf\&.d/*\&.conf +.RS 4 +\fBpstore.conf\fR(5) +.RE +.PP /run/systemd/resolve/io\&.systemd\&.Resolve .RS 4 -\fBnss-resolve\fR(8) +\fBnss-resolve\fR(8), +\fBsystemd-resolved.service\fR(8) .RE .PP /run/systemd/resolve/resolv\&.conf @@ -23837,11 +24918,21 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-resolved.service\fR(8) .RE .PP +/run/systemd/resolved\&.conf +.RS 4 +\fBresolved.conf\fR(5) +.RE +.PP /run/systemd/resolved\&.conf\&.d/*\&.conf .RS 4 \fBresolved.conf\fR(5) .RE .PP +/run/systemd/sleep\&.conf +.RS 4 +\fBsystemd-sleep.conf\fR(5) +.RE +.PP /run/systemd/sleep\&.conf\&.d/*\&.conf .RS 4 \fBsystemd-sleep.conf\fR(5) @@ -23876,6 +24967,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd.unit\fR(5) .RE .PP +/run/systemd/system\&.conf +.RS 4 +\fBsystemd-system.conf\fR(5) +.RE +.PP /run/systemd/system\&.conf\&.d/*\&.conf .RS 4 \fBsystemd-system.conf\fR(5) @@ -23897,6 +24993,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-timesyncd.service\fR(8) .RE .PP +/run/systemd/timesyncd\&.conf +.RS 4 +\fBtimesyncd.conf\fR(5) +.RE +.PP /run/systemd/timesyncd\&.conf\&.d/*\&.conf .RS 4 \fBtimesyncd.conf\fR(5) @@ -23963,6 +25064,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd.preset\fR(5) .RE .PP +/run/systemd/user\&.conf +.RS 4 +\fBsystemd-system.conf\fR(5) +.RE +.PP /run/systemd/user\&.conf\&.d/*\&.conf .RS 4 \fBsystemd-system.conf\fR(5) @@ -24014,11 +25120,33 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBudev\fR(7) .RE .PP +/run/udev/rules\&.d/50\-foobar\&.rules +.RS 4 +\fBsystemd.system-credentials\fR(7), +\fBudevadm\fR(8) +.RE +.PP /run/udev/static_node\-tags/\fItag\fR .RS 4 \fBudev\fR(7) .RE .PP +/run/udev/udev\&.conf +.RS 4 +\fBudev.conf\fR(5) +.RE +.PP +/run/udev/udev\&.conf\&.d/*\&.conf +.RS 4 +\fBudev.conf\fR(5) +.RE +.PP +/run/udev/udev\&.conf\&.d/50\-foobar\&.conf +.RS 4 +\fBsystemd.system-credentials\fR(7), +\fBudevadm\fR(8) +.RE +.PP /run/user/ .RS 4 \fBfile-hierarchy\fR(7), @@ -24216,6 +25344,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-sleep.conf\fR(5) .RE .PP +/sys/power/mem_sleep +.RS 4 +\fBsystemd-sleep.conf\fR(5) +.RE +.PP /sys/power/resume .RS 4 \fBsystemd-hibernate-resume.service\fR(8) @@ -24264,9 +25397,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBcrypttab\fR(5), \fBfile-hierarchy\fR(7), \fBrepart.d\fR(5), +\fBsystemd-sysext\fR(8), \fBsystemd-system.conf\fR(5), \fBsystemd-tmpfiles\fR(8), \fBsystemd.exec\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.special\fR(7), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), @@ -24336,6 +25471,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf /usr/bin/ .RS 4 \fBfile-hierarchy\fR(7), +\fBorg.freedesktop.systemd1\fR(5), \fBsystemd.exec\fR(5), \fBsystemd.service\fR(5) .RE @@ -24352,6 +25488,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemctl\fR(1) .RE .PP +/usr/foo +.RS 4 +\fBsystemd-repart\fR(8) +.RE +.PP /usr/include/ .RS 4 \fBfile-hierarchy\fR(7) @@ -24376,6 +25517,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBmodules-load.d\fR(5), \fBsysctl.d\fR(5), \fBsystemd-delta\fR(1), +\fBsystemd-mountfsd.service\fR(8), \fBsystemd-timedated.service\fR(8), \fBsystemd.dnssd\fR(5), \fBsystemd.link\fR(5), @@ -24458,6 +25600,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBkernel-install\fR(8) .RE .PP +/usr/lib/kernel/install\&.conf\&.d/*\&.conf +.RS 4 +\fBkernel-install\fR(8) +.RE +.PP /usr/lib/kernel/install\&.d/ .RS 4 \fBkernel-install\fR(8) @@ -24585,6 +25732,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-stub\fR(7) .RE .PP +/usr/lib/systemd/coredump\&.conf +.RS 4 +\fBcoredump.conf\fR(5) +.RE +.PP /usr/lib/systemd/coredump\&.conf\&.d/*\&.conf .RS 4 \fBcoredump.conf\fR(5) @@ -24595,6 +25747,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd.dnssd\fR(5) .RE .PP +/usr/lib/systemd/homed\&.conf +.RS 4 +\fBhomed.conf\fR(5) +.RE +.PP /usr/lib/systemd/homed\&.conf\&.d/*\&.conf .RS 4 \fBhomed.conf\fR(5) @@ -24602,20 +25759,35 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf .PP /usr/lib/systemd/import\-pubring\&.gpg .RS 4 -\fBmachinectl\fR(1), +\fBimportctl\fR(1), \fBsysupdate.d\fR(5) .RE .PP +/usr/lib/systemd/journal\-remote\&.conf +.RS 4 +\fBjournal-remote.conf\fR(5) +.RE +.PP /usr/lib/systemd/journal\-remote\&.conf\&.d/*\&.conf .RS 4 \fBjournal-remote.conf\fR(5) .RE .PP +/usr/lib/systemd/journal\-upload\&.conf +.RS 4 +\fBjournal-upload.conf\fR(5) +.RE +.PP /usr/lib/systemd/journal\-upload\&.conf\&.d/*\&.conf .RS 4 \fBjournal-upload.conf\fR(5) .RE .PP +/usr/lib/systemd/journald\&.conf +.RS 4 +\fBjournald.conf\fR(5) +.RE +.PP /usr/lib/systemd/journald\&.conf\&.d/*\&.conf .RS 4 \fBjournald.conf\fR(5) @@ -24628,6 +25800,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf .PP /usr/lib/systemd/logind\&.conf .RS 4 +\fBlogind.conf\fR(5), \fBsystemd-analyze\fR(1) .RE .PP @@ -24659,6 +25832,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-nspawn\fR(1) .RE .PP +/usr/lib/systemd/networkd\&.conf +.RS 4 +\fBnetworkd.conf\fR(5) +.RE +.PP /usr/lib/systemd/networkd\&.conf\&.d/*\&.conf .RS 4 \fBnetworkd.conf\fR(5) @@ -24669,6 +25847,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-timedated.service\fR(8) .RE .PP +/usr/lib/systemd/oomd\&.conf +.RS 4 +\fBoomd.conf\fR(5) +.RE +.PP /usr/lib/systemd/oomd\&.conf\&.d/*\&.conf .RS 4 \fBoomd.conf\fR(5) @@ -24684,17 +25867,37 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBportablectl\fR(1) .RE .PP +/usr/lib/systemd/pstore\&.conf +.RS 4 +\fBpstore.conf\fR(5) +.RE +.PP +/usr/lib/systemd/pstore\&.conf\&.d/*\&.conf +.RS 4 +\fBpstore.conf\fR(5) +.RE +.PP /usr/lib/systemd/resolv\&.conf .RS 4 \fBsystemd-nspawn\fR(1), \fBsystemd-resolved.service\fR(8) .RE .PP +/usr/lib/systemd/resolved\&.conf +.RS 4 +\fBresolved.conf\fR(5) +.RE +.PP /usr/lib/systemd/resolved\&.conf\&.d/*\&.conf .RS 4 \fBresolved.conf\fR(5) .RE .PP +/usr/lib/systemd/sleep\&.conf +.RS 4 +\fBsystemd-sleep.conf\fR(5) +.RE +.PP /usr/lib/systemd/sleep\&.conf\&.d/*\&.conf .RS 4 \fBsystemd-sleep.conf\fR(5) @@ -24777,6 +25980,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-run-generator\fR(8) .RE .PP +/usr/lib/systemd/system\-generators/systemd\-ssh\-generator +.RS 4 +\fBsystemd-ssh-generator\fR(8) +.RE +.PP /usr/lib/systemd/system\-generators/systemd\-system\-update\-generator .RS 4 \fBsystemd-system-update-generator\fR(8) @@ -24787,6 +25995,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-sysv-generator\fR(8) .RE .PP +/usr/lib/systemd/system\-generators/systemd\-tpm2\-generator +.RS 4 +\fBsystemd-tpm2-generator\fR(8) +.RE +.PP /usr/lib/systemd/system\-generators/systemd\-veritysetup\-generator .RS 4 \fBsystemd-veritysetup-generator\fR(8) @@ -24813,6 +26026,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-suspend.service\fR(8) .RE .PP +/usr/lib/systemd/system\&.conf +.RS 4 +\fBsystemd-system.conf\fR(5) +.RE +.PP /usr/lib/systemd/system\&.conf\&.d/*\&.conf .RS 4 \fBsystemd-system.conf\fR(5) @@ -24848,6 +26066,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-bless-boot.service\fR(8) .RE .PP +\fB/usr/lib/systemd/systemd\-bsod\fR +.RS 4 +\fBsystemd-bsod.service\fR(8) +.RE +.PP /usr/lib/systemd/systemd\-coredump .RS 4 \fBsystemd-coredump\fR(8) @@ -24858,11 +26081,6 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-fsck@.service\fR(8) .RE .PP -/usr/lib/systemd/systemd\-fsckd -.RS 4 -\fBsystemd-fsckd.service\fR(8) -.RE -.PP /usr/lib/systemd/systemd\-growfs .RS 4 \fBsystemd-makefs@.service\fR(8) @@ -24948,6 +26166,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-modules-load.service\fR(8) .RE .PP +/usr/lib/systemd/systemd\-mountfsd +.RS 4 +\fBsystemd-mountfsd.service\fR(8) +.RE +.PP /usr/lib/systemd/systemd\-network\-generator .RS 4 \fBsystemd-network-generator.service\fR(8) @@ -24963,6 +26186,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-networkd-wait-online.service\fR(8) .RE .PP +/usr/lib/systemd/systemd\-nsresourced +.RS 4 +\fBsystemd-nsresourced.service\fR(8) +.RE +.PP /usr/lib/systemd/systemd\-oomd .RS 4 \fBsystemd-oomd.service\fR(8) @@ -25019,6 +26247,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-poweroff.service\fR(8) .RE .PP +\fB/usr/lib/systemd/systemd\-ssh\-proxy\fR +.RS 4 +\fBsystemd-ssh-proxy\fR(1) +.RE +.PP \fB/usr/lib/systemd/systemd\-storagetm\fR .RS 4 \fBsystemd-storagetm.service\fR(8) @@ -25089,6 +26322,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-volatile-root.service\fR(8) .RE .PP +/usr/lib/systemd/timesyncd\&.conf +.RS 4 +\fBtimesyncd.conf\fR(5) +.RE +.PP /usr/lib/systemd/timesyncd\&.conf\&.d/*\&.conf .RS 4 \fBtimesyncd.conf\fR(5) @@ -25134,6 +26372,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd.preset\fR(5) .RE .PP +/usr/lib/systemd/user\&.conf +.RS 4 +\fBsystemd-system.conf\fR(5) +.RE +.PP /usr/lib/systemd/user\&.conf\&.d/*\&.conf .RS 4 \fBsystemd-system.conf\fR(5) @@ -25215,6 +26458,16 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBudev\fR(7) .RE .PP +/usr/lib/udev/udev\&.conf +.RS 4 +\fBudev.conf\fR(5) +.RE +.PP +/usr/lib/udev/udev\&.conf\&.d/*\&.conf +.RS 4 +\fBudev.conf\fR(5) +.RE +.PP /usr/lib/userdb/ .RS 4 \fBnss-systemd\fR(8), @@ -25253,6 +26506,16 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-sysext\fR(8) .RE .PP +/usr/local/lib/kernel/install\&.conf +.RS 4 +\fBkernel-install\fR(8) +.RE +.PP +/usr/local/lib/kernel/install\&.conf\&.d/*\&.conf +.RS 4 +\fBkernel-install\fR(8) +.RE +.PP /usr/local/lib/machines/ .RS 4 \fBmachinectl\fR(1) @@ -25263,6 +26526,24 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBportablectl\fR(1) .RE .PP +/usr/local/lib/systemd/ +.RS 4 +\fBcoredump.conf\fR(5), +\fBhomed.conf\fR(5), +\fBiocost.conf\fR(5), +\fBjournal-remote.conf\fR(5), +\fBjournal-upload.conf\fR(5), +\fBjournald.conf\fR(5), +\fBlogind.conf\fR(5), +\fBnetworkd.conf\fR(5), +\fBoomd.conf\fR(5), +\fBpstore.conf\fR(5), +\fBresolved.conf\fR(5), +\fBsystemd-sleep.conf\fR(5), +\fBsystemd-system.conf\fR(5), +\fBtimesyncd.conf\fR(5) +.RE +.PP /usr/local/lib/systemd/*\&.conf\&.d/ .RS 4 \fBcoredump.conf\fR(5), @@ -25367,6 +26648,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf /usr/sbin/ .RS 4 \fBfile-hierarchy\fR(7), +\fBorg.freedesktop.systemd1\fR(5), \fBsystemd.exec\fR(5) .RE .PP @@ -25422,6 +26704,16 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBtmpfiles.d\fR(5) .RE .PP +/usr/share/wayland\-sessions +.RS 4 +\fBhomectl\fR(1) +.RE +.PP +/usr/share/xesssions/ +.RS 4 +\fBhomectl\fR(1) +.RE +.PP /usr/share/zoneinfo/ .RS 4 \fBlocaltime\fR(5) @@ -25496,8 +26788,15 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBtmpfiles.d\fR(5) .RE .PP +/var/lib/capsules/ +.RS 4 +\fBcapsule@.service\fR(5) +.RE +.PP /var/lib/confexts/ .RS 4 +\fBimportctl\fR(1), +\fBsystemd-mountfsd.service\fR(8), \fBsystemd-sysext\fR(8) .RE .PP @@ -25513,15 +26812,39 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf .PP /var/lib/extensions/ .RS 4 +\fBimportctl\fR(1), \fBsystemd-dissect\fR(1), +\fBsystemd-mountfsd.service\fR(8), +\fBsystemd-sysext\fR(8) +.RE +.PP +/var/lib/extensions\&.mutable/ +.RS 4 +\fBsystemd-sysext\fR(8) +.RE +.PP +/var/lib/extensions\&.mutable/etc/ +.RS 4 +\fBsystemd-sysext\fR(8) +.RE +.PP +/var/lib/extensions\&.mutable/opt/ +.RS 4 +\fBsystemd-sysext\fR(8) +.RE +.PP +/var/lib/extensions\&.mutable/usr/ +.RS 4 \fBsystemd-sysext\fR(8) .RE .PP /var/lib/machines/ .RS 4 +\fBimportctl\fR(1), \fBmachinectl\fR(1), \fBorg.freedesktop.import1\fR(5), \fBsystemd-dissect\fR(1), +\fBsystemd-mountfsd.service\fR(8), \fBsystemd-nspawn\fR(1), \fBsystemd.nspawn\fR(5), \fBtmpfiles.d\fR(5) @@ -25537,6 +26860,26 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsysupdate.d\fR(5) .RE .PP +/var/lib/machines/mymachine\&.raw\&.v/ +.RS 4 +\fBsystemd.v\fR(7) +.RE +.PP +/var/lib/machines/mymachine\&.raw\&.v/mymachine_7\&.5\&.14_x86\-64\&.raw +.RS 4 +\fBsystemd.v\fR(7) +.RE +.PP +/var/lib/machines/quux\&.raw\&.v/quux*\&.raw +.RS 4 +\fBsystemd-vpick\fR(1) +.RE +.PP +/var/lib/machines/waldo\&.v/waldo +.RS 4 +\fBsystemd-vpick\fR(1) +.RE +.PP /var/lib/pcrlock\&.d/ .RS 4 \fBsystemd-pcrlock\fR(8) @@ -25614,8 +26957,10 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf .PP /var/lib/portables/ .RS 4 +\fBimportctl\fR(1), \fBportablectl\fR(1), -\fBsystemd-dissect\fR(1) +\fBsystemd-dissect\fR(1), +\fBsystemd-mountfsd.service\fR(8) .RE .PP /var/lib/private @@ -25789,6 +27134,7 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-nspawn\fR(1), \fBsystemd-system.conf\fR(5), \fBsystemd.exec\fR(5), +\fBsystemd.link\fR(5), \fBsystemd.special\fR(7), \fBsystemd.unit\fR(5), \fBsysupdate.d\fR(5), @@ -25801,6 +27147,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-stub\fR(7) .RE .PP +\fIESP\fR/\&.\&.\&./\fIfoo\fR\&.efi\&.extra\&.d/*\&.confext\&.raw +.RS 4 +\fBsystemd-stub\fR(7) +.RE +.PP \fIESP\fR/\&.\&.\&./\fIfoo\fR\&.efi\&.extra\&.d/*\&.cred .RS 4 \fBsystemd-stub\fR(7) @@ -25811,6 +27162,11 @@ $XDG_RUNTIME_DIR/user\-tmpfiles\&.d/*\&.conf \fBsystemd-stub\fR(7) .RE .PP +\fIESP\fR/\&.\&.\&./\fIfoo\fR\&.efi\&.extra\&.d/*\&.sysext\&.raw +.RS 4 +\fBsystemd-stub\fR(7) +.RE +.PP \fIESP\fR/loader/addons/*\&.addon\&.efi .RS 4 \fBsystemd-stub\fR(7) @@ -25872,6 +27228,16 @@ boot\-complete\&.target \fBbusctl\fR(1) .RE .PP +capsule\&.slice +.RS 4 +\fBsystemd.special\fR(7) +.RE +.PP +capsule@\fINAME\fR\&.service +.RS 4 +\fBcapsule@.service\fR(5) +.RE +.PP \fBcoredumpctl\fR .RS 4 \fBcoredumpctl\fR(1) @@ -25988,6 +27354,11 @@ hybrid\-sleep\&.target \fBsystemd.special\fR(7) .RE .PP +\fBimportctl\fR +.RS 4 +\fBimportctl\fR(1) +.RE +.PP \fBinit\fR .RS 4 \fBsystemd\fR(1) @@ -26287,6 +27658,11 @@ rpcbind\&.target \fBsystemd.special\fR(7) .RE .PP +\fBrun0\fR +.RS 4 +\fBrun0\fR(1) +.RE +.PP \fBrunlevel\fR .RS 4 \fBrunlevel\fR(8) @@ -26390,6 +27766,11 @@ sound\&.target \fBsystemd.special\fR(7) .RE .PP +ssh\-access\&.target +.RS 4 +\fBsystemd.special\fR(7) +.RE +.PP storage\-target\-mode\&.target .RS 4 \fBsystemd.special\fR(7) @@ -26524,11 +27905,6 @@ systemd\-boot\-random\-seed\&.service \fBsystemd-boot-random-seed.service\fR(8) .RE .PP -\fBsystemd\-bsod\fR -.RS 4 -\fBsystemd-bsod.service\fR(8) -.RE -.PP systemd\-bsod\&.service .RS 4 \fBsystemd-bsod.service\fR(8) @@ -26634,16 +28010,6 @@ systemd\-fsck@\&.service \fBsystemd-fsck@.service\fR(8) .RE .PP -systemd\-fsckd\&.service -.RS 4 -\fBsystemd-fsckd.service\fR(8) -.RE -.PP -systemd\-fsckd\&.socket -.RS 4 -\fBsystemd-fsckd.service\fR(8) -.RE -.PP systemd\-growfs\-root\&.service .RS 4 \fBsystemd-makefs@.service\fR(8) @@ -26659,6 +28025,11 @@ systemd\-halt\&.service \fBsystemd-poweroff.service\fR(8) .RE .PP +systemd\-hibernate\-clear\&.service +.RS 4 +\fBsystemd-hibernate-resume.service\fR(8) +.RE +.PP systemd\-hibernate\-resume\&.service .RS 4 \fBsystemd-hibernate-resume.service\fR(8) @@ -26829,6 +28200,11 @@ systemd\-modules\-load\&.service \fBsystemd-mount\fR(1) .RE .PP +systemd\-mountfsd\&.service +.RS 4 +\fBsystemd-mountfsd.service\fR(8) +.RE +.PP systemd\-network\-generator\&.service .RS 4 \fBsystemd-network-generator.service\fR(8) @@ -26859,6 +28235,11 @@ systemd\-networkd\&.service \fBsystemd-nspawn\fR(1) .RE .PP +systemd\-nsresourced\&.service +.RS 4 +\fBsystemd-nsresourced.service\fR(8) +.RE +.PP systemd\-oomd\&.service .RS 4 \fBsystemd-oomd.service\fR(8) @@ -27144,6 +28525,11 @@ systemd\-volatile\-root\&.service \fBsystemd-volatile-root.service\fR(8) .RE .PP +\fBsystemd\-vpick\fR +.RS 4 +\fBsystemd-vpick\fR(1) +.RE +.PP \fItarget\fR\&.target .RS 4 \fBsystemd.target\fR(5), @@ -27181,6 +28567,11 @@ timers\&.target \fBsystemd.special\fR(7) .RE .PP +tpm2\&.target +.RS 4 +\fBsystemd.special\fR(7) +.RE +.PP \fBudevadm\fR .RS 4 \fBudevadm\fR(8) @@ -27503,6 +28894,16 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.home1\fR(5) .RE .PP +\fIActivateHomeIfReferenced()\fR +.RS 4 +\fBorg.freedesktop.home1\fR(5) +.RE +.PP +\fIActivateIfReferenced()\fR +.RS 4 +\fBorg.freedesktop.home1\fR(5) +.RE +.PP \fIActivateSession()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) @@ -27624,6 +29025,11 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.login1\fR(5) .RE .PP +\fICanSleep()\fR +.RS 4 +\fBorg.freedesktop.login1\fR(5) +.RE +.PP \fICanSuspend()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) @@ -27735,6 +29141,11 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.home1\fR(5) .RE .PP +\fICreateHomeEx()\fR +.RS 4 +\fBorg.freedesktop.home1\fR(5) +.RE +.PP \fICreateMachine()\fR .RS 4 \fBorg.freedesktop.machine1\fR(5) @@ -27882,11 +29293,21 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.import1\fR(5) .RE .PP +\fIExportRawEx()\fR +.RS 4 +\fBorg.freedesktop.import1\fR(5) +.RE +.PP \fIExportTar()\fR .RS 4 \fBorg.freedesktop.import1\fR(5) .RE .PP +\fIExportTarEx()\fR +.RS 4 +\fBorg.freedesktop.import1\fR(5) +.RE +.PP \fIFixate()\fR .RS 4 \fBorg.freedesktop.home1\fR(5) @@ -28064,6 +29485,11 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.machine1\fR(5) .RE .PP +\fIGetMachineSSHInfo()\fR +.RS 4 +\fBorg.freedesktop.machine1\fR(5) +.RE +.PP \fIGetMachineUIDShift()\fR .RS 4 \fBorg.freedesktop.machine1\fR(5) @@ -28095,6 +29521,11 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.hostname1\fR(5) .RE .PP +\fIGetSSHInfo()\fR +.RS 4 +\fBorg.freedesktop.machine1\fR(5) +.RE +.PP \fIGetSeat()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) @@ -28221,16 +29652,31 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.import1\fR(5) .RE .PP +\fIImportFileSystemEx()\fR +.RS 4 +\fBorg.freedesktop.import1\fR(5) +.RE +.PP \fIImportRaw()\fR .RS 4 \fBorg.freedesktop.import1\fR(5) .RE .PP +\fIImportRawEx()\fR +.RS 4 +\fBorg.freedesktop.import1\fR(5) +.RE +.PP \fIImportTar()\fR .RS 4 \fBorg.freedesktop.import1\fR(5) .RE .PP +\fIImportTarEx()\fR +.RS 4 +\fBorg.freedesktop.import1\fR(5) +.RE +.PP \fIInhibit()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) @@ -28280,6 +29726,7 @@ Methods exposed in the D\-Bus interface\&. .PP \fIListImages()\fR .RS 4 +\fBorg.freedesktop.import1\fR(5), \fBorg.freedesktop.machine1\fR(5), \fBorg.freedesktop.portable1\fR(5) .RE @@ -28314,6 +29761,11 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.login1\fR(5) .RE .PP +\fIListSessionsEx()\fR +.RS 4 +\fBorg.freedesktop.login1\fR(5) +.RE +.PP \fIListTimezones()\fR .RS 4 \fBorg.freedesktop.timedate1\fR(5) @@ -28324,6 +29776,11 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.import1\fR(5) .RE .PP +\fIListTransfersEx()\fR +.RS 4 +\fBorg.freedesktop.import1\fR(5) +.RE +.PP \fIListUnitFiles()\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) @@ -28522,11 +29979,21 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.import1\fR(5) .RE .PP +\fIPullRawEx()\fR +.RS 4 +\fBorg.freedesktop.import1\fR(5) +.RE +.PP \fIPullTar()\fR .RS 4 \fBorg.freedesktop.import1\fR(5) .RE .PP +\fIPullTarEx()\fR +.RS 4 +\fBorg.freedesktop.import1\fR(5) +.RE +.PP \fIQueueSignal()\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) @@ -28614,11 +30081,21 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.home1\fR(5) .RE .PP +\fIRefHomeUnrestricted()\fR +.RS 4 +\fBorg.freedesktop.home1\fR(5) +.RE +.PP \fIRefUnit()\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) .RE .PP +\fIRefUnrestricted()\fR +.RS 4 +\fBorg.freedesktop.home1\fR(5) +.RE +.PP \fIRegisterHome()\fR .RS 4 \fBorg.freedesktop.home1\fR(5) @@ -28837,6 +30314,11 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.hostname1\fR(5) .RE .PP +\fISetClass()\fR +.RS 4 +\fBorg.freedesktop.login1\fR(5) +.RE +.PP \fISetDNS()\fR .RS 4 \fBorg.freedesktop.network1\fR(5), @@ -29118,6 +30600,11 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.locale1\fR(5) .RE .PP +\fISleep()\fR +.RS 4 +\fBorg.freedesktop.login1\fR(5) +.RE +.PP \fISoftReboot()\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) @@ -29128,6 +30615,11 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.systemd1\fR(5) .RE .PP +\fIStartAuxiliaryScope()\fR +.RS 4 +\fBorg.freedesktop.systemd1\fR(5) +.RE +.PP \fIStartTransientUnit()\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) @@ -29335,10 +30827,20 @@ Methods exposed in the D\-Bus interface\&. \fBorg.freedesktop.home1\fR(5) .RE .PP +\fIUpdateEx()\fR +.RS 4 +\fBorg.freedesktop.home1\fR(5) +.RE +.PP \fIUpdateHome()\fR .RS 4 \fBorg.freedesktop.home1\fR(5) .RE +.PP +\fIUpdateHomeEx()\fR +.RS 4 +\fBorg.freedesktop.home1\fR(5) +.RE .SH "D\-BUS PROPERTIES" .PP Properties exposed in the D\-Bus interface\&. @@ -30260,11 +31762,26 @@ Properties exposed in the D\-Bus interface\&. \fBorg.freedesktop.systemd1\fR(5) .RE .PP +\fIEffectiveMemoryHigh\fR +.RS 4 +\fBorg.freedesktop.systemd1\fR(5) +.RE +.PP +\fIEffectiveMemoryMax\fR +.RS 4 +\fBorg.freedesktop.systemd1\fR(5) +.RE +.PP \fIEffectiveMemoryNodes\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) .RE .PP +\fIEffectiveTasksMax\fR +.RS 4 +\fBorg.freedesktop.systemd1\fR(5) +.RE +.PP \fIEnableWallMessages\fR .RS 4 \fBorg.freedesktop.login1\fR(5) @@ -30315,6 +31832,16 @@ Properties exposed in the D\-Bus interface\&. \fBorg.freedesktop.systemd1\fR(5) .RE .PP +\fIExecMainHandoffTimestamp\fR +.RS 4 +\fBorg.freedesktop.systemd1\fR(5) +.RE +.PP +\fIExecMainHandoffTimestampMonotonic\fR +.RS 4 +\fBorg.freedesktop.systemd1\fR(5) +.RE +.PP \fIExecMainPID\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) @@ -31617,6 +33144,11 @@ Properties exposed in the D\-Bus interface\&. \fBorg.freedesktop.systemd1\fR(5) .RE .PP +\fIMemoryZSwapWriteback\fR +.RS 4 +\fBorg.freedesktop.systemd1\fR(5) +.RE +.PP \fIMessageQueueMaxMessages\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) @@ -31764,6 +33296,11 @@ Properties exposed in the D\-Bus interface\&. \fBorg.freedesktop.network1\fR(5) .RE .PP +\fINamespaceNSID\fR +.RS 4 +\fBorg.freedesktop.network1\fR(5) +.RE +.PP \fINeedDaemonReload\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) @@ -31934,6 +33471,11 @@ Properties exposed in the D\-Bus interface\&. \fBorg.freedesktop.systemd1\fR(5) .RE .PP +\fIPassFileDescriptorsToExec\fR +.RS 4 +\fBorg.freedesktop.systemd1\fR(5) +.RE +.PP \fIPassPacketInfo\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) @@ -32491,6 +34033,16 @@ Properties exposed in the D\-Bus interface\&. \fBorg.freedesktop.systemd1\fR(5) .RE .PP +\fISSHAddress\fR +.RS 4 +\fBorg.freedesktop.machine1\fR(5) +.RE +.PP +\fISSHPrivateKeyPath\fR +.RS 4 +\fBorg.freedesktop.machine1\fR(5) +.RE +.PP \fISameProcessGroup\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) @@ -32597,6 +34149,21 @@ Properties exposed in the D\-Bus interface\&. \fBorg.freedesktop.systemd1\fR(5) .RE .PP +\fIShutdownStartTimestamp\fR +.RS 4 +\fBorg.freedesktop.systemd1\fR(5) +.RE +.PP +\fIShutdownStartTimestampMonotonic\fR +.RS 4 +\fBorg.freedesktop.systemd1\fR(5) +.RE +.PP +\fISleepOperation\fR +.RS 4 +\fBorg.freedesktop.login1\fR(5) +.RE +.PP \fISlice\fR .RS 4 \fBorg.freedesktop.login1\fR(5), @@ -32663,6 +34230,11 @@ Properties exposed in the D\-Bus interface\&. \fBorg.freedesktop.systemd1\fR(5) .RE .PP +\fISoftRebootsCount\fR +.RS 4 +\fBorg.freedesktop.systemd1\fR(5) +.RE +.PP \fISourcePath\fR .RS 4 \fBorg.freedesktop.network1\fR(5), @@ -33273,6 +34845,12 @@ Properties exposed in the D\-Bus interface\&. \fBorg.freedesktop.locale1\fR(5) .RE .PP +\fIVSockCID\fR +.RS 4 +\fBorg.freedesktop.hostname1\fR(5), +\fBorg.freedesktop.machine1\fR(5) +.RE +.PP \fIVTNr\fR .RS 4 \fBorg.freedesktop.login1\fR(5) @@ -33313,6 +34891,11 @@ Properties exposed in the D\-Bus interface\&. \fBorg.freedesktop.systemd1\fR(5) .RE .PP +\fIWantsMountsFor\fR +.RS 4 +\fBorg.freedesktop.systemd1\fR(5) +.RE +.PP \fIWatchdogDevice\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) @@ -33391,140 +34974,145 @@ Properties exposed in the D\-Bus interface\&. .PP Signals emitted in the D\-Bus interface\&. .PP -\fIJobNew\fR +\fIJobNew()\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) .RE .PP -\fIJobRemoved\fR +\fIJobRemoved()\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) .RE .PP -\fIKilled\fR +\fIKilled()\fR .RS 4 \fBorg.freedesktop.oom1\fR(5) .RE .PP -\fILock\fR +\fILock()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) .RE .PP -\fILogMessage\fR +\fILogMessage()\fR .RS 4 \fBorg.freedesktop.import1\fR(5) .RE .PP -\fIMachineNew\fR +\fIMachineNew()\fR .RS 4 \fBorg.freedesktop.machine1\fR(5) .RE .PP -\fIMachineRemoved\fR +\fIMachineRemoved()\fR .RS 4 \fBorg.freedesktop.machine1\fR(5) .RE .PP -\fIPauseDevice\fR +\fIPauseDevice()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) .RE .PP -\fIPrepareForShutdown\fR +\fIPrepareForShutdown()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) .RE .PP -\fIPrepareForShutdownWithMetadata\fR +\fIPrepareForShutdownWithMetadata()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) .RE .PP -\fIPrepareForSleep\fR +\fIPrepareForSleep()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) .RE .PP -\fIReloading\fR +\fIProgressUpdate()\fR +.RS 4 +\fBorg.freedesktop.import1\fR(5) +.RE +.PP +\fIReloading()\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) .RE .PP -\fIRequestStop\fR +\fIRequestStop()\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) .RE .PP -\fIResumeDevice\fR +\fIResumeDevice()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) .RE .PP -\fISeatNew\fR +\fISeatNew()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) .RE .PP -\fISeatRemoved\fR +\fISeatRemoved()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) .RE .PP -\fISessionNew\fR +\fISessionNew()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) .RE .PP -\fISessionRemoved\fR +\fISessionRemoved()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) .RE .PP -\fIStartupFinished\fR +\fIStartupFinished()\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) .RE .PP -\fITransferNew\fR +\fITransferNew()\fR .RS 4 \fBorg.freedesktop.import1\fR(5) .RE .PP -\fITransferRemoved\fR +\fITransferRemoved()\fR .RS 4 \fBorg.freedesktop.import1\fR(5) .RE .PP -\fIUnitFilesChanged\fR +\fIUnitFilesChanged()\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) .RE .PP -\fIUnitNew\fR +\fIUnitNew()\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) .RE .PP -\fIUnitRemoved\fR +\fIUnitRemoved()\fR .RS 4 \fBorg.freedesktop.systemd1\fR(5) .RE .PP -\fIUnlock\fR +\fIUnlock()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) .RE .PP -\fIUserNew\fR +\fIUserNew()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) .RE .PP -\fIUserRemoved\fR +\fIUserRemoved()\fR .RS 4 \fBorg.freedesktop.login1\fR(5) .RE .SH "COLOPHON" .PP -This index contains 5991 entries in 24 sections, referring to 392 individual manual pages\&. +This index contains 6253 entries in 24 sections, referring to 401 individual manual pages\&. diff --git a/upstream/debian-unstable/man7/systemd.environment-generator.7 b/upstream/debian-unstable/man7/systemd.environment-generator.7 index 604a8d8b..42c3a918 100644 --- a/upstream/debian-unstable/man7/systemd.environment-generator.7 +++ b/upstream/debian-unstable/man7/systemd.environment-generator.7 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\&.ENVIRONMENT\-GENERATOR" "7" "" "systemd 255" "systemd.environment-generator" +.TH "SYSTEMD\&.ENVIRONMENT\-GENERATOR" "7" "" "systemd 256~rc3" "systemd.environment-generator" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -27,20 +27,31 @@ systemd.environment-generator \- systemd environment file generators .HP \w'\fB/usr/lib/systemd/user\-environment\-generators/some\-generator\fR\ 'u \fB/usr/lib/systemd/user\-environment\-generators/some\-generator\fR .PP -.nf +.RS 4 /run/systemd/system\-environment\-generators/* +.RE +.RS 4 /etc/systemd/system\-environment\-generators/* +.RE +.RS 4 /usr/local/lib/systemd/system\-environment\-generators/* +.RE +.RS 4 /usr/lib/systemd/system\-environment\-generators/* -.fi +.RE .PP -.nf +.RS 4 /run/systemd/user\-environment\-generators/* +.RE +.RS 4 /etc/systemd/user\-environment\-generators/* +.RE +.RS 4 /usr/local/lib/systemd/user\-environment\-generators/* +.RE +.RS 4 /usr/lib/systemd/user\-environment\-generators/* -.fi -.sp +.RE .SH "DESCRIPTION" .PP Generators are small executables that live in @@ -187,7 +198,4 @@ SYSTEMD_LOG_LEVEL=debug VAR_A=something VAR_B="something else" \e .\} .SH "SEE ALSO" .PP -\fBsystemd-environment-d-generator\fR(8), -\fBsystemd.generator\fR(7), -\fBsystemd\fR(1), -\fBsystemctl\fR(1) +\fBsystemd-environment-d-generator\fR(8), \fBsystemd.generator\fR(7), \fBsystemd\fR(1), \fBsystemctl\fR(1) diff --git a/upstream/debian-unstable/man7/systemd.generator.7 b/upstream/debian-unstable/man7/systemd.generator.7 index 3e7f3aaa..5538abb0 100644 --- a/upstream/debian-unstable/man7/systemd.generator.7 +++ b/upstream/debian-unstable/man7/systemd.generator.7 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\&.GENERATOR" "7" "" "systemd 255" "systemd.generator" +.TH "SYSTEMD\&.GENERATOR" "7" "" "systemd 256~rc3" "systemd.generator" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -25,20 +25,31 @@ systemd.generator \- systemd unit generators .HP \w'\fB/path/to/generator\fR\ 'u \fB/path/to/generator\fR \fInormal\-dir\fR [\fIearly\-dir\fR] [\fIlate\-dir\fR] .PP -.nf +.RS 4 /run/systemd/system\-generators/* +.RE +.RS 4 /etc/systemd/system\-generators/* +.RE +.RS 4 /usr/local/lib/systemd/system\-generators/* +.RE +.RS 4 /usr/lib/systemd/system\-generators/* -.fi +.RE .PP -.nf +.RS 4 /run/systemd/user\-generators/* +.RE +.RS 4 /etc/systemd/user\-generators/* +.RE +.RS 4 /usr/local/lib/systemd/user\-generators/* +.RE +.RS 4 /usr/lib/systemd/user\-generators/* -.fi -.sp +.RE .SH "DESCRIPTION" .PP Generators are small executables placed in @@ -460,18 +471,4 @@ find $dir .\} .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBsystemd-cryptsetup-generator\fR(8), -\fBsystemd-debug-generator\fR(8), -\fBsystemd-fstab-generator\fR(8), -\fBfstab\fR(5), -\fBsystemd-getty-generator\fR(8), -\fBsystemd-gpt-auto-generator\fR(8), -\fBsystemd-hibernate-resume-generator\fR(8), -\fBsystemd-rc-local-generator\fR(8), -\fBsystemd-system-update-generator\fR(8), -\fBsystemd-sysv-generator\fR(8), -\fBsystemd-xdg-autostart-generator\fR(8), -\fBsystemd.unit\fR(5), -\fBsystemctl\fR(1), -\fBsystemd.environment-generator\fR(7) +\fBsystemd\fR(1), \fBsystemd-cryptsetup-generator\fR(8), \fBsystemd-debug-generator\fR(8), \fBsystemd-fstab-generator\fR(8), \fBfstab\fR(5), \fBsystemd-getty-generator\fR(8), \fBsystemd-gpt-auto-generator\fR(8), \fBsystemd-hibernate-resume-generator\fR(8), \fBsystemd-rc-local-generator\fR(8), \fBsystemd-system-update-generator\fR(8), \fBsystemd-sysv-generator\fR(8), \fBsystemd-xdg-autostart-generator\fR(8), \fBsystemd.unit\fR(5), \fBsystemctl\fR(1), \fBsystemd.environment-generator\fR(7) diff --git a/upstream/debian-unstable/man7/systemd.image-policy.7 b/upstream/debian-unstable/man7/systemd.image-policy.7 index 8927360a..98ba64c0 100644 --- a/upstream/debian-unstable/man7/systemd.image-policy.7 +++ b/upstream/debian-unstable/man7/systemd.image-policy.7 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\&.IMAGE\-POLICY" "7" "" "systemd 255" "systemd.image-policy" +.TH "SYSTEMD\&.IMAGE\-POLICY" "7" "" "systemd 256~rc3" "systemd.image-policy" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -289,11 +289,7 @@ root=unprotected+encrypted:swap=absent+unused:=unprotected+encrypted+absent .\} .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBsystemd-dissect\fR(1), -\fBsystemd-gpt-auto-generator\fR(8), -\fBsystemd-sysext\fR(8), -\fBsystemd-analyze\fR(8) +\fBsystemd\fR(1), \fBsystemd-dissect\fR(1), \fBsystemd-gpt-auto-generator\fR(8), \fBsystemd-sysext\fR(8), \fBsystemd-analyze\fR(8) .SH "NOTES" .IP " 1." 4 Discoverable Partitions Specification diff --git a/upstream/debian-unstable/man7/systemd.index.7 b/upstream/debian-unstable/man7/systemd.index.7 index 79cb5db4..87961757 100644 --- a/upstream/debian-unstable/man7/systemd.index.7 +++ b/upstream/debian-unstable/man7/systemd.index.7 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\&.INDEX" "7" "" "systemd 255" "systemd.index" +.TH "SYSTEMD\&.INDEX" "7" "" "systemd 256~rc3" "systemd.index" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -44,6 +44,9 @@ systemd.index \- List all manpages from the systemd project .SH "C" .PP +\fBcapsule@.service\fR(5) +\(em System unit for the capsule service manager +.br \fBcoredump.conf\fR(5) \(em Core dump storage configuration files .br @@ -107,6 +110,9 @@ systemd.index \- List all manpages from the systemd project .SH "I" .PP +\fBimportctl\fR(1) +\(em Download, import or export disk images +.br \fBinit\fR(1) \(em systemd system and service manager .br @@ -350,6 +356,9 @@ systemd.index \- List all manpages from the systemd project \fBresolved.conf.d\fR(5) \(em Network Name Resolution configuration files .br +\fBrun0\fR(1) +\(em Elevate privileges +.br \fBrunlevel\fR(8) \(em Print previous and current SysV runlevel .br @@ -503,6 +512,9 @@ systemd.index \- List all manpages from the systemd project \fBsd_bus_creds_get_pid\fR(3) \(em Retrieve fields from a credentials object .br +\fBsd_bus_creds_get_pidfd_dup\fR(3) +\(em Retrieve fields from a credentials object +.br \fBsd_bus_creds_get_ppid\fR(3) \(em Retrieve fields from a credentials object .br @@ -566,6 +578,9 @@ systemd.index \- List all manpages from the systemd project \fBsd_bus_creds_new_from_pid\fR(3) \(em Retrieve credentials object for the specified PID .br +\fBsd_bus_creds_new_from_pidfd\fR(3) +\(em Retrieve credentials object for the specified PID +.br \fBsd_bus_creds_ref\fR(3) \(em Retrieve credentials object for the specified PID .br @@ -1733,6 +1748,9 @@ systemd.index \- List all manpages from the systemd project \fBsd_event_source_get_inotify_mask\fR(3) \(em Add an "inotify" file system inode event source to an event loop .br +\fBsd_event_source_get_inotify_path\fR(3) +\(em Add an "inotify" file system inode event source to an event loop +.br \fBsd_event_source_get_io_events\fR(3) \(em Add an I/O event source to an event loop .br @@ -2240,6 +2258,9 @@ systemd.index \- List all manpages from the systemd project \fBsd_journal_stream_fd\fR(3) \(em Create log stream file descriptor to the journal .br +\fBsd_journal_stream_fd_with_namespace\fR(3) +\(em Create log stream file descriptor to the journal +.br \fBSD_JOURNAL_SUPPRESS_LOCATION\fR(3) \(em Submit log entries to the journal .br @@ -2568,10 +2589,10 @@ systemd.index \- List all manpages from the systemd project \(em Refresh boot loader random seed at boot .br \fBsystemd-bsod\fR(8) -\(em Displays boot\-time emergency log message in full screen\&. +\(em Displays boot\-time emergency log message in full screen .br \fBsystemd-bsod.service\fR(8) -\(em Displays boot\-time emergency log message in full screen\&. +\(em Displays boot\-time emergency log message in full screen .br \fBsystemd-cat\fR(1) \(em Connect a pipeline or program\*(Aqs output with the journal @@ -2648,15 +2669,6 @@ systemd.index \- List all manpages from the systemd project \fBsystemd-fsck@.service\fR(8) \(em File system checker logic .br -\fBsystemd-fsckd\fR(8) -\(em File system check progress reporting -.br -\fBsystemd-fsckd.service\fR(8) -\(em File system check progress reporting -.br -\fBsystemd-fsckd.socket\fR(8) -\(em File system check progress reporting -.br \fBsystemd-fstab-generator\fR(8) \(em Unit generator for /etc/fstab .br @@ -2678,6 +2690,9 @@ systemd.index \- List all manpages from the systemd project \fBsystemd-halt.service\fR(8) \(em System shutdown logic .br +\fBsystemd-hibernate-clear.service\fR(8) +\(em Resume from hibernation +.br \fBsystemd-hibernate-resume\fR(8) \(em Resume from hibernation .br @@ -2693,6 +2708,9 @@ systemd.index \- List all manpages from the systemd project \fBsystemd-homed\fR(8) \(em Home Area/User Account Manager .br +\fBsystemd-homed-firstboot.service\fR(1) +\(em Create, remove, change or inspect home directories +.br \fBsystemd-homed.service\fR(8) \(em Home Area/User Account Manager .br @@ -2834,6 +2852,12 @@ systemd.index \- List all manpages from the systemd project \fBsystemd-mount\fR(1) \(em Establish and destroy transient mount or auto\-mount points .br +\fBsystemd-mountfsd\fR(8) +\(em Disk Image File System Mount Service +.br +\fBsystemd-mountfsd.service\fR(8) +\(em Disk Image File System Mount Service +.br \fBsystemd-network-generator\fR(8) \(em Generate network configuration from the kernel command line .br @@ -2861,6 +2885,12 @@ systemd.index \- List all manpages from the systemd project \fBsystemd-nspawn\fR(1) \(em Spawn a command or OS in a light\-weight container .br +\fBsystemd-nsresourced\fR(8) +\(em User Namespace Resource Delegation Service +.br +\fBsystemd-nsresourced.service\fR(8) +\(em User Namespace Resource Delegation Service +.br \fBsystemd-oomd\fR(8) \(em A userspace out\-of\-memory (OOM) killer .br @@ -2999,6 +3029,12 @@ systemd.index \- List all manpages from the systemd project \fBsystemd-soft-reboot.service\fR(8) \(em Userspace reboot operation .br +\fBsystemd-ssh-generator\fR(8) +\(em Generator for binding a socket\-activated SSH server to local AF_VSOCK and AF_UNIX sockets +.br +\fBsystemd-ssh-proxy\fR(1) +\(em SSH client plugin for connecting to AF_VSOCK and AF_UNIX sockets +.br \fBsystemd-stdio-bridge\fR(1) \(em D\-Bus proxy .br @@ -3078,22 +3114,25 @@ systemd.index \- List all manpages from the systemd project \(em Network Time Synchronization .br \fBsystemd-tmpfiles\fR(8) -\(em Creates, deletes and cleans up volatile and temporary files and directories +\(em Create, delete, and clean up files and directories .br \fBsystemd-tmpfiles-clean.service\fR(8) -\(em Creates, deletes and cleans up volatile and temporary files and directories +\(em Create, delete, and clean up files and directories .br \fBsystemd-tmpfiles-clean.timer\fR(8) -\(em Creates, deletes and cleans up volatile and temporary files and directories +\(em Create, delete, and clean up files and directories .br \fBsystemd-tmpfiles-setup-dev-early.service\fR(8) -\(em Creates, deletes and cleans up volatile and temporary files and directories +\(em Create, delete, and clean up files and directories .br \fBsystemd-tmpfiles-setup-dev.service\fR(8) -\(em Creates, deletes and cleans up volatile and temporary files and directories +\(em Create, delete, and clean up files and directories .br \fBsystemd-tmpfiles-setup.service\fR(8) -\(em Creates, deletes and cleans up volatile and temporary files and directories +\(em Create, delete, and clean up files and directories +.br +\fBsystemd-tpm2-generator\fR(8) +\(em Generator for inserting TPM2 synchronization point in the boot process .br \fBsystemd-tpm2-setup\fR(8) \(em Set up the TPM2 Storage Root Key (SRK) at boot @@ -3173,6 +3212,9 @@ systemd.index \- List all manpages from the systemd project \fBsystemd-volatile-root.service\fR(8) \(em Make the root file system volatile .br +\fBsystemd-vpick\fR(1) +\(em Resolve paths to \&.v/ versioned directories +.br \fBsystemd-xdg-autostart-generator\fR(8) \(em User unit generator for XDG autostart files .br @@ -3284,6 +3326,9 @@ systemd.index \- List all manpages from the systemd project \fBsystemd.unit\fR(5) \(em Unit configuration .br +\fBsystemd.v\fR(7) +\(em Directory with Versioned Resources +.br \fBsysupdate.d\fR(5) \(em Transfer Definition Files for Automatic Updates .br @@ -3306,7 +3351,7 @@ systemd.index \- List all manpages from the systemd project \(em Network Time Synchronization configuration files .br \fBtmpfiles.d\fR(5) -\(em Configuration for creation, deletion and cleaning of volatile and temporary files +\(em Configuration for creation, deletion, and cleaning of files and directories .br .SH "U" @@ -3317,6 +3362,9 @@ systemd.index \- List all manpages from the systemd project \fBudev.conf\fR(5) \(em Configuration for device event managing daemon .br +\fBudev.conf.d\fR(5) +\(em Configuration for device event managing daemon +.br \fBudev_device_get_action\fR(3) \(em Query device properties .br @@ -3553,4 +3601,4 @@ systemd.index \- List all manpages from the systemd project .PP \fBsystemd.directives\fR(7) .PP -This index contains 1156 entries, referring to 395 individual manual pages\&. +This index contains 1172 entries, referring to 404 individual manual pages\&. diff --git a/upstream/debian-unstable/man7/systemd.journal-fields.7 b/upstream/debian-unstable/man7/systemd.journal-fields.7 index fbc0084d..0f0de6ae 100644 --- a/upstream/debian-unstable/man7/systemd.journal-fields.7 +++ b/upstream/debian-unstable/man7/systemd.journal-fields.7 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\&.JOURNAL\-FIELDS" "7" "" "systemd 255" "systemd.journal-fields" +.TH "SYSTEMD\&.JOURNAL\-FIELDS" "7" "" "systemd 256~rc3" "systemd.journal-fields" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -407,6 +407,15 @@ is described, instead of the process which logged the message\&. .sp Added in version 205\&. .RE +.PP +\fIOBJECT_SYSTEMD_INVOCATION_ID=\fR +.RS 4 +An additional field added automatically by +\fBsystemd\-journald\fR\&. The meaning is mostly the same as +\fI_SYSTEMD_INVOCATION_ID=\fR, with the difference described above\&. +.sp +Added in version 235\&. +.RE .SH "ADDRESS FIELDS" .PP During serialization into external formats, such as the @@ -443,13 +452,7 @@ Added in version 254\&. .RE .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBsystemd-journald.service\fR(8), -\fBjournalctl\fR(1), -\fBjournald.conf\fR(5), -\fBsd-journal\fR(3), -\fBcoredumpctl\fR(1), -\fBsystemd.directives\fR(7) +\fBsystemd\fR(1), \fBsystemd-journald.service\fR(8), \fBjournalctl\fR(1), \fBjournald.conf\fR(5), \fBsd-journal\fR(3), \fBcoredumpctl\fR(1), \fBsystemd.directives\fR(7) .SH "NOTES" .IP " 1." 4 Journal Export Format diff --git a/upstream/debian-unstable/man7/systemd.net-naming-scheme.7 b/upstream/debian-unstable/man7/systemd.net-naming-scheme.7 index b0d4fe7b..28ef2fa9 100644 --- a/upstream/debian-unstable/man7/systemd.net-naming-scheme.7 +++ b/upstream/debian-unstable/man7/systemd.net-naming-scheme.7 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\&.NET\-NAMING\-SCHEME" "7" "" "systemd 255" "systemd.net-naming-scheme" +.TH "SYSTEMD\&.NET\-NAMING\-SCHEME" "7" "" "systemd 256~rc3" "systemd.net-naming-scheme" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -33,7 +33,7 @@ and exported as udev properties (\fIID_NET_NAME_ONBOARD=\fR, \fIID_NET_NAME_SLOT=\fR)\&. .PP Names and MAC addresses are derived from various stable device metadata attributes\&. Newer versions of udev take more of these attributes into account, improving (and thus possibly changing) the names and addresses used for the same devices\&. Different versions of those generation rules are called "naming schemes"\&. The default naming scheme is chosen at compilation time\&. Usually this will be the latest implemented version, but it is also possible to set one of the older versions to preserve compatibility\&. This may be useful for example for distributions, which may introduce new versions of systemd in stable releases without changing the naming scheme\&. The naming scheme may also be overridden using the -\fInet\&.naming\-scheme=\fR +\fInet\&.naming_scheme=\fR kernel command line switch, see \fBsystemd-udevd.service\fR(8)\&. Available naming schemes are described below\&. .PP @@ -103,7 +103,7 @@ The udev \fBnet_id\fR builtin exports the following udev device properties: .PP -\fIID_NET_NAME_ONBOARD=\fR\fI\fIprefix\fR\fR\fI\fBo\fR\fR\fI\fInumber\fR\fR, \fIID_NET_NAME_ONBOARD=\fR\fI\fIprefix\fR\fR\fI\fBd\fR\fR\fI\fInumber\fR\fR +\fIID_NET_NAME_ONBOARD=\fR\fIprefix\fR\fBo\fR\fInumber\fR, \fIID_NET_NAME_ONBOARD=\fR\fIprefix\fR\fBd\fR\fInumber\fR .RS 4 This name is set based on the numeric ordering information given by the firmware for on\-board devices\&. Different schemes are used depending on the firmware type, as described in the table below\&. .sp @@ -138,14 +138,14 @@ T} Added in version 243\&. .RE .PP -\fIID_NET_LABEL_ONBOARD=\fR\fI\fIprefix\fR\fR\fI \fR\fI\fIlabel\fR\fR +\fIID_NET_LABEL_ONBOARD=\fR\fIprefix\fR \fIlabel\fR .RS 4 This property is set based on textual label given by the firmware for on\-board devices\&. The name consists of the prefix concatenated with the label\&. This is only available for PCI devices\&. .sp Added in version 243\&. .RE .PP -\fIID_NET_NAME_MAC=\fR\fI\fIprefix\fR\fR\fI\fBx\fR\fR\fI\fIAABBCCDDEEFF\fR\fR +\fIID_NET_NAME_MAC=\fR\fIprefix\fR\fBx\fR\fIAABBCCDDEEFF\fR .RS 4 This name consists of the prefix, letter \fBx\fR, and 12 hexadecimal digits of the MAC address\&. It is available if the device has a fixed MAC address\&. Because this name is based on an attribute of the card itself, it remains "stable" when the device is moved (even between machines), but will change when the hardware is replaced\&. @@ -153,7 +153,7 @@ This name consists of the prefix, letter Added in version 243\&. .RE .PP -\fIID_NET_NAME_SLOT=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIport_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR, \fIID_NET_NAME_SLOT=\fR\fI\fIprefix\fR\fR\fI\fBv\fR\fR\fI\fIslot\fR\fR, \fIID_NET_NAME_SLOT=\fR\fI\fIprefix\fR\fR\fI\fBx\fR\fR\fI\fIslot\fR\fR, \fIID_NET_NAME_SLOT=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIport_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR\fI\fBb\fR\fR\fI\fInumber\fR\fR, \fIID_NET_NAME_SLOT=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIport_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR\fI\fBu\fR\fR\fI\fIport\fR\fR\fI\&...[\fR\fI\fBc\fR\fR\fI\fIconfig\fR\fR\fI][\fR\fI\fBi\fR\fR\fI\fIinterface\fR\fR\fI]\fR, \fIID_NET_NAME_SLOT=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIport_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR\fI\fBv\fR\fR\fI\fIslot\fR\fR, \fIID_NET_NAME_SLOT=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIport_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR\fI\fBr\fR\fR\fI\fIslot\fR\fR +\fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR], \fIID_NET_NAME_SLOT=\fR\fIprefix\fR\fBv\fR\fIslot\fR, \fIID_NET_NAME_SLOT=\fR\fIprefix\fR\fBx\fR\fIslot\fR, \fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR]\fBb\fR\fInumber\fR, \fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR]\fBu\fR\fIport\fR\&...[\fBc\fR\fIconfig\fR][\fBi\fR\fIinterface\fR], \fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR]\fBv\fR\fIslot\fR, \fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR]\fBr\fR\fIslot\fR .RS 4 This property describes the slot position\&. Different schemes are used depending on the bus type, as described in the table below\&. In case of USB, BCMA, and SR\-VIO devices, the full name consists of the prefix, PCI slot identifier, and USB or BCMA or SR\-VIO slot identifier\&. The first two parts are denoted as "\&..." in the table below\&. .sp @@ -216,7 +216,7 @@ T} .TE .sp 1 The PCI domain is only prepended when it is not 0\&. All multi\-function PCI devices will carry the -\fBf\fR\fB\fIfunction\fR\fR +\fBf\fR\fIfunction\fR number in the device name, including the function 0 device\&. For non\-multi\-function devices, the number is suppressed if 0\&. The port name \fIport_name\fR is used, or the port number @@ -240,7 +240,7 @@ In some configurations a parent PCI bridge of a given network controller may be Added in version 243\&. .RE .PP -\fIID_NET_NAME_PATH=\fR\fI\fIprefix\fR\fR\fI\fBc\fR\fR\fI\fIbus_id\fR\fR, \fIID_NET_NAME_PATH=\fR\fI\fIprefix\fR\fR\fI\fBa\fR\fR\fI\fIvendor\fR\fR\fI\fImodel\fR\fR\fI\fBi\fR\fR\fI\fIinstance\fR\fR, \fIID_NET_NAME_PATH=\fR\fI\fIprefix\fR\fR\fI\fBi\fR\fR\fI\fIaddress\fR\fR\fI\fBn\fR\fR\fI\fIport_name\fR\fR, \fIID_NET_NAME_PATH=\fR\fI\fIprefix\fR\fR\fI\fBu\fR\fR\fI\fIport\fR\fR\fI\&...\fR, \fIID_NET_NAME_PATH=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBp\fR\fR\fI\fIbus\fR\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIphys_port_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR, \fIID_NET_NAME_PATH=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBp\fR\fR\fI\fIbus\fR\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIphys_port_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR\fI\fBb\fR\fR\fI\fInumber\fR\fR, \fIID_NET_NAME_PATH=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBp\fR\fR\fI\fIbus\fR\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIphys_port_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR\fI\fBu\fR\fR\fI\fIport\fR\fR\fI\&...[\fR\fI\fBc\fR\fR\fI\fIconfig\fR\fR\fI][\fR\fI\fBi\fR\fR\fI\fIinterface\fR\fR\fI]\fR +\fIID_NET_NAME_PATH=\fR\fIprefix\fR\fBc\fR\fIbus_id\fR, \fIID_NET_NAME_PATH=\fR\fIprefix\fR\fBa\fR\fIvendor\fR\fImodel\fR\fBi\fR\fIinstance\fR, \fIID_NET_NAME_PATH=\fR\fIprefix\fR\fBi\fR\fIaddress\fR\fBn\fR\fIport_name\fR, \fIID_NET_NAME_PATH=\fR\fIprefix\fR\fBu\fR\fIport\fR\&..., \fIID_NET_NAME_PATH=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBp\fR\fIbus\fR\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIphys_port_name\fR|\fBd\fR\fIdev_port\fR], \fIID_NET_NAME_PATH=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBp\fR\fIbus\fR\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIphys_port_name\fR|\fBd\fR\fIdev_port\fR]\fBb\fR\fInumber\fR, \fIID_NET_NAME_PATH=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBp\fR\fIbus\fR\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIphys_port_name\fR|\fBd\fR\fIdev_port\fR]\fBu\fR\fIport\fR\&...[\fBc\fR\fIconfig\fR][\fBi\fR\fIinterface\fR] .RS 4 This property describes the device installation location\&. Different schemes are used depending on the bus type, as described in the table below\&. For BCMA and USB devices, PCI path information must known, and the full name consists of the prefix, PCI slot identifier, and USB or BCMA location\&. The first two parts are denoted as "\&..." in the table below\&. .sp @@ -305,7 +305,7 @@ Added in version 243\&. .SH "HISTORY" .PP The following "naming schemes" have been defined (which may be chosen at system boot\-up time via the -\fInet\&.naming\-scheme=\fR +\fInet\&.naming_scheme=\fR kernel command line switch, see above): .PP \fBv238\fR @@ -459,7 +459,7 @@ Added in version 253\&. Naming was changed for SR\-IOV virtual device representors, optionally settable at compilation time\&. The "r\fIslot\fR" suffix was added to differentiate SR\-IOV virtual device representors attached to a single physical device interface\&. Because of a mistake, this scheme was -\fInot the the default scheme for systemd version 254\fR\&. +\fInot the default scheme for systemd version 254\fR\&. .sp Added in version 255\&. .RE @@ -476,6 +476,38 @@ Added in version 255\&. Note that \fBlatest\fR may be used to denote the latest scheme known (to this particular version of systemd)\&. +.SH "LIMITING THE USE OF SPECIFIC SYSFS ATTRIBUTES" +.PP +When creating names for network cards, some naming schemes use data from sysfs populated by the kernel\&. This means that although a specific naming scheme in udev is picked, the network card\*(Aqs name can still change when a new kernel version adds a new sysfs attribute\&. For example if kernel starts setting the +\fBphys_port_name\fR, udev will append the "\fBn\fR\fIphys_port_name\fR" suffix to the device name\&. +.PP +\fIID_NET_NAME_ALLOW=\fR\fIBOOL\fR +.RS 4 +This udev property sets a fallback policy for reading a sysfs attribute\&. If set to +\fB0\fR +udev will not read any sysfs attribute by default, unless it is explicitly allowlisted, see below\&. If set to +\fB1\fR +udev can use any sysfs attribute unless it is explicitly forbidden\&. The default value is +\fB1\fR\&. +.sp +Added in version 256\&. +.RE +.PP +\fIID_NET_NAME_ALLOW_\fR\fI\fIsysfsattr\fR\fR\fI=\fR\fI\fIBOOL\fR\fR +.RS 4 +This udev property explicitly states if udev shall use the specified +\fIsysfsattr\fR, when composing the device name\&. +.sp +Added in version 256\&. +.RE +.PP +With these options, users can set an allowlist or denylist for sysfs attributes\&. To create an allowlist, the user needs to set +\fIID_NET_NAME_ALLOW=0\fR +for the device and then list the allowed attributes with the +\fIID_NET_NAME_ALLOW_\fR\fI\fIsysfsattr\fR\fR\fI=1\fR +options\&. In case of a denylist, the user needs to provide the list of denied attributes with the +\fIID_NET_NAME_ALLOW_\fR\fI\fIsysfsattr\fR\fR\fI=0\fR +options\&. .SH "EXAMPLES" .PP \fBExample\ \&1.\ \&Using udevadm test\-builtin to display device properties\fR @@ -615,12 +647,51 @@ ID_NET_NAME_PATH=encf5f0 .if n \{\ .RE .\} +.PP +\fBExample\ \&10.\ \&Set an allowlist for reading sysfs attributes for network card naming\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +/etc/udev/hwdb\&.d/50\-net\-naming\-allowlist\&.hwdb +net:naming:drvirtio_net:* + ID_NET_NAME_ALLOW=0 + ID_NET_NAME_ALLOW_ACPI_INDEX=1 + ID_NET_NAME_ALLOW_ADDR_ASSIGN_TYPE=1 + ID_NET_NAME_ALLOW_ADDRESS=1 + ID_NET_NAME_ALLOW_ARI_ENABLED=1 + ID_NET_NAME_ALLOW_DEV_PORT=1 + ID_NET_NAME_ALLOW_FUNCTION_ID=1 + ID_NET_NAME_ALLOW_IFLINK=1 + ID_NET_NAME_ALLOW_INDEX=1 + ID_NET_NAME_ALLOW_LABEL=1 + ID_NET_NAME_ALLOW_PHYS_PORT_NAME=1 + ID_NET_NAME_ALLOW_TYPE=1 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&11.\ \&Set a denylist so that specified sysfs attribute are ignored\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +/etc/udev/hwdb\&.d/50\-net\-naming\-denylist\&.hwdb +net:naming:drvirtio_net:* + ID_NET_NAME_ALLOW=1 + ID_NET_NAME_ALLOW_DEV_PORT=0 + ID_NET_NAME_ALLOW_PHYS_PORT_NAME=0 + +.fi +.if n \{\ +.RE +.\} .SH "SEE ALSO" .PP -\fBudev\fR(7), -\fBudevadm\fR(8), -\m[blue]\fBPredictable Network Interface Names\fR\m[]\&\s-2\u[1]\d\s+2, -\fBsystemd-nspawn\fR(1) +\fBudev\fR(7), \fBudevadm\fR(8), \m[blue]\fBPredictable Network Interface Names\fR\m[]\&\s-2\u[1]\d\s+2, \fBsystemd-nspawn\fR(1) .SH "NOTES" .IP " 1." 4 Predictable Network Interface Names diff --git a/upstream/debian-unstable/man7/systemd.offline-updates.7 b/upstream/debian-unstable/man7/systemd.offline-updates.7 index 3c098cce..f2ffdb15 100644 --- a/upstream/debian-unstable/man7/systemd.offline-updates.7 +++ b/upstream/debian-unstable/man7/systemd.offline-updates.7 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\&.OFFLINE\-UPDATES" "7" "" "systemd 255" "systemd.offline-updates" +.TH "SYSTEMD\&.OFFLINE\-UPDATES" "7" "" "systemd 256~rc3" "systemd.offline-updates" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -251,10 +251,7 @@ and add a symlink to that file under .RE .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBsystemd.generator\fR(7), -\fBsystemd-system-update-generator\fR(8), -\fBdnf.plugin.system-upgrade\fR(8) +\fBsystemd\fR(1), \fBsystemd.generator\fR(7), \fBsystemd-system-update-generator\fR(8), \fBdnf.plugin.system-upgrade\fR(8) .SH "NOTES" .IP " 1." 4 GNOME design whiteboard diff --git a/upstream/debian-unstable/man7/systemd.special.7 b/upstream/debian-unstable/man7/systemd.special.7 index 43e5332d..6596f118 100644 --- a/upstream/debian-unstable/man7/systemd.special.7 +++ b/upstream/debian-unstable/man7/systemd.special.7 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\&.SPECIAL" "7" "" "systemd 255" "systemd.special" +.TH "SYSTEMD\&.SPECIAL" "7" "" "systemd 256~rc3" "systemd.special" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -85,6 +85,7 @@ smartcard\&.target, sockets\&.target, soft\-reboot\&.target, sound\&.target, +ssh\-access\&.target, storage\-target\-mode\&.target, suspend\&.target, swap\&.target, @@ -94,12 +95,14 @@ system\-update\-pre\&.target, time\-set\&.target, time\-sync\&.target, timers\&.target, +tpm2\&.target, umount\&.target, usb\-gadget\&.target, \-\&.slice, +capsule\&.slice, +machine\&.slice, system\&.slice, user\&.slice, -machine\&.slice, \-\&.mount, dbus\&.service, dbus\&.socket, @@ -847,6 +850,19 @@ This may be used to pull in usb gadget dynamically when UDC hardware is found\&. .sp Added in version 242\&. .RE +.PP +tpm2\&.target +.RS 4 +This target is started automatically if a TPM2 device is discovered, either by the OS or by the firmware\&. It acts as synchronization point for services that require TPM2 device access\&. The target unit is enqueued by +\fBsystemd-tpm2-generator\fR(8) +if it detects that the firmware has discovered a TPM2 device but the OS kernel has not activated a driver for it yet\&. It is also pulled in whenever +\fBsystemd-udevd.service\fR(8) +discovers a TPM2 device\&. The target unit is ordered after the +/dev/tpmrm0 +device node, so that it only becomes active once the TPM2 device is actually accessible\&. Early boot programs that intend to access the TPM2 device should hence order themselves after this target unit, but not pull it in\&. +.sp +Added in version 256\&. +.RE .SS "Special Passive System Units" .PP A number of special system targets are defined that can be used to properly order boot\-up of optional services\&. These targets are generally not part of the initial boot transaction, unless they are explicitly pulled in by one of the implementing services\&. Note specifically that these @@ -1000,6 +1016,17 @@ for this target unit to all SysV init script service units with an LSB header re facility\&. .RE .PP +ssh\-access\&.target +.RS 4 +Service and socket units that provide remote SSH secure shell access to the local system should pull in this unit and order themselves before this unit\&. It\*(Aqs supposed to act as a milestone indicating if and when SSH access into the system is available\&. It should only become active when an SSH port is bound for remote clients (i\&.e\&. if SSH is used as a local privilege escalation mechanism, it should +\fInot\fR +involve this target unit), regardless of the protocol choices, i\&.e\&. regardless if IPv4, IPv6 or +\fBAF_VSOCK\fR +is used\&. +.sp +Added in version 256\&. +.RE +.PP time\-set\&.target .RS 4 Services responsible for setting the system clock (\fBCLOCK_REALTIME\fR) from a local source (such as a maintained timestamp file or imprecise real\-time clock) should pull in this target and order themselves before it\&. Services where approximate, roughly monotonic time is desired should be ordered after this unit, but not pull it in\&. @@ -1113,6 +1140,25 @@ The root slice is the root of the slice hierarchy\&. It usually does not contain Added in version 206\&. .RE .PP +machine\&.slice +.RS 4 +By default, all virtual machines and containers registered with +\fBsystemd\-machined\fR +are found in this slice\&. This is pulled in by +systemd\-machined\&.service\&. +.sp +Added in version 206\&. +.RE +.PP +capsule\&.slice +.RS 4 +By default, all capsules encapsulated in +capsule@\&.service +are found in this slice\&. +.sp +Added in version 255\&. +.RE +.PP system\&.slice .RS 4 By default, all system services started by @@ -1129,16 +1175,6 @@ systemd\-logind\&.service\&. .sp Added in version 206\&. .RE -.PP -machine\&.slice -.RS 4 -By default, all virtual machines and containers registered with -\fBsystemd\-machined\fR -are found in this slice\&. This is pulled in by -systemd\-machined\&.service\&. -.sp -Added in version 206\&. -.RE .SH "UNITS MANAGED BY THE USER SERVICE MANAGER" .SS "Special User Units" .PP @@ -1146,7 +1182,7 @@ When systemd runs as a user instance, the following special units are available: .PP default\&.target .RS 4 -This is the main target of the user session, started by default\&. Various services that compose the normal user session should be pulled into this target\&. In this regard, +This is the main target of the user service manager, started by default when the service manager is invoked\&. Various services that compose the normal user session should be pulled into this target\&. In this regard, default\&.target is similar to multi\-user\&.target @@ -1155,6 +1191,14 @@ in the system instance, but it is a real unit, not an alias\&. Added in version 242\&. .RE .PP +capsule@\&.target +.RS 4 +This is the main target of capsule service managers, started by default, instantiated with the capsule name\&. This may be used to define different sets of units that are started for different capsules via generic unit definitions\&. For details about capsules see +\fBcapsule@.service\fR(5)\&. +.sp +Added in version 255\&. +.RE +.PP In addition, the following units are available which have definitions similar to their system counterparts: exit\&.target, shutdown\&.target, @@ -1290,15 +1334,7 @@ Added in version 247\&. .RE .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBsystemd.unit\fR(5), -\fBsystemd.service\fR(5), -\fBsystemd.socket\fR(5), -\fBsystemd.target\fR(5), -\fBsystemd.slice\fR(5), -\fBbootup\fR(7), -\fBsystemd-fstab-generator\fR(8), -\fBuser@.service\fR(5) +\fBsystemd\fR(1), \fBsystemd.unit\fR(5), \fBsystemd.service\fR(5), \fBsystemd.socket\fR(5), \fBsystemd.target\fR(5), \fBsystemd.slice\fR(5), \fBbootup\fR(7), \fBsystemd-fstab-generator\fR(8), \fBuser@.service\fR(5) .SH "NOTES" .IP " 1." 4 Running Services After the Network Is Up diff --git a/upstream/debian-unstable/man7/systemd.syntax.7 b/upstream/debian-unstable/man7/systemd.syntax.7 index 7e334bb3..e6ba3086 100644 --- a/upstream/debian-unstable/man7/systemd.syntax.7 +++ b/upstream/debian-unstable/man7/systemd.syntax.7 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\&.SYNTAX" "7" "" "systemd 255" "systemd.syntax" +.TH "SYSTEMD\&.SYNTAX" "7" "" "systemd 256~rc3" "systemd.syntax" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -123,8 +123,6 @@ or are ignored, which may be used for commenting\&. .PP Lines ending in a backslash are concatenated with the following line while reading and the backslash is replaced by a space character\&. This may be used to wrap long lines\&. The limit on line length is very large (currently 1 MB), but it is recommended to avoid such long lines and use multiple directives, variable substitution, or other mechanism as appropriate for the given file type\&. When a comment line or lines follow a line ending with a backslash, the comment block is ignored, so the continued line is concatenated with whatever follows the comment block\&. -.PP -\fBExample\ \&1.\ \&\fR .sp .if n \{\ .RS 4 diff --git a/upstream/debian-unstable/man7/systemd.system-credentials.7 b/upstream/debian-unstable/man7/systemd.system-credentials.7 index 5ace9a31..b953256b 100644 --- a/upstream/debian-unstable/man7/systemd.system-credentials.7 +++ b/upstream/debian-unstable/man7/systemd.system-credentials.7 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\&.SYSTEM\-CREDENTIALS" "7" "" "systemd 255" "systemd.system-credentials" +.TH "SYSTEMD\&.SYSTEM\-CREDENTIALS" "7" "" "systemd 256~rc3" "systemd.system-credentials" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -118,6 +118,38 @@ DNS server information and search domains\&. Read by Added in version 253\&. .RE .PP +\fInetwork\&.conf\&.*\fR, \fInetwork\&.link\&.*\fR, \fInetwork\&.netdev\&.*\fR, \fInetwork\&.network\&.*\fR +.RS 4 +Configures network devices\&. Read by +\fBsystemd-network-generator.service\fR(8)\&. These credentials should contain valid +\fBnetworkd.conf\fR(5), +\fBsystemd.link\fR(5), +\fBsystemd.netdev\fR(5), +\fBsystemd.network\fR(5) +configuration data\&. From each matching credential a separate file is created\&. Example: the contents of a credential +network\&.link\&.50\-foobar +will be copied into a file +50\-foobar\&.link\&. +.sp +Note that the resulting files are created world\-readable, it\*(Aqs hence recommended to not include secrets in these credentials, but supply them via separate credentials directly to +systemd\-networkd\&.service, e\&.g\&. +\fInetwork\&.wireguard\&.*\fR +as described below\&. +.sp +Added in version 256\&. +.RE +.PP +\fInetwork\&.wireguard\&.*\fR +.RS 4 +Configures secrets for WireGuard netdevs\&. Read by +\fBsystemd-networkd.service\fR(8)\&. For more information, refer to the +\fB[WireGuard]\fR +section of +\fBsystemd.netdev\fR(5)\&. +.sp +Added in version 256\&. +.RE +.PP \fIpasswd\&.hashed\-password\&.root\fR, \fIpasswd\&.plaintext\-password\&.root\fR .RS 4 May contain the password (either in UNIX hashed format, or in plaintext) for the root users\&. Read by both @@ -151,6 +183,15 @@ Consumed by Added in version 252\&. .RE .PP +\fIssh\&.listen\fR +.RS 4 +May be used to configure SSH sockets the system shall be reachable on\&. See +\fBsystemd-ssh-generator\fR(8) +for details\&. +.sp +Added in version 256\&. +.RE +.PP \fIsysusers\&.extra\fR .RS 4 Additional @@ -204,6 +245,28 @@ for details\&. Added in version 254\&. .RE .PP +\fIjournal\&.forward_to_socket\fR +.RS 4 +Used by +\fBsystemd-journald\fR(8) +to determine where to forward log messages for socket forwarding, see +\fBjournald.conf\fR(5) +for details\&. +.sp +Added in version 256\&. +.RE +.PP +\fIjournal\&.storage\fR +.RS 4 +Used by +\fBsystemd-journald\fR(8) +to determine where to store journal files, see +\fBjournald.conf\fR(5) +for details\&. +.sp +Added in version 256\&. +.RE +.PP \fIvmm\&.notify_socket\fR .RS 4 Configures an @@ -223,11 +286,65 @@ Takes a 128bit ID to initialize the machine ID from (if it is not set yet)\&. In .sp Added in version 254\&. .RE +.PP +\fIsystem\&.hostname\fR +.RS 4 +Accepts a (transient) hostname to configure during early boot\&. The static hostname specified in +/etc/hostname, if configured, takes precedence over this setting\&. Interpreted by the service manager (PID 1)\&. For details see +\fBsystemd\fR(1)\&. +.sp +Added in version 254\&. +.RE +.PP +\fIhome\&.create\&.*\fR +.RS 4 +Creates a home area for the specified user with the user record data passed in\&. For details see +\fBhomectl\fR(1)\&. +.sp +Added in version 256\&. +.RE +.PP +\fIcryptsetup\&.passphrase\fR, \fIcryptsetup\&.tpm2\-pin\fR, \fIcryptsetup\&.fido2\-pin\fR, \fIcryptsetup\&.pkcs11\-pin\fR, \fIcryptsetup\&.luks2\-pin\fR +.RS 4 +Specifies the passphrase/PINs to use for unlock encrypted storage volumes\&. For details see +\fBsystemd-cryptsetup\fR(8)\&. +.sp +Added in version 256\&. +.RE +.PP +\fIsystemd\&.extra\-unit\&.*\fR, \fIsystemd\&.unit\-dropin\&.*\fR +.RS 4 +These credentials specify extra units and drop\-ins to add to the system\&. For details see +\fBsystemd-debug-generator\fR(8)\&. +.sp +Added in version 256\&. +.RE +.PP +\fIudev\&.conf\&.*\fR, \fIudev\&.rules\&.*\fR +.RS 4 +Configures udev configuration file and udev rules\&. Read by +systemd\-udev\-load\-credentials\&.service, which invokes +\fBudevadm control \-\-load\-credentials\fR\&. These credentials directly translate to a matching +\fBudev.conf\fR(5) +or +\fBudev\fR(7) +rules file\&. Example: the contents of a credential +udev\&.conf\&.50\-foobar +will be copied into a file +/run/udev/udev\&.conf\&.d/50\-foobar\&.conf, and +udev\&.rules\&.50\-foobar +will be copied into a file +/run/udev/rules\&.d/50\-foobar\&.rules\&. See +\fBudev\fR(7), +\fBudev.conf\fR(5), and +\fBudevadm\fR(8) +for details\&. +.sp +Added in version 256\&. +.RE .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBkernel-command-line\fR(7), -\fBsmbios-type-11\fR(7) +\fBsystemd\fR(1), \fBkernel-command-line\fR(7), \fBsmbios-type-11\fR(7) .SH "NOTES" .IP " 1." 4 System and Service Credentials diff --git a/upstream/debian-unstable/man7/systemd.time.7 b/upstream/debian-unstable/man7/systemd.time.7 index 39e552a7..3e3a776c 100644 --- a/upstream/debian-unstable/man7/systemd.time.7 +++ b/upstream/debian-unstable/man7/systemd.time.7 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\&.TIME" "7" "" "systemd 255" "systemd.time" +.TH "SYSTEMD\&.TIME" "7" "" "systemd 256~rc3" "systemd.time" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -452,12 +452,7 @@ command of to validate and normalize calendar time specifications for testing purposes\&. The tool also calculates when a specified calendar event would occur next\&. .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBjournalctl\fR(1), -\fBsystemd.timer\fR(5), -\fBsystemd.unit\fR(5), -\fBsystemd.directives\fR(7), -\fBsystemd-analyze\fR(1) +\fBsystemd\fR(1), \fBjournalctl\fR(1), \fBsystemd.timer\fR(5), \fBsystemd.unit\fR(5), \fBsystemd.directives\fR(7), \fBsystemd-analyze\fR(1) .SH "NOTES" .IP " 1." 4 RFC 3339 diff --git a/upstream/debian-unstable/man7/systemd.v.7 b/upstream/debian-unstable/man7/systemd.v.7 new file mode 100644 index 00000000..29139560 --- /dev/null +++ b/upstream/debian-unstable/man7/systemd.v.7 @@ -0,0 +1,343 @@ +'\" t +.TH "SYSTEMD\&.V" "7" "" "systemd 256~rc3" "systemd.v" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +systemd.v \- Directory with Versioned Resources +.SH "DESCRIPTION" +.PP +In various places systemd components accept paths whose trailing components have the +"\&.v/" +suffix, pointing to a directory\&. These components will then automatically look for suitable files inside the directory, do a version comparison and open the newest file found (by version)\&. Available since version v256\&. Specifically, two expressions are supported: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +When looking for files with a suffix +\fI\&.SUFFIX\fR, and a path +\&...\fIPATH\fR/\fINAME\fR\fI\&.SUFFIX\fR\&.v/ +is specified, then all files +\&...\fIPATH\fR/\fINAME\fR\fI\&.SUFFIX\fR\&.v/\fINAME\fR_*\fI\&.SUFFIX\fR +are enumerated, filtered, sorted and the newest file used\&. The primary sorting key is the +\fIvariable part\fR, here indicated by the wildcard +"*"\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +When a path +\&...\fIPATH\fR\&.v/\fINAME\fR___\fI\&.SUFFIX\fR +is specified (i\&.e\&. the penultimate component of the path ends in +"\&.v" +and the final component contains a triple underscore), then all files +\&...\fIPATH\fR\&.v/\fINAME\fR_*\fI\&.SUFFIX\fR +are enumerated, filtered, sorted and the newest file used (again, by the +\fIvariable part\fR, here indicated by the wildcard +"*")\&. +.RE +.PP +To illustrate this in an example, consider a directory +/var/lib/machines/mymachine\&.raw\&.v/, which is populated with three files: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +mymachine_7\&.5\&.13\&.raw +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +mymachine_7\&.5\&.14\&.raw +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +mymachine_7\&.6\&.0\&.raw +.RE +.PP +Invoke a tool such as +\fBsystemd-nspawn\fR(1) +with a command line like the following: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# systemd\-nspawn \-\-image=/var/lib/machines/mymachine\&.raw\&.v \-\-boot +.fi +.if n \{\ +.RE +.\} +.PP +Then this would automatically be resolved to the equivalent of: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# systemd\-nspawn \-\-image=/var/lib/machines/mymachine\&.raw\&.v/mymachine_7\&.6\&.0\&.raw \-\-boot +.fi +.if n \{\ +.RE +.\} +.PP +Much of systemd\*(Aqs functionality that expects a path to a disk image or OS directory hierarchy support the +"\&.v/" +versioned directory mechanism, for example +\fBsystemd-nspawn\fR(1), +\fBsystemd-dissect\fR(1) +or the +\fIRootDirectory=\fR/\fIRootImage=\fR +settings of service files (see +\fBsystemd.exec\fR(5))\&. +.PP +Use the +\fBsystemd-vpick\fR(1) +tool to resolve +"\&.v/" +paths from the command line, for example for usage in shell scripts\&. +.SH "FILTERING AND SORTING" +.PP +The variable part of the filenames in the +"\&.v/" +directories are filtered and compared primarily with a version comparison, implementing +\m[blue]\fBVersion Format Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. However, additional rules apply: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If the variable part is suffixed by one or two integer values ("tries left" and "tries done") in the formats ++\fILEFT\fR +or ++\fILEFT\fR\-\fIDONE\fR, then these indicate usage attempt counters\&. The idea is that each time before a file is attempted to be used, its "tries left" counter is decreased, and the "tries done" counter increased (simply by renaming the file)\&. When the file is successfully used (which for example could mean for an OS image: successfully booted) the counters are removed from the file name, indicating that the file has been validated to work correctly\&. This mechanism mirrors the boot assessment counters defined by +\m[blue]\fBAutomatic Boot Assessment\fR\m[]\&\s-2\u[2]\d\s+2\&. Any filenames with no boot counters or with a non\-zero "tries left" counter are sorted before filenames with a zero "tries left" counter\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Preceding the use counters (if they are specified), an optional CPU architecture identifier may be specified in the filename (separated from the version with an underscore), as defined in the architecture vocabulary of the +\fIConditionArchitecture=\fR +unit file setting, as documented in +\fBsystemd.unit\fR(5)\&. Files whose name indicates an architecture not supported locally are filtered and not considered for the version comparison\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The rest of the variable part is the version string\&. +.RE +.PP +Or in other words, the files in the +"\&.v/" +directories should follow one of these naming structures: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fINAME\fR_\fIVERSION\fR\fI\&.SUFFIX\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fINAME\fR_\fIVERSION\fR_\fIARCHITECTURE\fR\fI\&.SUFFIX\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fINAME\fR_\fIVERSION\fR+\fILEFT\fR\fI\&.SUFFIX\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fINAME\fR_\fIVERSION\fR+\fILEFT\fR\-\fIDONE\fR\fI\&.SUFFIX\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fINAME\fR_\fIVERSION\fR_\fIARCHITECTURE\fR+\fILEFT\fR\fI\&.SUFFIX\fR +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fINAME\fR_\fIVERSION\fR_\fIARCHITECTURE\fR+\fILEFT\fR\-\fIDONE\fR\fI\&.SUFFIX\fR +.RE +.SH "EXAMPLE" +.PP +Here\*(Aqs a more comprehensive example, further extending the one described above\&. Consider a directory +/var/lib/machines/mymachine\&.raw\&.v/, which is populated with the following files: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +mymachine_7\&.5\&.13\&.raw +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +mymachine_7\&.5\&.14_x86\-64\&.raw +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +mymachine_7\&.6\&.0_arm64\&.raw +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +mymachine_7\&.7\&.0_x86\-64+0\-5\&.raw +.RE +.PP +Now invoke the following command on an x86\-64 machine: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ systemd\-vpick \-\-suffix=\&.raw /var/lib/machines/mymachine\&.raw\&.v/ +.fi +.if n \{\ +.RE +.\} +.PP +This would resolve the specified path to +/var/lib/machines/mymachine\&.raw\&.v/mymachine_7\&.5\&.14_x86\-64\&.raw\&. Explanation: even though +mymachine_7\&.7\&.0_x86\-64+0\-5\&.raw +has the newest version, it is not preferred because its tries left counter is zero\&. And even though +mymachine_7\&.6\&.0_arm64\&.raw +has the second newest version it is also not considered, in this case because we operate on an x86_64 system and the image is intended for arm64 CPUs\&. Finally, the +mymachine_7\&.5\&.13\&.raw +image is not considered because it is older than +mymachine_7\&.5\&.14_x86\-64\&.raw\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), \fBsystemd-vpick\fR(1), \fBsystemd-nspawn\fR(1), \fBsystemd-dissect\fR(1), \fBsystemd.exec\fR(5), \fBsystemd-sysupdate\fR(1) +.SH "NOTES" +.IP " 1." 4 +Version Format Specification +.RS 4 +\%https://uapi-group.org/specifications/specs/version_format_specification/ +.RE +.IP " 2." 4 +Automatic Boot Assessment +.RS 4 +\%https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT/ +.RE diff --git a/upstream/debian-unstable/man7/sysvipc.7 b/upstream/debian-unstable/man7/sysvipc.7 index 307292c9..a70d9ad2 100644 --- a/upstream/debian-unstable/man7/sysvipc.7 +++ b/upstream/debian-unstable/man7/sysvipc.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sysvipc 7 2022-10-30 "Linux man-pages 6.05.01" +.TH sysvipc 7 2024-05-02 "Linux man-pages 6.8" .SH NAME sysvipc \- System V interprocess communication mechanisms .SH DESCRIPTION @@ -16,7 +16,7 @@ Each message can have an associated priority. POSIX message queues provide an alternative API for achieving the same result; see .BR mq_overview (7). -.PP +.P The System V message queue API consists of the following system calls: .TP .BR msgget (2) @@ -39,7 +39,7 @@ each semaphore in a set is a counting semaphore. POSIX semaphores provide an alternative API for achieving the same result; see .BR sem_overview (7). -.PP +.P The System V semaphore API consists of the following system calls: .TP .BR semget (2) @@ -57,7 +57,7 @@ System V shared memory allows processes to share a region a memory (a "segment"). POSIX shared memory is an alternative API for achieving the same result; see .BR shm_overview (7). -.PP +.P The System V shared memory API consists of the following system calls: .TP .BR shmget (2) diff --git a/upstream/debian-unstable/man7/tcp.7 b/upstream/debian-unstable/man7/tcp.7 index aec6b780..4306d975 100644 --- a/upstream/debian-unstable/man7/tcp.7 +++ b/upstream/debian-unstable/man7/tcp.7 @@ -88,7 +88,7 @@ .\" commit cd8ae85299d54155702a56811b2e035e63064d3d .\" Author: Eric Dumazet <edumazet@google.com> .\" -.TH tcp 7 2023-07-15 "Linux man-pages 6.05.01" +.TH tcp 7 2024-05-02 "Linux man-pages 6.8" .SH NAME tcp \- TCP protocol .SH SYNOPSIS @@ -96,7 +96,7 @@ tcp \- TCP protocol .B #include <sys/socket.h> .B #include <netinet/in.h> .B #include <netinet/tcp.h> -.PP +.P .IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);" .fi .SH DESCRIPTION @@ -112,7 +112,7 @@ retransmits lost packets. It generates and checks a per-packet checksum to catch transmission errors. TCP does not preserve record boundaries. -.PP +.P A newly created TCP socket has no remote or local address and is not fully specified. To create an outgoing TCP connection use @@ -131,7 +131,7 @@ or .BR connect (2) successfully called on it is fully specified and may transmit data. Data cannot be transmitted on listening or not yet connected sockets. -.PP +.P Linux supports RFC\ 1323 TCP high performance extensions. These include Protection Against Wrapped @@ -151,7 +151,7 @@ and socket options with the .BR setsockopt (2) call. -.PP +.P The maximum sizes for socket buffers declared via the .B SO_SNDBUF and @@ -182,7 +182,7 @@ calls in order to have it take effect. See .BR socket (7) for more information. -.PP +.P TCP supports urgent data. Urgent data is used to signal the receiver that some important message is part of the data @@ -214,7 +214,7 @@ flag is set for .BR recv (2) or .BR recvmsg (2). -.PP +.P When out-of-band data is present, .BR select (2) indicates the file descriptor as having an exceptional condition and @@ -222,7 +222,7 @@ indicates the file descriptor as having an exceptional condition and indicates a .B POLLPRI event. -.PP +.P Linux 2.4 introduced a number of changes for improved throughput and scaling, as well as enhanced functionality. Some of these features include support for zero-copy @@ -1068,7 +1068,7 @@ most socket options are valid on TCP sockets. For more information see .BR ip (7). -.PP +.P Following is a list of TCP-specific socket options. For details of some other socket options that are also applicable for TCP sockets, see @@ -1368,19 +1368,19 @@ the stream (even when .B SO_OOBINLINE is not set). This differs from BSD-based stacks. -.PP +.P Linux uses the BSD compatible interpretation of the urgent pointer field by default. This violates RFC\ 1122, but is required for interoperability with other stacks. It can be changed via .IR /proc/sys/net/ipv4/tcp_stdurg . -.PP +.P It is possible to peek at out-of-band data using the .BR recv (2) .B MSG_PEEK flag. -.PP +.P Since Linux 2.4, Linux supports the use of .B MSG_TRUNC in the @@ -1402,14 +1402,14 @@ The following calls return information in .IR value . The correct syntax is: -.PP +.P .RS .nf .BI int " value"; .IB error " = ioctl(" tcp_socket ", " ioctl_type ", &" value ");" .fi .RE -.PP +.P .I ioctl_type is one of the following: .TP @@ -1484,7 +1484,7 @@ When a network error occurs, TCP tries to resend the packet. If it doesn't succeed after some time, either .B ETIMEDOUT or the last received error on this connection is reported. -.PP +.P Some applications require a quicker error notification. This can be enabled with the .B IPPROTO_IP @@ -1509,7 +1509,7 @@ executed on a shut down socket. .TP .B ETIMEDOUT The other end didn't acknowledge retransmitted data after some time. -.PP +.P Any errors defined for .BR ip (7) or the generic socket layer may also be returned for TCP. @@ -1522,7 +1522,7 @@ Support for forward acknowledgement (FACK), TIME_WAIT recycling, and per-connection keepalive socket options were introduced in Linux 2.3. .SH BUGS Not all errors are documented. -.PP +.P IPv6 is not described. .\" Only a single Linux kernel version is described .\" Info for 2.2 was lost. Should be added again, @@ -1544,10 +1544,10 @@ IPv6 is not described. .BR socket (2), .BR ip (7), .BR socket (7) -.PP +.P The kernel source file .IR Documentation/networking/ip\-sysctl.txt . -.PP +.P RFC\ 793 for the TCP specification. .br RFC\ 1122 for the TCP requirements and a description of the Nagle algorithm. diff --git a/upstream/debian-unstable/man7/term.7 b/upstream/debian-unstable/man7/term.7 index 9c114775..9bd2ecf2 100644 --- a/upstream/debian-unstable/man7/term.7 +++ b/upstream/debian-unstable/man7/term.7 @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2021,2023 Thomas E. Dickey * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * .\" Copyright 1998-2011,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: term.7,v 1.46 2023/12/02 20:51:25 tom Exp $ -.TH term 7 2023-12-02 "ncurses 6.4" Miscellaneous +.\" $Id: term.7,v 1.48 2024/03/16 15:35:01 tom Exp $ +.TH term 7 2024-03-16 "ncurses 6.5" Miscellaneous .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq diff --git a/upstream/debian-unstable/man7/termio.7 b/upstream/debian-unstable/man7/termio.7 index 08bba54e..57076040 100644 --- a/upstream/debian-unstable/man7/termio.7 +++ b/upstream/debian-unstable/man7/termio.7 @@ -4,7 +4,7 @@ .\" .\" 28 Dec 2006 - Initial Creation .\" -.TH termio 7 2022-10-30 "Linux man-pages 6.05.01" +.TH termio 7 2024-05-02 "Linux man-pages 6.8" .SH NAME termio \- System V terminal driver interface .SH DESCRIPTION @@ -15,7 +15,7 @@ This interface defined a structure used to store terminal settings, and a range of .BR ioctl (2) operations to get and set terminal attributes. -.PP +.P The .B termio interface is now obsolete: POSIX.1-1990 standardized a modified @@ -30,7 +30,7 @@ operations that existed in System V. .BR ioctl (2) was unstandardized, and its variadic third argument does not allow argument type checking.) -.PP +.P If you're looking for a page called "termio", then you can probably find most of the information that you seek in either .BR termios (3) diff --git a/upstream/debian-unstable/man7/thread-keyring.7 b/upstream/debian-unstable/man7/thread-keyring.7 index 524bf227..ceefb4a4 100644 --- a/upstream/debian-unstable/man7/thread-keyring.7 +++ b/upstream/debian-unstable/man7/thread-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH thread-keyring 7 2022-10-30 "Linux man-pages 6.05.01" +.TH thread-keyring 7 2024-05-02 "Linux man-pages 6.8" .SH NAME thread-keyring \- per-thread keyring .SH DESCRIPTION @@ -11,19 +11,19 @@ The thread keyring is a keyring used to anchor keys on behalf of a process. It is created only when a thread requests it. The thread keyring has the name (description) .IR _tid . -.PP +.P A special serial number value, .BR KEY_SPEC_THREAD_KEYRING , is defined that can be used in lieu of the actual serial number of the calling thread's thread keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@t\fP' can be used instead of a numeric key ID in much the same way, but as .BR keyctl (1) is a program run after forking, this is of no utility. -.PP +.P Thread keyrings are not inherited across .BR clone (2) and @@ -31,7 +31,7 @@ and and are cleared by .BR execve (2). A thread keyring is destroyed when the thread that refers to it terminates. -.PP +.P Initially, a thread does not have a thread keyring. If a thread doesn't have a thread keyring when it is accessed, then it will be created if it is to be modified; diff --git a/upstream/debian-unstable/man7/time.7 b/upstream/debian-unstable/man7/time.7 index ee0db5d8..e3b03b1b 100644 --- a/upstream/debian-unstable/man7/time.7 +++ b/upstream/debian-unstable/man7/time.7 @@ -5,7 +5,7 @@ .\" 2008-06-24, mtk: added some details about where jiffies come into .\" play; added section on high-resolution timers. .\" -.TH time 7 2023-01-22 "Linux man-pages 6.05.01" +.TH time 7 2024-05-02 "Linux man-pages 6.8" .SH NAME time \- overview of time and timers .SH DESCRIPTION @@ -16,7 +16,7 @@ either from a standard point in the past (see the description of the Epoch and calendar time below), or from some point (e.g., the start) in the life of a process .RI ( "elapsed time" ). -.PP +.P .I "Process time" is defined as the amount of CPU time used by a process. This is sometimes divided into @@ -58,7 +58,7 @@ a clock maintained by the kernel which measures time in .IR jiffies . The size of a jiffy is determined by the value of the kernel constant .IR HZ . -.PP +.P The value of .I HZ varies across kernel versions and hardware platforms. @@ -75,7 +75,7 @@ yielding a jiffies value of, respectively, 0.01, 0.004, or 0.001 seconds. Since Linux 2.6.20, a further frequency is available: 300, a number that divides evenly for the common video frame rates (PAL, 25 Hz; NTSC, 30 Hz). -.PP +.P The .BR times (2) system call is a special case. @@ -99,7 +99,7 @@ The values of certain clocks are virtualized by time namespaces; see .SS High-resolution timers Before Linux 2.6.21, the accuracy of timer and sleep system calls (see below) was also limited by the size of the jiffy. -.PP +.P Since Linux 2.6.21, Linux supports high-resolution timers (HRTs), optionally configurable via .BR CONFIG_HIGH_RES_TIMERS . @@ -112,14 +112,14 @@ checking the resolution returned by a call to .BR clock_getres (2) or looking at the "resolution" entries in .IR /proc/timer_list . -.PP +.P HRTs are not supported on all hardware architectures. (Support is provided on x86, ARM, and PowerPC, among others.) .SS The Epoch UNIX systems represent time in seconds since the .IR Epoch , 1970-01-01 00:00:00 +0000 (UTC). -.PP +.P A program can determine the .I "calendar time" via the @@ -159,7 +159,7 @@ Various system calls and functions allow a program to sleep .BR clock_nanosleep (2), and .BR sleep (3). -.PP +.P Various system calls allow a process to set a timer that expires at some point in the future, and optionally at repeated intervals; see diff --git a/upstream/debian-unstable/man7/time_namespaces.7 b/upstream/debian-unstable/man7/time_namespaces.7 index 6e299962..3324f0dc 100644 --- a/upstream/debian-unstable/man7/time_namespaces.7 +++ b/upstream/debian-unstable/man7/time_namespaces.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH time_namespaces 7 2023-03-12 "Linux man-pages 6.05.01" +.TH time_namespaces 7 2024-05-02 "Linux man-pages 6.8" .SH NAME time_namespaces \- overview of Linux time namespaces .SH DESCRIPTION @@ -23,7 +23,7 @@ described by POSIX\[em]"some unspecified point in the past". a nonsettable clock that is identical to .BR CLOCK_MONOTONIC , except that it also includes any time that the system is suspended. -.PP +.P Thus, the processes in a time namespace share per-namespace values for these clocks. This affects various APIs that measure against these clocks, including: @@ -34,7 +34,7 @@ This affects various APIs that measure against these clocks, including: .BR timerfd_settime (2), and .IR /proc/uptime . -.PP +.P Currently, the only way to create a time namespace is by calling .BR unshare (2) with the @@ -66,13 +66,13 @@ These offsets are exposed via the file Within this file, the offsets are expressed as lines consisting of three space-delimited fields: -.PP +.P .in +4n .EX <clock-id> <offset-secs> <offset-nanosecs> .EE .in -.PP +.P The .I clock-id is a string that identifies the clock whose offsets are being shown. @@ -93,11 +93,11 @@ The value can be negative, subject to restrictions noted below; .I offset-nanosecs is an unsigned value. -.PP +.P In the initial time namespace, the contents of the .I timens_offsets file are as follows: -.PP +.P .in +4n .EX $ \fBcat /proc/self/timens_offsets\fP @@ -105,7 +105,7 @@ monotonic 0 0 boottime 0 0 .EE .in -.PP +.P In a new time namespace that has had no member processes, the clock offsets can be modified by writing newline-terminated records of the same form to the @@ -121,7 +121,7 @@ In order to write to the file, a process must have the .B CAP_SYS_TIME capability in the user namespace that owns the time namespace. -.PP +.P Writes to the .I timens_offsets file can fail with the following errors: @@ -158,7 +158,7 @@ inside the namespace would exceed half of the value of the kernel constant .B KTIME_SEC_MAX (this limits the clock value to a maximum of approximately 146 years). .RE -.PP +.P In a new time namespace created by .BR unshare (2), the contents of the @@ -168,13 +168,13 @@ file are inherited from the time namespace of the creating process. Use of time namespaces requires a kernel that is configured with the .B CONFIG_TIME_NS option. -.PP +.P Note that time namespaces do not virtualize the .B CLOCK_REALTIME clock. Virtualization of this clock was avoided for reasons of complexity and overhead within the kernel. -.PP +.P For compatibility with the initial implementation, when writing a .I clock-id to the @@ -185,7 +185,7 @@ instead of the symbolic names show above; i.e., 1 instead of and 7 instead of .IR boottime . For readability, the use of the symbolic names over the numbers is preferred. -.PP +.P The motivation for adding time namespaces was to allow the monotonic and boot-time clocks to maintain consistent values during container migration and checkpoint/restore. @@ -193,14 +193,14 @@ during container migration and checkpoint/restore. The following shell session demonstrates the operation of time namespaces. We begin by displaying the inode number of the time namespace of a shell in the initial time namespace: -.PP +.P .in +4n .EX $ \fBreadlink /proc/$$/ns/time\fP time:[4026531834] .EE .in -.PP +.P Continuing in the initial time namespace, we display the system uptime using .BR uptime (1) and use the @@ -208,7 +208,7 @@ and use the example program shown in .BR clock_getres (2) to display the values of various clocks: -.PP +.P .in +4n .EX $ \fBuptime \-\-pretty\fP @@ -220,7 +220,7 @@ CLOCK_MONOTONIC: 56338.247 (15h 38m 58s) CLOCK_BOOTTIME : 76633.544 (21h 17m 13s) .EE .in -.PP +.P We then use .BR unshare (1) to create a time namespace and execute a @@ -236,7 +236,7 @@ clock forward 2 days and the offset for the .B CLOCK_BOOTTIME clock forward 7 days: -.PP +.P .in +4n .EX $ \fBPS1="ns2# " sudo unshare \-T \-\- bash \-\-norc\fP @@ -244,7 +244,7 @@ ns2# \fBecho "monotonic $((2*24*60*60)) 0" > /proc/$$/timens_offsets\fP ns2# \fBecho "boottime $((7*24*60*60)) 0" > /proc/$$/timens_offsets\fP .EE .in -.PP +.P Above, we started the .BR bash (1) shell with the @@ -254,7 +254,7 @@ This ensures that no child processes are created from the shell before we have a chance to update the .I timens_offsets file. -.PP +.P We then use .BR cat (1) to display the contents of the @@ -266,7 +266,7 @@ creates the first process in the new time namespace, after which further attempts to update the .I timens_offsets file produce an error. -.PP +.P .in +4n .EX ns2# \fBcat /proc/$$/timens_offsets\fP @@ -276,13 +276,13 @@ ns2# \fBecho "boottime $((9*24*60*60)) 0" > /proc/$$/timens_offsets\fP bash: echo: write error: Permission denied .EE .in -.PP +.P Continuing in the new namespace, we execute .BR uptime (1) and the .I clock_times example program: -.PP +.P .in +4n .EX ns2# \fBuptime \-\-pretty\fP @@ -294,17 +294,17 @@ CLOCK_MONOTONIC: 229193.332 (2 days + 15h 39m 53s) CLOCK_BOOTTIME : 681488.629 (7 days + 21h 18m 8s) .EE .in -.PP +.P From the above output, we can see that the monotonic and boot-time clocks have different values in the new time namespace. -.PP +.P Examining the .IR /proc/ pid /ns/time and .IR /proc/ pid /ns/time_for_children symbolic links, we see that the shell is a member of the initial time namespace, but its children are created in the new namespace. -.PP +.P .in +4n .EX ns2# \fBreadlink /proc/$$/ns/time\fP @@ -315,13 +315,13 @@ ns2# \fBreadlink /proc/self/ns/time\fP # Creates a child process time:[4026532900] .EE .in -.PP +.P Returning to the shell in the initial time namespace, we see that the monotonic and boot-time clocks are unaffected by the .I timens_offsets changes that were made in the other time namespace: -.PP +.P .in +4n .EX $ \fBuptime \-\-pretty\fP diff --git a/upstream/debian-unstable/man7/udev.7 b/upstream/debian-unstable/man7/udev.7 index 9ca54f08..babc6868 100644 --- a/upstream/debian-unstable/man7/udev.7 +++ b/upstream/debian-unstable/man7/udev.7 @@ -1,5 +1,5 @@ '\" t -.TH "UDEV" "7" "" "systemd 255" "udev" +.TH "UDEV" "7" "" "systemd 256~rc3" "udev" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -707,9 +707,7 @@ character itself\&. .RE .SH "SEE ALSO" .PP -\fBsystemd-udevd.service\fR(8), -\fBudevadm\fR(8), -\fBsystemd.link\fR(5) +\fBsystemd-udevd.service\fR(8), \fBudevadm\fR(8), \fBsystemd.link\fR(5) .SH "NOTES" .IP " 1." 4 Escape sequences in C diff --git a/upstream/debian-unstable/man7/udp.7 b/upstream/debian-unstable/man7/udp.7 index 45c5cad1..ce25010e 100644 --- a/upstream/debian-unstable/man7/udp.7 +++ b/upstream/debian-unstable/man7/udp.7 @@ -4,7 +4,7 @@ .\" .\" $Id: udp.7,v 1.7 2000/01/22 01:55:05 freitag Exp $ .\" -.TH udp 7 2023-07-15 "Linux man-pages 6.05.01" +.TH udp 7 2024-05-02 "Linux man-pages 6.8" .SH NAME udp \- User Datagram Protocol for IPv4 .SH SYNOPSIS @@ -12,7 +12,7 @@ udp \- User Datagram Protocol for IPv4 .B #include <sys/socket.h> .B #include <netinet/in.h> .B #include <netinet/udp.h> -.PP +.P .IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" .fi .SH DESCRIPTION @@ -21,7 +21,7 @@ described in RFC\ 768. It implements a connectionless, unreliable datagram packet service. Packets may be reordered or duplicated before they arrive. UDP generates and checks checksums to catch transmission errors. -.PP +.P When a UDP socket is created, its local and remote addresses are unspecified. Datagrams can be sent immediately using @@ -50,7 +50,7 @@ a free local port out of the range defined by .I /proc/sys/net/ipv4/ip_local_port_range and bind the socket to .BR INADDR_ANY . -.PP +.P All receive operations return only one packet. When the packet is smaller than the passed buffer, only that much data is returned; when it is bigger, the packet is truncated and the @@ -58,7 +58,7 @@ data is returned; when it is bigger, the packet is truncated and the flag is set. .B MSG_WAITALL is not supported. -.PP +.P IP options may be sent or received using the socket options described in .BR ip (7). They are processed by the kernel only when the appropriate @@ -67,12 +67,12 @@ parameter is enabled (but still passed to the user even when it is turned off). See .BR ip (7). -.PP +.P When the .B MSG_DONTROUTE flag is set on sending, the destination address must refer to a local interface address and the packet is sent only to that interface. -.PP +.P By default, Linux UDP does path MTU (Maximum Transmission Unit) discovery. This means the kernel will keep track of the MTU to a specific target IP address and return @@ -106,7 +106,7 @@ This behavior differs from many other BSD socket implementations which don't pass any errors unless the socket is connected. Linux's behavior is mandated by .BR RFC\ 1122 . -.PP +.P For compatibility with legacy code, in Linux 2.0 and 2.2 it was possible to set the .B SO_BSDCOMPAT @@ -120,7 +120,7 @@ Locally generated errors are always passed. Support for this socket option was removed in later kernels; see .BR socket (7) for further information. -.PP +.P When the .B IP_RECVERR option is enabled, all errors are stored in the socket error queue, @@ -181,7 +181,7 @@ Unless otherwise noted, .I optval is a pointer to an .IR int . -.PP +.P Following is a list of UDP-specific socket options. For details of some other socket options that are also applicable for UDP sockets, see @@ -246,7 +246,7 @@ This option should not be used in code intended to be portable. These ioctls can be accessed using .BR ioctl (2). The correct syntax is: -.PP +.P .RS .nf .BI int " value"; @@ -275,7 +275,7 @@ to distinguish these cases. .BR TIOCOUTQ " (" SIOCOUTQ ) Returns the number of data bytes in the local send queue. Supported only with Linux 2.4 and above. -.PP +.P In addition, all ioctls documented in .BR ip (7) and @@ -301,10 +301,10 @@ is a new feature in Linux 2.2. .BR raw (7), .BR socket (7), .BR udplite (7) -.PP +.P The kernel source file .IR Documentation/networking/ip\-sysctl.txt . -.PP +.P RFC\ 768 for the User Datagram Protocol. .br RFC\ 1122 for the host requirements. diff --git a/upstream/debian-unstable/man7/udplite.7 b/upstream/debian-unstable/man7/udplite.7 index 36a2db89..a0b52e1d 100644 --- a/upstream/debian-unstable/man7/udplite.7 +++ b/upstream/debian-unstable/man7/udplite.7 @@ -4,7 +4,7 @@ .\" .\" $Id: udplite.7,v 1.12 2008/07/23 15:22:22 gerrit Exp gerrit $ .\" -.TH udplite 7 2023-02-10 "Linux man-pages 6.05.01" +.TH udplite 7 2024-05-02 "Linux man-pages 6.8" .SH NAME udplite \- Lightweight User Datagram Protocol .SH SYNOPSIS @@ -13,25 +13,25 @@ udplite \- Lightweight User Datagram Protocol .\" FIXME . see #defines under `BUGS', .\" when glibc supports this, add .\" #include <netinet/udplite.h> -.PP +.P .B sockfd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE); .fi .SH DESCRIPTION This is an implementation of the Lightweight User Datagram Protocol (UDP-Lite), as described in RFC\ 3828. -.PP +.P UDP-Lite is an extension of UDP (RFC\ 768) to support variable-length checksums. This has advantages for some types of multimedia transport that may be able to make use of slightly damaged datagrams, rather than having them discarded by lower-layer protocols. -.PP +.P The variable-length checksum coverage is set via a .BR setsockopt (2) option. If this option is not set, the only difference from UDP is in using a different IP protocol identifier (IANA number 136). -.PP +.P The UDP-Lite implementation is a full extension of .BR udp (7)\[em]that is, it shares the same API and API behavior, and in addition @@ -58,7 +58,7 @@ socket options are valid on a UDP-Lite socket. See .BR udp (7) for more information. -.PP +.P The following two options are specific to UDP-Lite. .TP .B UDPLITE_SEND_CSCOV @@ -93,7 +93,7 @@ exceeds the actual packet coverage, incoming packets are silently dropped, but may generate a warning message in the system log. .\" SO_NO_CHECK exists and is supported by UDPv4, but is .\" commented out in socket(7), hence also commented out here -.\".PP +.\".P .\"Since UDP-Lite mandates checksums, checksumming can not be disabled .\"via the .\".B SO_NO_CHECK @@ -116,7 +116,7 @@ UDP-Litev4/v6 first appeared in Linux 2.6.20. .SH BUGS .\" FIXME . remove this section once glibc supports UDP-Lite Where glibc support is missing, the following definitions are needed: -.PP +.P .in +4n .EX #define IPPROTO_UDPLITE 136 @@ -130,8 +130,8 @@ Where glibc support is missing, the following definitions are needed: .BR ipv6 (7), .BR socket (7), .BR udp (7) -.PP +.P RFC\ 3828 for the Lightweight User Datagram Protocol (UDP-Lite). -.PP +.P .I Documentation/networking/udplite.txt in the Linux kernel source tree diff --git a/upstream/debian-unstable/man7/unicode.7 b/upstream/debian-unstable/man7/unicode.7 index f65a9b2b..001335ec 100644 --- a/upstream/debian-unstable/man7/unicode.7 +++ b/upstream/debian-unstable/man7/unicode.7 @@ -7,7 +7,7 @@ .\" 2001-05-11 Markus Kuhn <mgk25@cl.cam.ac.uk> .\" Update .\" -.TH unicode 7 2023-03-12 "Linux man-pages 6.05.01" +.TH unicode 7 2024-05-02 "Linux man-pages 6.8" .SH NAME unicode \- universal character set .SH DESCRIPTION @@ -18,7 +18,7 @@ It also guarantees "round-trip compatibility"; in other words, conversion tables can be built such that no information is lost when a string is converted from any other encoding to UCS and back. -.PP +.P UCS contains the characters required to represent practically all known languages. This includes not only the Latin, Greek, Cyrillic, @@ -40,7 +40,7 @@ graphical, typographical, mathematical, and scientific symbols, including those provided by TeX, Postscript, APL, MS-DOS, MS-Windows, Macintosh, OCR fonts, as well as many word processing and publishing systems, and more are being added. -.PP +.P The UCS standard (ISO/IEC 10646) describes a 31-bit character set architecture consisting of 128 24-bit @@ -71,7 +71,7 @@ The supplemental planes added by ISO/IEC 10646-2 cover only more exotic characters for special scientific, dictionary printing, publishing industry, higher-level protocol and enthusiast needs. -.PP +.P The representation of each UCS character as a 2-byte word is referred to as the UCS-2 form (only for BMP characters), whereas UCS-4 is the representation of each character by a 4-byte word. @@ -79,12 +79,12 @@ In addition, there exist two encoding forms UTF-8 for backward compatibility with ASCII processing software and UTF-16 for the backward-compatible handling of non-BMP characters up to 0x10ffff by UCS-2 software. -.PP +.P The UCS characters 0x0000 to 0x007f are identical to those of the classic US-ASCII character set and the characters in the range 0x0000 to 0x00ff are identical to those in -ISO 8859-1 (Latin-1). +ISO/IEC\~8859-1 (Latin-1). .SS Combining characters Some code points in UCS have been assigned to @@ -101,7 +101,7 @@ character Umlaut-A ("Latin capital letter A with diaeresis") can either be represented by the precomposed UCS code 0x00c4, or alternatively as the combination of a normal "Latin capital letter A" followed by a "combining diaeresis": 0x0041 0x0308. -.PP +.P Combining characters are essential for instance for encoding the Thai script or for mathematical typesetting and users of the International Phonetic Alphabet. @@ -124,7 +124,7 @@ Arabic, Devanagari, Malayalam). .TP Level 3 All UCS characters are supported. -.PP +.P The Unicode 3.0 Standard published by the Unicode Consortium contains exactly the UCS Basic Multilingual Plane @@ -147,7 +147,7 @@ code values (in all locales), a convention that is signaled by the GNU C library to applications by defining the constant .B __STDC_ISO_10646__ as specified in the ISO C99 standard. -.PP +.P UCS/Unicode can be used just like ASCII in input/output streams, terminal communication, plaintext files, filenames, and environment variables in the ASCII compatible UTF-8 multibyte encoding. @@ -156,7 +156,7 @@ encoding to all applications, a suitable .I locale has to be selected via environment variables (e.g., "LANG=en_GB.UTF-8"). -.PP +.P The .B nl_langinfo(CODESET) function returns the name of the selected encoding. @@ -189,7 +189,7 @@ in the Linux kernel sources (or .I Documentation/unicode.txt before Linux 4.10). -.PP +.P Two other planes are reserved for private usage, plane 15 (Supplementary Private Use Area-A, range 0xf0000 to 0xffffd) and plane 16 (Supplementary Private Use Area-B, range diff --git a/upstream/debian-unstable/man7/units.7 b/upstream/debian-unstable/man7/units.7 index ca2bd2dd..75b6e72b 100644 --- a/upstream/debian-unstable/man7/units.7 +++ b/upstream/debian-unstable/man7/units.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH units 7 2023-02-10 "Linux man-pages 6.05.01" +.TH units 7 2024-05-02 "Linux man-pages 6.8" .SH NAME units \- decimal and binary prefixes .SH DESCRIPTION @@ -41,7 +41,7 @@ R ronna 10\[ha]27 = 1000000000000000000000000000 Q quetta 10\[ha]30 = 1000000000000000000000000000000 .TE .RE -.PP +.P The symbol for micro is the Greek letter mu, often written u in an ASCII context where this Greek letter is not available. .SS Binary prefixes @@ -70,7 +70,7 @@ Before these binary prefixes were introduced, it was fairly common to use k=1000 and K=1024, just like b=bit, B=byte. Unfortunately, the M is capital already, and cannot be capitalized to indicate binary-ness. -.PP +.P At first that didn't matter too much, since memory modules and disks came in sizes that were powers of two, so everyone knew that in such contexts "kilobyte" and "megabyte" meant @@ -81,26 +81,26 @@ regarded as the "real true meaning" when computers were involved. But then disk technology changed, and disk sizes became arbitrary numbers. After a period of uncertainty all disk manufacturers settled on the standard, namely k=1000, M=1000\ k, G=1000\ M. -.PP +.P The situation was messy: in the 14k4 modems, k=1000; in the 1.44\ MB .\" also common: 14.4k modem diskettes, M=1024000; and so on. In 1998 the IEC approved the standard that defines the binary prefixes given above, enabling people to be precise and unambiguous. -.PP +.P Thus, today, MB = 1000000\ B and MiB = 1048576\ B. -.PP +.P In the free software world programs are slowly being changed to conform. When the Linux kernel boots and says -.PP +.P .in +4n .EX hda: 120064896 sectors (61473 MB) w/2048KiB Cache .EE .in -.PP +.P the MB are megabytes and the KiB are kibibytes. .SH SEE ALSO .UR https://www.bipm.org/\:documents/\:20126/\:41483022/\:SI\-Brochure\-9.pdf diff --git a/upstream/debian-unstable/man7/unix.7 b/upstream/debian-unstable/man7/unix.7 index cfa41880..42f1e27d 100644 --- a/upstream/debian-unstable/man7/unix.7 +++ b/upstream/debian-unstable/man7/unix.7 @@ -12,14 +12,14 @@ .\" address that can appear in the sockaddr_un structure: pathname, .\" unnamed, and abstract. .\" -.TH UNIX 7 2023-07-15 "Linux man-pages 6.05.01" +.TH UNIX 7 2024-05-02 "Linux man-pages 6.8" .SH NAME unix \- sockets for local interprocess communication .SH SYNOPSIS .nf .B #include <sys/socket.h> .B #include <sys/un.h> -.PP +.P .IB unix_socket " = socket(AF_UNIX, type, 0);" .IB error " = socketpair(AF_UNIX, type, 0, int *" sv ");" .fi @@ -34,7 +34,7 @@ Traditionally, UNIX domain sockets can be either unnamed, or bound to a filesystem pathname (marked as being of type socket). Linux also supports an abstract namespace which is independent of the filesystem. -.PP +.P Valid socket types in the UNIX domain are: .BR SOCK_STREAM , for a stream-oriented socket; @@ -47,12 +47,12 @@ and (since Linux 2.6.4) for a sequenced-packet socket that is connection-oriented, preserves message boundaries, and delivers messages in the order that they were sent. -.PP +.P UNIX domain sockets support passing file descriptors or process credentials to other processes using ancillary data. .SS Address format A UNIX domain socket address is represented in the following structure: -.PP +.P .in +4n .EX .\" #define UNIX_PATH_MAX 108 @@ -63,7 +63,7 @@ struct sockaddr_un { }; .EE .in -.PP +.P The .I sun_family field always contains @@ -71,8 +71,8 @@ field always contains On Linux, .I sun_path is 108 bytes in size; see also BUGS, below. -.PP -Various systems calls (for example, +.P +Various system calls (for example, .BR bind (2), .BR connect (2), and @@ -87,7 +87,7 @@ Some other system calls (for example, and .BR accept (2)) return an argument of this type. -.PP +.P Three types of address are distinguished in the .I sockaddr_un structure: @@ -186,7 +186,7 @@ or, more simply, .I addrlen can be specified as .IR "sizeof(struct sockaddr_un)" . -.PP +.P There is some variation in how implementations handle UNIX domain socket addresses that do not follow the above rules. For example, some (but not all) implementations @@ -194,7 +194,7 @@ For example, some (but not all) implementations .\" is 108 bytes append a null terminator if none is present in the supplied .IR sun_path . -.PP +.P When coding portable applications, keep in mind that some implementations .\" HP-UX @@ -203,7 +203,7 @@ have as short as 92 bytes. .\" Modern BSDs generally have 104, Tru64 and AIX have 104, .\" Solaris and Irix have 108 -.PP +.P Various system calls .RB ( accept (2), .BR recvfrom (2), @@ -227,7 +227,7 @@ In the Linux implementation, pathname sockets honor the permissions of the directory they are in. Creation of a new socket fails if the process does not have write and search (execute) permission on the directory in which the socket is created. -.PP +.P On Linux, connecting to a stream socket object requires write permission on that socket; sending a datagram to a datagram socket likewise @@ -237,13 +237,13 @@ on a socket file, and on some systems (e.g., older BSDs), the socket permissions are ignored. Portable programs should not rely on this feature for security. -.PP +.P When creating a new socket, the owner and group of the socket file are set according to the usual rules. The socket file has all permissions enabled, other than those that are turned off by the process .BR umask (2). -.PP +.P The owner, group, and permissions of a pathname socket can be changed (using .BR chown (2) and @@ -260,10 +260,10 @@ and changing the ownership and permissions of the object (via and .BR fchmod (2)) has no effect on the accessibility of the socket. -.PP +.P Abstract sockets automatically disappear when all open references to the socket are closed. -.PP +.P The abstract socket namespace is a nonportable Linux extension. .\" .SS Socket options @@ -331,7 +331,8 @@ This read-only socket option returns the credentials of the peer process connected to this socket. The returned credentials are those that were in effect at the time of the call to -.BR connect (2) +.BR connect (2), +.BR listen (2), or .BR socketpair (2). .IP @@ -418,7 +419,7 @@ The change to 5 bytes came in Linux 2.3.15.) .SS Sockets API The following paragraphs describe domain-specific details and unsupported features of the sockets API for UNIX domain sockets on Linux. -.PP +.P UNIX domain sockets do not support the transmission of out-of-band data (the .B MSG_OOB @@ -426,12 +427,12 @@ flag for .BR send (2) and .BR recv (2)). -.PP +.P The .BR send (2) .B MSG_MORE flag is not supported by UNIX domain sockets. -.PP +.P Before Linux 3.4, .\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f the use of @@ -441,7 +442,7 @@ in the argument of .BR recv (2) was not supported by UNIX domain sockets. -.PP +.P The .B SO_SNDBUF socket option does have an effect for UNIX domain sockets, but the @@ -573,11 +574,11 @@ bytes in the data portion of the ancillary message for this data. To receive the security context, the .B SO_PASSSEC option must be enabled on the socket (see above). -.PP +.P When sending ancillary data with .BR sendmsg (2), only one item of each of the above types may be included in the sent message. -.PP +.P At least one byte of real data should be sent when sending ancillary data. On Linux, this is required to successfully send ancillary data over a UNIX domain stream socket. @@ -585,11 +586,11 @@ When sending ancillary data over a UNIX domain datagram socket, it is not necessary on Linux to send any accompanying real data. However, portable applications should also include at least one byte of real data when sending ancillary data over a datagram socket. -.PP +.P When receiving from a stream socket, ancillary data forms a kind of barrier for the received data. For example, suppose that the sender transmits as follows: -.PP +.P .RS .PD 0 .IP (1) 5 @@ -603,7 +604,7 @@ of one byte, with ancillary data. of four bytes, with no ancillary data. .PD .RE -.PP +.P Suppose that the receiver now performs .BR recvmsg (2) calls each with a buffer size of 20 bytes. @@ -612,7 +613,7 @@ along with the ancillary data sent by the second .BR sendmsg (2) call. The next call will receive the remaining four bytes of data. -.PP +.P If the space allocated for receiving incoming ancillary data is too small then the ancillary data is truncated to the number of headers that will fit in the supplied buffer (or, in the case of an @@ -639,14 +640,14 @@ The following calls return information in .IR value . The correct syntax is: -.PP +.P .RS .nf .BI int " value"; .IB error " = ioctl(" unix_socket ", " ioctl_type ", &" value ");" .fi .RE -.PP +.P .I ioctl_type can be: .TP @@ -800,7 +801,7 @@ by sending each file descriptor with and then closing the file descriptor so that it was not accounted against the .B RLIMIT_NOFILE resource limit. -.PP +.P Other errors can be generated by the generic socket layer or by the filesystem while generating a filesystem socket object. See the appropriate manual pages for more information. @@ -818,7 +819,7 @@ longer needed (using The usual UNIX close-behind semantics apply; the socket can be unlinked at any time and will be finally removed from the filesystem when the last reference to it is closed. -.PP +.P To pass file descriptors or credentials over a .B SOCK_STREAM socket, you must @@ -827,12 +828,12 @@ send or receive at least one byte of nonancillary data in the same or .BR recvmsg (2) call. -.PP +.P UNIX domain stream sockets do not support the notion of out-of-band data. .\" .SH BUGS When binding a socket to an address, -Linux is one of the implementations that appends a null terminator +Linux is one of the implementations that append a null terminator if none is supplied in .IR sun_path . In most cases this is unproblematic: @@ -855,7 +856,7 @@ then the returned address structure .I won't have a null terminator in .IR sun_path . -.PP +.P In addition, some implementations .\" i.e., traditional BSD don't require a null terminator when binding a socket (the @@ -865,12 +866,12 @@ argument is used to determine the length of and when the socket address is retrieved on these implementations, there is no null terminator in .IR sun_path . -.PP +.P Applications that retrieve socket addresses can (portably) code to handle the possibility that there is no null terminator in .I sun_path by respecting the fact that the number of valid bytes in the pathname is: -.PP +.P .in +4n .EX strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path)) @@ -886,7 +887,7 @@ strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path)) .\" 2012-04-18 .\" .\" FIXME . Track http://austingroupbugs.net/view.php?id=561 -.PP +.P Alternatively, an application can retrieve the socket address by allocating a buffer of size .I "sizeof(struct sockaddr_un)+1" @@ -898,7 +899,7 @@ as and the extra zero byte ensures that there will be a null terminator for the string returned in .IR sun_path : -.PP +.P .in +4n .EX void *addrp; @@ -915,7 +916,7 @@ if (getsockname(sfd, (struct sockaddr *) addrp, &addrlen)) == \-1) printf("sun_path = %s\en", ((struct sockaddr_un *) addrp)\->sun_path); .EE .in -.PP +.P This sort of messiness can be avoided if it is guaranteed that the applications that .I create @@ -933,7 +934,7 @@ The server sends back a message containing the sum of the client's integers. The client prints the sum and exits. The server waits for the next client to connect. To stop the server, the client is called with the command-line argument "DOWN". -.PP +.P The following output was recorded while running the server in the background and repeatedly executing the client. Execution of the server program ends when it receives the "DOWN" command. @@ -954,14 +955,23 @@ $ .in .SS Program source \& +.\" SRC BEGIN (connection.h) .EX /* * File connection.h */ +#ifndef CONNECTION_H +#define CONNECTION_H \& #define SOCKET_NAME "/tmp/9Lq7BNBnBycd6nxy.socket" #define BUFFER_SIZE 12 \& +#endif // include guard +.EE +.\" SRC END +.P +.\" SRC BEGIN (server.c) +.EX /* * File server.c */ @@ -970,20 +980,23 @@ $ #include <stdlib.h> #include <string.h> #include <sys/socket.h> +#include <sys/types.h> #include <sys/un.h> #include <unistd.h> +\& #include "connection.h" \& int -main(int argc, char *argv[]) +main(void) { - struct sockaddr_un name; - int down_flag = 0; - int ret; - int connection_socket; - int data_socket; - int result; - char buffer[BUFFER_SIZE]; + int down_flag = 0; + int ret; + int connection_socket; + int data_socket; + int result; + ssize_t r, w; + struct sockaddr_un name; + char buffer[BUFFER_SIZE]; \& /* Create local socket. */ \& @@ -1042,8 +1055,8 @@ main(int argc, char *argv[]) \& /* Wait for next data packet. */ \& - ret = read(data_socket, buffer, sizeof(buffer)); - if (ret == \-1) { + r = read(data_socket, buffer, sizeof(buffer)); + if (r == \-1) { perror("read"); exit(EXIT_FAILURE); } @@ -1056,13 +1069,17 @@ main(int argc, char *argv[]) \& if (!strncmp(buffer, "DOWN", sizeof(buffer))) { down_flag = 1; - break; + continue; } \& if (!strncmp(buffer, "END", sizeof(buffer))) { break; } \& + if (down_flag) { + continue; + } +\& /* Add received summand. */ \& result += atoi(buffer); @@ -1071,8 +1088,8 @@ main(int argc, char *argv[]) /* Send result. */ \& sprintf(buffer, "%d", result); - ret = write(data_socket, buffer, sizeof(buffer)); - if (ret == \-1) { + w = write(data_socket, buffer, sizeof(buffer)); + if (w == \-1) { perror("write"); exit(EXIT_FAILURE); } @@ -1096,27 +1113,33 @@ main(int argc, char *argv[]) \& exit(EXIT_SUCCESS); } -\& +.EE +.\" SRC END +.P +.\" SRC BEGIN (client.c) +.EX /* * File client.c */ \& -#include <errno.h> #include <stdio.h> #include <stdlib.h> #include <string.h> #include <sys/socket.h> +#include <sys/types.h> #include <sys/un.h> #include <unistd.h> +\& #include "connection.h" \& int main(int argc, char *argv[]) { - struct sockaddr_un addr; - int ret; - int data_socket; - char buffer[BUFFER_SIZE]; + int ret; + int data_socket; + ssize_t r, w; + struct sockaddr_un addr; + char buffer[BUFFER_SIZE]; \& /* Create local socket. */ \& @@ -1148,9 +1171,9 @@ main(int argc, char *argv[]) \& /* Send arguments. */ \& - for (size_t i = 1; i < argc; ++i) { - ret = write(data_socket, argv[i], strlen(argv[i]) + 1); - if (ret == \-1) { + for (int i = 1; i < argc; ++i) { + w = write(data_socket, argv[i], strlen(argv[i]) + 1); + if (w == \-1) { perror("write"); break; } @@ -1159,16 +1182,16 @@ main(int argc, char *argv[]) /* Request result. */ \& strcpy(buffer, "END"); - ret = write(data_socket, buffer, strlen(buffer) + 1); - if (ret == \-1) { + w = write(data_socket, buffer, strlen(buffer) + 1); + if (w == \-1) { perror("write"); exit(EXIT_FAILURE); } \& /* Receive result. */ \& - ret = read(data_socket, buffer, sizeof(buffer)); - if (ret == \-1) { + r = read(data_socket, buffer, sizeof(buffer)); + if (r == \-1) { perror("read"); exit(EXIT_FAILURE); } @@ -1186,7 +1209,8 @@ main(int argc, char *argv[]) exit(EXIT_SUCCESS); } .EE -.PP +.\" SRC END +.P For examples of the use of .BR SCM_RIGHTS , see diff --git a/upstream/debian-unstable/man7/uri.7 b/upstream/debian-unstable/man7/uri.7 index a571aec9..285ff19c 100644 --- a/upstream/debian-unstable/man7/uri.7 +++ b/upstream/debian-unstable/man7/uri.7 @@ -25,7 +25,7 @@ .\" Modified Fri Aug 21 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com) .\" Modified Tue Mar 14 2000 by David A. Wheeler (dwheeler@dwheeler.com) .\" -.TH uri 7 2023-04-30 "Linux man-pages 6.05.01" +.TH uri 7 2024-05-02 "Linux man-pages 6.8" .SH NAME uri, url, urn \- uniform resource identifier (URI), including a URL or URN .SH SYNOPSIS @@ -36,7 +36,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB [\~\[dq] # \[dq]\~\c .IR fragment \~] .YS -.PP +.P .SY "\fIabsoluteURI\fP \fR=\fP" .I scheme\~\c .RB \[dq] : \[dq] @@ -44,7 +44,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN | .IR opaque_part \~) .YS -.PP +.P .SY "\fIrelativeURI\fP \fR=\fP" .RI (\~ net_path | @@ -54,7 +54,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB [\~\[dq] ? \[dq]\~\c .IR query \~] .YS -.PP +.P .SY "\fIscheme\fP \fR=\fP" .RB \[dq] http \[dq] | @@ -83,7 +83,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB \[dq] wais \[dq] | \&... .YS -.PP +.P .SY "\fIhierarchical_part\fP \fR=\fP" .RI (\~ net_path | @@ -91,18 +91,18 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB [\~\[dq] ? \[dq]\~\c .IR query \~] .YS -.PP +.P .SY "\fInet_path\fP \fR=\fP" .RB \[dq] // \[dq]\~\c .I authority .RI [\~ absolute_path \~] .YS -.PP +.P .SY "\fIabsolute_path\fP \fR=\fP" .RB \[dq] / \[dq]\~\c .I path_segments .YS -.PP +.P .SY "\fIrelative_path\fP \fR=\fP" .I relative_segment .RI [\~ absolute_path \~] @@ -117,14 +117,14 @@ by name or some other attribute of that resource. A Uniform Resource Name (URN) is a URI that must remain globally unique and persistent even when the resource ceases to exist or becomes unavailable. -.PP +.P URIs are the standard way to name hypertext link destinations for tools such as web browsers. The string "http://www.kernel.org" is a URL (and thus it is also a URI). Many people use the term URL loosely as a synonym for URI (though technically URLs are a subset of URIs). -.PP +.P URIs can be absolute or relative. An absolute identifier refers to a resource independent of context, while a relative @@ -140,7 +140,7 @@ character can't be used as the first segment of a relative URI path precede such segments with ./ (e.g., "./this:that"). Note that descendants of MS-DOS (e.g., Microsoft Windows) replace devicename colons with the vertical bar ("|") in URIs, so "C:" becomes "C|". -.PP +.P A fragment identifier, if included, refers to a particular named portion (fragment) of a resource; @@ -155,9 +155,9 @@ For example, many URL schemes permit the authority to be the following format, called here an .I ip_server (square brackets show what's optional): -.PP +.P .IR "ip_server = " [ user " [ : " password " ] @ ] " host " [ : " port ] -.PP +.P This format allows you to optionally insert a username, a user plus password, and/or a port number. The @@ -173,18 +173,18 @@ security risks of having a password written down. If the URL supplies a username but no password, and the remote server requests a password, the program interpreting the URL should request one from the user. -.PP +.P Here are some of the most common schemes in use on UNIX-like systems that are understood by many tools. Note that many tools using URIs also have internal schemes or specialized schemes; see those tools' documentation for information on those schemes. -.PP +.P .B "http \- Web (HTTP) server" -.PP +.P .RI http:// ip_server / path .br .RI http:// ip_server / path ? query -.PP +.P This is a URL accessing a web (HTTP) server. The default port is 80. If the path refers to a directory, the web server will choose what @@ -192,7 +192,7 @@ to return; usually if there is a file named "index.html" or "index.htm" its content is returned, otherwise, a list of the files in the current directory (with appropriate links) is generated and returned. An example is <http://lwn.net>. -.PP +.P A query can be given in the archaic "isindex" format, consisting of a word or phrase and not including an equal sign (=). A query can also be in the longer "GET" format, which has one or more @@ -215,11 +215,11 @@ See the Common Gateway Interface specification at .UR http://www.w3.org\:/CGI .UE for more information. -.PP +.P .B "ftp \- File Transfer Protocol (FTP)" -.PP +.P .RI ftp:// ip_server / path -.PP +.P This is a URL accessing a file through the file transfer protocol (FTP). The default port (for control) is 21. If no username is included, the username "anonymous" is supplied, and @@ -227,16 +227,16 @@ in that case many clients provide as the password the requestor's Internet email address. An example is <ftp://ftp.is.co.za/rfc/rfc1808.txt>. -.PP +.P .B "gopher \- Gopher server" -.PP +.P .RI gopher:// ip_server / "gophertype selector" .br .RI gopher:// ip_server / "gophertype selector" %09 search .br .RI gopher:// ip_server / "gophertype selector" %09 search %09 gopher+_string .br -.PP +.P The default gopher port is 70. .I gophertype is a single-character field to denote the @@ -245,18 +245,18 @@ which the URL refers. The entire path may also be empty, in which case the delimiting "/" is also optional and the gophertype defaults to "1". -.PP +.P .I selector is the Gopher selector string. In the Gopher protocol, Gopher selector strings are a sequence of octets which may contain any octets except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal (US-ASCII character LF), and 0D (US-ASCII character CR). -.PP +.P .B "mailto \- Email address" -.PP +.P .RI mailto: email-address -.PP +.P This is an email address, usually of the form .IR name @ hostname . See @@ -264,13 +264,13 @@ See for more information on the correct format of an email address. Note that any % character must be rewritten as %25. An example is <mailto:dwheeler@dwheeler.com>. -.PP +.P .B "news \- Newsgroup or News message" -.PP +.P .RI news: newsgroup-name .br .RI news: message-id -.PP +.P A .I newsgroup-name is a period-delimited hierarchical name, such as @@ -278,7 +278,7 @@ is a period-delimited hierarchical name, such as If <newsgroup-name> is "*" (as in <news:*>), it is used to refer to "all available news groups". An example is <news:comp.lang.ada>. -.PP +.P A .I message-id corresponds to the Message-ID of @@ -290,23 +290,23 @@ and ">"; it takes the form .IR unique @ full_domain_name . A message identifier may be distinguished from a news group name by the presence of the "@" character. -.PP +.P .B "telnet \- Telnet login" -.PP +.P .RI telnet:// ip_server / -.PP +.P The Telnet URL scheme is used to designate interactive text services that may be accessed by the Telnet protocol. The final "/" character may be omitted. The default port is 23. An example is <telnet://melvyl.ucop.edu/>. -.PP +.P .B "file \- Normal file" -.PP +.P .RI file:// ip_server / path_segments .br .RI file: path_segments -.PP +.P This represents a file or directory accessible locally. As a special case, .I ip_server @@ -323,7 +323,7 @@ the filename via filename globbing .BR glob (7) and .BR glob (3)). -.PP +.P The second format (e.g., <file:/etc/passwd>) is a correct format for referring to a local file. @@ -337,13 +337,13 @@ Note that if you really mean to say "start from the current location", don't specify the scheme at all; use a relative address like <../test.txt>, which has the side-effect of being scheme-independent. An example of this scheme is <file:///etc/passwd>. -.PP +.P .B "man \- Man page documentation" -.PP +.P .RI man: command-name .br .RI man: command-name ( section ) -.PP +.P This refers to local online manual (man) reference pages. The command name can optionally be followed by a parenthesis and section number; see @@ -352,9 +352,9 @@ for more information on the meaning of the section numbers. This URI scheme is unique to UNIX-like systems (such as Linux) and is not currently registered by the IETF. An example is <man:ls(1)>. -.PP +.P .B "info \- Info page documentation" -.PP +.P .RI info: virtual-filename .br .RI info: virtual-filename # nodename @@ -362,7 +362,7 @@ An example is <man:ls(1)>. .RI info:( virtual-filename ) .br .RI info:( virtual-filename ) nodename -.PP +.P This scheme refers to online info reference pages (generated from texinfo files), a documentation format used by programs such as the GNU tools. @@ -381,11 +381,11 @@ In both GNOME and KDE, if the form without the nodename is used the nodename is assumed to be "Top". Examples of the GNOME format are <info:gcc> and <info:gcc#G++_and_GCC>. Examples of the KDE format are <info:(gcc)> and <info:(gcc)G++ and GCC>. -.PP +.P .B "whatis \- Documentation search" -.PP +.P .RI whatis: string -.PP +.P This scheme searches the database of short (one-line) descriptions of commands and returns a list of descriptions containing that string. Only complete word matches are returned. @@ -393,16 +393,16 @@ See .BR whatis (1). This URI scheme is unique to UNIX-like systems (such as Linux) and is not currently registered by the IETF. -.PP +.P .B "ghelp \- GNOME help documentation" -.PP +.P .RI ghelp: name-of-application -.PP +.P This loads GNOME help for the given application. Note that not much documentation currently exists in this format. -.PP +.P .B "ldap \- Lightweight Directory Access Protocol" -.PP +.P .RI ldap:// hostport .br .RI ldap:// hostport / @@ -416,7 +416,7 @@ Note that not much documentation currently exists in this format. .RI ldap:// hostport / dn ? attributes ? scope ? filter .br .RI ldap:// hostport / dn ? attributes ? scope ? filter ? extensions -.PP +.P This scheme supports queries to the Lightweight Directory Access Protocol (LDAP), a protocol for querying a set of servers for hierarchically organized information @@ -469,36 +469,36 @@ pairs, where the =value portion may be omitted for options not requiring it. An extension prefixed with a \[aq]!\[aq] is critical (must be supported to be valid), otherwise it is noncritical (optional). -.PP +.P LDAP queries are easiest to explain by example. Here's a query that asks ldap.itd.umich.edu for information about the University of Michigan in the U.S.: -.PP +.P .nf ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US .fi -.PP +.P To just get its postal address attribute, request: -.PP +.P .nf ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress .fi -.PP +.P To ask a host.com at port 6666 for information about the person with common name (cn) "Babs Jensen" at University of Michigan, request: -.PP +.P .nf ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen) .fi -.PP +.P .B "wais \- Wide Area Information Servers" -.PP +.P .RI wais:// hostport / database .br .RI wais:// hostport / database ? search .br .RI wais:// hostport / database / wtype / wpath -.PP +.P This scheme designates a WAIS database, search, or document (see .UR http://www.ietf.org\:/rfc\:/rfc1625.txt @@ -507,7 +507,7 @@ IETF RFC\ 1625 for more information on WAIS). Hostport is the hostname, optionally followed by a colon and port number (the default port number is 210). -.PP +.P The first form designates a WAIS database for searching. The second form designates a particular search of the WAIS database .IR database . @@ -517,9 +517,9 @@ database to be retrieved. is the WAIS designation of the type of the object and .I wpath is the WAIS document-id. -.PP +.P .B "other schemes" -.PP +.P There are many other URI schemes. Most tools that accept URIs support a set of internal URIs (e.g., Mozilla has the about: scheme for internal information, @@ -536,7 +536,7 @@ Not all tools support all schemes. .SS Character encoding URIs use a limited number of characters so that they can be typed in and used in a variety of situations. -.PP +.P The following characters are reserved, that is, they may appear in a URI but their use is limited to their reserved purpose (conflicting data must be escaped before forming the URI): @@ -546,7 +546,7 @@ URI but their use is limited to their reserved purpose ; / ? : @ & = + $ , .EE .in -.PP +.P Unreserved characters may be included in a URI. Unreserved characters include uppercase and lowercase Latin letters, @@ -558,7 +558,7 @@ limited set of punctuation marks and symbols: \- _ . ! \[ti] * ' ( ) .EE .in -.PP +.P All other characters must be escaped. An escaped octet is encoded as a character triplet, consisting of the percent character "%" followed by the two hexadecimal digits @@ -573,13 +573,13 @@ in query text; this practice isn't uniformly defined in the relevant RFCs (which recommend %20 instead) but any tool accepting URIs with query text should be prepared for them. A URI is always shown in its "escaped" form. -.PP +.P Unreserved characters can be escaped without changing the semantics of the URI, but this should not be done unless the URI is being used in a context that does not allow the unescaped character to appear. For example, "%7e" is sometimes used instead of "\[ti]" in an HTTP URL path, but the two are equivalent for an HTTP URL. -.PP +.P For URIs which must handle characters outside the US ASCII character set, the HTML 4.01 specification (section B.2) and IETF RFC\~3986 (last paragraph of section 2.5) @@ -609,7 +609,7 @@ This latter system, called the 'new' or 'logical' quoting system by is preferred practice in Great Britain and in various European languages. Older documents suggested inserting the prefix "URL:" just before the URI, but this form has never caught on. -.PP +.P The URI syntax was designed to be unambiguous. However, as URIs have become commonplace, traditional media (television, radio, newspapers, billboards, etc.) have increasingly @@ -644,9 +644,9 @@ be able to handle (directly or indirectly) all of the schemes described here, including the man: and info: schemes. Handling them by invoking some other program is fine and in fact encouraged. -.PP +.P Technically the fragment isn't part of the URI. -.PP +.P For information on how to embed URIs (including URLs) in a data format, see documentation on that format. HTML uses the format <A HREF="\fIuri\fP"> @@ -655,7 +655,7 @@ HTML uses the format <A HREF="\fIuri\fP"> Texinfo files use the format @uref{\fIuri\fP}. Man and mdoc have the recently added UR macro, or just include the URI in the text (viewers should be able to detect :// as part of a URI). -.PP +.P The GNOME and KDE desktop environments currently vary in the URIs they accept, in particular in their respective help browsers. To list man pages, GNOME uses <toc:man> while KDE uses <man:(index)>, and @@ -685,7 +685,7 @@ guarantee that a URL will not locate a different resource at some later point in time; such a guarantee can be obtained only from the person(s) controlling that namespace and the resource in question. -.PP +.P It is sometimes possible to construct a URL such that an attempt to perform a seemingly harmless operation, such as the retrieval of an entity associated with the resource, will in fact @@ -700,11 +700,11 @@ interpreted according to this other protocol, cause an unexpected operation. An example has been the use of a gopher URL to cause an unintended or impersonating message to be sent via a SMTP server. -.PP +.P Caution should be used when using any URL that specifies a port number other than the default for the protocol, especially when it is a number within the reserved space. -.PP +.P Care should be taken when a URI contains escaped delimiters for a given protocol (for example, CR and LF characters for telnet protocols) that these are not unescaped before transmission. @@ -712,7 +712,7 @@ This might violate the protocol, but avoids the potential for such characters to be used to simulate an extra operation or parameter in that protocol, which might lead to an unexpected and possibly harmful remote operation to be performed. -.PP +.P It is clearly unwise to use a URI that contains a password which is intended to be secret. In particular, the use of a password within @@ -739,10 +739,10 @@ without having to know the exact location of that documentation. Alternatively, a future version of the filesystem specification may specify file locations sufficiently so that the file: scheme will be able to locate documentation. -.PP +.P Many programs and file formats don't include a way to incorporate or implement links using URIs. -.PP +.P Many programs can't handle all of these different URI formats; there should be a standard mechanism to load an arbitrary URI that automatically detects the users' environment (e.g., text or graphics, @@ -755,7 +755,7 @@ tools) and invokes the right tool for any URI. .BR man2html (1), .BR mailaddr (7), .BR utf\-8 (7) -.PP +.P .UR http://www.ietf.org\:/rfc\:/rfc2255.txt IETF RFC\ 2255 .UE diff --git a/upstream/debian-unstable/man7/user-keyring.7 b/upstream/debian-unstable/man7/user-keyring.7 index 7468cc50..68f3f48c 100644 --- a/upstream/debian-unstable/man7/user-keyring.7 +++ b/upstream/debian-unstable/man7/user-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH user-keyring 7 2023-02-05 "Linux man-pages 6.05.01" +.TH user-keyring 7 2024-05-02 "Linux man-pages 6.8" .SH NAME user-keyring \- per-user keyring .SH DESCRIPTION @@ -15,7 +15,7 @@ The user keyring has a name (description) of the form where .I <UID> is the user ID of the corresponding user. -.PP +.P The user keyring is associated with the record that the kernel maintains for the UID. It comes into existence upon the first attempt to access either the @@ -27,28 +27,28 @@ The keyring remains pinned in existence so long as there are processes running with that real UID or files opened by those processes remain open. (The keyring can also be pinned indefinitely by linking it into another keyring.) -.PP +.P Typically, the user keyring is created by .BR pam_keyinit (8) when a user logs in. -.PP +.P The user keyring is not searched by default by .BR request_key (2). When .BR pam_keyinit (8) creates a session keyring, it adds to it a link to the user keyring so that the user keyring will be searched when the session keyring is. -.PP +.P A special serial number value, .BR KEY_SPEC_USER_KEYRING , is defined that can be used in lieu of the actual serial number of the calling process's user keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@u\fP' can be used instead of a numeric key ID in much the same way. -.PP +.P User keyrings are independent of .BR clone (2), .BR fork (2), @@ -58,14 +58,14 @@ and .BR _exit (2) excepting that the keyring is destroyed when the UID record is destroyed when the last process pinning it exits. -.PP +.P If it is necessary for a key associated with a user to exist beyond the UID record being garbage collected\[em]for example, for use by a .BR cron (8) script\[em]then the .BR persistent\-keyring (7) should be used instead. -.PP +.P If a user keyring does not exist when it is accessed, it will be created. .SH SEE ALSO .ad l diff --git a/upstream/debian-unstable/man7/user-session-keyring.7 b/upstream/debian-unstable/man7/user-session-keyring.7 index 3fc87956..1f3312b4 100644 --- a/upstream/debian-unstable/man7/user-session-keyring.7 +++ b/upstream/debian-unstable/man7/user-session-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH user-session-keyring 7 2023-02-05 "Linux man-pages 6.05.01" +.TH user-session-keyring 7 2024-05-02 "Linux man-pages 6.8" .SH NAME user-session-keyring \- per-user default session keyring .SH DESCRIPTION @@ -15,7 +15,7 @@ The user session keyring has a name (description) of the form where .I <UID> is the user ID of the corresponding user. -.PP +.P The user session keyring is associated with the record that the kernel maintains for the UID. It comes into existence upon the first attempt to access either the @@ -28,7 +28,7 @@ The keyring remains pinned in existence so long as there are processes running with that real UID or files opened by those processes remain open. (The keyring can also be pinned indefinitely by linking it into another keyring.) -.PP +.P The user session keyring is created on demand when a thread requests it or when a thread asks for its .BR session\-keyring (7) @@ -36,22 +36,22 @@ and that keyring doesn't exist. In the latter case, a user session keyring will be created and, if the session keyring wasn't to be created, the user session keyring will be set as the process's actual session keyring. -.PP +.P The user session keyring is searched by .BR request_key (2) if the actual session keyring does not exist and is ignored otherwise. -.PP +.P A special serial number value, .BR KEY_SPEC_USER_SESSION_KEYRING , is defined that can be used in lieu of the actual serial number of the calling process's user session keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@us\fP' can be used instead of a numeric key ID in much the same way. -.PP +.P User session keyrings are independent of .BR clone (2), .BR fork (2), @@ -61,10 +61,10 @@ and .BR _exit (2) excepting that the keyring is destroyed when the UID record is destroyed when the last process pinning it exits. -.PP +.P If a user session keyring does not exist when it is accessed, it will be created. -.PP +.P Rather than relying on the user session keyring, it is strongly recommended\[em]especially if the process is running as root\[em]that a diff --git a/upstream/debian-unstable/man7/user_namespaces.7 b/upstream/debian-unstable/man7/user_namespaces.7 index 0c29f93e..8ff49bbb 100644 --- a/upstream/debian-unstable/man7/user_namespaces.7 +++ b/upstream/debian-unstable/man7/user_namespaces.7 @@ -4,13 +4,13 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH user_namespaces 7 2023-05-03 "Linux man-pages 6.05.01" +.TH user_namespaces 7 2024-05-02 "Linux man-pages 6.8" .SH NAME user_namespaces \- overview of Linux user namespaces .SH DESCRIPTION For an overview of namespaces, see .BR namespaces (7). -.PP +.P User namespaces isolate security-related identifiers and attributes, in particular, user IDs and group IDs (see @@ -46,7 +46,7 @@ or with the .B CLONE_NEWUSER flag. -.PP +.P The kernel imposes (since Linux 3.11) a limit of 32 nested levels of .\" commit 8742f229b635bf1c1c84a3dfe5e47c814c20b5c8 user namespaces. @@ -57,7 +57,7 @@ or .BR clone (2) that would cause this limit to be exceeded fail with the error .BR EUSERS . -.PP +.P Each process is a member of exactly one user namespace. A process created via .BR fork (2) @@ -72,7 +72,7 @@ if it has the .B CAP_SYS_ADMIN in that namespace; upon doing so, it gains a full set of capabilities in that namespace. -.PP +.P A call to .BR clone (2) or @@ -84,14 +84,14 @@ flag makes the new child process (for or the caller (for .BR unshare (2)) a member of the new user namespace created by the call. -.PP +.P The .B NS_GET_PARENT .BR ioctl (2) operation can be used to discover the parental relationship between user namespaces; see .BR ioctl_ns (2). -.PP +.P A task that changes one of its effective IDs will have its dumpability reset to the value in .IR /proc/sys/fs/suid_dumpable . @@ -134,7 +134,7 @@ and user namespace, even if the new namespace is created or joined by the root user (i.e., a process with user ID 0 in the root namespace). -.PP +.P Note that a call to .BR execve (2) will cause a process's capabilities to be recalculated in the usual way (see @@ -144,7 +144,7 @@ unless the process has a user ID of 0 within the namespace, or the executable file has a nonempty inheritable capabilities mask, the process will lose all capabilities. See the discussion of user and group ID mappings, below. -.PP +.P A call to .BR clone (2) or @@ -172,7 +172,7 @@ retaining its user namespace membership by using a pair of .BR setns (2) calls to move to another user namespace and then return to its original user namespace. -.PP +.P The rules for determining whether or not a process has a capability in a particular user namespace are as follows: .IP \[bu] 3 @@ -230,7 +230,7 @@ In other words, having a capability in a user namespace permits a process to perform privileged operations on resources that are governed by (nonuser) namespaces owned by (associated with) the user namespace (see the next subsection). -.PP +.P On the other hand, there are many privileged operations that affect resources that are not associated with any namespace type, for example, changing the system (i.e., calendar) time (governed by @@ -242,14 +242,14 @@ and creating a device (governed by Only a process with privileges in the .I initial user namespace can perform such operations. -.PP +.P Holding .B CAP_SYS_ADMIN within the user namespace that owns a process's mount namespace allows that process to create bind mounts and mount the following types of filesystems: .\" fs_flags = FS_USERNS_MOUNT in kernel sources -.PP +.P .RS 4 .PD 0 .IP \[bu] 3 @@ -281,7 +281,7 @@ and mount the following types of filesystems: (since Linux 5.11) .PD .RE -.PP +.P Holding .B CAP_SYS_ADMIN within the user namespace that owns a process's cgroup namespace @@ -289,9 +289,9 @@ allows (since Linux 4.6) that process to the mount the cgroup version 2 filesystem and cgroup version 1 named hierarchies (i.e., cgroup filesystems mounted with the -.I """none,name=""" +.I \[dq]none,name=\[dq] option). -.PP +.P Holding .B CAP_SYS_ADMIN within the user namespace that owns a process's PID namespace @@ -299,7 +299,7 @@ allows (since Linux 3.8) that process to mount .I /proc filesystems. -.PP +.P Note, however, that mounting block-based filesystems can be done only by a process that holds .B CAP_SYS_ADMIN @@ -312,14 +312,14 @@ Starting in Linux 3.8, unprivileged processes can create user namespaces, and the other types of namespaces can be created with just the .B CAP_SYS_ADMIN capability in the caller's user namespace. -.PP +.P When a nonuser namespace is created, it is owned by the user namespace in which the creating process was a member at the time of the creation of the namespace. Privileged operations on resources governed by the nonuser namespace require that the process has the necessary capabilities in the user namespace that owns the nonuser namespace. -.PP +.P If .B CLONE_NEWUSER is specified along with other @@ -336,7 +336,7 @@ or caller privileges over the remaining namespaces created by the call. Thus, it is possible for an unprivileged caller to specify this combination of flags. -.PP +.P When a new namespace (other than a user namespace) is created via .BR clone (2) or @@ -358,7 +358,7 @@ the process's UTS namespace, and check whether the process has the required capability .RB ( CAP_SYS_ADMIN ) in that user namespace. -.PP +.P The .B NS_GET_USERNS .BR ioctl (2) @@ -383,13 +383,13 @@ inside the user namespace for the process .IR pid . These files can be read to view the mappings in a user namespace and written to (once) to define the mappings. -.PP +.P The description in the following paragraphs explains the details for .IR uid_map ; .I gid_map is exactly the same, but each instance of "user ID" is replaced by "group ID". -.PP +.P The .I uid_map file exposes the mapping of user IDs from the user namespace @@ -403,7 +403,7 @@ will potentially see different values when reading from a particular .I uid_map file, depending on the user ID mappings for the user namespaces of the reading processes. -.PP +.P Each line in the .I uid_map file specifies a 1-to-1 mapping of a range of contiguous @@ -448,14 +448,14 @@ that created this user namespace. .IP (3) The length of the range of user IDs that is mapped between the two user namespaces. -.PP +.P System calls that return user IDs (group IDs)\[em]for example, .BR getuid (2), .BR getgid (2), and the credential fields in the structure returned by .BR stat (2)\[em]return the user ID (group ID) mapped into the caller's user namespace. -.PP +.P When a process accesses a file, its user and group IDs are mapped into the initial user namespace for the purpose of permission checking and assigning IDs when creating a file. @@ -463,7 +463,7 @@ When a process retrieves file user and group IDs via .BR stat (2), the IDs are mapped in the opposite direction, to produce values relative to the process user and group ID mappings. -.PP +.P The initial user namespace has no parent namespace, but, for consistency, the kernel provides dummy user and group ID mapping files for this namespace. @@ -472,14 +472,14 @@ Looking at the file .RI ( gid_map is the same) from a shell in the initial namespace shows: -.PP +.P .in +4n .EX $ \fBcat /proc/$$/uid_map\fP 0 0 4294967295 .EE .in -.PP +.P This mapping tells us that the range starting at user ID 0 in this namespace maps to a range starting at 0 in the (nonexistent) parent namespace, @@ -512,7 +512,7 @@ file in a user namespace fails with the error Similar rules apply for .I gid_map files. -.PP +.P The lines written to .I uid_map .RI ( gid_map ) @@ -552,10 +552,10 @@ Linux 3.9 and later fix this limitation, allowing any valid set of nonoverlapping maps. .IP \[bu] At least one line must be written to the file. -.PP +.P Writes that violate the above rules fail with the error .BR EINVAL . -.PP +.P In order for a process to write to the .IR /proc/ pid /uid_map .RI ( /proc/ pid /gid_map ) @@ -661,7 +661,7 @@ file (see below) before writing to .IR gid_map . .RE .RE -.PP +.P Writes that violate the above rules fail with the error .BR EPERM . .\" @@ -674,13 +674,13 @@ it is possible to create project ID mappings for a user namespace. .BR setquota (8) and .BR quotactl (2).) -.PP +.P Project ID mappings are defined by writing to the .IR /proc/ pid /projid_map file (present since .\" commit f76d207a66c3a53defea67e7d36c3eb1b7d6d61d Linux 3.7). -.PP +.P The validity rules for writing to the .IR /proc/ pid /projid_map file are as for writing to the @@ -689,7 +689,7 @@ file; violation of these rules causes .BR write (2) to fail with the error .BR EINVAL . -.PP +.P The permission rules for writing to the .IR /proc/ pid /projid_map file are as follows: @@ -701,7 +701,7 @@ or be in the parent user namespace of the process .IP \[bu] The mapped project IDs must in turn have a mapping in the parent user namespace. -.PP +.P Violation of these rules causes .BR write (2) to fail with the error @@ -722,7 +722,7 @@ and .I gid_map files have been written, only the mapped values may be used in system calls that change user and group IDs. -.PP +.P For user IDs, the relevant system calls include .BR setuid (2), .BR setfsuid (2), @@ -736,7 +736,7 @@ For group IDs, the relevant system calls include .BR setresgid (2), and .BR setgroups (2). -.PP +.P Writing .RI \[dq] deny \[dq] to the @@ -784,7 +784,7 @@ file (and regardless of the process's capabilities), calls to are also not permitted if .IR /proc/ pid /gid_map has not yet been set. -.PP +.P A privileged process (one with the .B CAP_SYS_ADMIN capability in the namespace) may write either of the strings @@ -800,7 +800,7 @@ Writing the string .RI \[dq] deny \[dq] prevents any process in the user namespace from employing .BR setgroups (2). -.PP +.P The essence of the restrictions described in the preceding paragraph is that it is permitted to write to .IR /proc/ pid /setgroups @@ -819,10 +819,10 @@ a process can transition only from being disallowed to .BR setgroups (2) being allowed. -.PP +.P The default value of this file in the initial user namespace is .RI \[dq] allow \[dq]. -.PP +.P Once .IR /proc/ pid /gid_map has been written to @@ -837,11 +837,11 @@ to .IR /proc/ pid /setgroups (the write fails with the error .BR EPERM ). -.PP +.P A child user namespace inherits the .IR /proc/ pid /setgroups setting from its parent. -.PP +.P If the .I setgroups file has the value @@ -855,7 +855,7 @@ to the file) in this user namespace. .BR EPERM .) This restriction also propagates down to all child user namespaces of this user namespace. -.PP +.P The .IR /proc/ pid /setgroups file was added in Linux 3.19, @@ -913,7 +913,7 @@ and .I /proc/sys/kernel/overflowgid in .BR proc (5). -.PP +.P The cases where unmapped IDs are mapped in this fashion include system calls that return user IDs .RB ( getuid (2), @@ -941,7 +941,7 @@ credentials written to the process accounting file (see .BR acct (5)), and credentials returned with POSIX message queue notifications (see .BR mq_notify (3)). -.PP +.P There is one notable case where unmapped user and group IDs are .I not .\" from_kuid(), from_kgid() @@ -978,7 +978,7 @@ These capabilities are: .BR CAP_FOWNER , and .BR CAP_FSETID . -.PP +.P Within a user namespace, these capabilities allow a process to bypass the rules if the process has the relevant capability over the file, @@ -988,7 +988,7 @@ the process has the relevant effective capability in its user namespace; and .IP \[bu] the file's user ID and group ID both have valid mappings in the user namespace. -.PP +.P The .B CAP_FOWNER capability is treated somewhat exceptionally: @@ -1057,7 +1057,7 @@ User namespaces require support in a range of subsystems across the kernel. When an unsupported subsystem is configured into the kernel, it is not possible to configure user namespaces support. -.PP +.P As at Linux 3.8, most relevant subsystems supported user namespaces, but a number of filesystems did not have the infrastructure needed to map user and group IDs between user namespaces. @@ -1077,9 +1077,9 @@ The comments and .IR usage () function inside the program provide a full explanation of the program. The following shell session demonstrates its use. -.PP +.P First, we look at the run-time environment: -.PP +.P .in +4n .EX $ \fBuname \-rs\fP # Need Linux 3.8 or later @@ -1090,7 +1090,7 @@ $ \fBid \-g\fP 1000 .EE .in -.PP +.P Now start a new shell in new user .RI ( \-U ), mount @@ -1102,29 +1102,29 @@ namespaces, with user ID and group ID .RI ( \-G ) 1000 mapped to 0 inside the user namespace: -.PP +.P .in +4n .EX $ \fB./userns_child_exec \-p \-m \-U \-M \[aq]0 1000 1\[aq] \-G \[aq]0 1000 1\[aq] bash\fP .EE .in -.PP +.P The shell has PID 1, because it is the first process in the new PID namespace: -.PP +.P .in +4n .EX bash$ \fBecho $$\fP 1 .EE .in -.PP +.P Mounting a new .I /proc filesystem and listing all of the processes visible in the new PID namespace shows that the shell can't see any processes outside the PID namespace: -.PP +.P .in +4n .EX bash$ \fBmount \-t proc proc /proc\fP @@ -1134,10 +1134,10 @@ bash$ \fBps ax\fP 22 pts/3 R+ 0:00 ps ax .EE .in -.PP +.P Inside the user namespace, the shell has user and group ID 0, and a full set of permitted and effective capabilities: -.PP +.P .in +4n .EX bash$ \fBcat /proc/$$/status | egrep \[aq]\[ha][UG]id\[aq]\fP @@ -1464,6 +1464,6 @@ main(int argc, char *argv[]) .BR credentials (7), .BR namespaces (7), .BR pid_namespaces (7) -.PP +.P The kernel source file .IR Documentation/admin\-guide/namespaces/resource\-control.rst . diff --git a/upstream/debian-unstable/man7/utf-8.7 b/upstream/debian-unstable/man7/utf-8.7 index 8a5f7ab7..0ffd356e 100644 --- a/upstream/debian-unstable/man7/utf-8.7 +++ b/upstream/debian-unstable/man7/utf-8.7 @@ -7,7 +7,7 @@ .\" 2001-05-11 Markus Kuhn <mgk25@cl.cam.ac.uk> .\" Update .\" -.TH UTF-8 7 2023-03-12 "Linux man-pages 6.05.01" +.TH UTF-8 7 2024-05-02 "Linux man-pages 6.8" .SH NAME UTF-8 \- an ASCII compatible multibyte Unicode encoding .SH DESCRIPTION @@ -27,14 +27,13 @@ The ISO/IEC 10646 Universal Character Set (UCS), a superset of Unicode, occupies an even larger code space\[em]31\ bits\[em]and the obvious UCS-4 encoding for it (a sequence of 32-bit words) has the same problems. -.PP +.P The UTF-8 encoding of Unicode and UCS does not have these problems and is the common way in which Unicode is used on UNIX-style operating systems. .SS Properties The UTF-8 encoding has the following nice properties: -.TP 0.2i -* +.IP \[bu] 3 UCS characters 0x00000000 to 0x0000007f (the classic US-ASCII characters) are encoded simply as bytes 0x00 to 0x7f (ASCII @@ -43,24 +42,19 @@ This means that files and strings which contain only 7-bit ASCII characters have the same encoding under both ASCII and -UTF-8 . -.TP -* +UTF-8. +.IP \[bu] All UCS characters greater than 0x7f are encoded as a multibyte sequence consisting only of bytes in the range 0x80 to 0xfd, so no ASCII byte can appear as part of another character and there are no problems with, for example, \[aq]\e0\[aq] or \[aq]/\[aq]. -.TP -* +.IP \[bu] The lexicographic sorting order of UCS-4 strings is preserved. -.TP -* +.IP \[bu] All possible 2\[ha]31 UCS codes can be encoded using UTF-8. -.TP -* +.IP \[bu] The bytes 0xc0, 0xc1, 0xfe, and 0xff are never used in the UTF-8 encoding. -.TP -* +.IP \[bu] The first byte of a multibyte sequence which represents a single non-ASCII UCS character is always in the range 0xc2 to 0xfd and indicates how long this multibyte sequence is. @@ -68,8 +62,7 @@ All further bytes in a multibyte sequence are in the range 0x80 to 0xbf. This allows easy resynchronization and makes the encoding stateless and robust against missing bytes. -.TP -* +.IP \[bu] UTF-8 encoded UCS characters may be up to six bytes long, however the Unicode standard specifies no characters above 0x10ffff, so Unicode characters can be only up to four bytes long in @@ -77,7 +70,7 @@ UTF-8. .SS Encoding The following byte sequences are used to represent a character. The sequence to be used depends on the UCS code number of the character: -.TP 0.4i +.TP 0x00000000 \- 0x0000007F: .RI 0 xxxxxxx .TP @@ -110,14 +103,14 @@ The sequence to be used depends on the UCS code number of the character: .RI 10 xxxxxx .RI 10 xxxxxx .RI 10 xxxxxx -.PP +.P The .I xxx bit positions are filled with the bits of the character code number in binary representation, most significant bit first (big-endian). Only the shortest possible multibyte sequence which can represent the code number of the character can be used. -.PP +.P The UCS code values 0xd800\[en]0xdfff (UTF-16 surrogates) as well as 0xfffe and 0xffff (UCS noncharacters) should not appear in conforming UTF-8 streams. According to RFC 3629 no point above U+10FFFF should be used, @@ -125,45 +118,46 @@ which limits characters to four bytes. .SS Example The Unicode character 0xa9 = 1010 1001 (the copyright sign) is encoded in UTF-8 as -.PP +.P .RS 11000010 10101001 = 0xc2 0xa9 .RE -.PP +.P and character 0x2260 = 0010 0010 0110 0000 (the "not equal" symbol) is encoded as: -.PP +.P .RS 11100010 10001001 10100000 = 0xe2 0x89 0xa0 .RE .SS Application notes Users have to select a UTF-8 locale, for example with -.PP +.P .RS export LANG=en_GB.UTF-8 .RE -.PP +.P in order to activate the UTF-8 support in applications. -.PP +.P Application software that has to be aware of the used character encoding should always set the locale with for example -.PP +.P .RS setlocale(LC_CTYPE, "") .RE -.PP +.P and programmers can then test the expression -.PP +.P .RS strcmp(nl_langinfo(CODESET), "UTF-8") == 0 .RE -.PP +.P to determine whether a UTF-8 locale has been selected and whether therefore all plaintext standard input and output, terminal communication, plaintext file content, filenames, and environment variables are encoded in UTF-8. -.PP -Programmers accustomed to single-byte encodings such as US-ASCII or ISO 8859 +.P +Programmers accustomed to single-byte encodings +such as US-ASCII or ISO/IEC\~8859 have to be aware that two assumptions made so far are no longer valid in UTF-8 locales. Firstly, a single byte does not necessarily correspond any @@ -178,14 +172,14 @@ Library functions such as and .BR wcswidth (3) should be used today to count characters and cursor positions. -.PP -The official ESC sequence to switch from an ISO 2022 +.P +The official ESC sequence to switch from an ISO/IEC\~2022 encoding scheme (as used for instance by VT100 terminals) to UTF-8 is ESC % G ("\ex1b%G"). The corresponding return sequence from -UTF-8 to ISO 2022 is ESC % @ ("\ex1b%@"). -Other ISO 2022 sequences (such as +UTF-8 to ISO/IEC\~2022 is ESC % @ ("\ex1b%@"). +Other ISO/IEC\~2022 sequences (such as for switching the G0 and G1 sets) are not applicable in UTF-8 mode. .SS Security The Unicode and UCS standards require that producers of UTF-8 diff --git a/upstream/debian-unstable/man7/uts_namespaces.7 b/upstream/debian-unstable/man7/uts_namespaces.7 index 670d19ea..7207c90e 100644 --- a/upstream/debian-unstable/man7/uts_namespaces.7 +++ b/upstream/debian-unstable/man7/uts_namespaces.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH uts_namespaces 7 2022-12-04 "Linux man-pages 6.05.01" +.TH uts_namespaces 7 2024-05-02 "Linux man-pages 6.8" .SH NAME uts_namespaces \- overview of Linux UTS namespaces .SH DESCRIPTION @@ -21,7 +21,7 @@ and Changes made to these identifiers are visible to all other processes in the same UTS namespace, but are not visible to processes in other UTS namespaces. -.PP +.P When a process creates a new UTS namespace using .BR clone (2) or @@ -30,7 +30,7 @@ with the .B CLONE_NEWUTS flag, the hostname and domain name of the new UTS namespace are copied from the corresponding values in the caller's UTS namespace. -.PP +.P Use of UTS namespaces requires a kernel that is configured with the .B CONFIG_UTS_NS option. diff --git a/upstream/debian-unstable/man7/vdso.7 b/upstream/debian-unstable/man7/vdso.7 index 338ef722..c2c67c2c 100644 --- a/upstream/debian-unstable/man7/vdso.7 +++ b/upstream/debian-unstable/man7/vdso.7 @@ -11,13 +11,13 @@ .\" http://www.linuxjournal.com/content/creating-vdso-colonels-other-chicken .\" http://www.trilithium.com/johan/2005/08/linux-gate/ .\" -.TH vDSO 7 2023-05-03 "Linux man-pages 6.05.01" +.TH vDSO 7 2024-05-02 "Linux man-pages 6.8" .SH NAME vdso \- overview of the virtual ELF dynamic shared object .SH SYNOPSIS .nf .B #include <sys/auxv.h> -.PP +.P .B void *vdso = (uintptr_t) getauxval(AT_SYSINFO_EHDR); .fi .SH DESCRIPTION @@ -29,7 +29,7 @@ as the vDSO is most commonly called by the C library. This way you can code in the normal way using standard functions and the C library will take care of using any functionality that is available via the vDSO. -.PP +.P Why does the vDSO exist at all? There are some system calls the kernel provides that user-space code ends up using frequently, @@ -37,7 +37,7 @@ to the point that such calls can dominate overall performance. This is due both to the frequency of the call as well as the context-switch overhead that results from exiting user space and entering the kernel. -.PP +.P The rest of this documentation is geared toward the curious and/or C library writers rather than general developers. If you're trying to call the vDSO in your own application rather than using @@ -56,14 +56,14 @@ Rather than require the C library to figure out if this functionality is available at run time, the C library can use functions provided by the kernel in the vDSO. -.PP +.P Note that the terminology can be confusing. On x86 systems, the vDSO function used to determine the preferred method of making a system call is named "__kernel_vsyscall", but on x86-64, the term "vsyscall" also refers to an obsolete way to ask the kernel what time it is or what CPU the caller is on. -.PP +.P One frequently used system call is .BR gettimeofday (2). This system call is called both directly by user-space applications @@ -86,7 +86,7 @@ each program in the initial auxiliary vector (see via the .B AT_SYSINFO_EHDR tag. -.PP +.P You must not assume the vDSO is mapped at any particular location in the user's memory map. The base address will usually be randomized at run time every time a new @@ -95,7 +95,7 @@ process image is created (at time). This is done for security reasons, to prevent "return-to-libc" attacks. -.PP +.P For some architectures, there is also an .B AT_SYSINFO tag. @@ -111,7 +111,7 @@ and allows the C library to detect available functionality at run time when running under different kernel versions. Oftentimes the C library will do detection with the first call and then cache the result for subsequent calls. -.PP +.P All symbols are also versioned (using the GNU version format). This allows the kernel to update the function signature without breaking backward compatibility. @@ -120,12 +120,12 @@ return value. Thus, when looking up a symbol in the vDSO, you must always include the version to match the ABI you expect. -.PP +.P Typically the vDSO follows the naming convention of prefixing all symbols with "__vdso_" or "__kernel_" so as to distinguish them from other standard symbols. For example, the "gettimeofday" function is named "__vdso_gettimeofday". -.PP +.P You use the standard C calling conventions when calling any of these functions. No need to worry about weird register or stack behavior. @@ -134,7 +134,7 @@ No need to worry about weird register or stack behavior. When you compile the kernel, it will automatically compile and link the vDSO code for you. You will frequently find it under the architecture-specific directory: -.PP +.P .in +4n .EX find arch/$ARCH/ \-name \[aq]*vdso*.so*\[aq] \-o \-name \[aq]*gate*.so*\[aq] @@ -173,7 +173,7 @@ x86/x32 linux\-vdso.so.1 .ft P \} .SS strace(1), seccomp(2), and the vDSO -When tracing systems calls with +When tracing system calls with .BR strace (1), symbols (system calls) that are exported by the vDSO will .I not @@ -184,7 +184,7 @@ filters. .SH ARCHITECTURE-SPECIFIC NOTES The subsections below provide architecture-specific notes on the vDSO. -.PP +.P Note that the vDSO that is used is based on the ABI of your user-space code and not the ABI of the kernel. Thus, for example, @@ -211,14 +211,14 @@ __vdso_clock_gettime LINUX_2.6 (exported since Linux 4.1) .in .ft P \} -.PP +.P .\" See linux/arch/arm/kernel/entry-armv.S .\" See linux/Documentation/arm/kernel_user_helpers.rst Additionally, the ARM port has a code page full of utility functions. Since it's just a raw page of code, there is no ELF information for doing symbol lookups or versioning. It does provide support for different versions though. -.PP +.P For information on this code page, it's best to refer to the kernel documentation as it's extremely detailed and covers everything you need to know: @@ -254,7 +254,7 @@ There is no provision for backward compatibility beyond sniffing raw opcodes, but as this is an embedded CPU, it can get away with things\[em]some of the object formats it runs aren't even ELF based (they're bFLT/FLAT). -.PP +.P For information on this code page, it's best to refer to the public documentation: .br @@ -295,7 +295,7 @@ __kernel_syscall_via_epc LINUX_2.5 .in .ft P \} -.PP +.P The Itanium port is somewhat tricky. In addition to the vDSO above, it also has "light-weight system calls" (also known as "fast syscalls" or "fsys"). @@ -337,12 +337,12 @@ the page to the process via the SR2 register. The permissions on the page are such that merely executing those addresses automatically executes with kernel privileges and not in user space. This is done to match the way HP-UX works. -.PP +.P Since it's just a raw page of code, there is no ELF information for doing symbol lookups or versioning. Simply call into the appropriate offset via the branch instruction, for example: -.PP +.P .in +4n .EX ble <offset>(%sr2, %r0) @@ -394,7 +394,7 @@ __kernel_sync_dicache_p5 LINUX_2.6.15 .in .ft P \} -.PP +.P Before Linux 5.6, .\" commit 654abc69ef2e69712e6d4e8a6cb9292b97a4aa39 the @@ -434,7 +434,7 @@ __kernel_sync_dicache_p5 LINUX_2.6.15 .in .ft P \} -.PP +.P Before Linux 4.16, .\" commit 5c929885f1bb4b77f85b1769c49405a0e0f154a1 the @@ -598,15 +598,15 @@ to user space, so it was reconceived as a vDSO in the current format. .BR syscalls (2), .BR getauxval (3), .BR proc (5) -.PP +.P The documents, examples, and source code in the Linux source code tree: -.PP +.P .in +4n .EX Documentation/ABI/stable/vdso Documentation/ia64/fsys.rst Documentation/vDSO/* (includes examples of using the vDSO) -.PP +.P find arch/ \-iname \[aq]*vdso*\[aq] \-o \-iname \[aq]*gate*\[aq] .EE .in diff --git a/upstream/debian-unstable/man7/vsock.7 b/upstream/debian-unstable/man7/vsock.7 index f6c37110..fea5713c 100644 --- a/upstream/debian-unstable/man7/vsock.7 +++ b/upstream/debian-unstable/man7/vsock.7 @@ -2,14 +2,14 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH vsock 7 2022-10-30 "Linux man-pages 6.05.01" +.TH vsock 7 2024-05-02 "Linux man-pages 6.8" .SH NAME vsock \- Linux VSOCK address family .SH SYNOPSIS .nf .B #include <sys/socket.h> .B #include <linux/vm_sockets.h> -.PP +.P .IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);" .IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);" .fi @@ -19,7 +19,7 @@ the host they are running on. This address family is used by guest agents and hypervisor services that need a communications channel that is independent of virtual machine network configuration. -.PP +.P Valid socket types are .B SOCK_STREAM and @@ -31,26 +31,26 @@ provides a connectionless datagram packet service with best-effort delivery and best-effort ordering. Availability of these socket types is dependent on the underlying hypervisor. -.PP +.P A new socket is created with -.PP +.P .in +4n .EX socket(AF_VSOCK, socket_type, 0); .EE .in -.PP +.P When a process wants to establish a connection, it calls .BR connect (2) with a given destination socket address. The socket is automatically bound to a free port if unbound. -.PP +.P A process can listen for incoming connections by first binding to a socket address using .BR bind (2) and then calling .BR listen (2). -.PP +.P Data is transmitted using the .BR send (2) or @@ -67,7 +67,7 @@ The CID identifies the source or destination, which is either a virtual machine or the host. The port number differentiates between multiple services running on a single machine. -.PP +.P .in +4n .EX struct sockaddr_vm { @@ -83,7 +83,7 @@ struct sockaddr_vm { }; .EE .in -.PP +.P .I svm_family is always set to .BR AF_VSOCK . @@ -100,7 +100,7 @@ capability may to these port numbers. .I svm_zero must be zero-filled. -.PP +.P There are several special addresses: .B VMADDR_CID_ANY (\-1U) @@ -112,7 +112,7 @@ means any address for binding; .B VMADDR_CID_HOST (2) is the well-known address of the host. -.PP +.P The special constant .B VMADDR_PORT_ANY (\-1U) @@ -123,7 +123,7 @@ Connected .B SOCK_STREAM sockets become disconnected when the virtual machine migrates to a new host. Applications must reconnect when this happens. -.PP +.P The local CID may change across live migration if the old CID is not available on the new host. Bound sockets are automatically updated to the new CID. @@ -152,11 +152,11 @@ when binding instead of getting the local CID with (1) directs packets to the same host that generated them. This is useful for testing applications on a single host and for debugging. -.PP +.P The local CID obtained with .B IOCTL_VM_SOCKETS_GET_LOCAL_CID can be used for the same purpose, but it is preferable to use -.B VMADDR_CID_LOCAL . +.BR VMADDR_CID_LOCAL . .SH ERRORS .TP .B EACCES @@ -215,7 +215,7 @@ are valid. Support for VMware (VMCI) has been available since Linux 3.9. KVM (virtio) is supported since Linux 4.8. Hyper-V is supported since Linux 4.14. -.PP +.P .B VMADDR_CID_LOCAL is supported since Linux 5.6. .\" commit ef343b35d46667668a099655fca4a5b2e43a5dfe diff --git a/upstream/debian-unstable/man7/x25.7 b/upstream/debian-unstable/man7/x25.7 index 1dc498ea..1b424bd4 100644 --- a/upstream/debian-unstable/man7/x25.7 +++ b/upstream/debian-unstable/man7/x25.7 @@ -4,14 +4,16 @@ .\" .\" $Id: x25.7,v 1.4 1999/05/18 10:35:12 freitag Exp $ .\" -.TH x25 7 2023-07-15 "Linux man-pages 6.05.01" +.TH x25 7 2024-05-02 "Linux man-pages 6.8" .SH NAME -x25 \- ITU-T X.25 / ISO-8208 protocol interface +x25 +\- +ITU-T X.25 / ISO/IEC\~8208 protocol interface .SH SYNOPSIS .nf .B #include <sys/socket.h> .B #include <linux/x25.h> -.PP +.P .IB x25_socket " = socket(AF_X25, SOCK_SEQPACKET, 0);" .fi .SH DESCRIPTION @@ -22,8 +24,8 @@ International Telecommunication Union's recommendation X.25 (X.25 DTE-DCE mode). X25 sockets can also be used for communication without an intermediate X.25 network (X.25 DTE-DTE mode) as described -in ISO-8208. -.PP +in ISO/IEC\~8208. +.P Message boundaries are preserved \[em] a .BR read (2) from a socket will @@ -47,7 +49,7 @@ socket address family uses the .I struct sockaddr_x25 for representing network addresses as defined in ITU-T recommendation X.121. -.PP +.P .in +4n .EX struct sockaddr_x25 { @@ -56,7 +58,7 @@ struct sockaddr_x25 { }; .EE .in -.PP +.P .I sx25_addr contains a char array .I x25_addr[] @@ -98,23 +100,23 @@ The AF_X25 protocol family is a new feature of Linux 2.2. .SH BUGS Plenty, as the X.25 PLP implementation is .BR CONFIG_EXPERIMENTAL . -.PP +.P This man page is incomplete. -.PP +.P There is no dedicated application programmer's header file yet; you need to include the kernel header file .IR <linux/x25.h> . .B CONFIG_EXPERIMENTAL might also imply that future versions of the interface are not binary compatible. -.PP +.P X.25 N-Reset events are not propagated to the user process yet. Thus, if a reset occurred, data might be lost without notice. .SH SEE ALSO .BR socket (2), .BR socket (7) -.PP +.P Jonathan Simon Naylor: \[lq]The Re-Analysis and Re-Implementation of X.25.\[rq] The URL is diff --git a/upstream/debian-unstable/man7/x509.7ssl b/upstream/debian-unstable/man7/x509.7ssl index 445b7af2..69c79846 100644 --- a/upstream/debian-unstable/man7/x509.7ssl +++ b/upstream/debian-unstable/man7/x509.7ssl @@ -55,7 +55,7 @@ .\" ======================================================================== .\" .IX Title "X509 7SSL" -.TH X509 7SSL 2024-02-03 3.1.5 OpenSSL +.TH X509 7SSL 2024-04-04 3.2.2-dev OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l diff --git a/upstream/debian-unstable/man7/xattr.7 b/upstream/debian-unstable/man7/xattr.7 index c2f12c95..048d0857 100644 --- a/upstream/debian-unstable/man7/xattr.7 +++ b/upstream/debian-unstable/man7/xattr.7 @@ -6,7 +6,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH xattr 7 2023-02-05 "Linux man-pages 6.05.01" +.TH xattr 7 2024-05-02 "Linux man-pages 6.8" .SH NAME xattr \- Extended attributes .SH DESCRIPTION @@ -15,7 +15,7 @@ files and directories, similar to the environment strings associated with a process. An attribute may be defined or undefined. If it is defined, its value may be empty or non-empty. -.PP +.P Extended attributes are extensions to the normal attributes which are associated with all inodes in the system (i.e., the .BR stat (2) @@ -23,11 +23,11 @@ data). They are often used to provide additional functionality to a filesystem\[em]for example, additional security features such as Access Control Lists (ACLs) may be implemented using extended attributes. -.PP +.P Users with search access to a file or directory may use .BR listxattr (2) to retrieve a list of attribute names defined for that file or directory. -.PP +.P Extended attributes are accessed as atomic objects. Reading .RB ( getxattr (2)) @@ -35,7 +35,7 @@ retrieves the whole value of an attribute and stores it in a buffer. Writing .RB ( setxattr (2)) replaces any previous value with the new value. -.PP +.P Space consumed for extended attributes may be counted towards the disk quotas of the file owner and file group. .SS Extended attribute namespaces @@ -48,14 +48,14 @@ form, for example, .IR system.posix_acl_access , or .IR security.selinux . -.PP +.P The namespace mechanism is used to define different classes of extended attributes. These different classes exist for several reasons; for example, the permissions and capabilities required for manipulating extended attributes of one namespace may differ to another. -.PP +.P Currently, the .IR security , .IR system , @@ -97,7 +97,7 @@ The access permissions for user attributes are defined by the file permission bits: read permission is required to retrieve the attribute value, and writer permission is required to change it. -.PP +.P The file permission bits of regular files and directories are interpreted differently from the file permission bits of special files and symbolic links. @@ -108,7 +108,7 @@ The file permissions of symbolic links are not used in access checks. These differences would allow users to consume filesystem resources in a way not controllable by disk quotas for group or world writable special files and directories. -.PP +.P For this reason, user extended attributes are allowed only for regular files and directories, and access to user extended attributes is restricted to the @@ -125,26 +125,26 @@ The list of attribute names that can be returned is also limited to 64\ kB (see BUGS in .BR listxattr (2)). -.PP +.P Some filesystems, such as Reiserfs (and, historically, ext2 and ext3), require the filesystem to be mounted with the .B user_xattr mount option in order for user extended attributes to be used. -.PP +.P In the current ext2, ext3, and ext4 filesystem implementations, the total bytes used by the names and values of all of a file's extended attributes must fit in a single filesystem block (1024, 2048 or 4096 bytes, depending on the block size specified when the filesystem was created). -.PP +.P In the Btrfs, XFS, and Reiserfs filesystem implementations, there is no practical limit on the number of extended attributes associated with a file, and the algorithms used to store extended attribute information on disk are scalable. -.PP +.P In the JFS, XFS, and Reiserfs filesystem implementations, the limit on bytes used in an EA value is the ceiling imposed by the VFS. -.PP +.P In the Btrfs filesystem implementation, the total bytes used for the name, value, and implementation overhead bytes is limited to the filesystem @@ -158,7 +158,7 @@ Since the filesystems on which extended attributes are stored might also be used on architectures with a different byte order and machine word size, care should be taken to store attribute values in an architecture-independent format. -.PP +.P This page was formerly named .BR attr (5). .\" .SH AUTHORS |