1 files changed, 49 insertions, 27 deletions
diff --git a/src/lib/libc/stdlib/rand.3 b/src/lib/libc/stdlib/rand.3
index 5d4bfe7ab6..c760161ba7 100644
--- a/src/lib/libc/stdlib/rand.3
+++ b/src/lib/libc/stdlib/rand.3
@@ -29,52 +29,65 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"     $OpenBSD: rand.3,v 1.17 2014/11/25 17:41:12 millert Exp $
+.\"     $OpenBSD: rand.3,v 1.18 2014/12/08 21:45:20 deraadt Exp $
 .\"
-.Dd $Mdocdate: November 25 2014 $
+.Dd $Mdocdate: December 8 2014 $
 .Dt RAND 3
 .Os
 .Sh NAME
 .Nm rand ,
 .Nm rand_r ,
-.Nm srand
+.Nm srand ,
+.Nm srand_deterministic
 .Nd bad pseudo-random number generator
 .Sh SYNOPSIS
 .In stdlib.h
 .Ft void
 .Fn srand "unsigned int seed"
+.Ft void
+.Fn srand_deterministic "unsigned int seed"
 .Ft int
 .Fn rand void
 .Ft int
 .Fn rand_r "unsigned int *seed"
 .Sh DESCRIPTION
 .Bf -symbolic
-These interfaces are obsoleted by
+Standards insist that this interface return deterministic results.
-.Xr random 3 ,
+Unsafe usage is very common, so
-which is also unsafe.
+.Ox
-Consider using
+changed the subsystem to return non-deterministic results by default.
-.Xr arc4random 3 .
 .Ef
 .Pp
-The
+To satisfy portable code,
+.Fn srand
+may be called to initialize the subsystem.
+In
+.Ox
+the
+.Ar seed
+variable is ignored, and strong random number results will be provided from
+.Xr arc4random 3.
+In other systems, the
+.Ar seed
+variable primes a simplistic deterministic algorithm.
+.Pp
+If the standardized behavior is required
+.Fn srand_deterministic
+can be substituted for
+.Fn srand ,
+then subsequent
 .Fn rand
-function computes a sequence of pseudo-random integers in the range
+calls will return results using the deterministic algorithm.
-of 0 to
-.Dv RAND_MAX
-(as defined by the header file
-.In stdlib.h ) .
 .Pp
 The
-.Fn srand
+.Fn rand
-function sets its argument as the seed for a new sequence of
+function returns a result in the range of 0 to
-pseudo-random numbers to be returned by
+.Dv RAND_MAX .
-.Fn rand .
+By default, this result comes from
-These sequences are repeatable by calling
+.Xr arc4random 3 .
-.Fn srand
+If
-with the same seed value.
+.Fn srand_deterministic
-.Pp
+was called, the result will be computed using the deterministic algorithm.
-If no seed value is provided, the functions are automatically
-seeded with a value of 1.
 .Pp
 The
 .Fn rand_r
@@ -83,6 +96,7 @@ is a thread-safe version of
 Storage for the seed must be provided through the
 .Fa seed
 argument, and needs to have been initialized by the caller.
+It always operates using the deterministic algorithm.
 .Sh SEE ALSO
 .Xr arc4random 3 ,
 .Xr rand48 3 ,
@@ -90,15 +104,23 @@ argument, and needs to have been initialized by the caller.
 .Sh STANDARDS
 The
 .Fn rand
-and
+function conforms to
-.Fn srand
-functions conform to
 .St -ansiC .
 .Pp
 The
 .Fn rand_r
 function conforms to
 .St -p1003.1-2008 .
+.Pp
+The
+.Fn srand
+function does not conform to
+.St -ansiC ,
+intentionally.
+.Pp
+The
+.Fn srand_deterministic
+function is an OpenBSD extension.
 .Sh HISTORY
 The functions
 .Fn rand

diff --git a/src/lib/libc/stdlib/rand.3 b/src/lib/libc/stdlib/rand.3 index 5d4bfe7ab6..c760161ba7 100644 --- a/src/lib/libc/stdlib/rand.3 +++ b/src/lib/libc/stdlib/rand.3
@@ -29,52 +29,65 @@
29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30	.\" SUCH DAMAGE.	30	.\" SUCH DAMAGE.
31	.\"	31	.\"
32	.\" $OpenBSD: rand.3,v 1.17 2014/11/25 17:41:12 millert Exp $	32	.\" $OpenBSD: rand.3,v 1.18 2014/12/08 21:45:20 deraadt Exp $
33	.\"	33	.\"
34	.Dd $Mdocdate: November 25 2014 $	34	.Dd $Mdocdate: December 8 2014 $
35	.Dt RAND 3	35	.Dt RAND 3
36	.Os	36	.Os
37	.Sh NAME	37	.Sh NAME
38	.Nm rand ,	38	.Nm rand ,
39	.Nm rand_r ,	39	.Nm rand_r ,
40	.Nm srand	40	.Nm srand ,
		41	.Nm srand_deterministic
