Changeset View
Changeset View
Standalone View
Standalone View
head/lib/libc/sys/getrandom.2
.\" Copyright (c) 2018 Conrad Meyer <cem@FreeBSD.org> | .\" Copyright 2020, 2018 Conrad Meyer <cem@FreeBSD.org>. All rights reserved. | ||||
.\" All rights reserved. | |||||
.\" | .\" | ||||
.\" Redistribution and use in source and binary forms, with or without | .\" Redistribution and use in source and binary forms, with or without | ||||
.\" modification, are permitted provided that the following conditions | .\" modification, are permitted provided that the following conditions | ||||
.\" are met: | .\" are met: | ||||
.\" 1. Redistributions of source code must retain the above copyright | .\" 1. Redistributions of source code must retain the above copyright | ||||
.\" notice, this list of conditions and the following disclaimer. | .\" notice, this list of conditions and the following disclaimer. | ||||
.\" 2. Redistributions in binary form must reproduce the above copyright | .\" 2. Redistributions in binary form must reproduce the above copyright | ||||
.\" notice, this list of conditions and the following disclaimer in the | .\" notice, this list of conditions and the following disclaimer in the | ||||
.\" documentation and/or other materials provided with the distribution. | .\" documentation and/or other materials provided with the distribution. | ||||
.\" | .\" | ||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND | ||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | ||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE | ||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | ||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | ||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd February 24, 2018 | .Dd January 12, 2020 | ||||
.Dt GETRANDOM 2 | .Dt GETRANDOM 2 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm getrandom | .Nm getrandom | ||||
.Nd get random data | .Nd get random data | ||||
.Sh LIBRARY | .Sh LIBRARY | ||||
.Lb libc | .Lb libc | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
Show All 23 Lines | |||||
will block until the device is seeded. | will block until the device is seeded. | ||||
.It Ql GRND_RANDOM | .It Ql GRND_RANDOM | ||||
This flag does nothing on | This flag does nothing on | ||||
.Fx . | .Fx . | ||||
.Pa /dev/random | .Pa /dev/random | ||||
and | and | ||||
.Pa /dev/urandom | .Pa /dev/urandom | ||||
are identical. | are identical. | ||||
.It Ql GRND_INSECURE | |||||
This flag is treated as an alternative name for | |||||
.Dv GRND_NONBLOCK . | |||||
It is provided solely for API compatibility with Linux. | |||||
.El | .El | ||||
.Pp | .Pp | ||||
If the | If the | ||||
.Xr random 4 | .Xr random 4 | ||||
device has been seeded, reads of up to 256 bytes will always return as many | device has been seeded, reads of up to 256 bytes will always return as many | ||||
bytes as requested and will not be interrupted by signals. | bytes as requested and will not be interrupted by signals. | ||||
.Pp | |||||
.Sh RETURN VALUES | .Sh RETURN VALUES | ||||
Upon successful completion, the number of bytes which were actually read is | Upon successful completion, the number of bytes which were actually read is | ||||
returned. | returned. | ||||
For requests larger than 256 bytes, this can be fewer bytes than were | For requests larger than 256 bytes, this can be fewer bytes than were | ||||
requested. | requested. | ||||
Otherwise, -1 is returned and the global variable | Otherwise, -1 is returned and the global variable | ||||
.Va errno | .Va errno | ||||
is set to indicate the error. | is set to indicate the error. | ||||
.Sh ERRORS | .Sh ERRORS | ||||
The | The | ||||
.Fn getrandom | .Fn getrandom | ||||
operation returns the following errors: | operation returns the following errors: | ||||
.Bl -tag -width Er | .Bl -tag -width Er | ||||
.It Bq Er EAGAIN | .It Bq Er EAGAIN | ||||
The | The | ||||
.Ql GRND_NONBLOCK | .Ql GRND_NONBLOCK | ||||
(or | |||||
.Ql GRND_INSECURE ) | |||||
flag was set and the | flag was set and the | ||||
.Xr random 4 | .Xr random 4 | ||||
device was not yet seeded. | device was not yet seeded. | ||||
.It Bq Er EFAULT | .It Bq Er EFAULT | ||||
The | The | ||||
.Fa buf | .Fa buf | ||||
parameter points to an invalid address. | parameter points to an invalid address. | ||||
.It Bq Er EINTR | .It Bq Er EINTR | ||||
The sleep was interrupted by a signal. | The sleep was interrupted by a signal. | ||||
.It Bq Er EINVAL | .It Bq Er EINVAL | ||||
An invalid | An invalid | ||||
.Fa flags | .Fa flags | ||||
was specified. | was specified. | ||||
.It Bq Er EINVAL | .It Bq Er EINVAL | ||||
The requested | The requested | ||||
.Fa buflen | .Fa buflen | ||||
was larger than | was larger than | ||||
.Dv IOSIZE_MAX . | .Dv IOSIZE_MAX . | ||||
.El | .El | ||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr arc4random 3 , | .Xr arc4random 3 , | ||||
.Xr getentropy 3 , | .Xr getentropy 3 , | ||||
.Xr random 4 | .Xr random 4 | ||||
.Sh STANDARDS | .Sh STANDARDS | ||||
.Fn getentropy | .Fn getrandom | ||||
is non-standard. | is non-standard. | ||||
It is present in Linux. | It is present in Linux. | ||||
.Sh HISTORY | .Sh HISTORY | ||||
The | The | ||||
.Fn getrandom | .Fn getrandom | ||||
system call first appeared in | system call first appeared in | ||||
.Fx 12.0 . | .Fx 12.0 . | ||||
.Sh CAVEATS | |||||
Unlike Linux, the | |||||
.Dv GRND_INSECURE | |||||
flag on | |||||
.Fx | |||||
does not produce any output before the | |||||
.Xr random 4 | |||||
device is seeded. |