random(3) and RAND_MAX

random(3) and RAND_MAX

[John Marshall]

Observed in CentOS 8's man-pages-4.15-6.el8.x86_64 and also on man-pages Git master:

Man-pages's rand.3 says rand() returns values in the range [0, RAND_MAX] and is very clear that this is inclusive. This is the same as the POSIX description of rand(3).

Man-pages's random.3 says random() returns values "in the range from 0 to RAND_MAX". However POSIX describes random() as returning values "in the range from 0 to 2^31-1".

In practice glibc and musl both fix RAND_MAX as a constant 2^31-1 so on these platforms it is the same thing. Similarly on macOS. It appears that FreeBSD used to have a slightly lower value of RAND_MAX but several months ago raised it to 2^31-1 similarly. OTOH it appears that Windows, Cygwin, etc still use a much smaller value for RAND_MAX (32767) but the full POSIX range for random(3).

So random.3 describing the range as 0..RAND_MAX is correct on Linux (unless you're using a very unusual libc) but misleading when used as a reference for writing code portable to other platforms. It would be good to change random.3 to refer to the hardcoded constant (2^31-1) instead of RAND_MAX (and perhaps add a note that on Linux this is the same as RAND_MAX), or at least to add a note saying that RAND_MAX may be an unrelated value on other platforms.

Thanks,

    John

AW: random(3) and RAND_MAX

[Walter Harms]

Hi John,
i have read the pages and you are right. POSIX says:
rand -> 0...RAND_MAX
random -> 0...2^31-1

that RAND_MAX is 2^31-1 in some cases does not matter. IMHO
it is wrong to mention RAND_MAX in the random page. it can
simply be replaced with (2**31-1)


re,
 wh
________________________________________
Von: linux-man-owner@vger.kernel.org <linux-man-owner@vger.kernel.org> im Auftrag von John Marshall <John.W.Marshall@glasgow.ac.uk>
Gesendet: Freitag, 5. Juni 2020 19:21:00
An: mtk.manpages@gmail.com
Cc: linux-man@vger.kernel.org
Betreff: random(3) and RAND_MAX

Observed in CentOS 8's man-pages-4.15-6.el8.x86_64 and also on man-pages Git master:

Man-pages's rand.3 says rand() returns values in the range [0, RAND_MAX] and is very clear that this is inclusive. This is the same as the POSIX description of rand(3).

Man-pages's random.3 says random() returns values "in the range from 0 to RAND_MAX". However POSIX describes random() as returning values "in the range from 0 to 2^31-1".

In practice glibc and musl both fix RAND_MAX as a constant 2^31-1 so on these platforms it is the same thing. Similarly on macOS. It appears that FreeBSD used to have a slightly lower value of RAND_MAX but several months ago raised it to 2^31-1 similarly. OTOH it appears that Windows, Cygwin, etc still use a much smaller value for RAND_MAX (32767) but the full POSIX range for random(3).

So random.3 describing the range as 0..RAND_MAX is correct on Linux (unless you're using a very unusual libc) but misleading when used as a reference for writing code portable to other platforms. It would be good to change random.3 to refer to the hardcoded constant (2^31-1) instead of RAND_MAX (and perhaps add a note that on Linux this is the same as RAND_MAX), or at least to add a note saying that RAND_MAX may be an unrelated value on other platforms.

Thanks,

    John

[patch] random.3: wfix: RAND_MAX is for rand(3)

[John Marshall]

POSIX fixes random()'s range at 2^31-1; RAND_MAX may be smaller on some
platforms (even though with glibc or musl on Linux they are the same).
---

On Sat, Jun 06, 2020 at 12:45:58PM +0000, Walter Harms wrote:
> that RAND_MAX is 2^31-1 in some cases does not matter. IMHO
> it is wrong to mention RAND_MAX in the random page. it can
> simply be replaced with (2**31-1)

Thanks for confirming, Walter. I forgot to mention I was happy to
provide a patch -- suggested fix in this git-format-patch message.

    John

 man3/random.3 | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/man3/random.3 b/man3/random.3
index 76b076f42..e3550f802 100644
--- a/man3/random.3
+++ b/man3/random.3
@@ -69,7 +69,7 @@ The
 function uses a nonlinear additive feedback random
 number generator employing a default table of size 31 long integers to
 return successive pseudo-random numbers in
-the range from 0 to \fBRAND_MAX\fR.
+the range from 0 to 2^31\ \-\ 1.
 The period of this random number generator is very large, approximately
 .IR "16\ *\ ((2^31)\ \-\ 1)" .
 .PP
@@ -125,7 +125,9 @@ or be the result of a previous call of
 The
 .BR random ()
 function returns a value between 0 and
-.BR RAND_MAX .
+.BR INT32_MAX ,
+i.e.,
+.IR "(2^31)\ \-\ 1" .
 The
 .BR srandom ()
 function returns no value.
-- 
2.18.2

AW: [patch] random.3: wfix: RAND_MAX is for rand(3)

[Walter Harms]

just a nit pick:
INT32_MAX  is not mentioned in the POSIX page, just drop it.

________________________________________
Von: linux-man-owner@vger.kernel.org <linux-man-owner@vger.kernel.org> im Auftrag von John Marshall <John.W.Marshall@glasgow.ac.uk>
Gesendet: Montag, 8. Juni 2020 13:04:16
An: mtk.manpages@gmail.com
Cc: linux-man@vger.kernel.org
Betreff: [patch] random.3: wfix: RAND_MAX is for rand(3)

POSIX fixes random()'s range at 2^31-1; RAND_MAX may be smaller on some
platforms (even though with glibc or musl on Linux they are the same).
---

On Sat, Jun 06, 2020 at 12:45:58PM +0000, Walter Harms wrote:
> that RAND_MAX is 2^31-1 in some cases does not matter. IMHO
> it is wrong to mention RAND_MAX in the random page. it can
> simply be replaced with (2**31-1)

Thanks for confirming, Walter. I forgot to mention I was happy to
provide a patch -- suggested fix in this git-format-patch message.

    John

 man3/random.3 | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/man3/random.3 b/man3/random.3
index 76b076f42..e3550f802 100644
--- a/man3/random.3
+++ b/man3/random.3
@@ -69,7 +69,7 @@ The
 function uses a nonlinear additive feedback random
 number generator employing a default table of size 31 long integers to
 return successive pseudo-random numbers in
-the range from 0 to \fBRAND_MAX\fR.
+the range from 0 to 2^31\ \-\ 1.
 The period of this random number generator is very large, approximately
 .IR "16\ *\ ((2^31)\ \-\ 1)" .
 .PP
@@ -125,7 +125,9 @@ or be the result of a previous call of
 The
 .BR random ()
 function returns a value between 0 and
-.BR RAND_MAX .
+.BR INT32_MAX ,
+i.e.,
+.IR "(2^31)\ \-\ 1" .
 The
 .BR srandom ()
 function returns no value.
--
2.18.2

Re: [patch] random.3: wfix: RAND_MAX is for rand(3)

[John Marshall]

On 8 Jun 2020, at 12:10, Walter Harms <wharms@bfs.de> wrote:
> just a nit pick:
> INT32_MAX  is not mentioned in the POSIX page, just drop it.

Indeed it is not (presumably because that POSIX text predates these stdint macros), but it is by definition the same -- on currently existent platforms that matter, and post-N2412 on all platforms [1]. So it's the maintainer's choice whether mentioning it as a constant for code to use is useful.

    John

[1] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2412.pdf

Re: AW: [patch] random.3: wfix: RAND_MAX is for rand(3)

[Jakub Wilk]

* Walter Harms <wharms@bfs.de>, 2020-06-08, 11:10:
>INT32_MAX is not mentioned in the POSIX page

Yes, it is:
https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/stdint.h.html#tag_13_47_03_02

-- 
Jakub Wilk

AW: AW: [patch] random.3: wfix: RAND_MAX is for rand(3)

[Walter Harms]

misunderstanding,

the page random(3) says (in my version)
"range from 0 to 2**31-1." it does not mention
rand_max, INT32_MAX or some other constant only the numerical value.

It happens to be INT32_MAX, but in this case i would simply drop it.
________________________________________
Von: Jakub Wilk <jwilk@jwilk.net>
Gesendet: Montag, 8. Juni 2020 13:21:01
An: Walter Harms
Cc: John Marshall; Michael Kerrisk; linux-man@vger.kernel.org
Betreff: Re: AW: [patch] random.3: wfix: RAND_MAX is for rand(3)

* Walter Harms <wharms@bfs.de>, 2020-06-08, 11:10:
>INT32_MAX is not mentioned in the POSIX page

Yes, it is:
https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/stdint.h.html#tag_13_47_03_02

--
Jakub Wilk

Re: [patch] random.3: wfix: RAND_MAX is for rand(3)

[Michael Kerrisk (man-pages)]

On 6/8/20 1:04 PM, John Marshall wrote:
> POSIX fixes random()'s range at 2^31-1; RAND_MAX may be smaller on some
> platforms (even though with glibc or musl on Linux they are the same).
> ---
> 
> On Sat, Jun 06, 2020 at 12:45:58PM +0000, Walter Harms wrote:
>> that RAND_MAX is 2^31-1 in some cases does not matter. IMHO
>> it is wrong to mention RAND_MAX in the random page. it can
>> simply be replaced with (2**31-1)
> 
> Thanks for confirming, Walter. I forgot to mention I was happy to
> provide a patch -- suggested fix in this git-format-patch message.
> 
>     John
> 
>  man3/random.3 | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
> 
> diff --git a/man3/random.3 b/man3/random.3
> index 76b076f42..e3550f802 100644
> --- a/man3/random.3
> +++ b/man3/random.3
> @@ -69,7 +69,7 @@ The
>  function uses a nonlinear additive feedback random
>  number generator employing a default table of size 31 long integers to
>  return successive pseudo-random numbers in
> -the range from 0 to \fBRAND_MAX\fR.
> +the range from 0 to 2^31\ \-\ 1.
>  The period of this random number generator is very large, approximately
>  .IR "16\ *\ ((2^31)\ \-\ 1)" .
>  .PP
> @@ -125,7 +125,9 @@ or be the result of a previous call of
>  The
>  .BR random ()
>  function returns a value between 0 and
> -.BR RAND_MAX .
> +.BR INT32_MAX ,
> +i.e.,
> +.IR "(2^31)\ \-\ 1" .
>  The
>  .BR srandom ()
>  function returns no value.

Hello John,

Thanks. I applied this patch. I also agree with Walter. There's no
real need to mention INT32_MAX, so I removed that piece.

Cheers,

Michael




-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/