1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2018 Joyent, Inc.
  13 .\"
  14 .Dd "November 6, 2018"
  15 .Dt GETRANDOM 2
  16 .Os
  17 .Sh NAME
  18 .Nm getrandom
  19 .Nd get random numbers
  20 .Sh LIBRARY
  21 .Lb libc
  22 .Sh SYNOPSIS
  23 .In sys/random.h
  24 .Ft ssize_t
  25 .Fo getrandom
  26 .Fa "void *bufp"
  27 .Fa "size_t buflen"
  28 .Fa "unsigned int flags"
  29 .Fc
  30 .Sh DESCRIPTION
  31 The
  32 .Fn getrandom
  33 function is used to retrieve random and pseudo-random numbers from the
  34 operating system.
  35 .Pp
  36 By default, the
  37 .Fn getrandom
  38 function will read up to
  39 .Fa buflen
  40 bytes of pseudo-random data into
  41 .Fa bufp .
  42 Pseudo-random data will be retrieved from the same source that provides
  43 data to
  44 .Pa /dev/urandom .
  45 The
  46 .Fn getrandom
  47 function may return less data than was requested in
  48 .Fa buflen .
  49 This can happen because of interrupts from signals, availability of
  50 data, or because the request was too large.
  51 Callers must always check to see how much data was actually returned.
  52 .Pp
  53 The following values may be bitwise-ORed together in the
  54 .Fa flags
  55 argument to modify the behavior of the function:
  56 .Bl -tag -width Dv
  57 .It Dv GRND_NONBLOCK
  58 Instead of blocking, return immediately if data is not available.
  59 If no data was obtained,
  60 .Er EAGAIN
  61 will be set in
  62 .Va errno .
  63 Otherwise, less data will be returned than requested.
  64 .It Dv GRND_RANDOM
  65 Use the same source of random data as reading from
  66 .Pa /dev/random ,
  67 instead of
  68 .Pa /dev/urandom .
  69 .El
  70 .Pp
  71 The
  72 .Fn getrandom
  73 function is intended to eliminate the need to explicitly call
  74 .Xr open 2
  75 and
  76 .Xr read 2
  77 on
  78 .Pa /dev/random
  79 or
  80 .Pa /dev/urandom .
  81 This eliminates the need to have the character devices available or
  82 cases where a program may not have an available file descriptor.
  83 For other uses,
  84 .Xr arc4random 3C
  85 may be a better interface.
  86 .Sh RETURN VALUES
  87 Upon successful completion, the
  88 .Fn getrandom
  89 function returns the number of bytes written into
  90 .Fa bufp .
  91 Otherwise,
  92 .Sy -1
  93 is returned and
  94 .Va errno
  95 is set to indicate the error.
  96 .Sh ERRORS
  97 The
  98 .Fn getrandom
  99 function will fail if:
 100 .Bl -tag -width Er
 101 .It Er EAGAIN
 102 The
 103 .Fn getrandom
 104 function would have blocked and
 105 .Dv GRND_NONBLOCK
 106 flag was set.
 107 .It Er EFAULT
 108 The
 109 .Fa bufp
 110 argument points to an illegal address.
 111 .It Er EINAVL
 112 An invalid value was passed in
 113 .Fa flags .
 114 .It Er EINTR
 115 A signal was caught during the operation and no data was transferred.
 116 .It Er EIO
 117 An internal error occurred with the corresponding
 118 .Xr random 7D
 119 device.
 120 .El
 121 .Sh INTERFACE STABILITY
 122 .Sy Committed
 123 .Sh MT-LEVEL
 124 .Sy MT-Safe
 125 .Sh SEE ALSO
 126 .Xr open 2 ,
 127 .Xr read 2 ,
 128 .Xr arc4random 3C ,
 129 .Xr random 7D
 130 .Sh STANDARDS
 131 .Fn getrandom
 132 is non-standard.
 133 It originally appeared in Linux.