+++ /dev/null
-.\" Copyright (C) 2014, Theodore Ts'o <tytso@mit.edu>
-.\" Copyright (C) 2014, Heinrich Schuchardt <xypron.glpk@gmx.de>
-.\"
-.\" %%%LICENSE_START(VERBATIM)
-.\" Permission is granted to make and distribute verbatim copies of this
-.\" manual provided the copyright notice and this permission notice are
-.\" preserved on all copies.
-.\"
-.\" Permission is granted to copy and distribute modified versions of
-.\" this manual under the conditions for verbatim copying, provided that
-.\" the entire resulting derived work is distributed under the terms of
-.\" a permission notice identical to this one.
-.\"
-.\" Since the Linux kernel and libraries are constantly changing, this
-.\" manual page may be incorrect or out-of-date. The author(s) assume.
-.\" no responsibility for errors or omissions, or for damages resulting.
-.\" from the use of the information contained herein. The author(s) may.
-.\" not have taken the same level of care in the production of this.
-.\" manual, which is licensed free of charge, as they might when working.
-.\" professionally.
-.\"
-.\" Formatted or processed versions of this manual, if unaccompanied by
-.\" the source, must acknowledge the copyright and authors of this work.
-.\" %%%LICENSE_END
-
-.TH GETRANDOM 2 2015-01-22 "Linux" "Linux Programmer's Manual"
-.SH NAME
-getrandom \- obtain a series of random bytes
-.SH SYNOPSIS
-.B #include <linux/random.h>
-.sp
-.BI "int getrandom(void *"buf ", size_t " buflen ", unsigned int " flags );
-.SH DESCRIPTION
-The
-.BR getrandom ()
-system call fills the buffer pointed to by
-.I buf
-with up to
-.I buflen
-random bytes.
-These can be used to seed user-space random number generators
-or for cryptographic purposes.
-.PP
-.BR getrandom ()
-relies on entropy gathered from device drivers and other sources of
-environmental noise.
-Unnecessarily reading large quantities of data will have a negative impact
-on other users of the
-.I /dev/random
-and
-.I /dev/urandom
-devices.
-Therefore
-.BR getrandom ()
-should not be used for Monte Carlo simulations or other
-programs/algorithms which are doing probabilistic sampling.
-
-By default,
-.BR getrandom ()
-draws entropy from the
-.IR /dev/urandom
-pool.
-This behavior can be changed via the
-.I flags
-argument.
-If the
-.IR /dev/urandom
-pool has been initialized, reading from that pool never blocks.
-If the pool has not yet been initialized, then the call blocks, unless
-.B GRND_RANDOM
-is specified in
-.IR flags .
-.\" FIXME We need a bit more information here.
-.\" The reader will ask: when is /dev/urandom initialized?
-.\" There should be some text here to explain that.
-
-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 /dev/random
-pool instead of the
-.I /dev/urandom
-pool.
-The
-.I /dev/random
-pool is limited based on the entropy that can be obtained from environmental
-noise.
-If the number of available bytes in
-.I /dev/random
-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, if there are no random bytes available at all (when reading from
-.IR /dev/random ),
-or the entropy pool has not yet been initialized (when reading from
-.IR /dev/urandom ),
-.BR getrandom ()
-blocks until data is available.
-If the
-.B GRND_NONBLOCK
-flag is set, then
-.BR getrandom ()
-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
-.BR GRND_RANDOM
-was specified in
-.IR flags
-and insufficient entropy was present in the
-.IR /dev/random
-pool, or if the system call was interrupted by a signal.
-.PP
-On error, \-1 is returned, and
-.I errno
-is set appropriately.
-.SH ERRORS
-.TP
-.B EINVAL
-An invalid flag was specified in
-.IR flags .
-.TP
-.B EFAULT
-The address referred to by
-.I buf
-is outside the accessible address space.
-.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 EINTR
-While blocked waiting for entropy, 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.
-.SH VERSIONS
-.BR getrandom ()
-was introduced in version 3.17 of the Linux kernel.
-.SH CONFORMING TO
-This system call is Linux-specific.
-.SH NOTES
-.SS Interruption by a signal handler
-A call to
-.BR getrandom ()
-can block only when called without the
-.B GRND_NONBLOCK
-flag.
-When reading from
-.I /dev/urandom
-.RB ( GRND_RANDOM
-is not set),
-blocking occurs only if the entropy pool has not been initialized yet.
-When reading from
-.I /dev/random
-.RB ( GRND_RANDOM
-is set),
-blocking occurs if not enough random bytes are available.
-
-The behavior when a call to
-.BR getrandom ()
-that is blocked while reading from
-.I /dev/urandom
-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 will fail 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
-.IR /dev/random ,
-these guarantees do
-.I not
-apply.
-.PP
-Calling
-.BR getrandom ()
-to read
-.I /dev/urandom
-for small values (<=\ 256) of
-.I buflen
-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 ()
-system call.
-.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!
-.SS Choice of random device
-Unless you are doing long-term key generation (and perhaps not even
-then), you probably shouldn't be using
-.B GRND_RANDOM.
-The cryptographic algorithms used for
-.I /dev/urandom
-are quite conservative, and so should be sufficient for all purposes.
-The disadvantage of
-.B GRND_RANDOM
-is that it can block.
-Furthermore, dealing with the partially fulfilled
-.BR getrandom ()
-requests that can occur when using
-.B GRND_RANDOM
-increases code complexity.
-.SS Emulating OpenBSD's getentropy()
-The
-.BR getentropy ()
-system call in OpenBSD can be emulated using the following
-function:
-
-.in +4n
-.nf
-int
-getentropy(void *buf, size_t buflen)
-{
- int ret;
-
- if (buflen > 256)
- goto failure;
- ret = getrandom(buf, buflen, 0);
- if (ret < 0)
- return ret;
- if (ret == buflen)
- return 0;
-failure:
- errno = EIO;
- return \-1;
-}
-.fi
-.in
-.SH BUGS
-As of Linux 3.19, the following bug exists:
-.\" FIXME patch proposed https://lkml.org/lkml/2014/11/29/16
-.IP * 3
-Depending on CPU load,
-.BR getrandom ()
-does not react to interrupts before reading all bytes requested.
-.SH SEE ALSO
-.BR random (4),
-.BR urandom (4)
projects / thirdparty / man-pages.git / blobdiff