lib/libc/sys/getrandom.2

   1 .\" Copyright (c) 2018 Conrad Meyer <cem@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd February 24, 2018
  28 .Dt GETRANDOM 2
  29 .Os
  30 .Sh NAME
  31 .Nm getrandom
  32 .Nd get random data
  33 .Sh LIBRARY
  34 .Lb libc
  35 .Sh SYNOPSIS
  36 .In sys/random.h
  37 .Ft ssize_t
  38 .Fn getrandom "void *buf" "size_t buflen" "unsigned int flags"
  39 .Sh DESCRIPTION
  40 .Fn getrandom
  41 fills
  42 .Fa buf
  43 with up to
  44 .Fa buflen
  45 bytes of random data.
  46 .Pp
  47 The
  48 .Fa flags
  49 argument may include zero or more of the following:
  50 .Bl -tag -width _GRND_NONBLOCK_
  51 .It Ql GRND_NONBLOCK
  52 Return
  53 .Er EAGAIN
  54 instead of blocking, if the
  55 .Xr random 4
  56 device has not yet been seeded.
  57 By default,
  58 .Fn getrandom
  59 will block until the device is seeded.
  60 .It Ql GRND_RANDOM
  61 This flag does nothing on
  62 .Fx .
  63 .Pa /dev/random
  64 and
  65 .Pa /dev/urandom
  66 are identical.
  67 .El
  68 .Pp
  69 If the
  70 .Xr random 4
  71 device has been seeded, reads of up to 256 bytes will always return as many
  72 bytes as requested and will not be interrupted by signals.
  73 .Pp
  74 .Sh RETURN VALUES
  75 Upon successful completion, the number of bytes which were actually read is
  76 returned.
  77 For requests larger than 256 bytes, this can be fewer bytes than were
  78 requested.
  79 Otherwise, -1 is returned and the global variable
  80 .Va errno
  81 is set to indicate the error.
  82 .Sh ERRORS
  83 The
  84 .Fn getrandom
  85 operation returns the following errors:
  86 .Bl -tag -width Er
  87 .It Bq Er EAGAIN
  88 The
  89 .Ql GRND_NONBLOCK
  90 flag was set and the
  91 .Xr random 4
  92 device was not yet seeded.
  93 .It Bq Er EFAULT
  94 The
  95 .Fa buf
  96 parameter points to an invalid address.
  97 .It Bq Er EINTR
  98 The sleep was interrupted by a signal.
  99 .It Bq Er EINVAL
 100 An invalid
 101 .Fa flags
 102 was specified.
 103 .It Bq Er EINVAL
 104 The requested
 105 .Fa buflen
 106 was larger than
 107 .Dv IOSIZE_MAX .
 108 .El
 109 .Sh SEE ALSO
 110 .Xr arc4random 3 ,
 111 .Xr getentropy 3 ,
 112 .Xr random 4
 113 .Sh STANDARDS
 114 .Fn getentropy
 115 is non-standard.
 116 It is present in Linux.
 117 .Sh HISTORY
 118 The
 119 .Fn getrandom
 120 system call first appeared in
 121 .Fx 12.0 .