https://github.com/mauke/sys-getrandom-pp

Sys::GetRandom::PP - pure Perl interface to getrandom(2)
https://github.com/mauke/sys-getrandom-pp

getrandom perl perl-module random

Last synced: 2 days ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/mauke/sys-getrandom-pp
• Owner: mauke
• Created: 2024-04-07T22:40:16.000Z (6 months ago)
• Default Branch: main
• Last Pushed: 2024-09-20T17:22:31.000Z (6 days ago)
• Last Synced: 2024-09-24T19:47:10.079Z (2 days ago)
• Topics: getrandom, perl, perl-module, random
• Language: Perl
• Homepage: https://metacpan.org/pod/Sys::GetRandom::PP
• Size: 33.2 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: .github/README.md
  • Changelog: Changes

Awesome Lists containing this project

README

        
# NAME

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

# SYNOPSIS

```perl

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)](http://man.he.net/man2/getrandom) call present on

Linux and FreeBSD. It exports (on request) two functions and two constants.

It is written in pure Perl using the [syscall](https://perldoc.perl.org/perlfunc#syscall-NUMBER-LIST)

function. Otherwise it presents the same interface as [Sys::GetRandom](https://metacpan.org/pod/Sys%3A%3AGetRandom), 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](https://metacpan.org/pod/Sys%3A%3AGetRandom),

[getrandom(2)](http://man.he.net/man2/getrandom),

[h2ph](https://metacpan.org/pod/h2ph)

# AUTHOR

Lukas Mai, ``

# 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/](https://dev.perl.org/licenses/) for more information.