skalibs

Mirror/fork of https://skarnet.org/software/skalibs/
git clone https://ccx.te2000.cz/git/skalibs
Log | Files | Refs | README | LICENSE

index.html (3943B)

      1 <html>
      2   <head>
      3     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      4     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
      5     <meta http-equiv="Content-Language" content="en" />
      6     <title>skalibs: the random library interface</title
      7     <meta name="Description" content="skalibs: the random library interface" />
      8     <meta name="Keywords" content="skalibs library random librandom random.h" />
      9     <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
     10   </head>
     11 <body>
     12 
     13 <p>
     14 <a href="../libskarnet.html">libskarnet</a><br />
     15 <a href="../index.html">skalibs</a><br />
     16 <a href="//skarnet.org/software/">Software</a><br />
     17 <a href="//skarnet.org/">skarnet.org</a>
     18 </p>
     19 
     20 <h1> The <tt>random</tt> library interface </h1>
     21 
     22 <p>
     23 <tt>librandom</tt> is a small library designed to provide an
     24 interface to some reasonable-quality pseudorandom number
     25 generation. <tt>librandom</tt> uses arc4random when available,
     26 or getrandom - else it defaults to  <tt>/dev/urandom</tt> and a
     27 a SURF PRNG.
     28 </p>
     29 
     30 <h2> Compiling </h2>
     31 
     32 <ul>
     33  <li> Use <tt>#include &lt;skalibs/random.h&gt;</tt> </li>
     34 </ul>
     35 
     36 <h2> Programming </h2>
     37 
     38 <p>
     39  You should refer to the <tt>skalibs/random.h</tt> header for the exact
     40 function prototypes.
     41 </p>
     42 
     43 <h3> Basic functions </h3>
     44 
     45 <pre>
     46   unsigned char c ;
     47   uint32_t max ;
     48   uint32_t n ;
     49   size_t b ;
     50   char data[at least b] ;
     51   int r ;
     52 
     53   r = random_init() ;
     54   c = random_char() ;
     55   n = random_uint32(max) ;
     56   random_string(data, b) ;
     57   random_finish() ;
     58 </pre>    
     59 
     60 <p>
     61  <tt>random_init()</tt> must be called before any other function in
     62 the random library. It returns 0 (and sets errno) on failure, and
     63 nonzero on success.
     64 </p>
     65 
     66 <p>
     67  It is recommended that you let the library perform cleanups after you
     68 are done using it, by calling <tt>random_finish()</tt> - unless your
     69 process exits right away.
     70 </p>
     71 
     72 <ul>
     73   <li> <tt>random_char()</tt> returns a random character. </li>
     74   <li> <tt>random_uint32(<em>max</em>)</tt> returns a random integer
     75 between 0 and <em>max</em>-1. </li>
     76   <li> <tt>random_string(<em>data</em>, <em>b</em>)</tt> fills
     77 <em>b</em> bytes in <em>data</em> (which must be preallocated)
     78 with random data. </li>
     79 </ul>
     80 
     81 <h3> Advanced functions </h3>
     82 
     83 <p>
     84 <code> void random_unsort (char *s, unsigned int n, unsigned int chunksize) </code> <br />
     85 Shuffles the array <em>s</em> (of size at least <em>n</em>*<em>chunksize</em>) by
     86 performing a random permutation of the <em>n</em> blocks of <em>chunksize</em> bytes.
     87 Bytes are not permuted inside chunks.
     88 </p>
     89 
     90 <p>
     91 <code> void random_name (char *s, size_t n) </code> <br />
     92 Writes <em>n</em> random readable ASCII characters into <em>s</em>:
     93 letters, numbers, hyphens or underscores. Does not terminate with a
     94 null character.
     95 </p>
     96 
     97 <p>
     98 <code> int random_sauniquename (stralloc *sa, unsigned int n) </code> <br />
     99 Appends a (non-null-terminated) unique, unpredictable ASCII name to the
    100 <a href="../libstddjb/stralloc.html">stralloc</a> <em>*sa</em>. That
    101 name includes <em>n</em> randomly generated ASCII characters.
    102 </p>
    103 
    104 <h2> Notes </h2>
    105 
    106 <ul>
    107  <li> The <tt>random</tt> library is a thin wrapper around the best
    108 available random generator provided by the underlying system. By
    109 decreasing order of preference, it will use the following
    110 implementations if available:
    111  <ul>
    112   <li> <a href="https://man.openbsd.org/arc4random.3">arc4random()</a> </li>
    113   <li> <a href="https://man7.org/linux/man-pages/man2/getrandom.2.html">getrandom()</a> </li>
    114   <li> <tt>/dev/urandom</tt> </li>
    115   <li> a basic <a href="https://cr.yp.to/papers/surf.pdf">SURF</a> pseudo-random generator</li>
    116  </ul> </li>
    117  <li> The <tt>random_init()</tt> function tries to automatically add some
    118 reasonably random data to the underlying random generator's entropy pool.
    119 However, that pseudorandom data is not 100% unpredictable, so it will not
    120 replace proper seeding of the random generator at boot time. </li>
    121 </ul>
    122 
    123 </body>
    124 </html>