41	.Nd bad pseudo-random number generator	42	.Nd bad pseudo-random number generator
42	.Sh SYNOPSIS	43	.Sh SYNOPSIS
43	.In stdlib.h	44	.In stdlib.h
44	.Ft void	45	.Ft void
45	.Fn srand "unsigned int seed"	46	.Fn srand "unsigned int seed"
		47	.Ft void
		48	.Fn srand_deterministic "unsigned int seed"
46	.Ft int	49	.Ft int
47	.Fn rand void	50	.Fn rand void
48	.Ft int	51	.Ft int
49	.Fn rand_r "unsigned int *seed"	52	.Fn rand_r "unsigned int *seed"
50	.Sh DESCRIPTION	53	.Sh DESCRIPTION
51	.Bf -symbolic	54	.Bf -symbolic
52	These interfaces are obsoleted by	55	Standards insist that this interface return deterministic results.
53	.Xr random 3 ,	56	Unsafe usage is very common, so
54	which is also unsafe.	57	.Ox
55	Consider using	58	changed the subsystem to return non-deterministic results by default.
56	.Xr arc4random 3 .
57	.Ef	59	.Ef
58	.Pp	60	.Pp
59	The	61	To satisfy portable code,
		62	.Fn srand
		63	may be called to initialize the subsystem.
		64	In
		65	.Ox
		66	the
		67	.Ar seed
		68	variable is ignored, and strong random number results will be provided from
		69	.Xr arc4random 3.
		70	In other systems, the
		71	.Ar seed
		72	variable primes a simplistic deterministic algorithm.
		73	.Pp
		74	If the standardized behavior is required
		75	.Fn srand_deterministic
		76	can be substituted for
		77	.Fn srand ,
		78	then subsequent
60	.Fn rand	79	.Fn rand
61	function computes a sequence of pseudo-random integers in the range	80	calls will return results using the deterministic algorithm.
62	of 0 to
63	.Dv RAND_MAX
64	(as defined by the header file
65	.In stdlib.h ) .
66	.Pp	81	.Pp
67	The	82	The
68	.Fn srand	83	.Fn rand
69	function sets its argument as the seed for a new sequence of	84	function returns a result in the range of 0 to
70	pseudo-random numbers to be returned by	85	.Dv RAND_MAX .
71	.Fn rand .	86	By default, this result comes from
72	These sequences are repeatable by calling	87	.Xr arc4random 3 .
73	.Fn srand	88	If
74	with the same seed value.	89	.Fn srand_deterministic
75	.Pp	90	was called, the result will be computed using the deterministic algorithm.
76	If no seed value is provided, the functions are automatically
77	seeded with a value of 1.
78	.Pp	91	.Pp
79	The	92	The
80	.Fn rand_r	93	.Fn rand_r
@@ -83,6 +96,7 @@ is a thread-safe version of
83	Storage for the seed must be provided through the	96	Storage for the seed must be provided through the
84	.Fa seed	97	.Fa seed
85	argument, and needs to have been initialized by the caller.	98	argument, and needs to have been initialized by the caller.
		99	It always operates using the deterministic algorithm.
86	.Sh SEE ALSO	100	.Sh SEE ALSO
87	.Xr arc4random 3 ,	101	.Xr arc4random 3 ,
88	.Xr rand48 3 ,	102	.Xr rand48 3 ,
@@ -90,15 +104,23 @@ argument, and needs to have been initialized by the caller.
90	.Sh STANDARDS	104	.Sh STANDARDS
91	The	105	The
92	.Fn rand	106	.Fn rand
93	and	107	function conforms to
94	.Fn srand
95	functions conform to
96	.St -ansiC .	108	.St -ansiC .
97	.Pp	109	.Pp
98	The	110	The
99	.Fn rand_r	111	.Fn rand_r
100	function conforms to	112	function conforms to
101	.St -p1003.1-2008 .	113	.St -p1003.1-2008 .
		114	.Pp
		115	The
		116	.Fn srand
		117	function does not conform to
		118	.St -ansiC ,
		119	intentionally.
		120	.Pp
		121	The
		122	.Fn srand_deterministic
		123	function is an OpenBSD extension.
102	.Sh HISTORY	124	.Sh HISTORY
103	The functions	125	The functions
104	.Fn rand	126	.Fn rand