| Jason King | de6af22 | 2018-12-13 10:43:17 -0800 | [diff] [blame^] | 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 |
| 31 | The |
| 32 | .Fn getrandom |
| 33 | function is used to retrieve random and pseudo-random numbers from the |
| 34 | operating system. |
| 35 | .Pp |
| 36 | By default, the |
| 37 | .Fn getrandom |
| 38 | function will read up to |
| 39 | .Fa buflen |
| 40 | bytes of pseudo-random data into |
| 41 | .Fa bufp . |
| 42 | Pseudo-random data will be retrieved from the same source that provides |
| 43 | data to |
| 44 | .Pa /dev/urandom . |
| 45 | The |
| 46 | .Fn getrandom |
| 47 | function may return less data than was requested in |
| 48 | .Fa buflen . |
| 49 | This can happen because of interrupts from signals, availability of |
| 50 | data, or because the request was too large. |
| 51 | Callers must always check to see how much data was actually returned. |
| 52 | .Pp |
| 53 | The following values may be bitwise-ORed together in the |
| 54 | .Fa flags |
| 55 | argument to modify the behavior of the function: |
| 56 | .Bl -tag -width Dv |
| 57 | .It Dv GRND_NONBLOCK |
| 58 | Instead of blocking, return immediately if data is not available. |
| 59 | If no data was obtained, |
| 60 | .Er EAGAIN |
| 61 | will be set in |
| 62 | .Va errno . |
| 63 | Otherwise, less data will be returned than requested. |
| 64 | .It Dv GRND_RANDOM |
| 65 | Use the same source of random data as reading from |
| 66 | .Pa /dev/random , |
| 67 | instead of |
| 68 | .Pa /dev/urandom . |
| 69 | .El |
| 70 | .Pp |
| 71 | The |
| 72 | .Fn getrandom |
| 73 | function is intended to eliminate the need to explicitly call |
| 74 | .Xr open 2 |
| 75 | and |
| 76 | .Xr read 2 |
| 77 | on |
| 78 | .Pa /dev/random |
| 79 | or |
| 80 | .Pa /dev/urandom . |
| 81 | This eliminates the need to have the character devices available or |
| 82 | cases where a program may not have an available file descriptor. |
| 83 | For other uses, |
| 84 | .Xr arc4random 3C |
| 85 | may be a better interface. |
| 86 | .Sh RETURN VALUES |
| 87 | Upon successful completion, the |
| 88 | .Fn getrandom |
| 89 | function returns the number of bytes written into |
| 90 | .Fa bufp . |
| 91 | Otherwise, |
| 92 | .Sy -1 |
| 93 | is returned and |
| 94 | .Va errno |
| 95 | is set to indicate the error. |
| 96 | .Sh ERRORS |
| 97 | The |
| 98 | .Fn getrandom |
| 99 | function will fail if: |
| 100 | .Bl -tag -width Er |
| 101 | .It Er EAGAIN |
| 102 | The |
| 103 | .Fn getrandom |
| 104 | function would have blocked and |
| 105 | .Dv GRND_NONBLOCK |
| 106 | flag was set. |
| 107 | .It Er EFAULT |
| 108 | The |
| 109 | .Fa bufp |
| 110 | argument points to an illegal address. |
| 111 | .It Er EINAVL |
| 112 | An invalid value was passed in |
| 113 | .Fa flags . |
| 114 | .It Er EINTR |
| 115 | A signal was caught during the operation and no data was transferred. |
| 116 | .It Er EIO |
| 117 | An internal error occurred with the corresponding |
| 118 | .Xr random 7D |
| 119 | device. |
| 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 7D |
| 130 | .Sh STANDARDS |
| 131 | The |
| 132 | .Fn getrandom |
| 133 | function is non-standard. |
| 134 | It originally appeared in Linux. |