xref: /illumos-gate/usr/src/man/man2/getrandom.2 (revision bbf215553c7233fbab8a0afdf1fac74c44781867)
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