1getrandom(2)                  System Calls Manual                 getrandom(2)
2
3
4

NAME

6       getrandom - obtain a series of random bytes
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/random.h>
13
14       ssize_t getrandom(void buf[.buflen], size_t buflen, unsigned int flags);
15

DESCRIPTION

17       The  getrandom() system call fills the buffer pointed to by buf with up
18       to buflen random bytes.  These bytes can be  used  to  seed  user-space
19       random number generators or for cryptographic purposes.
20
21       By  default,  getrandom()  draws entropy from the urandom source (i.e.,
22       the same source as the /dev/urandom  device).   This  behavior  can  be
23       changed via the flags argument.
24
25       If  the  urandom  source has been initialized, reads of up to 256 bytes
26       will always return as many bytes as requested and will  not  be  inter‐
27       rupted  by  signals.  No such guarantees apply for larger buffer sizes.
28       For example, if the call is interrupted by a signal handler, it may re‐
29       turn a partially filled buffer, or fail with the error EINTR.
30
31       If  the  urandom  source has not yet been initialized, then getrandom()
32       will block, unless GRND_NONBLOCK is specified in flags.
33
34       The flags argument is a bit mask that can contain zero or more  of  the
35       following values ORed together:
36
37       GRND_RANDOM
38              If  this bit is set, then random bytes are drawn from the random
39              source (i.e., the same source as the /dev/random device) instead
40              of  the  urandom  source.  The random source is limited based on
41              the entropy that can be obtained from environmental  noise.   If
42              the  number of available bytes in the random source is less than
43              requested in buflen, the call returns just the available  random
44              bytes.   If  no random bytes are available, the behavior depends
45              on the presence of GRND_NONBLOCK in the flags argument.
46
47       GRND_NONBLOCK
48              By default, when reading from  the  random  source,  getrandom()
49              blocks  if  no random bytes are available, and when reading from
50              the urandom source, it blocks if the entropy pool  has  not  yet
51              been  initialized.   If  the GRND_NONBLOCK flag is set, then ge‐
52              trandom() does not block in these cases, but instead immediately
53              returns -1 with errno set to EAGAIN.
54

RETURN VALUE

56       On success, getrandom() returns the number of bytes that were copied to
57       the buffer buf.  This may be less than the number  of  bytes  requested
58       via  buflen  if  either GRND_RANDOM was specified in flags and insuffi‐
59       cient entropy was present in the random source or the system  call  was
60       interrupted by a signal.
61
62       On error, -1 is returned, and errno is set to indicate the error.
63

ERRORS

65       EAGAIN The  requested  entropy was not available, and getrandom() would
66              have blocked if the GRND_NONBLOCK flag was not set.
67
68       EFAULT The address referred to by buf is outside the accessible address
69              space.
70
71       EINTR  The  call  was interrupted by a signal handler; see the descrip‐
72              tion of how interrupted read(2) calls on "slow" devices are han‐
73              dled  with  and without the SA_RESTART flag in the signal(7) man
74              page.
75
76       EINVAL An invalid flag was specified in flags.
77
78       ENOSYS The glibc wrapper function for getrandom() determined  that  the
79              underlying kernel does not implement this system call.
80

STANDARDS

82       Linux.
83

HISTORY

85       Linux 3.17, glibc 2.25.
86

NOTES

88       For  an  overview  and comparison of the various interfaces that can be
89       used to obtain randomness, see random(7).
90
91       Unlike /dev/random and /dev/urandom, getrandom() does not  involve  the
92       use  of pathnames or file descriptors.  Thus, getrandom() can be useful
93       in cases where chroot(2) makes /dev pathnames invisible, and  where  an
94       application  (e.g.,  a daemon during start-up) closes a file descriptor
95       for one of these files that was opened by a library.
96
97   Maximum number of bytes returned
98       As of Linux 3.19 the following limits apply:
99
100       •  When reading from the urandom source, a maximum of 32Mi-1  bytes  is
101          returned  by a single call to getrandom() on systems where int has a
102          size of 32 bits.
103
104       •  When reading from the random source, a maximum of 512 bytes  is  re‐
105          turned.
106
107   Interruption by a signal handler
108       When  reading from the urandom source (GRND_RANDOM is not set), getran‐
109       dom() will block until the entropy pool has  been  initialized  (unless
110       the  GRND_NONBLOCK flag was specified).  If a request is made to read a
111       large number of bytes (more than 256),  getrandom()  will  block  until
112       those  bytes  have been generated and transferred from kernel memory to
113       buf.  When reading from the random source (GRND_RANDOM is set), getran‐
114       dom()  will  block until some random bytes become available (unless the
115       GRND_NONBLOCK flag was specified).
116
117       The behavior when a call to getrandom() that is blocked  while  reading
118       from  the  urandom source is interrupted by a signal handler depends on
119       the initialization state of the entropy buffer and on the request size,
120       buflen.   If  the  entropy  is not yet initialized, then the call fails
121       with the EINTR error.  If the entropy pool has been initialized and the
122       request size is large (buflen > 256), the call either succeeds, return‐
123       ing a partially filled buffer, or fails with the error EINTR.   If  the
124       entropy  pool  has  been initialized and the request size is small (bu‐
125       flen <= 256), then getrandom() will not fail with EINTR.   Instead,  it
126       will return all of the bytes that have been requested.
127
128       When  reading from the random source, blocking requests of any size can
129       be interrupted by a signal handler  (the  call  fails  with  the  error
130       EINTR).
131
132       Using getrandom() to read small buffers (<= 256 bytes) from the urandom
133       source is the preferred mode of usage.
134
135       The special treatment of small values of buflen was designed  for  com‐
136       patibility with OpenBSD's getentropy(3), which is nowadays supported by
137       glibc.
138
139       The user of getrandom() must always check the return value,  to  deter‐
140       mine  whether  either  an  error occurred or fewer bytes than requested
141       were returned.  In the case where GRND_RANDOM is not specified and  bu‐
142       flen  is  less  than  or equal to 256, a return of fewer bytes than re‐
143       quested should never happen, but the careful programmer will check  for
144       this anyway!
145

BUGS

147       As of Linux 3.19, the following bug exists:
148
149       •  Depending  on CPU load, getrandom() does not react to interrupts be‐
150          fore reading all bytes requested.
151

SEE ALSO

153       getentropy(3), random(4), urandom(4), random(7), signal(7)
154
155
156
157Linux man-pages 6.04              2023-03-30                      getrandom(2)
Impressum