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.\" $FreeBSD$ 19.\" 20.Dd December 31, 2021 21.Dt GETENTROPY 3 22.Os 23.Sh NAME 24.Nm getentropy 25.Nd get entropy 26.Sh LIBRARY 27.Lb libc 28.Sh SYNOPSIS 29.In unistd.h 30.Ft int 31.Fn getentropy "void *buf" "size_t buflen" 32.Sh DESCRIPTION 33.Fn getentropy 34fills a buffer with high-quality random data. 35.Pp 36The maximum 37.Fa buflen 38permitted is 256 bytes. 39.Pp 40If it does not produce an error, 41.Fn getentropy 42always provides the requested number of bytes of random data. 43.Pp 44Similar to reading from 45.Pa /dev/urandom 46just after boot, 47.Fn getentropy 48may block until the system has collected enough entropy to seed the CSPRNG. 49.Sh IMPLEMENTATION NOTES 50The 51.Fn getentropy 52function is implemented using 53.Xr getrandom 2 . 54.Sh RETURN VALUES 55.Rv -std 56.Sh ERRORS 57.Fn getentropy 58will succeed unless: 59.Bl -tag -width Er 60.It Bq Er EFAULT 61The 62.Fa buf 63parameter points to an 64invalid address. 65.It Bq Er EIO 66Too many bytes requested, or some other fatal error occurred. 67.El 68.Sh SEE ALSO 69.Xr getrandom 2 , 70.Xr arc4random 3 , 71.Xr random 4 72.Sh STANDARDS 73.Fn getentropy 74is non-standard. 75It is present on 76.Ox , 77.Fx 78and Linux. 79.Sh HISTORY 80The 81.Fn getentropy 82function appeared in 83.Ox 5.6 . 84The 85.Fx 86and 87.Dx 88libc compatibility shims first appeared in 89.Fx 12.0 90and 91.Dx 6.1 , 92respectively. 93