.\"	$NetBSD: randomid.3,v 1.9 2017/10/24 19:07:12 abhinav Exp $
.\"
.\" Copyright (C) 2006 The NetBSD Foundation
.\" All rights reserved.
.\"
.\" Copyright (C) 2003 WIDE Project.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the project nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd January 5, 2006
.Dt RANDOMID 3
.Os
.Sh NAME
.Nm randomid ,
.Nm randomid_new ,
.Nm randomid_delete
.Nd provide pseudo-random data stream without repetitions
.Sh SYNOPSIS
.In sys/types.h
.In randomid.h
.Ft uint32_t
.Fn randomid "randomid_t ctx"
.Ft randomid_t
.Fn randomid_new "int bits" "long timeo"
.Ft void
.Fn randomid_delete "randomid_t ctx"
.Sh DESCRIPTION
The
.Fn randomid
function provides pseudo-random data stream,
which is guaranteed not to generate the same number twice during
a certain duration.
.Fa ctx
is the context which holds internal state for the random number generator.
.Pp
To initialize a context,
.Fa randomid_new
is used.
.Fa bits
specifies the bitwidth of the value generated by
.Fn randomid .
Currently 32, 20, and 16 are supported.
.Fa timeo
specifies the reinitialization interval in seconds.
.Fa timeo
has to be bigger than
.Dv RANDOMID_TIMEO_MIN .
.Fa randomid_new
returns a dynamically-allocated memory region allocated by
.Xr malloc 3 .
.Pp
.Fn randomid_delete
will
.Xr free 3
the internal state
.Fa ctx .
.Pp
The same number may appear after two reinitialization events of the internal state,
.Fa ctx .
Reinitialization happens when the random number generator cycle is exhausted,
or
.Fa timeo
seconds have passed since the last reinitialization.
For instance,
.Fa ctx
configured to generate 16 bit data stream will reinitialize its internal state
every 30000 calls to
.Fn randomid
.Po
or after
.Fa timeo
seconds
.Pc ,
therefore the same data will not appear until after 30000 calls to
.Fn randomid
.Po
or after
.Fa timeo
seconds
.Pc .
.Pp
The internal state,
.Fa ctx ,
determines the data stream generated by
.Fn randomid .
.Fa ctx
must be allocated per data stream
.Pq such as a specific data field .
It must not be shared among multiple data streams with different usage.
.\"
.Sh EXAMPLES
.Bd -literal -offset indent
#include <stdio.h>
#include <sys/types.h>
#include <randomid.h>

uint32_t
genid(void)
{
	static randomid_t ctx = NULL;

	if (!ctx)
		ctx = randomid_new(16, (long)3600);
	return randomid(ctx);
}
.Ed
.\"
.Sh ERRORS
.Fn randomid_new
returns
.Dv NULL
on error and sets the external variable
.Va errno .
.\"
.Sh SEE ALSO
.Xr arc4random 3
.\"
.Sh HISTORY
The pseudo-random data stream generator was designed by Niels Provos for
.Ox
IPv4 fragment ID generation.
.Fn randomid
is a generalized version of the generator, reworked by Jun-ichiro itojun Hagino,
and was introduced in
.Nx 2.0 .