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