1.\" $OpenBSD: getentropy.2,v 1.8 2015/01/31 00:20:12 schwarze Exp $ 2.\" 3.\" Copyright (c) 2018 Conrad Meyer <cem@FreeBSD.org> 4.\" Copyright (c) 2014 Theo de Raadt 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd February 24, 2018 19.Dt GETENTROPY 3 20.Os 21.Sh NAME 22.Nm getentropy 23.Nd get entropy 24.Sh LIBRARY 25.Lb libc 26.Sh SYNOPSIS 27.In unistd.h 28.Ft int 29.Fn getentropy "void *buf" "size_t buflen" 30.Sh DESCRIPTION 31.Fn getentropy 32fills a buffer with high-quality random data. 33.Pp 34The maximum 35.Fa buflen 36permitted is 256 bytes. 37.Pp 38If it does not produce an error, 39.Fn getentropy 40always provides the requested number of bytes of random data. 41.Pp 42Similar to reading from 43.Pa /dev/urandom 44just after boot, 45.Fn getentropy 46may block until the system has collected enough entropy to seed the CSPRNG. 47.Sh IMPLEMENTATION NOTES 48The 49.Fn getentropy 50function is implemented using 51.Xr getrandom 2 . 52.Sh RETURN VALUES 53.Rv -std 54.Sh ERRORS 55.Fn getentropy 56will succeed unless: 57.Bl -tag -width Er 58.It Bq Er EFAULT 59The 60.Fa buf 61parameter points to an 62invalid address. 63.It Bq Er EIO 64Too many bytes requested, or some other fatal error occurred. 65.El 66.Sh SEE ALSO 67.Xr getrandom 2 , 68.Xr arc4random 3 , 69.Xr random 4 70.Sh STANDARDS 71.Fn getentropy 72is non-standard. 73It is present on 74.Ox 75and Linux. 76.Sh HISTORY 77The 78.Fn getentropy 79function appeared in 80.Ox 5.6 . 81The 82.Fx 83libc compatibility shim first appeared in 84.Fx 12.0 . 85