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

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

getrandom perl perl-module random

Last synced: 7 days ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/mauke/sys-getrandom
• Owner: mauke
• Created: 2023-02-10T00:31:20.000Z (almost 2 years ago)
• Default Branch: main
• Last Pushed: 2023-02-10T00:59:35.000Z (almost 2 years ago)
• Last Synced: 2023-08-09T12:16:58.464Z (over 1 year ago)
• Topics: getrandom, perl, perl-module, random
• Language: Perl
• Homepage:
• Size: 11.7 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: .github/README.md
  • Changelog: Changes

Awesome Lists containing this project

README

        
# NAME

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

# SYNOPSIS

```perl

use Sys::GetRandom qw(getrandom random_bytes GRND_NONBLOCK GRND_RANDOM);

my $n = getrandom($buf, $count, $flags, $offset);

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.

## Functions

- getrandom SCALAR, LENGTH

- getrandom SCALAR, LENGTH, FLAGS

- getrandom SCALAR, LENGTH, FLAGS, OFFSET

    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`.

    By default, the generated bytes are placed at the beginning of _SCALAR_. You

    can pass a positive value for _OFFSET_ to place them within the string,

    leaving the first _OFFSET_ bytes unchanged.

- 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.

# AUTHOR

Lukas Mai, ``

# COPYRIGHT & LICENSE

Copyright 2023 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.