1 files changed, 103 insertions, 0 deletions
diff --git a/man/man3/getentropy.3 b/man/man3/getentropy.3
new file mode 100644
index 000000000..a26a4eff5
--- /dev/null
+++ b/man/man3/getentropy.3
@@ -0,0 +1,103 @@
+.\" Copyright (C) 2017, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH getentropy 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+getentropy \- fill a buffer with random bytes
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.BI "int getentropy(void " buffer [. length "], size_t " length );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR getentropy ():
+.nf
+    _DEFAULT_SOURCE
+.fi
+.SH DESCRIPTION
+The
+.BR getentropy ()
+function writes
+.I length
+bytes of high-quality random data to the buffer starting
+at the location pointed to by
+.IR buffer .
+The maximum permitted value for the
+.I length
+argument is 256.
+.P
+A successful call to
+.BR getentropy ()
+always provides the requested number of bytes of entropy.
+.SH RETURN VALUE
+On success, this function returns zero.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EFAULT
+Part or all of the buffer specified by
+.I buffer
+and
+.I length
+is not in valid addressable memory.
+.TP
+.B EIO
+.I length
+is greater than 256.
+.TP
+.B EIO
+An unspecified error occurred while trying to overwrite
+.I buffer
+with random data.
+.TP
+.B ENOSYS
+This kernel version does not implement the
+.BR getrandom (2)
+system call required to implement this function.
+.SH STANDARDS
+None.
+.SH HISTORY
+glibc 2.25.
+OpenBSD.
+.SH NOTES
+The
+.BR getentropy ()
+function is implemented using
+.BR getrandom (2).
+.P
+Whereas the glibc wrapper makes
+.BR getrandom (2)
+a cancelation point,
+.BR getentropy ()
+is not a cancelation point.
+.P
+.BR getentropy ()
+is also declared in
+.BR <sys/random.h> .
+(No feature test macro need be defined to obtain the declaration from
+that header file.)
+.P
+A call to
+.BR getentropy ()
+may block if the system has just booted and the kernel has
+not yet collected enough randomness to initialize the entropy pool.
+In this case,
+.BR getentropy ()
+will keep blocking even if a signal is handled,
+and will return only once the entropy pool has been initialized.
+.SH SEE ALSO
+.BR getrandom (2),
+.BR urandom (4),
+.BR random (7)