[PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[Alejandro Colomar]

arc4random(3)
arc4random_uniform(3)
arc4random_buf(3)

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man3/arc4random.3 | 104 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 man3/arc4random.3

diff --git a/man3/arc4random.3 b/man3/arc4random.3
new file mode 100644
index 000000000..5fd292321
--- /dev/null
+++ b/man3/arc4random.3
@@ -0,0 +1,104 @@
+.\" Copyright (C) 2023 Alejandro Colomar <alx@kernel.org>
+.\"
+.\" 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)
-- 
2.39.0

Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2975 bytes --]

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)

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[Tom Schwindl]

On Sun Jan 1, 2023 at 5:26 PM CET, Alejandro Colomar wrote:
> arc4random(3)
> arc4random_uniform(3)
> arc4random_buf(3)
>
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> ---
>  man3/arc4random.3 | 104 ++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 104 insertions(+)
>  create mode 100644 man3/arc4random.3
>
> diff --git a/man3/arc4random.3 b/man3/arc4random.3
> new file mode 100644
> index 000000000..5fd292321
> --- /dev/null
> +++ b/man3/arc4random.3
> @@ -0,0 +1,104 @@
> +.\" Copyright (C) 2023 Alejandro Colomar <alx@kernel.org>
> +.\"
> +.\" 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.

I'm not a native speaker, but I think it should be s/in/on/.

--
Best Regards,
Tom Schwindl

Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 408 bytes --]

Hi Tom,

On 1/1/23 17:39, Tom Schwindl wrote:
>> +.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

> 
> --
> Best Regards,
> Tom Schwindl

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 3492 bytes --]

[dropping libc-alpha due to scope of my comments]

Hi Alex,

At 2023-01-01T17:26:28+0100, Alejandro Colomar wrote:
[...]
> +.ad l
> +.nh
> +.TS
[...]
> +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".

> +.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

> +.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.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4274 bytes --]

Hi Branden!

On 1/1/23 21:48, G. Branden Robinson wrote:
> [dropping libc-alpha due to scope of my comments]
> 
> Hi Alex,
> 
> At 2023-01-01T17:26:28+0100, Alejandro Colomar wrote:
> [...]
>> +.ad l
>> +.nh
>> +.TS
> [...]
>> +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.

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 :)

> 
> --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".
> 
>> +.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

:)

> 
>> +.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]

Thanks for the detailed explanation!

> 
> 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.

> 
> 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

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[Jakub Wilk]

* Alejandro Colomar <alx.manpages@gmail.com>, 2023-01-01 17:26:
>+.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.

-- 
Jakub Wilk

Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[Tom Schwindl]

On Mon Mar 13, 2023 at 10:30 PM CET, Jakub Wilk wrote:
> * Alejandro Colomar <alx.manpages@gmail.com>, 2023-01-01 17:26:
> >+.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?

-- 
Best Regards,
Tom Schwindl

Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1803 bytes --]

Hi Tom & Jakub,

On 3/14/23 19:57, Tom Schwindl wrote:
> On Mon Mar 13, 2023 at 10:30 PM CET, Jakub Wilk wrote:
>> * Alejandro Colomar <alx.manpages@gmail.com>, 2023-01-01 17:26:
>>> +.SH LIBRARY
>>> +Standard C library
>>> +.RI ( libc ", " -lc )
>>
>> That should be \-lc, but...

Ahh, I thought I had fixed that; it seems not.  Thanks!

>> 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.

>> 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.

>>
> 
> 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

> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 8403 bytes --]

At 2023-03-15T13:04:29+0100, Alejandro Colomar wrote:
> > 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 <g.branden.robinson@gmail.com>
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.)

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

commit a997ee7d2936e1c5e3f61a9218b02118dbae9a52
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
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).

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

commit 8a5bc95aba96c409b74f7128f9a9b30b34dc976e
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
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".

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

commit 5619f1fff3457a5f0d67c983b76fb329eaae7b92
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
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.

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

commit f9c89fd1697f3354f570a93814665d2b665ffdad
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
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.

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

commit 12a26baf73d984d1c2c3075246aa64b7a5162348
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
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.

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

