Debian Codegraph @

upstream/debian-unstable/man3/arc4random.3

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