NAME

Sys::GetRandom::PP - pure Perl interface to getrandom(2)

SYNOPSIS

    use Sys::GetRandom::PP qw(getrandom random_bytes GRND_NONBLOCK GRND_RANDOM);
    my $n = getrandom($buf, $count, $flags);
    my $bytes = random_bytes($count);

DESCRIPTION

This module provides a Perl interface to the getrandom(2) call present on Linux and FreeBSD. It exports (on request) two functions and two constants.

It is written in pure Perl using the syscall function. Otherwise it presents the same interface as Sys::GetRandom, which is written in C.

Functions

getrandom SCALAR, LENGTH

getrandom SCALAR, LENGTH, FLAGS

Generates up to LENGTH bytes of random data and stores them in SCALAR. Returns the number of random bytes generated, or undef on error (in which case $! is also set).

By default, getrandom is equivalent to reading from /dev/urandom (but without accessing the file system or requiring the use of a file descriptor). If /dev/urandom has not been initialized yet, getrandom will block by default.

If /dev/urandom has been initialized and LENGTH is 256 or less, getrandom will atomically return the requested amount of random data (i.e. it will generate exactly LENGTH bytes of data and will not be interrupted by a signal). For larger values of LENGTH it may be interrupted by signals and either generate fewer random bytes than requested or fail with $! set to EINTR.

The FLAGS argument must be either 0 (the default value) or the bitwise OR of one or more of the following flags:

GRND_RANDOM

Read from the same source as /dev/random, not /dev/urandom (the default).

GRND_NONBLOCK

By default, getrandom will block if /dev/urandom has not been initialized yet or (with GRND_RANDOM) if there are no random bytes available in /dev/random. If the GRND_NONBLOCK flag is passed, it will fail immediately instead, returning undef and setting $! to EAGAIN.

random_bytes LENGTH

Generates and returns a string of LENGTH random bytes.

LENGTH must be between 0 and 256 (inclusive).

This is just a wrapper around getrandom with default flags.

SEE ALSO

Sys::GetRandom, getrandom(2), h2ph

AUTHOR

Lukas Mai, <lmai at web.de>

COPYRIGHT & LICENSE

Copyright 2024 Lukas Mai.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See https://dev.perl.org/licenses/ for more information.