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