--- /dev/null
+.\" Copyright (C) 2014, Theodore Ts'o <tytso@mit.edu>
+.\" Copyright (C) 2014,2015 Heinrich Schuchardt <xypron.glpk@gmx.de>
+.\" Copyright (C) 2015, Michael Kerrisk <tmk.manpages@gmail.com>
+.\"
+.\" %%%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 bytes 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,
+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 .
+If the pool has not yet been initialized, then the call blocks, unless
+.B GRND_RANDOM
+is specified in
+.IR flags .
+
+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, when reading from
+.IR /dev/random ,
+.BR getrandom ()
+blocks if no random bytes are available,
+and when reading from
+.IR /dev/urandom ,
+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
+.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
+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 Maximum number of bytes returned
+As of Linux 3.19 the following limits apply:
+.IP * 3
+When reading from
+.IR /dev/urandom ,
+a maximum of 33554431 bytes is returned by a single call to
+.BR getrandom ()
+on a system where
+.I int
+has a size of 32 bits.
+.IP *
+When reading from
+.IR /dev/random ,
+a maximum of 512 bytes is returned.
+.SS Initialization of the entropy pool
+The kernel collects bits of entropy from environment.
+When a sufficient number of random bits has been collected, the
+.I /dev/urandom
+entropy pool is considered to be initialized.
+This state is normally reached early in the system bootstrap phase.
+.SS Interruption by a signal handler
+When reading from
+.I /dev/urandom
+.RB ( GRND_RANDOM
+is not set),
+.BR getrandom ()
+will block until the entropy pool has been initialized
+(unless the
+.BR GRND_NONBLOCK
+flag was specified).
+If a request is made to read a large number (more than 256) of bytes,
+.BR getrandom ()
+will block until those bytes have been generated and transferred
+from kernel memory to
+.IR buf .
+When reading from
+.I /dev/random
+.RB ( GRND_RANDOM
+is set),
+.BR getrandom ()
+will block until some random bytes become available
+(unless the
+.BR GRND_NONBLOCK
+flag was specified).
+
+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.
+
+When reading from
+.IR /dev/random ,
+blocking requests of any size can be interrupted by a signal
+(the call fails with the error
+.BR EINTR ).
+
+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),
+.BR signal (7)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
