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