getentropy() to be added to POSIX in the next version

[Robert Elz <kre%munnari.OZ.AU@localhost>]

I know there has been discussion here about getentropy() etc.
Normally outside my area of direct interest, so I didn't pay
all that much attention, but I thought that you all should know
that getentropy() has been added in the draft (next draft when
it appears) of the forthcoming version of the POSIX standard.
(Perhaps in 2022, outside chance 2021, no chance 2020, beyond
2022 is possible).

The actual page (or something close to it) is included
below - there are also some extra changes elsewhere that aren't
particularly interesting (like the addition of GETENTROPY_MAX
in <limits.h>, a prototype in <unistd.h>,  and some references
from other places).

How the NetBSD version fits with this spec I have no idea,
but I assume that others out there do.

Note that in the cut&paste below, all markup has been lost, and the
text has been re-justified to fit this e-mail.

kre


NAME

    getentropy -- fill a buffer with random bytes


SYNOPSIS

    #include <unistd.h>

    int getentropy(void *buffer, size_t length);


DESCRIPTION

    The getentropy() function shall write length bytes of data
    starting at the location pointed to by buffer. The output shall
    be unpredictable high quality random data, generated by a
    cryptographically secure pseudo-random number generator. The
    maximum permitted value for the length argument is given by the
    {GETENTROPY_MAX} symbolic constant defined in <limits.h>.

    A successful call to getentropy() shall always provide the
    requested number of bytes of entropy.


RETURN VALUE

    Upon successful completion, getentropy() shall return 0;
    otherwise, -1 shall be returned and errno set to indicate the error.


ERRORS

    The getentropy() function shall fail if:

    [EINVAL]

        The value of length is greater than {GETENTROPY_MAX}.

    The getentropy() function may fail if:

    [ENOSYS]

        The system does not provide the necessary source of entropy.


EXAMPLES

    None.


APPLICATION USAGE

    The intended use of this function is to create a seed for other
    pseudo-random number generators.


RATIONALE

    The getentropy() function is not a cancellation point.
    (See [xref to 2.9.5.2 Cancellation Points].)


FUTURE DIRECTIONS

    None.


SEE ALSO

    drand48(), initstate(), rand()

    XBD <limits.h>, <unistd.h>


CHANGE HISTORY

    First released in Issue 8.