lib/libc/gen/randomid.3

   1 .\"     $NetBSD: randomid.3,v 1.6 2005/12/26 19:40:14 perry 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
  51 The
  52 .Fn randomid
  53 function provides pseudo-random data stream,
  54 which is guaranteed not to generate the same number twice during
  55 a certain duration.
  56 .Fa ctx
  57 is the context which holds internal state for the random number generator.
  58 .Pp
  59 To initialize a context,
  60 .Fa randomid_new
  61 is used.
  62 .Fa bits
  63 specifies the bitwidth of the value generated by
  64 .Fn randomid .
  65 Currently 32, 20, and 16 are supported.
  66 .Fa timeo
  67 specifies the reinitialization interval in seconds.
  68 .Fa timeo
  69 has to be bigger than
  70 .Dv RANDOMID_TIMEO_MIN .
  71 .Fa randomid_new
  72 returns a dynamically-allocated memory region allocated by
  73 .Xr malloc 3 .
  74 .Pp
  75 .Fn randomid_delete
  76 will
  77 .Xr free 3
  78 the internal state
  79 .Fa ctx .
  80 .Pp
  81 The same number may appear after two reinitialization events of the internal state,
  82 .Fa ctx .
  83 Reinitialization happens when the random number generator cycle is exhausted,
  84 or
  85 .Fa timeo
  86 seconds have passed since the last reinitialization.
  87 For instance,
  88 .Fa ctx
  89 configured to generate 16 bit data stream will reinitialize its internal state
  90 every 30000 calls to
  91 .Fn randomid
  92 .Po
  93 or after
  94 .Fa timeo
  95 seconds
  96 .Pc ,
  97 therefore the same data will not appear until after 30000 calls to
  98 .Fn randomid
  99 .Po
 100 or after
 101 .Fa timeo
 102 seconds
 103 .Pc .
 104 .Pp
 105 The internal state,
 106 .Fa ctx ,
 107 determines the data stream generated by
 108 .Fn randomid .
 109 .Fa ctx
 110 must be allocated per data stream
 111 .Pq such as a specific data field .
 112 It 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
 120 uint32_t
 121 genid(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
 133 returns
 134 .Dv NULL
 135 on error and sets the external variable
 136 .Va errno .
 137 .\"
 138 .Sh SEE ALSO
 139 .Xr arc4random 3
 140 .\"
 141 .Sh HISTORY
 142 The pseudo-random data stream generator was designed by Niels Provos for
 143 .Ox
 144 IPv4 fragment ID generation.
 145 .Fn randomid
 146 is a generalized version of the generator, reworked by Jun-ichiro itojun Hagino,
 147 and was introduced in
 148 .Nx 2.0 .