Skip to contentSkip to conversation

random(3) and RAND_MAX

PATCH In review John Marshall 4 participants 8 messages Jun 5, 2020 – Jun 8, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

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

#1 lore raw

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: [email protected] <[email protected]> im Auftrag von John Marshall <[email protected]>
Gesendet: Freitag, 5. Juni 2020 19:21:00
An: [email protected]
Cc: [email protected]
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

#2 lore raw

PATCH 1/1 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).
---

Quoted 3 lines · Walter Harms

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(-)
man3/random.3 +4 -2
index 76b076f42..e3550f802 100644
@@ -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.
Signature · 1 line
2.18.2
#3 lore raw

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

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

________________________________________
Von: [email protected] <[email protected]> im Auftrag von John Marshall <[email protected]>
Gesendet: Montag, 8. Juni 2020 13:04:16
An: [email protected]
Cc: [email protected]
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).
---

Quoted 3 lines · Walter Harms

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(-)
man3/random.3 +4 -2
index 76b076f42..e3550f802 100644
@@ -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

#5 lore raw

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

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 <[email protected]>
Gesendet: Montag, 8. Juni 2020 13:21:01
An: Walter Harms
Cc: John Marshall; Michael Kerrisk; [email protected]
Betreff: Re: AW: [patch] random.3: wfix: RAND_MAX is for rand(3)

* Walter Harms <[email protected]>, 2020-06-08, 11:10:

Quoted 1 line

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

#6 lore raw

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

In reply to Walter Harms
Quoted 2 lines · Walter Harms

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

#7 lore raw

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

In reply to John Marshall
Quoted 31 lines · 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).
---

Quoted 3 lines · Walter Harms

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(-)
man3/random.3 +1 -1
index 76b076f42..e3550f802 100644
@@ -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

man3/random.3 or be the result of a previous call of · line 133

Quoted 10 lines
man3/random.3 +3 -1
@@ -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

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