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 2021-03-22 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 getentropy \- fill a buffer with random bytes
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <unistd.h>
  31 .PP
  32 .BI "int getentropy(void *" buffer ", size_t " length );
  33 .fi
  34 .PP
  35 .RS -4
  36 Feature Test Macro Requirements for glibc (see
  37 .BR feature_test_macros (7)):
  38 .RE
  39 .PP
  40 .BR getentropy ():
  41 .nf
  42     _DEFAULT_SOURCE
  43 .fi
  44 .SH DESCRIPTION
  45 The
  46 .BR getentropy ()
  47 function writes
  48 .I length
  49 bytes of high-quality random data to the buffer starting
  50 at the location pointed to by
  51 .IR buffer .
  52 The maximum permitted value for the
  53 .I length
  54 argument is 256.
  55 .PP
  56 A successful call to
  57 .BR getentropy ()
  58 always provides the requested number of bytes of entropy.
  59 .SH RETURN VALUE
  60 On success, this function returns zero.
  61 On error, \-1 is returned, and
  62 .I errno
  63 is set to indicate the error.
  64 .SH ERRORS
  65 .TP
  66 .B EFAULT
  67 Part or all of the buffer specified by
  68 .I buffer
  69 and
  70 .I length
  71 is not in valid addressable memory.
  72 .TP
  73 .B EIO
  74 .I length
  75 is greater than 256.
  76 .TP
  77 .B EIO
  78 An unspecified error occurred while trying to overwrite
  79 .I buffer
  80 with random data.
  81 .TP
  82 .B ENOSYS
  83 This kernel version does not implement the
  84 .BR getrandom (2)
  85 system call required to implement this function.
  86 .SH VERSIONS
  87 The
  88 .BR getentropy ()
  89 function first appeared in glibc 2.25.
  90 .SH CONFORMING TO
  91 This function is nonstandard.
  92 It is also present on OpenBSD.
  93 .SH NOTES
  94 The
  95 .BR getentropy ()
  96 function is implemented using
  97 .BR getrandom (2).
  98 .PP
  99 Whereas the glibc wrapper makes
 100 .BR getrandom (2)
 101 a cancellation point,
 102 .BR getentropy ()
 103 is not a cancellation point.
 104 .PP
 105 .BR getentropy ()
 106 is also declared in
 107 .BR <sys/random.h> .
 108 (No feature test macro need be defined to obtain the declaration from
 109 that header file.)
 110 .PP
 111 A call to
 112 .BR getentropy ()
 113 may block if the system has just booted and the kernel has
 114 not yet collected enough randomness to initialize the entropy pool.
 115 In this case,
 116 .BR getentropy ()
 117 will keep blocking even if a signal is handled,
 118 and will return only once the entropy pool has been initialized.
 119 .SH SEE ALSO
 120 .BR getrandom (2),
 121 .BR urandom (4),
 122 .BR random (7)