man3/getentropy.3

   1 .\" Copyright (C) 2017, Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of
   9 .\" this manual under the conditions for verbatim copying, provided that
  10 .\" the entire resulting derived work is distributed under the terms of
  11 .\" a permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume.
  15 .\" no responsibility for errors or omissions, or for damages resulting.
  16 .\" from the use of the information contained herein.  The author(s) may.
  17 .\" not have taken the same level of care in the production of this.
  18 .\" manual, which is licensed free of charge, as they might when working.
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH GETENTROPY 3 2017-09-15 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 getentropy \- fill a buffer with random bytes
  28 .SH SYNOPSIS
  29 .B #include <unistd.h>
  30 .PP
  31 .BI "int getentropy(void *" buffer ", size_t " length );
  32 .PP
  33 .in -4n
  34 Feature Test Macro Requirements for glibc (see
  35 .BR feature_test_macros (7)):
  36 .in
  37 .PP
  38 .BR getentropy ():
  39 .br
  40 .RS 4
  41 .ad l
  42 _DEFAULT_SOURCE
  43 .RE
  44 .ad
  45 .SH DESCRIPTION
  46 The
  47 .BR getentropy ()
  48 function writes
  49 .I length
  50 bytes of high-quality random data to the buffer starting
  51 at the location pointed to by
  52 .IR buffer .
  53 The maximum permitted value for the
  54 .I length
  55 argument is 256.
  56 .PP
  57 A successful call to
  58 .BR getentropy ()
  59 always provides the requested number of bytes of entropy.
  60 .SH RETURN VALUE
  61 On success, this function returns zero.
  62 On error, \-1 is returned, and
  63 .I errno
  64 is set appropriately.
  65 .SH ERRORS
  66 .TP
  67 .B EFAULT
  68 Part or all of the buffer specified by
  69 .I buffer
  70 and
  71 .I length
  72 is not in valid addressable memory.
  73 .TP
  74 .B EIO
  75 .I length
  76 is greater than 256.
  77 .TP
  78 .B EIO
  79 An unspecified error occurred while trying to overwrite
  80 .I buffer
  81 with random data.
  82 .TP
  83 .B ENOSYS
  84 This kernel version does not implement the
  85 .BR getrandom (2)
  86 system call required to implement this function.
  87 .SH VERSIONS
  88 The
  89 .BR getentropy ()
  90 function first appeared in glibc 2.25.
  91 .SH CONFORMING TO
  92 This function is nonstandard.
  93 It is also present on OpenBSD.
  94 .SH NOTES
  95 The
  96 .BR getentropy ()
  97 function is implemented using
  98 .BR getrandom (2).
  99 .PP
 100 Whereas the glibc wrapper makes
 101 .BR getrandom (2)
 102 a cancellation point,
 103 .BR getentropy ()
 104 is not a cancellation point.
 105 .PP
 106 .BR getentropy ()
 107 is also declared in
 108 .BR <sys/random.h> .
 109 (No feature test macro need be defined to obtain the declaration from
 110 that header file.)
 111 .PP
 112 A call to
 113 .BR getentropy ()
 114 may block if the system has just booted and the kernel has
 115 not yet collected enough randomness to initialize the entropy pool.
 116 In this case,
 117 .BR getentropy ()
 118 will keep blocking even if a signal is handled,
 119 and will return only once the entropy pool has been initialized.
 120 .SH SEE ALSO
 121 .BR getrandom (2),
 122 .BR urandom (4),
 123 .BR random (7)