Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 295 insertions, 0 deletions

diff --git a/man/man2/getrandom.2 b/man/man2/getrandom.2
new file mode 100644
index 0000000..fb96cf2
--- /dev/null
+++ b/man/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 2024-05-02 "Linux man-pages (unreleased)"
+.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>
+.P
+.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.
+.P
+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.
+.P
+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 .
+.P
+If the
+.I urandom
+source has not yet been initialized, then
+.BR getrandom ()
+will block, unless
+.B GRND_NONBLOCK
+is specified in
+.IR flags .
+.P
+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.
+.P
+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).
+.P
+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).
+.P
+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.
+.P
+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 ).
+.P
+Using
+.BR getrandom ()
+to read small buffers (<=\ 256 bytes) from the
+.I urandom
+source is the preferred mode of usage.
+.P
+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.
+.P
+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)