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.\" $FreeBSD$ 25.\" 26.Dd December 31, 2021 27.Dt GETRANDOM 2 28.Os 29.Sh NAME 30.Nm getrandom 31.Nd get random data 32.Sh LIBRARY 33.Lb libc 34.Sh SYNOPSIS 35.In sys/random.h 36.Ft ssize_t 37.Fn getrandom "void *buf" "size_t buflen" "unsigned int flags" 38.Sh DESCRIPTION 39.Fn getrandom 40fills 41.Fa buf 42with up to 43.Fa buflen 44bytes of random data. 45.Pp 46The 47.Fa flags 48argument may include zero or more of the following: 49.Bl -tag -width _GRND_NONBLOCK_ 50.It Dv GRND_NONBLOCK 51Return 52.Er EAGAIN 53instead of blocking, if the 54.Xr random 4 55device has not yet been seeded. 56By default, 57.Fn getrandom 58will block until the device is seeded. 59.It Dv GRND_RANDOM 60This flag does nothing on 61.Dx . 62.Pa /dev/random 63and 64.Pa /dev/urandom 65are identical. 66.It Dv GRND_INSECURE 67This flag is treated as an alternative name for 68.Dv GRND_NONBLOCK . 69It is provided solely for API compatibility with Linux. 70.El 71.Pp 72If the 73.Xr random 4 74device has been seeded, reads of up to 256 bytes will always return as many 75bytes as requested and will not be interrupted by signals. 76.Sh RETURN VALUES 77Upon successful completion, the number of bytes which were actually read is 78returned. 79For requests larger than 256 bytes, this can be fewer bytes than were 80requested. 81Otherwise, -1 is returned and the global variable 82.Va errno 83is set to indicate the error. 84.Sh ERRORS 85The 86.Fn getrandom 87operation returns the following errors: 88.Bl -tag -width Er 89.It Bq Er EAGAIN 90The 91.Dv GRND_NONBLOCK 92(or 93.Dv GRND_INSECURE ) 94flag was set and the 95.Xr random 4 96device was not yet seeded. 97.It Bq Er EFAULT 98The 99.Fa buf 100parameter points to an invalid address. 101.It Bq Er EINTR 102The sleep was interrupted by a signal. 103.It Bq Er EINVAL 104An invalid 105.Fa flags 106was specified. 107.It Bq Er EINVAL 108The requested 109.Fa buflen 110is invalid (typically if negative). 111.Dx 112does not impose a limit on the buffer size. 113.El 114.Sh SEE ALSO 115.Xr arc4random 3 , 116.Xr getentropy 3 , 117.Xr random 4 118.Sh STANDARDS 119.Fn getrandom 120is non-standard. 121It is present in Linux. 122.Sh HISTORY 123The 124.Fn getrandom 125system call first appeared in 126.Dx 5.7 . 127.Sh CAVEATS 128Unlike Linux, the 129.Dv GRND_INSECURE 130flag on 131.Dx 132does not produce any output before the 133.Xr random 4 134device is seeded. 135