Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
.Dd January 12, 2020 .Dt GETRANDOM 2 .Os .Sh NAME .Nm getrandom .Nd get random data .Sh LIBRARY .Lb libc .Sh SYNOPSIS n sys/random.h .Ft ssize_t .Fn getrandom "void *buf" "size_t buflen" "unsigned int flags" .Sh DESCRIPTION .Fn getrandom fills .Fa buf with up to .Fa buflen bytes of random data.
p The .Fa flags argument may include zero or more of the following: l -tag -width _GRND_NONBLOCK_ t Ql GRND_NONBLOCK Return .Er EAGAIN instead of blocking, if the .Xr random 4 device has not yet been seeded. By default, .Fn getrandom will block until the device is seeded. t Ql GRND_RANDOM This flag does nothing on .Fx .
a /dev/urandom are identical. t Ql GRND_INSECURE This flag is treated as an alternative name for .Dv GRND_NONBLOCK . It is provided solely for API compatibility with Linux. .El
p If the .Xr random 4 device has been seeded, reads of up to 256 bytes will always return as many bytes as requested and will not be interrupted by signals. .Sh RETURN VALUES Upon successful completion, the number of bytes which were actually read is returned. For requests larger than 256 bytes, this can be fewer bytes than were requested. Otherwise, -1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS The .Fn getrandom operation returns the following errors: l -tag -width Er t Bq Er EAGAIN The .Ql GRND_NONBLOCK (or .Ql GRND_INSECURE ) flag was set and the .Xr random 4 device was not yet seeded. t Bq Er EFAULT The .Fa buf parameter points to an invalid address. t Bq Er EINTR The sleep was interrupted by a signal. t Bq Er EINVAL An invalid .Fa flags was specified. t Bq Er EINVAL The requested .Fa buflen was larger than .Dv IOSIZE_MAX . .El .Sh SEE ALSO .Xr arc4random 3 , .Xr getentropy 3 , .Xr random 4 .Sh STANDARDS .Fn getrandom is non-standard. It is present in Linux. .Sh HISTORY The .Fn getrandom system call first appeared in .Fx 12.0 . .Sh CAVEATS Unlike Linux, the .Dv GRND_INSECURE flag on .Fx does not produce any output before the .Xr random 4 device is seeded.