From pherman@frenchfries.net  Thu Feb 20 11:51:57 2003
Return-Path: <pherman@frenchfries.net>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id CC6E637B401
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 20 Feb 2003 11:51:57 -0800 (PST)
Received: from darius.concentric.net (darius.concentric.net [207.155.198.79])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 89F7143FBF
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 20 Feb 2003 11:51:56 -0800 (PST)
	(envelope-from pherman@frenchfries.net)
Received: from cliff.concentric.net (cliff.concentric.net [206.173.118.90])
	by darius.concentric.net [Concentric SMTP Routing 1.0] id h1KJpUw02798 
        for <FreeBSD-gnats-submit@freebsd.org.>; Thu, 20 Feb 2003 14:51:31 -0500 (EST)
Received: from frenchfries.net (da001d0246.lax-ca.osd.concentric.net [66.239.48.246])
	by cliff.concentric.net (8.9.1a)
	id OAA22575; Thu, 20 Feb 2003 14:51:27 -0500 (EST)
Received: by frenchfries.net (Postfix, from userid 1000)
	id AD2484B0F; Thu, 20 Feb 2003 11:50:15 -0800 (PST)
Message-Id: <20030220195015.AD2484B0F@frenchfries.net>
Date: Thu, 20 Feb 2003 11:50:15 -0800 (PST)
From: Paul Herman <pherman@frenchfries.net>
To: FreeBSD-gnats-submit@freebsd.org
Subject: missing range information in arc4random() manpage
X-Send-Pr-Version: 3.113

>Number:         48493
>Category:       docs
>Synopsis:       missing range information in arc4random() manpage
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Feb 20 12:00:06 PST 2003
>Closed-Date:    Tue May 06 14:40:56 PDT 2003
>Last-Modified:  Tue May 06 14:40:56 PDT 2003
>Originator:     Paul Herman
>Release:        FreeBSD 4.7-STABLE i386
>Organization:
>Environment:
System: FreeBSD mammoth.eat.frenchfries.net 4.7-STABLE FreeBSD 4.7-STABLE #0: Sat Jan 25 23:29:57 PST 2003 pherman@mammoth.eat.frenchfries.net:/u02/obj/u01/src/sys/mammoth i386

>Description:
   The manpage for arc4random doesn't state the fact that the range is twice
   the traditional RAND_MAX.  This can lead to erroneous results if used
   like the traditional rand()/random() functions.  A short explanation
   of this fact, and a simple example should be added to the manpage.

   This was already discussed on -hackers.  See archive for details.

>How-To-Repeat:
   man arc4random

>Fix:
Index: arc4random.3
===================================================================
RCS file: /u02/ncvs/src/lib/libc/gen/arc4random.3,v
retrieving revision 1.8.2.4
diff -u -r1.8.2.4 arc4random.3
--- arc4random.3	14 Dec 2001 18:33:50 -0000	1.8.2.4
+++ arc4random.3	20 Feb 2003 19:32:58 -0000
@@ -57,7 +57,13 @@
 can be in about
 .if t 2\u\s71700\s10\d
 .if n (2**1700)
-states.
+states. The
+.Fn arc4random
+function returns pseudo-random numbers in the range of 0 to
+.if t 2\u\s731\s10\d\(mi1,
+.if n (2**31)\(mi1,
+and therefore has twice the range of
+.Dv RAND_MAX .
 .Pp
 The
 .Fn arc4random_stir
@@ -73,6 +79,15 @@
 since
 .Fn arc4random
 automatically initializes itself.
+.Sh EXAMPLES
+The following produces a drop-in replacement for the traditional
+.Fn rand
+and
+.Fn random
+functions using
+.Fn arc4random :
+.Bd -literal -offset indent
+#define foo4random()  (arc4random() % ((unsigned)RAND_MAX + 1))
 .Sh SEE ALSO
 .Xr rand 3 ,
 .Xr random 3 ,

At this point, I had to manually edit the mdoc to:

-Remove the tables, we do not need them here.
-Replaced the #define line with:
.Dv #define Fn foo4random ( Fn arc4random Ft % ((unsigned)RAND_MAX + 1))
as it looks more correct.

Everything else was applied.

>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->patched 
State-Changed-By: trhodes 
State-Changed-When: Thu May 1 12:33:52 PDT 2003 
State-Changed-Why:  
Patch applied with some conditioning, see comments. 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Thu May 1 12:33:52 PDT 2003 
Responsible-Changed-Why:  
Over to me. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=48493 
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Tue May 6 14:40:36 PDT 2003 
State-Changed-Why:  
MFC complete.  Thanks for the submission! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=48493 
>Unformatted:
