.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Data::Entropy::RawSource::Local 3pm"
.TH Data::Entropy::RawSource::Local 3pm "2021-01-01" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::Entropy::RawSource::Local \- read randomness from local device
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        use Data::Entropy::RawSource::Local;
\&
\&        my $rawsrc = Data::Entropy::RawSource::Local\->new;
\&
\&        $rawsrc\->sysread($c, 1);
\&        # and the rest of the I/O handle interface
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class provides a constructor to open an I/O handle connected to
a local source of random octets.  This may be a strong entropy source,
depending on the \s-1OS,\s0 but not every \s-1OS\s0 has such a facility at all.
.PP
There are no actual objects blessed into this class.  Only the constructor
belongs to this class; it returns \f(CW\*(C`IO::File\*(C'\fR objects.  For use as
a general entropy source, it is recommended to wrap the handle using
\&\f(CW\*(C`Data::Entropy::Source\*(C'\fR, which provides methods to extract entropy in
more convenient forms than mere octets.
.PP
On systems with a blocking \fB/dev/random\fR, such as Linux, the bits
generated can be totally unbiased and uncorrelated.  Such an entropy
stream is suitable for all uses, including security applications.
However, the rate of entropy generation is limited, so applications
requiring a large amount of apparently-random data might prefer to fake
it cryptographically (see Data::Entropy::RawSource::CryptCounter).
.PP
On systems where \fB/dev/random\fR does not block, the bits generated are
necessarily correlated to some extent, but it should be cryptographically
difficult to detect the correlation.  Such an entropy source is not
suitable for all applications.  Some other systems lack \fB/dev/random\fR
entirely.  If satisfactory entropy cannot be generated locally, consider
downloading it from a server (see Data::Entropy::RawSource::RandomOrg
and Data::Entropy::RawSource::RandomnumbersInfo).
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "Data::Entropy::RawSource::Local\->new([\s-1FILENAME\s0])" 4
.IX Item "Data::Entropy::RawSource::Local->new([FILENAME])"
Opens a file handle referring to the randomness device, or \f(CW\*(C`die\*(C'\fRs
on error.  The device opened is \fB/dev/random\fR by default, but this may
be overridden by giving a \s-1FILENAME\s0 argument.
.Sp
The default device name may in the future be different on different OSes,
if their equivalent devices are in different places.
.SH "METHODS"
.IX Header "METHODS"
There are no actual objects blessed into this class.  The constuctor
returns \f(CW\*(C`IO::File\*(C'\fR objects.  See IO::File for the interface.  It is
recommended to use unbuffered reads (the \f(CW\*(C`sysread\*(C'\fR method) rather than
buffered reads (the \f(CW\*(C`getc\*(C'\fR method et al), to avoid wasting entropy that
could be used by another process.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Data::Entropy::RawSource::CryptCounter,
Data::Entropy::RawSource::RandomOrg,
Data::Entropy::RawSource::RandomnumbersInfo,
Data::Entropy::Source,
IO::File
.SH "AUTHOR"
.IX Header "AUTHOR"
Andrew Main (Zefram) <zefram@fysh.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2006, 2007, 2009, 2011
Andrew Main (Zefram) <zefram@fysh.org>
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.