1.\"	$NetBSD: randomid.3,v 1.7 2006/01/05 19:45:29 rpaulo Exp $
2.\"
3.\" Copyright (C) 2006 The NetBSD Foundation
4.\" All rights reserved.
5.\"
6.\" Copyright (C) 2003 WIDE Project.
7.\" All rights reserved.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\" 3. Neither the name of the project nor the names of its contributors
18.\"    may be used to endorse or promote products derived from this software
19.\"    without specific prior written permission.
20.\"
21.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31.\" SUCH DAMAGE.
32.\"
33.Dd January 5, 2006
34.Dt RANDOMID 3
35.Os
36.Sh NAME
37.Nm randomid
38.Nm randomid_new ,
39.Nm randomid_delete ,
40.Nd provide pseudo-random data stream without repetitions
41.Sh SYNOPSIS
42.In sys/types.h
43.In randomid.h
44.Ft uint32_t
45.Fn randomid "randomid_t ctx"
46.Ft randomid_t
47.Fn randomid_new "int bits" "long timeo"
48.Ft void
49.Fn randomid_delete "randomid_t ctx"
50.Sh DESCRIPTION
51The
52.Fn randomid
53function provides pseudo-random data stream,
54which is guaranteed not to generate the same number twice during
55a certain duration.
56.Fa ctx
57is the context which holds internal state for the random number generator.
58.Pp
59To initialize a context,
60.Fa randomid_new
61is used.
62.Fa bits
63specifies the bitwidth of the value generated by
64.Fn randomid .
65Currently 32, 20, and 16 are supported.
66.Fa timeo
67specifies the reinitialization interval in seconds.
68.Fa timeo
69has to be bigger than
70.Dv RANDOMID_TIMEO_MIN .
71.Fa randomid_new
72returns a dynamically-allocated memory region allocated by
73.Xr malloc 3 .
74.Pp
75.Fn randomid_delete
76will
77.Xr free 3
78the internal state
79.Fa ctx .
80.Pp
81The same number may appear after two reinitialization events of the internal state,
82.Fa ctx .
83Reinitialization happens when the random number generator cycle is exhausted,
84or
85.Fa timeo
86seconds have passed since the last reinitialization.
87For instance,
88.Fa ctx
89configured to generate 16 bit data stream will reinitialize its internal state
90every 30000 calls to
91.Fn randomid
92.Po
93or after
94.Fa timeo
95seconds
96.Pc ,
97therefore the same data will not appear until after 30000 calls to
98.Fn randomid
99.Po
100or after
101.Fa timeo
102seconds
103.Pc .
104.Pp
105The internal state,
106.Fa ctx ,
107determines the data stream generated by
108.Fn randomid .
109.Fa ctx
110must be allocated per data stream
111.Pq such as a specific data field .
112It must not be shared among multiple data streams with different usage.
113.\"
114.Sh EXAMPLES
115.Bd -literal -offset indent
116#include \*[Lt]stdio.h\*[Gt]
117#include \*[Lt]sys/types.h\*[Gt]
118#include \*[Lt]randomid.h\*[Gt]
119
120uint32_t
121genid(void)
122{
123	static randomid_t ctx = NULL;
124
125	if (!ctx)
126		ctx = randomid_new(16, (long)3600);
127	return randomid(ctx);
128}
129.Ed
130.\"
131.Sh ERRORS
132.Fn randomid_new
133returns
134.Dv NULL
135on error and sets the external variable
136.Va errno .
137.\"
138.Sh SEE ALSO
139.Xr arc4random 3
140.\"
141.Sh HISTORY
142The pseudo-random data stream generator was designed by Niels Provos for
143.Ox
144IPv4 fragment ID generation.
145.Fn randomid
146is a generalized version of the generator, reworked by Jun-ichiro itojun Hagino,
147and was introduced in
148.Nx 2.0 .
149