1.\" Copyright (c) 2018 Conrad Meyer <[email protected]> 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 41fills 42.Fa buf 43with up to 44.Fa buflen 45bytes of random data. 46.Pp 47The 48.Fa flags 49argument may include zero or more of the following: 50.Bl -tag -width _GRND_NONBLOCK_ 51.It Ql GRND_NONBLOCK 52Return 53.Er EAGAIN 54instead of blocking, if the 55.Xr random 4 56device has not yet been seeded. 57By default, 58.Fn getrandom 59will block until the device is seeded. 60.It Ql GRND_RANDOM 61This flag does nothing on 62.Fx . 63.Pa /dev/random 64and 65.Pa /dev/urandom 66are identical. 67.El 68.Pp 69If the 70.Xr random 4 71device has been seeded, reads of up to 256 bytes will always return as many 72bytes as requested and will not be interrupted by signals. 73.Pp 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 90flag was set and the 91.Xr random 4 92device was not yet seeded. 93.It Bq Er EFAULT 94The 95.Fa buf 96parameter points to an invalid address. 97.It Bq Er EINTR 98The sleep was interrupted by a signal. 99.It Bq Er EINVAL 100An invalid 101.Fa flags 102was specified. 103.It Bq Er EINVAL 104The requested 105.Fa buflen 106was 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 115is non-standard. 116It is present in Linux. 117.Sh HISTORY 118The 119.Fn getrandom 120system call first appeared in 121.Fx 12.0 . 122