1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2018 Joyent, Inc. 13.\" 14.Dd "November 6, 2018" 15.Dt GETRANDOM 2 16.Os 17.Sh NAME 18.Nm getrandom 19.Nd get random numbers 20.Sh LIBRARY 21.Lb libc 22.Sh SYNOPSIS 23.In sys/random.h 24.Ft ssize_t 25.Fo getrandom 26.Fa "void *bufp" 27.Fa "size_t buflen" 28.Fa "unsigned int flags" 29.Fc 30.Sh DESCRIPTION 31The 32.Fn getrandom 33function is used to retrieve random and pseudo-random numbers from the 34operating system. 35.Pp 36By default, the 37.Fn getrandom 38function will read up to 39.Fa buflen 40bytes of pseudo-random data into 41.Fa bufp . 42Pseudo-random data will be retrieved from the same source that provides 43data to 44.Pa /dev/urandom . 45The 46.Fn getrandom 47function may return less data than was requested in 48.Fa buflen . 49This can happen because of interrupts from signals, availability of 50data, or because the request was too large. 51Callers must always check to see how much data was actually returned. 52.Pp 53The following values may be bitwise-ORed together in the 54.Fa flags 55argument to modify the behavior of the function: 56.Bl -tag -width Dv 57.It Dv GRND_NONBLOCK 58Instead of blocking, return immediately if data is not available. 59If no data was obtained, 60.Er EAGAIN 61will be set in 62.Va errno . 63Otherwise, less data will be returned than requested. 64.It Dv GRND_RANDOM 65Use the same source of random data as reading from 66.Pa /dev/random , 67instead of 68.Pa /dev/urandom . 69.El 70.Pp 71The 72.Fn getrandom 73function is intended to eliminate the need to explicitly call 74.Xr open 2 75and 76.Xr read 2 77on 78.Pa /dev/random 79or 80.Pa /dev/urandom . 81This eliminates the need to have the character devices available or 82cases where a program may not have an available file descriptor. 83For other uses, 84.Xr arc4random 3C 85may be a better interface. 86.Sh RETURN VALUES 87Upon successful completion, the 88.Fn getrandom 89function returns the number of bytes written into 90.Fa bufp . 91Otherwise, 92.Sy -1 93is returned and 94.Va errno 95is set to indicate the error. 96.Sh ERRORS 97The 98.Fn getrandom 99function will fail if: 100.Bl -tag -width Er 101.It Er EAGAIN 102The 103.Fn getrandom 104function would have blocked and 105.Dv GRND_NONBLOCK 106flag was set. 107.It Er EFAULT 108The 109.Fa bufp 110argument points to an illegal address. 111.It Er EINAVL 112An invalid value was passed in 113.Fa flags . 114.It Er EINTR 115A signal was caught during the operation and no data was transferred. 116.It Er EIO 117An internal error occurred with the corresponding 118.Xr random 4D 119device. 120.El 121.Sh INTERFACE STABILITY 122.Sy Committed 123.Sh MT-LEVEL 124.Sy MT-Safe 125.Sh SEE ALSO 126.Xr open 2 , 127.Xr read 2 , 128.Xr arc4random 3C , 129.Xr random 4D 130.Sh STANDARDS 131The 132.Fn getrandom 133function is non-standard. 134It originally appeared in Linux. 135