* [PATCH] man-pages(7): Add attributive annotation advice
@ 2023-07-19 4:18 G. Branden Robinson
2023-07-19 20:01 ` Alejandro Colomar
0 siblings, 1 reply; 5+ messages in thread
From: G. Branden Robinson @ 2023-07-19 4:18 UTC (permalink / raw)
To: linux-man; +Cc: alx
[-- Attachment #1: Type: text/plain, Size: 1143 bytes --]
From 0e3a24fda10445d6fd92c7dbbfb54106b1284931 Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Date: Sat, 15 Jul 2023 14:54:32 -0500
Subject: [PATCH] man-pages(7): Add attributive annotation advice
Cc: Alejandro Colomar <alx@kernel.org>
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
---
man7/man-pages.7 | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/man7/man-pages.7 b/man7/man-pages.7
index d63f2d8f2..aa39dbfd2 100644
--- a/man7/man-pages.7
+++ b/man7/man-pages.7
@@ -255,6 +255,13 @@ .SS Sections within a manual page
Including version information is especially useful to users
who are constrained to using older kernel or C library versions
(which is typical in embedded systems, for example).
+.IP
+When an aspect of an interface requires multiple annotations,
+such as an applicable architecture,
+data type,
+or indication of read-only status,
+include these before the version information and separate them
+with semicolons.
.TP
.B OPTIONS
A description of the command-line options accepted by a
--
2.30.2
Regards,
Branden
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH] man-pages(7): Add attributive annotation advice
2023-07-19 4:18 [PATCH] man-pages(7): Add attributive annotation advice G. Branden Robinson
@ 2023-07-19 20:01 ` Alejandro Colomar
2023-07-20 2:13 ` G. Branden Robinson
0 siblings, 1 reply; 5+ messages in thread
From: Alejandro Colomar @ 2023-07-19 20:01 UTC (permalink / raw)
To: G. Branden Robinson, linux-man
[-- Attachment #1.1: Type: text/plain, Size: 1581 bytes --]
On 2023-07-19 06:18, G. Branden Robinson wrote:
> From 0e3a24fda10445d6fd92c7dbbfb54106b1284931 Mon Sep 17 00:00:00 2001
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> Date: Sat, 15 Jul 2023 14:54:32 -0500
> Subject: [PATCH] man-pages(7): Add attributive annotation advice
>
> Cc: Alejandro Colomar <alx@kernel.org>
> Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
> ---
> man7/man-pages.7 | 7 +++++++
> 1 file changed, 7 insertions(+)
>
> diff --git a/man7/man-pages.7 b/man7/man-pages.7
> index d63f2d8f2..aa39dbfd2 100644
> --- a/man7/man-pages.7
> +++ b/man7/man-pages.7
> @@ -255,6 +255,13 @@ .SS Sections within a manual page
> Including version information is especially useful to users
> who are constrained to using older kernel or C library versions
> (which is typical in embedded systems, for example).
> +.IP
> +When an aspect of an interface requires multiple annotations,
> +such as an applicable architecture,
> +data type,
> +or indication of read-only status,
> +include these before the version information and separate them
> +with semicolons.
I'm now doubting the necessity of this patch. It's like very
obvious content when you already know what it talks about, and
not very clear until you know what it's talking about. Maybe
following existing practice is just simpler.
Cheers,
Alex
> .TP
> .B OPTIONS
> A description of the command-line options accepted by a
--
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] man-pages(7): Add attributive annotation advice
2023-07-19 20:01 ` Alejandro Colomar
@ 2023-07-20 2:13 ` G. Branden Robinson
2023-07-20 8:24 ` Alejandro Colomar
0 siblings, 1 reply; 5+ messages in thread
From: G. Branden Robinson @ 2023-07-20 2:13 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: linux-man
[-- Attachment #1: Type: text/plain, Size: 472 bytes --]
At 2023-07-19T22:01:35+0200, Alejandro Colomar wrote:
> I'm now doubting the necessity of this patch. It's like very
> obvious content when you already know what it talks about, and
> not very clear until you know what it's talking about. Maybe
> following existing practice is just simpler.
Okay. I withdraw it.
(Also, waiting to see if my 275 KiB inline patch to "unbracket tables"
comes through. How should I get it to this list if it doesn't?)
Regards,
Branden
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] man-pages(7): Add attributive annotation advice
2023-07-20 2:13 ` G. Branden Robinson
@ 2023-07-20 8:24 ` Alejandro Colomar
2023-07-20 9:14 ` G. Branden Robinson
0 siblings, 1 reply; 5+ messages in thread
From: Alejandro Colomar @ 2023-07-20 8:24 UTC (permalink / raw)
To: G. Branden Robinson; +Cc: linux-man
[-- Attachment #1.1: Type: text/plain, Size: 930 bytes --]
On 2023-07-20 04:13, G. Branden Robinson wrote:
> At 2023-07-19T22:01:35+0200, Alejandro Colomar wrote:
>> I'm now doubting the necessity of this patch. It's like very
>> obvious content when you already know what it talks about, and
>> not very clear until you know what it's talking about. Maybe
>> following existing practice is just simpler.
>
> Okay. I withdraw it.
>
> (Also, waiting to see if my 275 KiB inline patch to "unbracket tables"
> comes through. How should I get it to this list if it doesn't?)
A gzip works, although in such cases of scripted patches, you can
just send the header of the patch, and maybe the first pages to
allow me to check the results of the script, and then I will
reproduce the patch myself by running the script.
Cheers,
Alex
>
> Regards,
> Branden
--
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] man-pages(7): Add attributive annotation advice
2023-07-20 8:24 ` Alejandro Colomar
@ 2023-07-20 9:14 ` G. Branden Robinson
0 siblings, 0 replies; 5+ messages in thread
From: G. Branden Robinson @ 2023-07-20 9:14 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: linux-man
[-- Attachment #1.1: Type: text/plain, Size: 504 bytes --]
Hi Alex,
At 2023-07-20T10:24:18+0200, Alejandro Colomar wrote:
> A gzip works,
And it did! I see it on lore.kernel.org.
> although in such cases of scripted patches, you can just send the
> header of the patch, and maybe the first pages to allow me to check
> the results of the script, and then I will reproduce the patch myself
> by running the script.
I did not include my annotations of the changes I observed when applying
it. I hope this will save you some time. Attached.
Regards,
Branden
[-- Attachment #1.2: dump-annotated.diff --]
[-- Type: text/x-diff, Size: 43509 bytes --]
Annotation key:
[MR]: Hyphenation will be suppressed by migration to `MR` macro.
[CH]: Change in hyphenation break location due to undesired change of
hyphenation mode by former use of `.hy` request outside of tbl(1)
data, which caused the hyphenation mode to be set to "1", which
works suboptimally with the TeX-based hyphenation patterns groff
has used since around 1990. (A better value for English is 4, and
this is used by default [unless loading of troffrc is suppressed]
in groff 1.23.0. I have further ideas to improve quality-of-life
around groff hyphenation; please raise the subject on groff@gnu if
interested.)
[HY]: New hyphenation breaks appear because I only disabled hyphenation
in text blocks that seemed to need it; that is, in the "Interface"
column of "MT-safety" tables, where the only cell content is a
list of C function names. Two text blocks in namespaces(7) were
ordinary prose that, other things being equal, should be formatted
ordinarily.
--- DUMP1 2023-07-19 20:18:36.754653394 -0500
+++ DUMP2 2023-07-19 20:18:48.274710984 -0500
@@ -15162,8 +15162,9 @@
SEE ALSO
prlimit(1), dup(2), fcntl(2), fork(2), getrusage(2), mlock(2), mmap(2),
- open(2), quotactl(2), sbrk(2), shmctl(2), malloc(3), sigqueue(3), ulim‐
- it(3), core(5), capabilities(7), cgroups(7), credentials(7), signal(7)
+ open(2), quotactl(2), sbrk(2), shmctl(2), malloc(3), sigqueue(3),
+ ulimit(3), core(5), capabilities(7), cgroups(7), credentials(7), sig‐
+ nal(7)
[MR]
Linux man‐pages (unreleased) (date) getrlimit(2)
───────────────────────────────────────────────────────────────────────────────
@@ -26226,8 +26227,8 @@
Certain flags constants are defined only if suitable feature test
macros are defined (possibly by default): _DEFAULT_SOURCE with glibc
- 2.19 or later; or _BSD_SOURCE or _SVID_SOURCE in glibc 2.19 and earli‐
- er. (Employing _GNU_SOURCE also suffices, and requiring that macro
+ 2.19 or later; or _BSD_SOURCE or _SVID_SOURCE in glibc 2.19 and ear‐
+ lier. (Employing _GNU_SOURCE also suffices, and requiring that macro
[CH]
specifically would have been more logical, since these flags are all
Linux‐specific.) The relevant flags are: MAP_32BIT, MAP_ANONYMOUS (and
the synonym MAP_ANON), MAP_DENYWRITE, MAP_EXECUTABLE, MAP_FILE,
@@ -51676,8 +51677,8 @@
the inclusion of SS_ONSTACK in ss.ss_flags is a no‐op). On other im‐
plementations, and according to POSIX.1, SS_ONSTACK appears only as a
reported flag in old_ss.ss_flags. On Linux, there is no need ever to
- specify SS_ONSTACK in ss.ss_flags, and indeed doing so should be avoid‐
- ed on portability grounds: various other systems give an error if
+ specify SS_ONSTACK in ss.ss_flags, and indeed doing so should be
+ avoided on portability grounds: various other systems give an error if
[CH]
SS_ONSTACK is specified in ss.ss_flags.
EXAMPLES
@@ -64251,19 +64252,20 @@
These functions make some assumptions about how a function’s return ad‐
dress is stored on the stack. Note the following:
- • Omission of the frame pointers (as implied by any of gcc(1)’s nonze‐
- ro optimization levels) may cause these assumptions to be violated.
+ • Omission of the frame pointers (as implied by any of gcc(1)’s
+ nonzero optimization levels) may cause these assumptions to be vio‐
+ lated.
[CH]
• Inlined functions do not have stack frames.
• Tail‐call optimization causes one stack frame to replace another.
- • backtrace() and backtrace_symbols_fd() don’t call malloc() explicit‐
- ly, but they are part of libgcc, which gets loaded dynamically when
- first used. Dynamic loading usually triggers a call to malloc(3).
- If you need certain calls to these two functions to not allocate
- memory (in signal handlers, for example), you need to make sure
- libgcc is loaded beforehand.
+ • backtrace() and backtrace_symbols_fd() don’t call malloc() explic‐
+ itly, but they are part of libgcc, which gets loaded dynamically
+ when first used. Dynamic loading usually triggers a call to mal‐
+ loc(3). If you need certain calls to these two functions to not al‐
+ locate memory (in signal handlers, for example), you need to make
+ sure libgcc is loaded beforehand.
[CH]
[MR] (malloc(3))
The symbol names may be unavailable without the use of special linker
options. For systems using the GNU linker, it is necessary to use the
@@ -65238,8 +65240,8 @@
by a correct program, then it may remove the bzero() call altogether.
This is a problem if the intent of the bzero() call was to erase sensi‐
tive data (e.g., passwords) to prevent the possibility that the data
- was leaked by an incorrect or compromised program. Calls to explic‐
- it_bzero() are never optimized away by the compiler.
+ was leaked by an incorrect or compromised program. Calls to ex‐
+ plicit_bzero() are never optimized away by the compiler.
[CH]
The explicit_bzero() function does not solve all problems associated
with erasing sensitive data:
@@ -66177,8 +66179,8 @@
rno to ERANGE, or raise an FE_OVERFLOW exception). In practice, the
result cannot overflow on any current machine, so this error‐handling
stuff is just nonsense. (More precisely, overflow can happen only when
- the maximum value of the exponent is smaller than the number of mantis‐
- sa bits. For the IEEE‐754 standard 32‐bit and 64‐bit floating‐point
+ the maximum value of the exponent is smaller than the number of man‐
+ tissa bits. For the IEEE‐754 standard 32‐bit and 64‐bit floating‐point
[CH]
numbers the maximum value of the exponent is 127 (respectively, 1023),
and the number of mantissa bits including the implicit bit is 24 (re‐
spectively, 53).)
@@ -68463,10 +68465,10 @@
and does not employ the double‐fork technique (i.e., fork(2), set‐
sid(2), fork(2)) that is necessary to ensure that the resulting daemon
process is not a session leader. Instead, the resulting daemon is a
- session leader. On systems that follow System V semantics (e.g., Lin‐
- ux), this means that if the daemon opens a terminal that is not already
- a controlling terminal for another session, then that terminal will in‐
- advertently become the controlling terminal for the daemon.
+ session leader. On systems that follow System V semantics (e.g.,
+ Linux), this means that if the daemon opens a terminal that is not al‐
+ ready a controlling terminal for another session, then that terminal
+ will inadvertently become the controlling terminal for the daemon.
[CH]
SEE ALSO
fork(2), setsid(2), daemon(7), logrotate(8)
@@ -69169,10 +69171,10 @@
dlpi_phdr, and dlpi_phnum in addition to other implementation‐specific
fields.
- Future versions of the C library may add further fields to the dl_ph‐
- dr_info structure; in that event, the size argument provides a mecha‐
- nism for the callback function to discover whether it is running on a
- system with added fields.
+ Future versions of the C library may add further fields to the
+ dl_phdr_info structure; in that event, the size argument provides a
+ mechanism for the callback function to discover whether it is running
+ on a system with added fields.
[CH]
STANDARDS
None.
@@ -70202,13 +70204,13 @@
NOTES
There are several scenarios when the address of a global symbol is
- NULL. For example, a symbol can be placed at zero address by the link‐
- er, via a linker script or with --defsym command‐line option. Unde‐
- fined weak symbols also have NULL value. Finally, the symbol value may
- be the result of a GNU indirect function (IFUNC) resolver function that
- returns NULL as the resolved value. In the latter case, dlsym() also
- returns NULL without error. However, in the former two cases, the be‐
- havior of GNU dynamic linker is inconsistent: relocation processing
+ NULL. For example, a symbol can be placed at zero address by the
+ linker, via a linker script or with --defsym command‐line option. Un‐
+ defined weak symbols also have NULL value. Finally, the symbol value
+ may be the result of a GNU indirect function (IFUNC) resolver function
+ that returns NULL as the resolved value. In the latter case, dlsym()
+ also returns NULL without error. However, in the former two cases, the
+ behavior of GNU dynamic linker is inconsistent: relocation processing
[CH]
succeeds and the symbol can be observed to have NULL value, but dlsym()
fails and dlerror() indicates a lookup error.
@@ -72116,8 +72118,8 @@
AT_EACCESS and AT_SYMLINK_NOFOLLOW.
SEE ALSO
- access(2), chmod(2), chown(2), faccessat(2), open(2), setgid(2), setu‐
- id(2), stat(2), credentials(7), path_resolution(7)
+ access(2), chmod(2), chown(2), faccessat(2), open(2), setgid(2), se‐
+ tuid(2), stat(2), credentials(7), path_resolution(7)
[MR]
Linux man‐pages (unreleased) (date) euidaccess(3)
───────────────────────────────────────────────────────────────────────────────
@@ -72414,13 +72416,13 @@
Except in the above cases, where the signalled processes may be chil‐
dren of the terminating process, termination of a process does not in
- general cause a signal to be sent to children of that process. Howev‐
- er, a process can use the prctl(2) PR_SET_PDEATHSIG operation to
+ general cause a signal to be sent to children of that process. How‐
+ ever, a process can use the prctl(2) PR_SET_PDEATHSIG operation to
[CH]
arrange that it receives a signal if its parent terminates.
SEE ALSO
- _exit(2), get_robust_list(2), setpgid(2), wait(2), atexit(3), on_ex‐
- it(3), tmpfile(3)
+ _exit(2), get_robust_list(2), setpgid(2), wait(2), atexit(3),
+ on_exit(3), tmpfile(3)
[MR]
Linux man‐pages (unreleased) (date) exit(3)
───────────────────────────────────────────────────────────────────────────────
@@ -73545,9 +73547,9 @@
NOTES
It is not advisable to mix calls to input functions from the stdio li‐
- brary with low‐level calls to read(2) for the file descriptor associat‐
- ed with the input stream; the results will be undefined and very proba‐
- bly not what you want.
+ brary with low‐level calls to read(2) for the file descriptor associ‐
+ ated with the input stream; the results will be undefined and very
+ probably not what you want.
[CH]
SEE ALSO
read(2), write(2), ferror(3), fgetwc(3), fgetws(3), fopen(3), fread(3),
@@ -73823,8 +73825,8 @@
it is reasonable to expect that fgetws() will actually read a multibyte
string from the stream and then convert it to a wide‐character string.
- This function is unreliable, because it does not permit to deal proper‐
- ly with null wide characters that may be present in the input.
+ This function is unreliable, because it does not permit to deal prop‐
+ erly with null wide characters that may be present in the input.
[CH]
SEE ALSO
fgetwc(3), unlocked_stdio(3)
@@ -74117,8 +74119,8 @@
rno to ERANGE, or raise an FE_OVERFLOW exception). In practice, the
result cannot overflow on any current machine, so this error‐handling
stuff is just nonsense. (More precisely, overflow can happen only when
- the maximum value of the exponent is smaller than the number of mantis‐
- sa bits. For the IEEE‐754 standard 32‐bit and 64‐bit floating‐point
+ the maximum value of the exponent is smaller than the number of man‐
+ tissa bits. For the IEEE‐754 standard 32‐bit and 64‐bit floating‐point
[CH]
numbers the maximum value of the exponent is 127 (respectively, 1023),
and the number of mantissa bits including the implicit bit is 24 (re‐
spectively, 53).)
@@ -74407,10 +74409,10 @@
BUGS
Before glibc 2.22, if size is specified as zero, fmemopen() fails with
- the error EINVAL. It would be more consistent if this case successful‐
- ly created a stream that then returned end‐of‐file on the first attempt
- at reading; since glibc 2.22, the glibc implementation provides that
- behavior.
+ the error EINVAL. It would be more consistent if this case success‐
+ fully created a stream that then returned end‐of‐file on the first at‐
+ tempt at reading; since glibc 2.22, the glibc implementation provides
+ that behavior.
[CH]
Before glibc 2.22, specifying append mode ("a" or "a+") for fmemopen()
sets the initial buffer position to the first null byte, but (if the
@@ -82129,10 +82131,10 @@
VERSIONS
POSIX specifies that the argv array argument should be const, but these
- functions permute its elements unless the environment variable POSIX‐
- LY_CORRECT is set. const is used in the actual prototype to be compat‐
- ible with other systems; however, this page doesn’t show the qualifier,
- to avoid confusing readers.
+ functions permute its elements unless the environment variable
+ POSIXLY_CORRECT is set. const is used in the actual prototype to be
+ compatible with other systems; however, this page doesn’t show the
+ qualifier, to avoid confusing readers.
[CH]
STANDARDS
getopt()
@@ -82157,8 +82159,8 @@
NOTES
A program that scans multiple argument vectors, or rescans the same
vector more than once, and wants to make use of GNU extensions such as
- '+' and '-' at the start of optstring, or changes the value of POSIX‐
- LY_CORRECT between scans, must reinitialize getopt() by resetting
+ '+' and '-' at the start of optstring, or changes the value of
+ POSIXLY_CORRECT between scans, must reinitialize getopt() by resetting
[CH]
optind to 0, rather than the traditional value of 1. (Resetting to 0
forces the invocation of an internal initialization routine that
rechecks POSIXLY_CORRECT and checks for GNU extensions in optstring.)
@@ -86999,8 +87001,8 @@
This is still what you will get if _GNU_SOURCE is defined before in‐
cluding <search.h>.
- The location of the prototypes for these functions differs among sever‐
- al versions of UNIX. The above is the POSIX version. Some systems
+ The location of the prototypes for these functions differs among sev‐
+ eral versions of UNIX. The above is the POSIX version. Some systems
[CH]
place them in <string.h>.
STANDARDS
@@ -89391,9 +89393,9 @@
SEE ALSO
fcntl(2), flock(2)
- locks.txt and mandatory-locking.txt in the Linux kernel source directo‐
- ry Documentation/filesystems (on older kernels, these files are direct‐
- ly under the Documentation directory, and mandatory-locking.txt is
+ locks.txt and mandatory-locking.txt in the Linux kernel source direc‐
+ tory Documentation/filesystems (on older kernels, these files are di‐
+ rectly under the Documentation directory, and mandatory-locking.txt is
[CH]
called mandatory.txt)
Linux man‐pages (unreleased) (date) lockf(3)
@@ -90237,20 +90239,20 @@
use POSIX threads instead.
NOTES
- The interpretation of ucp->uc_stack is just as in sigaltstack(2), name‐
- ly, this struct contains the start and length of a memory area to be
- used as the stack, regardless of the direction of growth of the stack.
- Thus, it is not necessary for the user program to worry about this di‐
- rection.
+ The interpretation of ucp->uc_stack is just as in sigaltstack(2),
+ namely, this struct contains the start and length of a memory area to
+ be used as the stack, regardless of the direction of growth of the
+ stack. Thus, it is not necessary for the user program to worry about
+ this direction.
[CH]
On architectures where int and pointer types are the same size (e.g.,
x86‐32, where both types are 32 bits), you may be able to get away with
- passing pointers as arguments to makecontext() following argc. Howev‐
- er, doing this is not guaranteed to be portable, is undefined according
- to the standards, and won’t work on architectures where pointers are
- larger than ints. Nevertheless, starting with glibc 2.8, glibc makes
- some changes to makecontext(), to permit this on some 64‐bit architec‐
- tures (e.g., x86‐64).
+ passing pointers as arguments to makecontext() following argc. How‐
+ ever, doing this is not guaranteed to be portable, is undefined accord‐
+ ing to the standards, and won’t work on architectures where pointers
+ are larger than ints. Nevertheless, starting with glibc 2.8, glibc
+ makes some changes to makecontext(), to permit this on some 64‐bit ar‐
+ chitectures (e.g., x86‐64).
[CH]
EXAMPLES
The example program below demonstrates the use of getcontext(3), make‐
@@ -90512,8 +90514,8 @@
EXAMPLES
The program below employs mallinfo2() to retrieve memory allocation
- statistics before and after allocating and freeing some blocks of memo‐
- ry. The statistics are displayed on standard output.
+ statistics before and after allocating and freeing some blocks of mem‐
+ ory. The statistics are displayed on standard output.
[CH]
The first two command‐line arguments specify the number and size of
blocks to be allocated with malloc(3).
@@ -90832,8 +90834,8 @@
tions; see "Replacing malloc" in the glibc manual for details.
Crashes in memory allocators are almost always related to heap corrup‐
- tion, such as overflowing an allocated chunk or freeing the same point‐
- er twice.
+ tion, such as overflowing an allocated chunk or freeing the same
+ pointer twice.
[CH]
The malloc() implementation is tunable via environment variables; see
mallopt(3) for details.
@@ -93728,8 +93730,8 @@
glibc 2.4. POSIX.1‐2008.
SEE ALSO
- mkfifo(1), close(2), open(2), read(2), stat(2), umask(2), write(2), fi‐
- fo(7)
+ mkfifo(1), close(2), open(2), read(2), stat(2), umask(2), write(2),
+ fifo(7)
[CH] (but would also be addressed by [MR])
Linux man‐pages (unreleased) (date) mkfifo(3)
───────────────────────────────────────────────────────────────────────────────
@@ -96025,8 +96027,8 @@
None.
HISTORY
- SunOS 4, glibc. Removed in Solaris (SunOS 5). Use the standard atex‐
- it(3) instead.
+ SunOS 4, glibc. Removed in Solaris (SunOS 5). Use the standard
+ atexit(3) instead.
[CH] (but would also be addressed by [MR])
CAVEATS
By the time function is executed, stack (auto) variables may already
@@ -98160,8 +98162,8 @@
Code such as printf(foo); often indicates a bug, since foo may contain
a % character. If foo comes from untrusted user input, it may contain
- %n, causing the printf() call to write to memory and creating a securi‐
- ty hole.
+ %n, causing the printf() call to write to memory and creating a secu‐
+ rity hole.
[CH]
EXAMPLES
To print Pi to five decimal places:
@@ -99386,10 +99388,10 @@
NOTES
The PTHREAD_SCOPE_SYSTEM contention scope typically indicates that a
- user‐space thread is bound directly to a single kernel‐scheduling enti‐
- ty. This is the case on Linux for the obsolete LinuxThreads implemen‐
- tation and the modern NPTL implementation, which are both 1:1 threading
- implementations.
+ user‐space thread is bound directly to a single kernel‐scheduling en‐
+ tity. This is the case on Linux for the obsolete LinuxThreads imple‐
+ mentation and the modern NPTL implementation, which are both 1:1
+ threading implementations.
[CH]
POSIX.1 specifies that the default contention scope is implementation‐
defined.
@@ -99466,8 +99468,8 @@
NOTES
The signal mask attribute determines the signal mask that will be as‐
signed to a thread created using the thread attributes object attr. If
- this attribute is not set, then a thread created using attr will inher‐
- it a copy of the creating thread’s signal mask.
+ this attribute is not set, then a thread created using attr will in‐
+ herit a copy of the creating thread’s signal mask.
[CH]
For more details on signal masks, see sigprocmask(2). For a descrip‐
tion of a set of macros that can be used to manipulate and inspect sig‐
@@ -100684,8 +100686,8 @@
NOTES
The pthread_equal() function is necessary because thread IDs should be
- considered opaque: there is no portable way for applications to direct‐
- ly compare two pthread_t values.
+ considered opaque: there is no portable way for applications to di‐
+ rectly compare two pthread_t values.
[CH]
SEE ALSO
pthread_create(3), pthread_self(3), pthreads(7)
@@ -101361,8 +101363,8 @@
}
SEE ALSO
- clock_gettime(2), clock_settime(2), timer_create(2), clock_getcpuclock‐
- id(3), pthread_self(3), pthreads(7), time(7)
+ clock_gettime(2), clock_settime(2), timer_create(2), clock_getcpu‐
+ clockid(3), pthread_self(3), pthreads(7), time(7)
[MR]
Linux man‐pages (unreleased) (date) pthread_getcpuclockid(3)
───────────────────────────────────────────────────────────────────────────────
@@ -101443,8 +101445,8 @@
threads (or processes).
There is no pthreads analog of waitpid(-1, &status, 0), that is, "join
- with any terminated thread". If you believe you need this functionali‐
- ty, you probably need to rethink your application design.
+ with any terminated thread". If you believe you need this functional‐
+ ity, you probably need to rethink your application design.
[CH]
All of the threads in a process are peers: any thread can join with any
other thread in the process.
@@ -101453,8 +101455,8 @@
See pthread_create(3).
SEE ALSO
- pthread_cancel(3), pthread_create(3), pthread_detach(3), pthread_ex‐
- it(3), pthread_tryjoin_np(3), pthreads(7)
+ pthread_cancel(3), pthread_create(3), pthread_detach(3),
+ pthread_exit(3), pthread_tryjoin_np(3), pthreads(7)
[MR]
Linux man‐pages (unreleased) (date) pthread_join(3)
───────────────────────────────────────────────────────────────────────────────
@@ -102729,13 +102731,13 @@
In the following run, the main thread sets its scheduling policy to
SCHED_FIFO with a priority of 10, and initializes a thread attributes
object with a scheduling policy attribute of SCHED_RR and a scheduling
- priority attribute of 20. The program then sets (using pthread_at‐
- tr_setinheritsched(3)) the inherit scheduler attribute of the thread
- attributes object to PTHREAD_EXPLICIT_SCHED, meaning that threads cre‐
- ated using this attributes object should take their scheduling attrib‐
- utes from the thread attributes object. The program then creates a
- thread using the thread attributes object, and that thread displays its
- scheduling policy and priority.
+ priority attribute of 20. The program then sets (using
+ pthread_attr_setinheritsched(3)) the inherit scheduler attribute of the
+ thread attributes object to PTHREAD_EXPLICIT_SCHED, meaning that
+ threads created using this attributes object should take their schedul‐
+ ing attributes from the thread attributes object. The program then
+ creates a thread using the thread attributes object, and that thread
+ displays its scheduling policy and priority.
[CH] (but the first hyphenation break would also be addressed by [MR])
$ su # Need privilege to set real-time scheduling policies
Password:
@@ -102750,8 +102752,8 @@
Scheduler attributes of new thread
policy=SCHED_RR, priority=20
- In the above output, one can see that the scheduling policy and priori‐
- ty were taken from the values specified in the thread attributes ob‐
+ In the above output, one can see that the scheduling policy and prior‐
+ ity were taken from the values specified in the thread attributes ob‐
[CH]
ject.
The next run is the same as the previous, except that the inherit
@@ -102771,8 +102773,8 @@
Scheduler attributes of new thread
policy=SCHED_FIFO, priority=10
- In the above output, one can see that the scheduling policy and priori‐
- ty were taken from the creating thread, rather than the thread attrib‐
+ In the above output, one can see that the scheduling policy and prior‐
+ ity were taken from the creating thread, rather than the thread attrib‐
[CH]
utes object.
Note that if we had omitted the -i i option, the output would have been
@@ -103572,9 +103574,9 @@
BUGS
The pthread_timedjoin_np() function measures time by internally calcu‐
lating a relative sleep interval that is then measured against the
- CLOCK_MONOTONIC clock instead of the CLOCK_REALTIME clock. Consequent‐
- ly, the timeout is unaffected by discontinuous changes to the CLOCK_RE‐
- ALTIME clock.
+ CLOCK_MONOTONIC clock instead of the CLOCK_REALTIME clock. Conse‐
+ quently, the timeout is unaffected by discontinuous changes to the
+ CLOCK_REALTIME clock.
[CH]
EXAMPLES
The following code waits to join for up to 5 seconds:
@@ -104528,9 +104530,9 @@
NOTES
Random‐number generation is a complex topic. Numerical Recipes in C:
The Art of Scientific Computing (William H. Press, Brian P. Flannery,
- Saul A. Teukolsky, William T. Vetterling; New York: Cambridge Universi‐
- ty Press, 2007, 3rd ed.) provides an excellent discussion of practical
- random‐number generation issues in Chapter 7 (Random Numbers).
+ Saul A. Teukolsky, William T. Vetterling; New York: Cambridge Univer‐
+ sity Press, 2007, 3rd ed.) provides an excellent discussion of practi‐
+ cal random‐number generation issues in Chapter 7 (Random Numbers).
[CH]
For a more theoretical discussion which also covers many practical is‐
sues in depth, see Chapter 3 (Random Numbers) in Donald E. Knuth’s The
@@ -105008,10 +105010,10 @@
unspecified size, with at most NAME_MAX characters preceding the termi‐
nating null byte ('\0').
- POSIX.1 explicitly notes that this field should not be used as an lval‐
- ue. The standard also notes that the use of sizeof(d_name) is incor‐
- rect; use strlen(d_name) instead. (On some systems, this field is de‐
- fined as char d_name[1]!) By implication, the use sizeof(struct
+ POSIX.1 explicitly notes that this field should not be used as an
+ lvalue. The standard also notes that the use of sizeof(d_name) is in‐
+ correct; use strlen(d_name) instead. (On some systems, this field is
+ defined as char d_name[1]!) By implication, the use sizeof(struct
dirent) to capture the size of the record including the size of d_name
is also incorrect.
[CH]
@@ -105021,8 +105023,8 @@
returns the value 255 for most filesystems, on some filesystems (e.g.,
CIFS, Windows SMB servers), the null‐terminated filename that is (cor‐
- rectly) returned in d_name can actually exceed this size. In such cas‐
- es, the d_reclen field will contain a value that exceeds the size of
+ rectly) returned in d_name can actually exceed this size. In such
+ cases, the d_reclen field will contain a value that exceeds the size of
[CH]
the glibc dirent structure shown above.
STANDARDS
@@ -106501,8 +106503,8 @@
rno to ERANGE, or raise an FE_OVERFLOW exception). In practice, the
result cannot overflow on any current machine, so this error‐handling
stuff is just nonsense. (More precisely, overflow can happen only when
- the maximum value of the exponent is smaller than the number of mantis‐
- sa bits. For the IEEE‐754 standard 32‐bit and 64‐bit floating‐point
+ the maximum value of the exponent is smaller than the number of man‐
+ tissa bits. For the IEEE‐754 standard 32‐bit and 64‐bit floating‐point
[CH]
numbers the maximum value of the exponent is 127 (respectively, 1023),
and the number of mantissa bits including the implicit bit is 24 (re‐
spectively, 53).)
@@ -109348,11 +109350,11 @@
mends avoiding the use of these functions from signal handlers and goes
on to point out that if these functions are called from a signal han‐
dler that interrupted a call to a non‐async‐signal‐safe function (or
- some equivalent, such as the steps equivalent to exit(3) that occur up‐
- on a return from the initial call to main()), the behavior is undefined
- if the program subsequently makes a call to a non‐async‐signal‐safe
- function. The only way of avoiding undefined behavior is to ensure one
- of the following:
+ some equivalent, such as the steps equivalent to exit(3) that occur
+ upon a return from the initial call to main()), the behavior is unde‐
+ fined if the program subsequently makes a call to a non‐async‐signal‐
+ safe function. The only way of avoiding undefined behavior is to en‐
+ sure one of the following:
[CH]
• After long jumping from the signal handler, the program does not
call any non‐async‐signal‐safe functions and does not return from
@@ -109416,12 +109418,12 @@
If locale is an empty string, "", each part of the locale that should
be modified is set according to the environment variables. The details
- are implementation‐dependent. For glibc, first (regardless of catego‐
- ry), the environment variable LC_ALL is inspected, next the environment
- variable with the same name as the category (see the table above), and
- finally the environment variable LANG. The first existing environment
- variable is used. If its value is not a valid locale specification,
- the locale is unchanged, and setlocale() returns NULL.
+ are implementation‐dependent. For glibc, first (regardless of cate‐
+ gory), the environment variable LC_ALL is inspected, next the environ‐
+ ment variable with the same name as the category (see the table above),
+ and finally the environment variable LANG. The first existing environ‐
+ ment variable is used. If its value is not a valid locale specifica‐
+ tion, the locale is unchanged, and setlocale() returns NULL.
[CH]
The locale "C" or "POSIX" is a portable locale; it exists on all con‐
forming systems.
@@ -109460,8 +109462,8 @@
honored.
ATTRIBUTES
- For an explanation of the terms used in this section, see attribut‐
- es(7).
+ For an explanation of the terms used in this section, see attrib‐
+ utes(7).
[MR]
┌────────────────────────┬───────────────┬────────────────────────────┐
│ Interface │ Attribute │ Value │
├────────────────────────┼───────────────┼────────────────────────────┤
@@ -109836,8 +109838,8 @@
Program source: pshm_ucase.h
The following header file is included by both programs below. Its pri‐
- mary purpose is to define a structure that will be imposed on the memo‐
- ry object that is shared between the two programs.
+ mary purpose is to define a structure that will be imposed on the mem‐
+ ory object that is shared between the two programs.
[CH]
#include <fcntl.h>
#include <semaphore.h>
@@ -109870,8 +109872,8 @@
semaphores inside the object to 0.
After the "send" program has posted the first of the semaphores, the
- "bounce" program upper cases the data that has been placed in the memo‐
- ry by the "send" program and then posts the second semaphore to tell
+ "bounce" program upper cases the data that has been placed in the mem‐
+ ory by the "send" program and then posts the second semaphore to tell
[CH]
the "send" program that it may now access the shared memory.
/* pshm_ucase_bounce.c
@@ -110849,8 +110851,8 @@
See pthread_sigmask(3).
SEE ALSO
- sigaction(2), signalfd(2), sigpending(2), sigsuspend(2), sigwaitin‐
- fo(2), sigsetops(3), signal(7)
+ sigaction(2), signalfd(2), sigpending(2), sigsuspend(2), sigwait‐
+ info(2), sigsetops(3), signal(7)
[MR]
Linux man‐pages (unreleased) (date) sigwait(3)
───────────────────────────────────────────────────────────────────────────────
@@ -114260,8 +114262,8 @@
strftime_l()
POSIX.1‐2008.
- There are strict inclusions between the set of conversions given in AN‐
- SI C (unmarked), those given in the Single UNIX Specification (marked
+ There are strict inclusions between the set of conversions given in
+ ANSI C (unmarked), those given in the Single UNIX Specification (marked
[CH]
SU), those given in Olson’s timezone package (marked TZ), and those
given in glibc (marked GNU), except that %+ is not supported in glibc2.
On the other hand glibc2 has several more extensions. POSIX.1 only
@@ -114310,8 +114312,8 @@
^ Convert alphabetic characters in result string to uppercase.
# Swap the case of the result string. (This flag works only with
- certain conversion specifier characters, and of these, it is on‐
- ly really useful with %Z.)
+ certain conversion specifier characters, and of these, it is
+ only really useful with %Z.)
[CH]
An optional decimal width specifier may follow the (possibly absent)
flag. If the natural size of the field is smaller than this width,
@@ -115457,8 +115459,8 @@
VERSIONS
In the glibc implementation, the n‐char‐sequence that optionally fol‐
lows "NAN" is interpreted as an integer number (with an optional ’0’ or
- ’0x’ prefix to select base 8 or 16) that is to be placed in the mantis‐
- sa component of the returned value.
+ ’0x’ prefix to select base 8 or 16) that is to be placed in the man‐
+ tissa component of the returned value.
[CH]
STANDARDS
C11, POSIX.1‐2008.
@@ -115710,8 +115712,8 @@
exit(EXIT_SUCCESS);
}
- Another example program using strtok() can be found in getaddrin‐
- fo_a(3).
+ Another example program using strtok() can be found in getad‐
+ drinfo_a(3).
[MR]
SEE ALSO
memchr(3), strchr(3), string(3), strpbrk(3), strsep(3), strspn(3),
@@ -116805,8 +116807,8 @@
system(" -unfortunate-command-name");
SEE ALSO
- sh(1), execve(2), fork(2), sigaction(2), sigprocmask(2), wait(2), ex‐
- ec(3), signal(7)
+ sh(1), execve(2), fork(2), sigaction(2), sigprocmask(2), wait(2),
+ exec(3), signal(7)
[MR]
Linux man‐pages (unreleased) (date) system(3)
───────────────────────────────────────────────────────────────────────────────
@@ -118358,9 +118360,9 @@
Before glibc 2.19, the glibc implementation of these functions did not
set errno to ERANGE on an underflow range error.
- In glibc versions 2.3.3 and earlier, an argument of +0 or -0 incorrect‐
- ly produced a domain error (errno set to EDOM and an FE_INVALID excep‐
- tion raised), rather than a pole error.
+ In glibc versions 2.3.3 and earlier, an argument of +0 or -0 incor‐
+ rectly produced a domain error (errno set to EDOM and an FE_INVALID ex‐
+ ception raised), rather than a pole error.
[CH]
SEE ALSO
gamma(3), lgamma(3)
@@ -120347,8 +120349,8 @@
Only the EINVAL error return is documented by SUSv2 and POSIX.1‐2001.
CAVEATS
- The interaction of this function with the SIGALRM signal, and with oth‐
- er timer functions such as alarm(2), sleep(3), nanosleep(2),
+ The interaction of this function with the SIGALRM signal, and with
+ other timer functions such as alarm(2), sleep(3), nanosleep(2),
[CH]
setitimer(2), timer_create(2), timer_delete(2), timer_getoverrun(2),
timer_gettime(2), timer_settime(2), ualarm(3) is unspecified.
@@ -122641,8 +122643,8 @@
ing their Unicode (ISO/IEC 10646) code point, but other platforms don’t
do this. Also, the use of C99 universal character names of the form
\unnnn does not solve this problem.) Therefore, in internationalized
- programs, the format string should consist of ASCII wide characters on‐
- ly, or should be constructed at run time in an internationalized way
+ programs, the format string should consist of ASCII wide characters
+ only, or should be constructed at run time in an internationalized way
[CH]
(e.g., using gettext(3) or iconv(3), followed by mbstowcs(3)).
SEE ALSO
@@ -164342,8 +164344,8 @@
umn is a summary of the resources that are isolated by the namespace
type.
Namespace Flag Page Isolates
- Cgroup CLONE_NEWCGROUP cgroup_namespaces(7) Cgroup root
- directory
+ Cgroup CLONE_NEWCGROUP cgroup_namespaces(7) Cgroup root di‐
+ rectory
[HY]
IPC CLONE_NEWIPC ipc_namespaces(7) System V IPC,
POSIX message
queues
@@ -164352,8 +164354,8 @@
etc.
Mount CLONE_NEWNS mount_namespaces(7) Mount points
PID CLONE_NEWPID pid_namespaces(7) Process IDs
- Time CLONE_NEWTIME time_namespaces(7) Boot and
- monotonic clocks
+ Time CLONE_NEWTIME time_namespaces(7) Boot and monoto‐
+ nic clocks
[HY]
User CLONE_NEWUSER user_namespaces(7) User and group
IDs
UTS CLONE_NEWUTS uts_namespaces(7) Hostname and NIS
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2023-07-20 9:28 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-07-19 4:18 [PATCH] man-pages(7): Add attributive annotation advice G. Branden Robinson
2023-07-19 20:01 ` Alejandro Colomar
2023-07-20 2:13 ` G. Branden Robinson
2023-07-20 8:24 ` Alejandro Colomar
2023-07-20 9:14 ` G. Branden Robinson
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox