Linux-man Archive on lore.kernel.org
 help / color / Atom feed
* random(3) and RAND_MAX
@ 2020-06-05 17:21 John Marshall
  2020-06-06 12:45 ` AW: " Walter Harms
  0 siblings, 1 reply; 8+ messages in thread
From: John Marshall @ 2020-06-05 17:21 UTC (permalink / raw)
  To: mtk.manpages; +Cc: linux-man

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

^ permalink raw reply	[flat|nested] 8+ messages in thread

* AW: random(3) and RAND_MAX
  2020-06-05 17:21 random(3) and RAND_MAX John Marshall
@ 2020-06-06 12:45 ` Walter Harms
  2020-06-08 11:04   ` [patch] random.3: wfix: RAND_MAX is for rand(3) John Marshall
  0 siblings, 1 reply; 8+ messages in thread
From: Walter Harms @ 2020-06-06 12:45 UTC (permalink / raw)
  To: John Marshall, mtk.manpages; +Cc: linux-man

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

^ permalink raw reply	[flat|nested] 8+ messages in thread

* [patch] random.3: wfix: RAND_MAX is for rand(3)
  2020-06-06 12:45 ` AW: " Walter Harms
@ 2020-06-08 11:04   ` John Marshall
  2020-06-08 11:10     ` AW: " Walter Harms
  2020-06-08 20:27     ` Michael Kerrisk (man-pages)
  0 siblings, 2 replies; 8+ messages in thread
From: John Marshall @ 2020-06-08 11:04 UTC (permalink / raw)
  To: mtk.manpages; +Cc: linux-man

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


^ permalink raw reply	[flat|nested] 8+ messages in thread

* AW: [patch] random.3: wfix: RAND_MAX is for rand(3)
  2020-06-08 11:04   ` [patch] random.3: wfix: RAND_MAX is for rand(3) John Marshall
@ 2020-06-08 11:10     ` Walter Harms
  2020-06-08 11:20       ` John Marshall
  2020-06-08 11:21       ` AW: " Jakub Wilk
  2020-06-08 20:27     ` Michael Kerrisk (man-pages)
  1 sibling, 2 replies; 8+ messages in thread
From: Walter Harms @ 2020-06-08 11:10 UTC (permalink / raw)
  To: John Marshall, mtk.manpages; +Cc: linux-man

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


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [patch] random.3: wfix: RAND_MAX is for rand(3)
  2020-06-08 11:10     ` AW: " Walter Harms
@ 2020-06-08 11:20       ` John Marshall
  2020-06-08 11:21       ` AW: " Jakub Wilk
  1 sibling, 0 replies; 8+ messages in thread
From: John Marshall @ 2020-06-08 11:20 UTC (permalink / raw)
  To: Walter Harms; +Cc: mtk.manpages, linux-man

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

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: AW: [patch] random.3: wfix: RAND_MAX is for rand(3)
  2020-06-08 11:10     ` AW: " Walter Harms
  2020-06-08 11:20       ` John Marshall
@ 2020-06-08 11:21       ` Jakub Wilk
  2020-06-08 12:50         ` AW: " Walter Harms
  1 sibling, 1 reply; 8+ messages in thread
From: Jakub Wilk @ 2020-06-08 11:21 UTC (permalink / raw)
  To: Walter Harms; +Cc: John Marshall, Michael Kerrisk, linux-man

* 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

^ permalink raw reply	[flat|nested] 8+ messages in thread

* AW: AW: [patch] random.3: wfix: RAND_MAX is for rand(3)
  2020-06-08 11:21       ` AW: " Jakub Wilk
@ 2020-06-08 12:50         ` Walter Harms
  0 siblings, 0 replies; 8+ messages in thread
From: Walter Harms @ 2020-06-08 12:50 UTC (permalink / raw)
  To: Jakub Wilk; +Cc: John Marshall, Michael Kerrisk, linux-man

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

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [patch] random.3: wfix: RAND_MAX is for rand(3)
  2020-06-08 11:04   ` [patch] random.3: wfix: RAND_MAX is for rand(3) John Marshall
  2020-06-08 11:10     ` AW: " Walter Harms
@ 2020-06-08 20:27     ` Michael Kerrisk (man-pages)
  1 sibling, 0 replies; 8+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-06-08 20:27 UTC (permalink / raw)
  To: John Marshall; +Cc: mtk.manpages, linux-man, walter harms

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/

^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, back to index

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-06-05 17:21 random(3) and RAND_MAX John Marshall
2020-06-06 12:45 ` AW: " Walter Harms
2020-06-08 11:04   ` [patch] random.3: wfix: RAND_MAX is for rand(3) John Marshall
2020-06-08 11:10     ` AW: " Walter Harms
2020-06-08 11:20       ` John Marshall
2020-06-08 11:21       ` AW: " Jakub Wilk
2020-06-08 12:50         ` AW: " Walter Harms
2020-06-08 20:27     ` Michael Kerrisk (man-pages)

Linux-man Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-man/0 linux-man/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-man linux-man/ https://lore.kernel.org/linux-man \
		linux-man@vger.kernel.org
	public-inbox-index linux-man

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-man


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git