arc4random.3: New page documenting the arc4random(3) family of functions
PATCH 1/1 arc4random.3: New page documenting the arc4random(3) family of functions
arc4random(3)arc4random_uniform(3)arc4random_buf(3)
--- man3/arc4random.3 | 104 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 man3/arc4random.3
man3/arc4random.3 new file +104 -0
@@ -0,0 +1,104 @@ +.\" Copyright (C) 2023 Alejandro Colomar <[email protected]> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH arc4random 3 (date) "Linux man-pages (unreleased)" +.SH NAME +arc4random, arc4random_uniform, arc4random_buf +\- cryptographically-secure pseudorandom number generator +.SH LIBRARY +Standard C library +.RI ( libc ", " -lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.PP +.B uint32_t arc4random(void); +.BI "uint32_t arc4random_uniform(uint32_t " upper_bound ); +.BI "void arc4random_buf(void " buf [. n "], size_t " n ); +.fi +.SH DESCRIPTION +These functions give cryptographically-secure random numbers. +.PP +.BR arc4random () +returns a uniformly-distributed value. +.PP +.BR arc4random_uniform () +returns a uniformly-distributed value less than +.I upper_bound +(see CAVEATS). +.PP +.BR arc4random_buf () +fills the memory pointed to by +.IR buf , +with +.I n +bytes of random data. +.PP +The +.BR rand (3) +and +.BR rand48 (3) +families of functions should only be used where +the quality of the random numbers is not a concern +.I and +there's a need for repeatability of the results. +Unless you meet both of those conditions, +use the +.BR arc4random () +functions. +.SH RETURN VALUE +.BR arc4random () +returns a random number. +.PP +.BR arc4random_uniform () +returns a random number less than +.I upper_bound +for valid input, or +.B 0 +when +.I upper_bound +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.nh +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.BR arc4random (), +.BR arc4random_uniform (), +.BR arc4random_buf () +T} Thread safety MT-Safe +.TE +.hy +.ad +.sp 1 +.SH STANDARDS +These nonstandard functions are present in several Unix systems. +.SH CAVEATS +An +.I upper_bound +of +.B 0 +doesn't make sense in a call to +.BR arc4random_uniform (). +Such a call will fail, and return +.BR 0 . +Be careful, +since that value is +.I not +less than +.IR upper_bound . +In some cases, +such as accessing an array, +using that value could result in Undefined Behavior. +.SH SEE ALSO +.BR getrandom (3), +.BR rand (3), +.BR rand48 (3), +.BR random (7)
Signature · 1 line
2.39.0
arc4random(3) Library Functions Manual arc4random(3)
NAME
arc4random, arc4random_uniform, arc4random_buf - cryptographically‐se‐ cure pseudorandom number generator
LIBRARY
Standard C library (libc, ‐lc)
SYNOPSIS
#include <stdlib.h>
uint32_t arc4random(void);
uint32_t arc4random_uniform(uint32_t upper_bound);
void arc4random_buf(void buf[.n], size_t n);DESCRIPTION
These functions give cryptographically‐secure random numbers.
arc4random() returns a uniformly‐distributed value.
arc4random_uniform() returns a uniformly‐distributed value less than upper_bound (see CAVEATS).
arc4random_buf() fills the memory pointed to by buf, with n bytes of random data.
The rand(3) and rand48(3) families of functions should only be used where the quality of the random numbers is not a concern and there’s a need for repeatability of the results. Unless you meet both of those conditions, use the arc4random() functions.
RETURN VALUE
arc4random() returns a random number.
arc4random_uniform() returns a random number less than upper_bound for valid input, or 0 when upper_bound is invalid.
ATTRIBUTES
For an explanation of the terms used in this section, see attrib‐ utes(7). ┌────────────────────────────────────────────┬───────────────┬─────────┐
│Interface │ Attribute │ Value │
├────────────────────────────────────────────┼───────────────┼─────────┤
│arc4random(), arc4random_uniform(), │ Thread safety │ MT‐Safe │
│arc4random_buf() │ │ │
└────────────────────────────────────────────┴───────────────┴─────────┘
STANDARDS
These nonstandard functions are present in several Unix systems.
CAVEATS
An upper_bound of 0 doesn’t make sense in a call to arc4random_uni‐ form(). Such a call will fail, and return 0. Be careful, since that value is not less than upper_bound. In some cases, such as accessing an array, using that value could result in Undefined Behavior.
SEE ALSO
getrandom(3), rand(3), rand48(3), random(7)
Linux man‐pages (unreleased) (date) arc4random(3)
* Alejandro Colomar <[email protected]>, 2023-01-01 17:27:
Quoted 1 line
arc4random_uniform()returns a random number less thanupper_boundfor valid input, or 0 whenupper_boundis invalid.
Is the "or 0 ..." thing part of the API? I could find anything like that in glibc docs or BSD man pages.
Quoted 2 lines
STANDARDS
These nonstandard functions are present in several Unix systems.
That's not really helpful. Also, the VERSIONS section is missing ("every new interface should include a VERSIONS section").
In contrast, the libbsd man page is much more informative:
Quoted 3 lines
These functions first appeared in OpenBSD 2.1, FreeBSD 3.0, NetBSD 1.6, and DragonFly 1.0. The functions
arc4random(),arc4random_buf()andarc4random_uniform()appeared in glibc 2.36.The original version of this random number generator used the RC4 (also known as ARC4) algorithm. In OpenBSD 5.5 it was replaced with the ChaCha20 cipher, and it may be replaced again in the future as cryptographic techniques advance. A good mnemonic is “A Replacement Call for Random”.
Signature · 1 line
Jakub Wilk
Hi Jakub,
Quoted 5 lines · Jakub Wilk
* Alejandro Colomar <[email protected]>, 2023-01-01 17:27:
Quoted 2 lines
arc4random_uniform()returns a random number less thanupper_boundfor valid input, or 0 whenupper_boundis invalid.Is the "or 0 ..." thing part of the API?
Yes, it is part of the (undocumented) API. At least, their authors claim to have thought about it when designing it, and purposefully took the decision of returning 0. They fail to acknowledge that it's a bug, also fail to acknowledge that their documentation doesn't document this behavior, and don't have any intention of changing the API because "we don't know what can possibly fail; you'd have to audit all software in the world to confirm that none depends on that detail".
I have serious doubts that any software can depend on that, because mathematically it doesn't make any sense, so algorithms will likely have to purposefully special-case arc4random_uniform(0), but can't know for sure, because well, I haven't audited all software in the world.
I didn't find any case in OpenBSD's source code that depends on that, however.
Quoted 2 lines
I could find anything like that
in glibc docs or BSD man pages.
<https://inbox.sourceware.org/libc-alpha/[email protected]/>
Their manual page is bogus, and the funny thing is that one of Theo's arguments to reject a proposal to fix the bug in the API was that I wouldn't be able to document it reasonably. Well, as you saw, it's the current behavior that isn't well documented, and I had to special-case it in BUGS.
Quoted 6 lines
Quoted 3 lines
STANDARDS
These nonstandard functions are present in several Unix systems.That's not really helpful. Also, the VERSIONS section is missing ("every new interface should include a VERSIONS section").
I thought of that this morning, while doing some reorganization of that section globally. I'll add the version.
Quoted 6 lines
In contrast, the libbsd man page is much more informative:
Quoted 3 lines
These functions first appeared in OpenBSD 2.1, FreeBSD 3.0, NetBSD 1.6, and DragonFly 1.0. The functions
arc4random(),arc4random_buf()andarc4random_uniform()appeared in glibc 2.36.
Yup. :)
Thanks a lot for this thorough review!
Alex
Quoted 7 lines
Quoted 6 lines
The original version of this random number generator used the RC4 (also known as ARC4) algorithm. In OpenBSD 5.5 it was replaced with the ChaCha20 cipher, and it may be replaced again in the future as cryptographic techniques advance. A good mnemonic is “A Replacement Call for Random”.
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Quoted 22 lines · Alejandro Colomar
Hi Jakub,
Quoted 5 lines · Jakub Wilk
* Alejandro Colomar <[email protected]>, 2023-01-01 17:27:
Quoted 2 lines
arc4random_uniform()returns a random number less thanupper_boundfor valid input, or 0 whenupper_boundis invalid.Is the "or 0 ..." thing part of the API?
Yes, it is part of the (undocumented) API. At least, their authors claim to have thought about it when designing it, and purposefully took the decision of returning 0. They fail to acknowledge that it's a bug, also fail to acknowledge that their documentation doesn't document this behavior, and don't have any intention of changing the API because "we don't know what can possibly fail; you'd have to audit all software in the world to confirm that none depends on that detail".
I have serious doubts that any software can depend on that, because mathematically it doesn't make any sense, so algorithms will likely have to purposefully special-case
arc4random_uniform(0), but can't know for sure, because well, I haven't audited all software in the world.
Quoted 7 lines
I didn't find any case in OpenBSD's source code that depends on that, however.
Quoted 2 lines
I could find anything like that
in glibc docs or BSD man pages.<https://inbox.sourceware.org/libc-alpha/[email protected]/>
Sorry, I pasted the wrong link. I wanted to paste this one:
<https://inbox.sourceware.org/libc-alpha/[email protected]/T/>
Quoted 38 lines
Their manual page is bogus, and the funny thing is that one of Theo's arguments to reject a proposal to fix the bug in the API was that I wouldn't be able to document it reasonably. Well, as you saw, it's the current behavior that isn't well documented, and I had to special-case it in BUGS.
Quoted 6 lines
Quoted 3 lines
STANDARDS
These nonstandard functions are present in several Unix systems.That's not really helpful. Also, the VERSIONS section is missing ("every new interface should include a VERSIONS section").
I thought of that this morning, while doing some reorganization of that section globally. I'll add the version.
Quoted 6 lines
In contrast, the libbsd man page is much more informative:
Quoted 3 lines
These functions first appeared in OpenBSD 2.1, FreeBSD 3.0, NetBSD 1.6, and DragonFly 1.0. The functions
arc4random(),arc4random_buf()andarc4random_uniform()appeared in glibc 2.36.Yup. :)
Thanks a lot for this thorough review!
Alex
Quoted 7 lines
Quoted 6 lines
The original version of this random number generator used the RC4 (also known as ARC4) algorithm. In OpenBSD 5.5 it was replaced with the ChaCha20 cipher, and it may be replaced again in the future as cryptographic techniques advance. A good mnemonic is “A Replacement Call for Random”.
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Quoted 88 lines · Alejandro Colomar
arc4random(3)
arc4random_uniform(3)arc4random_buf(3)Signed-off-by Alejandro Colomar <[email protected]>--- man3/arc4random.3 | 104 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 man3/arc4random.3man3/arc4random.3 new file +72
-0@@ -0,0 +1,104 @@ +.\" Copyright (C) 2023 Alejandro Colomar <[email protected]> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH arc4random 3 (date) "Linux man-pages (unreleased)" +.SH NAME +arc4random, arc4random_uniform, arc4random_buf +\- cryptographically-secure pseudorandom number generator +.SH LIBRARY +Standard C library +.RI ( libc ", " -lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.PP +.B uint32_t arc4random(void); +.BI "uint32_t arc4random_uniform(uint32_t " upper_bound ); +.BI "void arc4random_buf(void " buf [. n "], size_t " n ); +.fi +.SH DESCRIPTION +These functions give cryptographically-secure random numbers. +.PP +.BR arc4random () +returns a uniformly-distributed value. +.PP +.BR arc4random_uniform () +returns a uniformly-distributed value less than +.I upper_bound +(see CAVEATS). +.PP +.BR arc4random_buf () +fills the memory pointed to by +.IR buf , +with +.I n +bytes of random data. +.PP +The +.BR rand (3) +and +.BR rand48 (3) +families of functions should only be used where +the quality of the random numbers is not a concern +.I and +there's a need for repeatability of the results. +Unless you meet both of those conditions, +use the +.BR arc4random () +functions. +.SH RETURN VALUE +.BR arc4random () +returns a random number. +.PP +.BR arc4random_uniform () +returns a random number less than +.I upper_bound +for valid input, or +.B 0 +when +.I upper_bound +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.nh +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{
man3/arc4random.3 line 82
Quoted 10 lines
man3/arc4random.3 new file +10
-0+.BR arc4random (), +.BR arc4random_uniform (), +.BR arc4random_buf () +T} Thread safety MT-Safe +.TE +.hy +.ad +.sp 1 +.SH STANDARDS +These nonstandard functions are present in several Unix systems.
I'm not a native speaker, but I think it should be s/in/on/.
--
Best Regards,
Tom Schwindl
Hi Tom,
Quoted 4 lines · Tom Schwindl
Quoted 2 lines
+.SH STANDARDS
+These nonstandard functions are present in several Unix systems.I'm not a native speaker, but I think it should be s/in/on/.
Thanks. I'm not either, and always have doubts about those, so I'll assume you're right.
Cheers,
Alex
Quoted 4 lines
--
Best Regards,
Tom Schwindl
Signature · 1 line
<http://www.alejandro-colomar.es/>
[dropping libc-alpha due to scope of my comments]
Hi Alex,
At 2023-01-01T17:26:28+0100, Alejandro Colomar wrote:
[...]
Quoted 3 lines
+.ad l
+.nh
+.TS
[...]
man3/arc4random.3 line 79
Quoted 8 lines
man3/arc4random.3 new file +8
-0+T{ +.BR arc4random (), +.BR arc4random_uniform (), +.BR arc4random_buf () +T} Thread safety MT-Safe +.TE +.hy +.ad
I would counsel against putting these *roff requests outside the table definition. I think that having them where you do (1) misleads the reader/maintainer into thinking that they influence how table entries in general are typeset, and (2) they risk being retained in the event the man page is refactored to stop using a table definition to present the material.
--begin snip--
Ordinarily, a table entry is typeset rigidly. It is not filled, broken, hyphenated, adjusted, or populated with additional inter‐ sentence space. [...] In contrast to conventional roff input (within a paragraph, say), changes to text formatting, such as font selection or vertical spacing, do not persist between entries.
[...]
Text blocks are formatted as was the text prior to the table, modified by applicable column descriptors. Specifically, the classifiers A, C, L, N, R, and S determine a text block’s alignment within its cell, but not its adjustment. Add na or ad requests to the beginning of a text block to alter its adjustment distinctly from other text in the document. As with other table entries, when a text block ends, any alterations to formatting parameters are discarded. They do not affect subsequent table entries, not even other text blocks.[1]
--end snip--
Admittedly, if you had a single table region with a bunch of text blocks in it, it is more economical to change (and later restore) the formatting of "the text prior to the table", so you don't have to whack each text block with ".ad l" and ".nh" individually.
But in this case you can move 2 lines and drop two, since the changed alignment and automatic hyphenation disablement will be "discarded".
Quoted 1 line
+.sp 1
When you throw the groff 1.23.0 switch and start using the MR macro, you can get rid of this too. https://savannah.gnu.org/bugs/?49390
Quoted 4 lines
+.SH STANDARDS
+These nonstandard functions are present in several Unix systems.I'm not a native speaker, but I think it should be s/in/on/.
[a native English speaker has entered the chat]
Neither will sound wrong to most ears. I think "on" is a little more idiomatic, as we tend to speak of operating systems as some kind of platform or foundation upon which other activities are conducted or interfaces are constructed. But we also speak of an OS as an environment in which we carry out tasks. ("I tried doing development in Windows--it was hell!") When speaking of an entry point to "the system" (not to say "the kernel"), I think the argument for "on" is stronger, since we are speaking of it in that platform/foundational sense. I see this usage in man-pages(7) itself.[2]
More important, I think, would be to pick one phrasing for the Linux man-pages and use it consistently.
Regards,
Branden
[1] https://git.savannah.gnu.org/cgit/groff.git/tree/src/preproc/tbl/tbl.1.man
[2] I also see both "The conventions described on this page" and "The first command in a man page", revealing that slippage between these prepositions is common in other contexts as well. I never noticed this until I looked for it.
Hi Branden!
Quoted 10 lines · G. Branden Robinson
[dropping libc-alpha due to scope of my comments]
Hi Alex,
At 2023-01-01T17:26:28+0100, Alejandro Colomar wrote:
[...]Quoted 3 lines
+.ad l
+.nh
+.TS[...]
Quoted 15 lines
man3/arc4random.3 line 79
Quoted 8 lines
man3/arc4random.3 new file +8
-0+T{ +.BR arc4random (), +.BR arc4random_uniform (), +.BR arc4random_buf () +T} Thread safety MT-Safe +.TE +.hy +.adI would counsel against putting these *roff requests outside the table definition. I think that having them where you do (1) misleads the reader/maintainer into thinking that they influence how table entries in general are typeset, and (2) they risk being retained in the event the man page is refactored to stop using a table definition to present the material.
To be honest, tbl(1) is still something I can't write without looking at the manual, so what I end up doing normally is just copy an existing one and trust that it was written correctly.
It seems I was assuming too much :)
Quoted 24 lines
--begin snip--
Ordinarily, a table entry is typeset rigidly. It is not filled, broken, hyphenated, adjusted, or populated with additional inter‐ sentence space. [...] In contrast to conventional roff input (within a paragraph, say), changes to text formatting, such as font selection or vertical spacing, do not persist between entries.
[...]
Text blocks are formatted as was the text prior to the table, modified by applicable column descriptors. Specifically, the classifiers A, C, L, N, R, and S determine a text block’s alignment within its cell, but not its adjustment. Add na or ad requests to the beginning of a text block to alter its adjustment distinctly from other text in the document. As with other table entries, when a text block ends, any alterations to formatting parameters are discarded. They do not affect subsequent table entries, not even other text blocks.[1]
--end snip--Admittedly, if you had a single table region with a bunch of text blocks in it, it is more economical to change (and later restore) the formatting of "the text prior to the table", so you don't have to whack each text block with ".ad l" and ".nh" individually.
Quoted 7 lines
But in this case you can move 2 lines and drop two, since the changed alignment and automatic hyphenation disablement will be "discarded".
Quoted 1 line
+.sp 1
When you throw the groff 1.23.0 switch and start using the
MRmacro, you can get rid of this too. https://savannah.gnu.org/bugs/?49390
:)
Quoted 8 lines
Quoted 5 lines
+.SH STANDARDS
+These nonstandard functions are present in several Unix systems.I'm not a native speaker, but I think it should be s/in/on/.
[a native English speaker has entered the chat]
Quoted 9 lines
Neither will sound wrong to most ears. I think "on" is a little more idiomatic, as we tend to speak of operating systems as some kind of platform or foundation upon which other activities are conducted or interfaces are constructed. But we also speak of an OS as an environment in which we carry out tasks. ("I tried doing development in Windows--it was hell!") When speaking of an entry point to "the system" (not to say "the kernel"), I think the argument for "on" is stronger, since we are speaking of it in that platform/foundational sense. I see this usage in man-pages(7) itself.[2]
Thanks for the detailed explanation!
Quoted 3 lines
More important, I think, would be to pick one phrasing for the Linux man-pages and use it consistently.
I should do that. If I only remembered this every time I write... I'll try to.
Quoted 9 lines
Regards,
Branden[1] https://git.savannah.gnu.org/cgit/groff.git/tree/src/preproc/tbl/tbl.1.man
[2] I also see both "The conventions described on this page" and "The first command in a man page", revealing that slippage between these prepositions is common in other contexts as well. I never noticed this until I looked for it.
When we have some time, we could do some global language consistency fixes like these. I'll need help for that.
Cheers,
Alex
Signature · 1 line
<http://www.alejandro-colomar.es/>
* Alejandro Colomar <[email protected]>, 2023-01-01 17:26:
Quoted 3 lines
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " -lc )
That should be \-lc, but... To be frank, I'd just remove the whole section. Most people shouldn't use -lc, and those who do need it can figure it out on their own.
Signature · 1 line
Jakub Wilk
Quoted 9 lines · Jakub Wilk
* Alejandro Colomar <[email protected]>, 2023-01-01 17:26:
Quoted 3 lines
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " -lc )That should be \-lc, but... To be frank, I'd just remove the whole section. Most people shouldn't use -lc, and those who do need it can figure it out on their own.
I don't quite remember what the arguments for the LIBRARY section were, but it should be kept for consistency with the other man-pages.
off-topic for Alex:
As we're talking about libc here, what about the libc.7 patch? Is there any progress regarding it?
Signature · 2 lines
Best Regards, Tom Schwindl
Hi Tom & Jakub,
Quoted 7 lines · Tom Schwindl
Quoted 6 lines · Jakub Wilk
* Alejandro Colomar <[email protected]>, 2023-01-01 17:26:
Quoted 3 lines
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " -lc )That should be \-lc, but...
Ahh, I thought I had fixed that; it seems not. Thanks!
Quoted 2 lines
Quoted 2 lines
To be frank, I'd just remove the whole
section. Most people shouldn't use -lc,
While there's no need for most users, it's not wrong to specify it. I always do it, just for completeness, and treat libc as any other library.
Quoted 2 lines
Quoted 2 lines
and those who do need it can
figure it out on their own.
It's surprising how much trivial knowledge is not taught anywhere just because it's so trivial, and then it becomes not so trivial because nobody tells it. I'll keep it just in case. Anyway, I think being consistent so that all C functions specify a LIBRARY section is in itself good, since that will probably prompt authors of pages to use it in their own pages. Also, since I copied this idea from FreeBSD, it makes sense to follow their decissions unless we find them harmful.
Quoted 9 lines
Quoted 1 line
I don't quite remember what the arguments for the LIBRARY section were, but it should be kept for consistency with the other man-pages.
off-topic for Alex:
As we're talking about libc here, what about the libc.7 patch? Is there any progress regarding it?
I guess you refer to the patch set by Branden that touched ldconfig(8), libc(7), and a some more? I guess Branden is busy with his own stuff (releasing groff-1.23.0). Probably after the release we'll see some updated patches.
Cheers,
Alex
Quoted 1 line
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Quoted 8 lines · Alejandro Colomar
Quoted 3 lines
off-topic for Alex:
As we're talking about libc here, what about the libc.7 patch? Is there any progress regarding it?I guess you refer to the patch set by Branden that touched ldconfig(8), libc(7), and a some more? I guess Branden is busy with his own stuff (releasing groff-1.23.0). Probably after the release we'll see some updated patches.
That's about the size of it.
This is what I have queued up to submit after I review Alex's feedback. (Some of these I haven't submitted at all yet, I think.) Also I haven't rebased lately, so my view of origin/master may be stale.
commit 06a104b5be1ac103f9858a7a898284fea2137a7b (HEAD -> master)
Author: G. Branden Robinson <[email protected]> Date: Fri Jan 6 01:48:55 2023 -0600
intro.3: srcfix (hyphenation control)
Protect man page cross reference from hyphenation. (This will not be necessary upon migration to groff 1.23's MR macro.)
commit a997ee7d2936e1c5e3f61a9218b02118dbae9a52
Author: G. Branden Robinson <[email protected]> Date: Wed Jan 4 01:16:17 2023 -0600
intro.3: Revise discussion
* Recast introduction to discuss the purpose of section 3 as a whole instead of focussing solely on the standard C library.
* Provide historical context for usage of subsections in section 3. Resurrect information from comments, in rewritten form, of section 3 subsections, so as to contrast them with the current approach developed by Alex. Be even more emphatic that those documenting other C libraries should not mess with subsections.
* Explain basic principles of usage of any C library to the novice. (This page _is_ called "intro".)
* Drop material about organization of glibc, now moved to libc(7).
commit 8a5bc95aba96c409b74f7128f9a9b30b34dc976e
Author: G. Branden Robinson <[email protected]> Date: Thu Jan 5 16:37:20 2023 -0600
intro.3: wfix
* Tighten cross reference. It wastes words to tell people to look elsewhere "for further information". Why else would they look there?
* Use passive voice less.
* Relocate sentence for more coherent discussion.
* Say "application _programming_ interface".
commit 5619f1fff3457a5f0d67c983b76fb329eaae7b92
Author: G. Branden Robinson <[email protected]> Date: Tue Jan 3 01:06:55 2023 -0600
libc.7: Revise content
* Define the term "standard C library".
* Say who's responsible for standardizing it.
* Practically all C _libraries_ use libc, too.
* Move material describing structure glibc from intro(3) to here and recast in more detail.
* Update example filespec for libc.so.6.
commit f9c89fd1697f3354f570a93814665d2b665ffdad
Author: G. Branden Robinson <[email protected]> Date: Thu Jan 5 16:34:39 2023 -0600
libc.7: wfix
* Say "GNU/Linux distributions" instead of "Linux distributions".
* Clarify claim about popularity of glibc.
* Tighten wording.
commit 12a26baf73d984d1c2c3075246aa64b7a5162348
Author: G. Branden Robinson <[email protected]> Date: Fri Jan 6 01:44:20 2023 -0600
ldconfig.8: Revise and update for glibc 2.32
* Recast summary description to identify relevance of libraries.
* Drop -V option from synopsis; it doesn't make any sense combined with the operation mode shown, and no other "get out quick" option, including its synonym --version, is documented in the synopsis.
* Clarify that the "links" manipulated by the program are symbolic.
* Discuss caching feature separately from symbolic link management.
* Clarify how ldconfig can be run by unprivileged users (probably for troubleshooting).
* Recast example of shared library linkage chain and motivate the existence for each link or file. Define term "soname" and present it in lowercase like other Linux man-pages, instead of full caps.
* Document auxiliary cache file, which apparently has been described nowhere but a source comment in the original commit 15 years ago.
* Document that -C implies -i. See elf/ldconfig.c:162.
* Clarify how -l option works (a little).
* Drop mention of "quiet mode", which does not seem to exist.
* Be explicit that -p/--print-cache option exits early; i.e., it doesn't undertake ldconfig's primary function.
* Document --usage and -?/--help options.
* Clarify what -v/--verbose does.
* Clarify that -V/--version exits early.
* Expand description of "ld.so.conf" file to discuss "include" and "hwcap" features. Describe these as "directives" (though the latter died upstream in glibc 2.32 before we got around to documenting it). Document ld.so.conf's comment syntax.
* Document handling of leading spaces and empty lines in ld.so.conf.
* Document location of auxiliary cache file.
commit afc8fa5eebd36de2d8a372873a781abebaddf996
Author: G. Branden Robinson <[email protected]> Date: Sun Jan 8 16:20:29 2023 -0600
adjtimex.2: Drop dead hyperlink.
"UNIX and Scientific Computing Services Pages
The information that was previously in this area is out of date. Please refer to the SCS Confluence Page or contact unix-admin."
commit 0b8b5b30064ecd9d2398f6389cac27683051fb19
Author: G. Branden Robinson <[email protected]> Date: Sun Jan 8 15:49:21 2023 -0600
localedef.1: ffix
* Protect literals from hyphenation.
* Specify break points in lengthy file names.
commit 3e3272e211c2ac1a628dce272b14c1b61e7c03c4
Author: G. Branden Robinson <[email protected]> Date: Sun Jan 8 15:37:24 2023 -0600
localedef.1: ffix
Spell metasyntactic variables as hyphenated noun phrases.
commit 9da1c0128b4f0d3ce18434fb3fae633e208cd0c9
Author: G. Branden Robinson <[email protected]> Date: Sun Jan 8 15:36:02 2023 -0600
localedef.1: ffix
Spell ellipsis such that it will render better on typesetters.
Use unadjustable space \~ instead of quoted space at the boundary of a macro argument, for readability.
commit d8e77e33049230f27a45f1040fcfec847bfae64b
Author: G. Branden Robinson <[email protected]> Date: Sun Jan 8 15:34:19 2023 -0600
localedef.1: ffix
Use typographer's quotation marks.
commit 64e88fdd36ab6fb9cae6d0671962cbfe54a92c1c
Author: G. Branden Robinson <[email protected]> Date: Sat Jan 7 03:36:35 2023 -0600
signal.2, utf-8.7: srcfix
Use IP macro instead of TP for paragraph tags with no semantic value.
commit c423b1bd51992a2316d4812624c0392638665d49
Author: G. Branden Robinson <[email protected]> Date: Wed Feb 15 09:08:02 2023 -0600
memcmp.3: Recast security caveat
Use terminology more carefully.
* Refer to the info sec property of confidentiality instead of saying, vaguely, "security-critical".
https://informationsecurity.wustl.edu/items/\
confidentiality-integrity-and-availability-the-cia-triad/
* Try not to confuse anyone who's studied the analysis of algorithms:
don't say "constant time" when "deterministic time" is meant. The time to perform the memory comparison remains linear (O(n)), not constant (O(1)).
* Tighten wording.
commit 88163675125a0facf3709eea30239734119d2459 (origin/master, origin/HEAD) [snip]
Regards,
Branden