.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "Cksum 3pm"
.TH Cksum 3pm "2010-07-13" "perl v5.14.2" "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"
String::CRC::Cksum \- Perl extension for calculating checksums
in a manner compatible with the POSIX cksum program.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fB\s-1OO\s0 style\fR:
  use String::CRC::Cksum;
.PP
.Vb 2
\&  $cksum = String::CRC::Cksum\->new;
\&  $cksum1 = $cksum\->new;     # clone (clone is reset)
\&
\&  $cksum\->add("string1");
\&  $cksum\->add("string2");
\&  $cksum\->add("string3", "string4", "string5", ...);
\&  ...
\&  ($ck, $sz) = $cksum\->peek;
\&  $cksum\->add("string6", ...);
\&  ...
\&  ($ck, $sz) = $cksum\->result;
\&
\&  $cksum1\->addfile(\e*file1);     # note: adding many files
\&  $cksum1\->addfile(\e*file2);     # is probably a silly thing
\&  $cksum1\->addfile(\e*file3);     # to do, but you *could*...
\&  ...
.Ve
.PP
\&\fBFunctional style\fR:
  use String::CRC::Cksum qw(cksum);
.PP
.Vb 1
\&  $ck = cksum("string1", "string2", ...);
\&
\&  ($ck, $sz) = cksum("string1", "string2", ...);
\&
\&  $ck = cksum(\e*FILE);
\&
\&  ($ck, $sz) = cksum(\e*FILE);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The String::CRC::Cksum module calculates a 32 bit \s-1CRC\s0,
generating the same \s-1CRC\s0 value as the \s-1POSIX\s0 cksum program.
If called in a list context, returns the length of the data
object as well, which is useful for fully emulating
the cksum program. The returned checksum will always be
a non-negative integral number in the range 0..2^32\-1.
.PP
Despite its name, this module is able to compute the
checksum of files as well as of strings.
Just pass in a reference to a filehandle,
or a reference to any object that can respond to
a \fIread()\fR call and eventually return 0 at \*(L"end of file\*(R".
.PP
Beware: consider proper use of \fIbinmode()\fR
if you are on a non-UNIX platform
or processing files derived from other platforms.
.PP
The object oriented interface can be used
to progressively add data into the checksum
before yielding the result.
.PP
The functional interface is a convenient way
to get a checksum of a single data item.
.PP
None of the routines make local copies of passed-in strings
so you can safely Cksum large strings safe in the knowledge
that there won't be any memory issues.
.PP
Passing in multiple files is acceptable,
but perhaps of questionable value.
However I don't want to hamper your creativity...
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
The following functions are provided
by the \*(L"String::CRC::Cksum\*(R" module.
None of these functions are exported by default.
.IP "\fB\f(BInew()\fB\fR" 4
.IX Item "new()"
Creates a new String::CRC::Cksum object
which is in a reset state, ready for action.
If passed an existing String::CRC::Cksum object,
it takes only the class \-
ie yields a fresh, reset object.
.IP "\fB\f(BIreset()\fB\fR" 4
.IX Item "reset()"
Resets the Cksum object to the intialized state.
An interesting phenomenom is,
the \s-1CRC\s0 is not zero but 0xFFFFFFFF
for a reset Cksum object.
The returned size of a reset item will be zero.
.ie n .IP "\fBadd(""string"", ...)\fR" 4
.el .IP "\fBadd(``string'', ...)\fR" 4
.IX Item "add(string, ...)"
Progressively inject data into the Cksum object
prior to requesting the final result.
.IP "\fBaddfile(\e*FILE, ...)\fR" 4
.IX Item "addfile(*FILE, ...)"
Progressively inject all (remaining) data from the file
into the Cksum object prior to requesting the final result.
The file handle passed in
need only respond to the \fIread()\fR function to be usable,
so feel free to pass in \s-1IO\s0 handles as needed.
[hmmm \- methinks I should have a test for that]
.IP "\fBpeek($)\fR" 4
.IX Item "peek($)"
Yields the \s-1CRC\s0 checksum
(and optionally the total size in list context)
but does not reset the Cksum object.
Repeated calls to \fIpeek()\fR may be made
and more data may be added.
.IP "\fBresult($)\fR" 4
.IX Item "result($)"
Yields the \s-1CRC\s0 checksum
(and optionally the total size in list context)
and then resets the Cksum object.
.IP "\fBcksum(@)\fR" 4
.IX Item "cksum(@)"
A convenient functional interface
that may be passed a list of strings and filehandles.
It will instantiate a Cksum object,
apply the data and return the result
in one swift, sweet operation.
See how much I'm looking after you?
.Sp
\&\s-1NOTE:\s0 the filehandles must be passed as \e*FD
because I'm detecting a file handle using the \fIref()\fR function.
Therefore any blessed \s-1IO\s0 handle will also satisfy \fIref()\fR
and be interpreted as a file handle.
.SS "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
None by default.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
manpages: \fIcksum\fR\|(1) or cksum(C) depending on your flavour of \s-1UNIX\s0.
.PP
http://www.opengroup.org/onlinepubs/007904975/utilities/cksum.html
.SH "AUTHOR"
.IX Header "AUTHOR"
Andrew Clarke, <ahamm@cpan.org>.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright disclaimed 2003 by Andrew Clarke
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.