man3/arc4random.3

   1 '\" t
   2 .\" Copyright (C) 2023 Alejandro Colomar <alx@kernel.org>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH arc4random 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 arc4random, arc4random_uniform, arc4random_buf
   9 \- cryptographically-secure pseudorandom number generator
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <stdlib.h>
  16 .P
  17 .B uint32_t arc4random(void);
  18 .BI "uint32_t arc4random_uniform(uint32_t " upper_bound );
  19 .BI "void arc4random_buf(void " buf [. n "], size_t " n );
  20 .fi
  21 .SH DESCRIPTION
  22 These functions give cryptographically-secure pseudorandom numbers.
  23 .P
  24 .BR arc4random ()
  25 returns a uniformly-distributed value.
  26 .P
  27 .BR arc4random_uniform ()
  28 returns a uniformly-distributed value less than
  29 .I upper_bound
  30 (see BUGS).
  31 .P
  32 .BR arc4random_buf ()
  33 fills the memory pointed to by
  34 .IR buf ,
  35 with
  36 .I n
  37 bytes of pseudorandom data.
  38 .P
  39 The
  40 .BR rand (3)
  41 and
  42 .BR drand48 (3)
  43 families of functions should only be used where
  44 the quality of the pseudorandom numbers is not a concern
  45 .I and
  46 there's a need for repeatability of the results.
  47 Unless you meet both of those conditions,
  48 use the
  49 .BR arc4random ()
  50 functions.
  51 .SH RETURN VALUE
  52 .BR arc4random ()
  53 returns a pseudorandom number.
  54 .P
  55 .BR arc4random_uniform ()
  56 returns a pseudorandom number less than
  57 .I upper_bound
  58 for valid input, or
  59 .B 0
  60 when
  61 .I upper_bound
  62 is invalid.
  63 .SH ATTRIBUTES
  64 For an explanation of the terms used in this section, see
  65 .BR attributes (7).
  66 .TS
  67 allbox;
  68 lbx lb lb
  69 l l l.
  70 Interface       Attribute       Value
  71 T{
  72 .na
  73 .nh
  74 .BR arc4random (),
  75 .BR arc4random_uniform (),
  76 .BR arc4random_buf ()
  77 T}      Thread safety   MT-Safe
  78 .TE
  79 .SH STANDARDS
  80 BSD.
  81 .SH HISTORY
  82 OpenBSD 2.1,
  83 FreeBSD 3.0,
  84 NetBSD 1.6,
  85 DragonFly 1.0,
  86 libbsd,
  87 glibc 2.36.
  88 .SH BUGS
  89 An
  90 .I upper_bound
  91 of
  92 .B 0
  93 doesn't make sense in a call to
  94 .BR arc4random_uniform ().
  95 Such a call will fail, and return
  96 .BR 0 .
  97 Be careful,
  98 since that value is
  99 .I not
 100 less than
 101 .IR upper_bound .
 102 In some cases,
 103 such as accessing an array,
 104 using that value could result in Undefined Behavior.
 105 .SH SEE ALSO
 106 .BR getrandom (3),
 107 .BR rand (3),
 108 .BR drand48 (3),
 109 .BR random (7)