commit afc8fa5eebd36de2d8a372873a781abebaddf996
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
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."

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

commit 0b8b5b30064ecd9d2398f6389cac27683051fb19
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Jan 8 15:49:21 2023 -0600

    localedef.1: ffix

    * Protect literals from hyphenation.
    * Specify break points in lengthy file names.

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

commit 3e3272e211c2ac1a628dce272b14c1b61e7c03c4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Jan 8 15:37:24 2023 -0600

    localedef.1: ffix

    Spell metasyntactic variables as hyphenated noun phrases.

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

commit 9da1c0128b4f0d3ce18434fb3fae633e208cd0c9
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
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.

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

commit d8e77e33049230f27a45f1040fcfec847bfae64b
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Jan 8 15:34:19 2023 -0600

    localedef.1: ffix

    Use typographer's quotation marks.

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

commit 64e88fdd36ab6fb9cae6d0671962cbfe54a92c1c
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
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.

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

commit c423b1bd51992a2316d4812624c0392638665d49
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
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.

    Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

commit 88163675125a0facf3709eea30239734119d2459 (origin/master, origin/HEAD)
[snip]

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[Jakub Wilk]

* Alejandro Colomar <alx.manpages@gmail.com>, 2023-01-01 17:27:
>arc4random_uniform() returns a random number less than upper_bound for 
>valid input, or 0 when upper_bound is invalid.

Is the "or 0 ..." thing part of the API? I could find anything like that 
in glibc docs or BSD man pages.

>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:

>These functions first appeared in OpenBSD 2.1, FreeBSD 3.0, NetBSD 
>1.6, and DragonFly 1.0.  The functions arc4random(), arc4random_buf() 
>and arc4random_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”.

-- 
Jakub Wilk

Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2720 bytes --]

Hi Jakub,

On 3/17/23 22:31, Jakub Wilk wrote:
> * Alejandro Colomar <alx.manpages@gmail.com>, 2023-01-01 17:27:
>> arc4random_uniform() returns a random number less than upper_bound for 
>> valid input, or 0 when upper_bound is 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.

> I could find anything like that 
> in glibc docs or BSD man pages.

<https://inbox.sourceware.org/libc-alpha/20230101162627.28031-1-alx@kernel.org/>

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.

> 
>> 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.

> 
> In contrast, the libbsd man page is much more informative:
> 
>> These functions first appeared in OpenBSD 2.1, FreeBSD 3.0, NetBSD 
>> 1.6, and DragonFly 1.0.  The functions arc4random(), arc4random_buf() 
>> and arc4random_uniform() appeared in glibc 2.36.

Yup.  :)

Thanks a lot for this thorough review!

Alex

>>
>> 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”.
> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] arc4random.3: New page documenting the arc4random(3) family of functions

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3024 bytes --]



On 3/17/23 22:44, Alejandro Colomar wrote:
> Hi Jakub,
> 
> On 3/17/23 22:31, Jakub Wilk wrote:
>> * Alejandro Colomar <alx.manpages@gmail.com>, 2023-01-01 17:27:
>>> arc4random_uniform() returns a random number less than upper_bound for 
>>> valid input, or 0 when upper_bound is 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.
> 
>> I could find anything like that 
>> in glibc docs or BSD man pages.
> 
> <https://inbox.sourceware.org/libc-alpha/20230101162627.28031-1-alx@kernel.org/>

Sorry, I pasted the wrong link.  I wanted to paste this one:

<https://inbox.sourceware.org/libc-alpha/20221231023653.41877-1-alx@kernel.org/T/>

> 
> 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.
> 
>>
>>> 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.
> 
>>
>> In contrast, the libbsd man page is much more informative:
>>
>>> These functions first appeared in OpenBSD 2.1, FreeBSD 3.0, NetBSD 
>>> 1.6, and DragonFly 1.0.  The functions arc4random(), arc4random_buf() 
>>> and arc4random_uniform() appeared in glibc 2.36.
> 
> Yup.  :)
> 
> Thanks a lot for this thorough review!
> 
> Alex
> 
>>>
>>> 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”.
>>
> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]