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