Changeset View
Changeset View
Standalone View
Standalone View
lib/libc/sys/getrandom.2
| .\" Copyright (c) 2018 Conrad Meyer <cem@FreeBSD.org> | .\" Copyright 2020, 2018 Conrad Meyer <cem@FreeBSD.org>. All rights reserved. | ||||
markm: Aren't we dropping the "All rights reserved" bit as being legally meaningless? | |||||
cemAuthorUnsubmitted Done Inline ActionsI'm not a lawyer and I haven't heard that from my lawyer, so I'll just leave it in for now. (This revision just pulls it all on a single line, which is the current guidance -- to clarify which copyright(s) the A.R.R. applies to.) cem: I'm not a lawyer and I haven't heard that from my lawyer, so I'll just leave it in for now. | |||||
| .\" 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 10, 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. | |||||
Aren't we dropping the "All rights reserved" bit as being legally meaningless?