diff options
Diffstat (limited to '')
| -rw-r--r-- | man2/getrandom.2 | 295 |
1 files changed, 295 insertions, 0 deletions
diff --git a/man2/getrandom.2 b/man2/getrandom.2 new file mode 100644 index 0000000..565763b --- /dev/null +++ b/man2/getrandom.2 @@ -0,0 +1,295 @@ +.\" Copyright (C) 2014, Theodore Ts'o <tytso@mit.edu> +.\" Copyright (C) 2014,2015 Heinrich Schuchardt <xypron.glpk@gmx.de> +.\" Copyright (C) 2015, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getrandom 2 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +getrandom \- obtain a series of random bytes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/random.h> +.PP +.BI "ssize_t getrandom(void " buf [. buflen "], size_t " buflen ", \ +unsigned int " flags ); +.fi +.SH DESCRIPTION +The +.BR getrandom () +system call fills the buffer pointed to by +.I buf +with up to +.I buflen +random bytes. +These bytes can be used to seed user-space random number generators +or for cryptographic purposes. +.PP +By default, +.BR getrandom () +draws entropy from the +.I urandom +source (i.e., the same source as the +.I /dev/urandom +device). +This behavior can be changed via the +.I flags +argument. +.PP +If the +.I urandom +source has been initialized, +reads of up to 256 bytes will always return as many bytes as +requested and will not be interrupted by signals. +No such guarantees apply for larger buffer sizes. +For example, if the call is interrupted by a signal handler, +it may return a partially filled buffer, or fail with the error +.BR EINTR . +.PP +If the +.I urandom +source has not yet been initialized, then +.BR getrandom () +will block, unless +.B GRND_NONBLOCK +is specified in +.IR flags . +.PP +The +.I flags +argument is a bit mask that can contain zero or more of the following values +ORed together: +.TP +.B GRND_RANDOM +If this bit is set, then random bytes are drawn from the +.I random +source +(i.e., the same source as the +.I /dev/random +device) +instead of the +.I urandom +source. +The +.I random +source is limited based on the entropy that can be obtained from environmental +noise. +If the number of available bytes in the +.I random +source is less than requested in +.IR buflen , +the call returns just the available random bytes. +If no random bytes are available, the behavior depends on the presence of +.B GRND_NONBLOCK +in the +.I flags +argument. +.TP +.B GRND_NONBLOCK +By default, when reading from the +.I random +source, +.BR getrandom () +blocks if no random bytes are available, +and when reading from the +.I urandom +source, it blocks if the entropy pool has not yet been initialized. +If the +.B GRND_NONBLOCK +flag is set, then +.BR getrandom () +does not block in these cases, but instead immediately returns \-1 with +.I errno +set to +.BR EAGAIN . +.SH RETURN VALUE +On success, +.BR getrandom () +returns the number of bytes that were copied to the buffer +.IR buf . +This may be less than the number of bytes requested via +.I buflen +if either +.B GRND_RANDOM +was specified in +.I flags +and insufficient entropy was present in the +.I random +source or the system call was interrupted by a signal. +.PP +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The requested entropy was not available, and +.BR getrandom () +would have blocked if the +.B GRND_NONBLOCK +flag was not set. +.TP +.B EFAULT +The address referred to by +.I buf +is outside the accessible address space. +.TP +.B EINTR +The call was interrupted by a signal +handler; see the description of how interrupted +.BR read (2) +calls on "slow" devices are handled with and without the +.B SA_RESTART +flag in the +.BR signal (7) +man page. +.TP +.B EINVAL +An invalid flag was specified in +.IR flags . +.TP +.B ENOSYS +The glibc wrapper function for +.BR getrandom () +determined that the underlying kernel does not implement this system call. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 3.17, +glibc 2.25. +.SH NOTES +For an overview and comparison of the various interfaces that +can be used to obtain randomness, see +.BR random (7). +.PP +Unlike +.I /dev/random +and +.IR /dev/urandom , +.BR getrandom () +does not involve the use of pathnames or file descriptors. +Thus, +.BR getrandom () +can be useful in cases where +.BR chroot (2) +makes +.I /dev +pathnames invisible, +and where an application (e.g., a daemon during start-up) +closes a file descriptor for one of these files +that was opened by a library. +.\" +.SS Maximum number of bytes returned +As of Linux 3.19 the following limits apply: +.IP \[bu] 3 +When reading from the +.I urandom +source, a maximum of 32Mi-1 bytes is returned by a single call to +.BR getrandom () +on systems where +.I int +has a size of 32 bits. +.IP \[bu] +When reading from the +.I random +source, a maximum of 512 bytes is returned. +.SS Interruption by a signal handler +When reading from the +.I urandom +source +.RB ( GRND_RANDOM +is not set), +.BR getrandom () +will block until the entropy pool has been initialized +(unless the +.B GRND_NONBLOCK +flag was specified). +If a request is made to read a large number of bytes (more than 256), +.BR getrandom () +will block until those bytes have been generated and transferred +from kernel memory to +.IR buf . +When reading from the +.I random +source +.RB ( GRND_RANDOM +is set), +.BR getrandom () +will block until some random bytes become available +(unless the +.B GRND_NONBLOCK +flag was specified). +.PP +The behavior when a call to +.BR getrandom () +that is blocked while reading from the +.I urandom +source is interrupted by a signal handler +depends on the initialization state of the entropy buffer +and on the request size, +.IR buflen . +If the entropy is not yet initialized, then the call fails with the +.B EINTR +error. +If the entropy pool has been initialized +and the request size is large +.RI ( buflen "\ >\ 256)," +the call either succeeds, returning a partially filled buffer, +or fails with the error +.BR EINTR . +If the entropy pool has been initialized and the request size is small +.RI ( buflen "\ <=\ 256)," +then +.BR getrandom () +will not fail with +.BR EINTR . +Instead, it will return all of the bytes that have been requested. +.PP +When reading from the +.I random +source, blocking requests of any size can be interrupted by a signal handler +(the call fails with the error +.BR EINTR ). +.PP +Using +.BR getrandom () +to read small buffers (<=\ 256 bytes) from the +.I urandom +source is the preferred mode of usage. +.PP +The special treatment of small values of +.I buflen +was designed for compatibility with +OpenBSD's +.BR getentropy (3), +which is nowadays supported by glibc. +.PP +The user of +.BR getrandom () +.I must +always check the return value, +to determine whether either an error occurred +or fewer bytes than requested were returned. +In the case where +.B GRND_RANDOM +is not specified and +.I buflen +is less than or equal to 256, +a return of fewer bytes than requested should never happen, +but the careful programmer will check for this anyway! +.SH BUGS +As of Linux 3.19, the following bug exists: +.\" FIXME patch proposed https://lkml.org/lkml/2014/11/29/16 +.IP \[bu] 3 +Depending on CPU load, +.BR getrandom () +does not react to interrupts before reading all bytes requested. +.SH SEE ALSO +.BR getentropy (3), +.BR random (4), +.BR urandom (4), +.BR random (7), +.BR signal (7) |