[thirdparty/man-pages.git] / man3 / getentropy.3

.\" Copyright (C) 2017, Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of
.\" this manual under the conditions for verbatim copying, provided that
.\" the entire resulting derived work is distributed under the terms of
.\" a permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume.
.\" no responsibility for errors or omissions, or for damages resulting.
.\" from the use of the information contained herein.  The author(s) may.
.\" not have taken the same level of care in the production of this.
.\" manual, which is licensed free of charge, as they might when working.
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.TH GETENTROPY 3 2017-09-15 "Linux" "Linux Programmer's Manual"
.SH NAME
getentropy \- fill a buffer with random bytes
.SH SYNOPSIS
.B #include <unistd.h>
.PP
.BI "int getentropy(void *" buffer ", size_t " length );
.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
.PP
.BR getentropy ():
.br
.RS 4
.ad l
_DEFAULT_SOURCE
.RE
.ad
.SH DESCRIPTION
The
.BR getentropy ()
function writes
.I length
bytes of high-quality random data to the buffer starting
at the location pointed to by
.IR buffer .
The maximum permitted value for the
.I length
argument is 256.
.PP
A successful call to
.BR getentropy ()
always provides the requested number of bytes of entropy.
.SH RETURN VALUE
On success, this function returns zero.
On error, \-1 is returned, and
.I errno
is set appropriately.
.SH ERRORS
.TP
.B EFAULT
Part or all of the buffer specified by
.I buffer
and
.I length
is not in valid addressable memory.
.TP
.B EIO
.I length
is greater than 256.
.TP
.B EIO
An unspecified error occurred while trying to overwrite
.I buffer
with random data.
.TP
.B ENOSYS
This kernel version does not implement the
.BR getrandom (2)
system call required to implement this function.
.SH VERSIONS
The
.BR getentropy ()
function first appeared in glibc 2.25.
.SH CONFORMING TO
This function is nonstandard.
It is also present on OpenBSD.
.SH NOTES
The
.BR getentropy ()
function is implemented using
.BR getrandom (2).
.PP
Whereas the glibc wrapper makes
.BR getrandom (2)
a cancellation point,
.BR getentropy ()
is not a cancellation point.
.PP
.BR getentropy ()
is also declared in
.BR <sys/random.h> .
(No feature test macro need be defined to obtain the declaration from
that header file.)
.PP
A call to
.BR getentropy ()
may block if the system has just booted and the kernel has
not yet collected enough randomness to initialize the entropy pool.
In this case,
.BR getentropy ()
will keep blocking even if a signal is handled,
and will return only once the entropy pool has been initialized.
.SH SEE ALSO
.BR getrandom (2),
.BR urandom (4),
.BR random (7)
Commit	Line	Data
b0265728 MK	1	.\" Copyright (C) 2017, Michael Kerrisk <mtk.manpages@gmail.com>
	2	.\"
	3	.\" %%%LICENSE_START(VERBATIM)
	4	.\" Permission is granted to make and distribute verbatim copies of this
	5	.\" manual provided the copyright notice and this permission notice are
	6	.\" preserved on all copies.
	7	.\"
	8	.\" Permission is granted to copy and distribute modified versions of
	9	.\" this manual under the conditions for verbatim copying, provided that
	10	.\" the entire resulting derived work is distributed under the terms of
	11	.\" a permission notice identical to this one.
	12	.\"
	13	.\" Since the Linux kernel and libraries are constantly changing, this
	14	.\" manual page may be incorrect or out-of-date. The author(s) assume.
	15	.\" no responsibility for errors or omissions, or for damages resulting.
	16	.\" from the use of the information contained herein. The author(s) may.
	17	.\" not have taken the same level of care in the production of this.
	18	.\" manual, which is licensed free of charge, as they might when working.
	19	.\" professionally.
	20	.\"
	21	.\" Formatted or processed versions of this manual, if unaccompanied by
	22	.\" the source, must acknowledge the copyright and authors of this work.
	23	.\" %%%LICENSE_END
	24	.\"
4b8c67d9	25	.TH GETENTROPY 3 2017-09-15 "Linux" "Linux Programmer's Manual"
b0265728 MK	26	.SH NAME
	27	getentropy \- fill a buffer with random bytes
	28	.SH SYNOPSIS
9cf011f9	29	.B #include <unistd.h>
68e4db0a	30	.PP
d75c6df9	31	.BI "int getentropy(void *" buffer ", size_t " length );
68e4db0a	32	.PP
f0ed9710 MK	33	.in -4n
	34	Feature Test Macro Requirements for glibc (see
	35	.BR feature_test_macros (7)):
	36	.in
68e4db0a	37	.PP
f0ed9710 MK	38	.BR getentropy ():
	39	.br
	40	.RS 4
	41	.ad l
	42	_DEFAULT_SOURCE
	43	.RE
	44	.ad
b0265728 MK	45	.SH DESCRIPTION
	46	The
	47	.BR getentropy ()
	48	function writes
	49	.I length
	50	bytes of high-quality random data to the buffer starting
	51	at the location pointed to by
	52	.IR buffer .
	53	The maximum permitted value for the
	54	.I length
	55	argument is 256.
847e0d88	56	.PP
b0265728 MK	57	A successful call to
b0265728 MK	58	.BR getentropy ()
419ba7b3	59	always provides the requested number of bytes of entropy.
b0265728	60	.SH RETURN VALUE
78cba5ac	61	On success, this function returns zero.
b0265728 MK	62	On error, \-1 is returned, and
	63	.I errno
	64	is set appropriately.
	65	.SH ERRORS
	66	.TP
	67	.B EFAULT
	68	Part or all of the buffer specified by
	69	.I buffer
	70	and
	71	.I length
	72	is not in valid addressable memory.
	73	.TP
	74	.B EIO
	75	.I length
	76	is greater than 256.
	77	.TP
	78	.B EIO
	79	An unspecified error occurred while trying to overwrite
	80	.I buffer
	81	with random data.
	82	.TP
	83	.B ENOSYS
	84	This kernel version does not implement the
	85	.BR getrandom (2)
	86	system call required to implement this function.
	87	.SH VERSIONS
	88	The
	89	.BR getentropy ()
	90	function first appeared in glibc 2.25.
	91	.SH CONFORMING TO
	92	This function is nonstandard.
	93	It is also present on OpenBSD.
	94	.SH NOTES
	95	The
	96	.BR getentropy ()
	97	function is implemented using
	98	.BR getrandom (2).
847e0d88	99	.PP
b0265728 MK	100	Whereas the glibc wrapper makes
	101	.BR getrandom (2)
	102	a cancellation point,
	103	.BR getentropy ()
	104	is not a cancellation point.
847e0d88	105	.PP
f0ed9710 MK	106	.BR getentropy ()
	107	is also declared in
	108	.BR <sys/random.h> .
	109	(No feature test macro need be defined to obtain the declaration from
	110	that header file.)
847e0d88	111	.PP
b0265728 MK	112	A call to
	113	.BR getentropy ()
	114	may block if the system has just booted and the kernel has
	115	not yet collected enough randomness to initialize the entropy pool.
	116	In this case,
	117	.BR getentropy ()
	118	will keep blocking even if a signal is handled,
	119	and will return only once the entropy pool has been initialized.
	120	.SH SEE ALSO
	121	.BR getrandom (2),
	122	.BR urandom (4),
	123	.BR random (7)