1 GETRANDOM(2)                     System Calls                     GETRANDOM(2)
   2 
   3 NAME
   4      getrandom - get random numbers
   5 
   6 LIBRARY
   7      Standard C Library (libc, -lc)
   8 
   9 SYNOPSIS
  10      #include <sys/random.h>
  11 
  12      ssize_t
  13      getrandom(void *bufp, size_t buflen, unsigned int flags);
  14 
  15 DESCRIPTION
  16      The getrandom() function is used to retrieve random and pseudo-random
  17      numbers from the operating system.
  18 
  19      By default, the getrandom() function will read up to buflen bytes of
  20      pseudo-random data into bufp.  Pseudo-random data will be retrieved from
  21      the same source that provides data to /dev/urandom.  The getrandom()
  22      function may return less data than was requested in buflen.  This can
  23      happen because of interrupts from signals, availability of data, or
  24      because the request was too large.  Callers must always check to see how
  25      much data was actually returned.
  26 
  27      The following values may be bitwise-ORed together in the flags argument
  28      to modify the behavior of the function:
  29 
  30      GRND_NONBLOCK
  31                    Instead of blocking, return immediately if data is not
  32                    available.  If no data was obtained, EAGAIN will be set in
  33                    errno.  Otherwise, less data will be returned than
  34                    requested.
  35 
  36      GRND_RANDOM   Use the same source of random data as reading from
  37                    /dev/random, instead of /dev/urandom.
  38 
  39      The getrandom() function is intended to eliminate the need to explicitly
  40      call open(2) and read(2) on /dev/random or /dev/urandom.  This eliminates
  41      the need to have the character devices available or cases where a program
  42      may not have an available file descriptor.  For other uses,
  43      arc4random(3C) may be a better interface.
  44 
  45 RETURN VALUES
  46      Upon successful completion, the getrandom() function returns the number
  47      of bytes written into bufp.  Otherwise, -1 is returned and errno is set
  48      to indicate the error.
  49 
  50 ERRORS
  51      The getrandom() function will fail if:
  52 
  53      EAGAIN             The getrandom() function would have blocked and
  54                         GRND_NONBLOCK flag was set.
  55 
  56      EFAULT             The bufp argument points to an illegal address.
  57 
  58      EINAVL             An invalid value was passed in flags.
  59 
  60      EINTR              A signal was caught during the operation and no data
  61                         was transferred.
  62 
  63      EIO                An internal error occurred with the corresponding
  64                         random(7D) device.
  65 
  66 INTERFACE STABILITY
  67      Committed
  68 
  69 MT-LEVEL
  70      MT-Safe
  71 
  72 SEE ALSO
  73      open(2), read(2), arc4random(3C), random(7D)
  74 
  75 STANDARDS
  76      getrandom() is non-standard.  It originally appeared in Linux.
  77 
  78 illumos                        November 6, 2018                        illumos