.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Dpkg::Checksums 3perl"
.TH Dpkg::Checksums 3perl 2026-03-06 1.23.7-dirty libdpkg-perl
.\" 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
Dpkg::Checksums \- generate and manipulate file checksums
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module provides a class that can generate and manipulate
various file checksums as well as some methods to query information
about supported checksums.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.ie n .IP "@list = \fBchecksums_get_list()\fR" 4
.el .IP "\f(CW@list\fR = \fBchecksums_get_list()\fR" 4
.IX Item "@list = checksums_get_list()"
Returns the list of supported checksums algorithms.
.ie n .IP "$bool = checksums_is_supported($alg)" 4
.el .IP "\f(CW$bool\fR = checksums_is_supported($alg)" 4
.IX Item "$bool = checksums_is_supported($alg)"
Returns a boolean indicating whether the given checksum algorithm is
supported. The checksum algorithm is case\-insensitive.
.ie n .IP "$value = checksums_get_property($alg, $property)" 4
.el .IP "\f(CW$value\fR = checksums_get_property($alg, \f(CW$property\fR)" 4
.IX Item "$value = checksums_get_property($alg, $property)"
Returns the requested property of the checksum algorithm. Returns undef if
either the property or the checksum algorithm doesn\*(Aqt exist. Valid
properties currently include "name" (returns the name of the digest
algorithm), "regex" for the regular expression describing the common
string representation of the checksum, and "strong" for a boolean describing
whether the checksum algorithm is considered cryptographically strong.
.SH METHODS
.IX Header "METHODS"
.ie n .IP "$ck = Dpkg::Checksums\->\fBnew()\fR" 4
.el .IP "\f(CW$ck\fR = Dpkg::Checksums\->\fBnew()\fR" 4
.IX Item "$ck = Dpkg::Checksums->new()"
Create a new Dpkg::Checksums object. This object is able to store
the checksums of several files to later export them or verify them.
.ie n .IP $ck\->\fBreset()\fR 4
.el .IP \f(CW$ck\fR\->\fBreset()\fR 4
.IX Item "$ck->reset()"
Forget about all checksums stored. The object is again in the same state
as if it was newly created.
.ie n .IP "$ck\->add_from_file($filename, %opts)" 4
.el .IP "\f(CW$ck\fR\->add_from_file($filename, \f(CW%opts\fR)" 4
.IX Item "$ck->add_from_file($filename, %opts)"
Add or verify checksums information for the file \f(CW$filename\fR. The file must
exists for the call to succeed. By default if the \f(CW$filename\fR is known and
the checksums do not match, the function will error out.
.Sp
Options:
.RS 4
.IP \fBkey\fR 4
.IX Item "key"
Set to the public name to use when exporting the checksums,
instead of using \f(CW$filename\fR.
.IP \fBchecksums\fR 4
.IX Item "checksums"
Set an array reference with the list of wanted checksums to generate instead
of generating all of them.
.IP \fBupdate\fR 4
.IX Item "update"
Set a boolean on whether the object should update the checksums information
associated with the \f(CW$filename\fR (or key), instead of emitting an error if
it does not match.
.RE
.RS 4
.RE
.ie n .IP "$ck\->add_from_string($alg, $value, %opts)" 4
.el .IP "\f(CW$ck\fR\->add_from_string($alg, \f(CW$value\fR, \f(CW%opts\fR)" 4
.IX Item "$ck->add_from_string($alg, $value, %opts)"
Add checksums of type \f(CW$alg\fR that are stored in the \f(CW$value\fR variable.
\&\f(CW$value\fR can be multi\-lines, each line should be a space separated list
of checksum, file size and filename. Leading or trailing spaces are
not allowed.
.Sp
Options:
.RS 4
.IP \fBupdate\fR 4
.IX Item "update"
Set a boolean on whether the object should update the checksums information
associated with the \f(CW$filename\fR (or key), instead of emitting an error if
it does not match.
.RE
.RS 4
.RE
.ie n .IP "$ck\->add_from_control($control, %opts)" 4
.el .IP "\f(CW$ck\fR\->add_from_control($control, \f(CW%opts\fR)" 4
.IX Item "$ck->add_from_control($control, %opts)"
Read checksums from Checksums\-* fields stored in the Dpkg::Control object
\&\f(CW$control\fR. It uses \f(CW$self\fR\->\fBadd_from_string()\fR on the field values to do the
actual work. The default field used is \fBChecksums\-Md5\fR.
.Sp
Options:
.RS 4
.IP \fBuse_files_for_md5\fR 4
.IX Item "use_files_for_md5"
Set to true to use the \fBFiles\fR field instead of \fBChecksums\-Md5\fR.
.Sp
Defaults to false.
.RE
.RS 4
.RE
.ie n .IP "@files = $ck\->\fBget_files()\fR" 4
.el .IP "\f(CW@files\fR = \f(CW$ck\fR\->\fBget_files()\fR" 4
.IX Item "@files = $ck->get_files()"
Return the list of files whose checksums are stored in the object.
.ie n .IP "$bool = $ck\->has_file($file)" 4
.el .IP "\f(CW$bool\fR = \f(CW$ck\fR\->has_file($file)" 4
.IX Item "$bool = $ck->has_file($file)"
Return true if we have checksums for the given file. Returns false
otherwise.
.ie n .IP $ck\->remove_file($file) 4
.el .IP \f(CW$ck\fR\->remove_file($file) 4
.IX Item "$ck->remove_file($file)"
Remove all checksums of the given file.
.ie n .IP "$checksum = $ck\->get_checksum($file, $alg)" 4
.el .IP "\f(CW$checksum\fR = \f(CW$ck\fR\->get_checksum($file, \f(CW$alg\fR)" 4
.IX Item "$checksum = $ck->get_checksum($file, $alg)"
Return the checksum of type \f(CW$alg\fR for the requested \f(CW$file\fR. This will not
compute the checksum but only return the checksum stored in the object, if
any.
.Sp
If \f(CW$alg\fR is not defined, it returns a reference to a hash: keys are
the checksum algorithms and values are the checksums themselves. The
hash returned must not be modified, it\*(Aqs internal to the object.
.ie n .IP "$size = $ck\->get_size($file)" 4
.el .IP "\f(CW$size\fR = \f(CW$ck\fR\->get_size($file)" 4
.IX Item "$size = $ck->get_size($file)"
Return the size of the requested file if it\*(Aqs available in the object.
.ie n .IP "$bool = $ck\->has_strong_checksums($file)" 4
.el .IP "\f(CW$bool\fR = \f(CW$ck\fR\->has_strong_checksums($file)" 4
.IX Item "$bool = $ck->has_strong_checksums($file)"
Return a boolean on whether the file has a strong checksum.
.ie n .IP "$ck\->export_to_string($alg, %opts)" 4
.el .IP "\f(CW$ck\fR\->export_to_string($alg, \f(CW%opts\fR)" 4
.IX Item "$ck->export_to_string($alg, %opts)"
Return a multi\-line string containing the checksums of type \f(CW$alg\fR. The
string can be stored as\-is in a Checksum\-* field of a Dpkg::Control
object.
.ie n .IP "$ck\->export_to_control($control, %opts)" 4
.el .IP "\f(CW$ck\fR\->export_to_control($control, \f(CW%opts\fR)" 4
.IX Item "$ck->export_to_control($control, %opts)"
Export the checksums in the Checksums\-* fields of the Dpkg::Control
\&\f(CW$control\fR object.
.Sp
Options:
.RS 4
.IP \fBuse_files_for_md5\fR 4
.IX Item "use_files_for_md5"
Set to true to use the \fBFiles\fR field instead of \fBChecksums\-Md5\fR.
.Sp
Defaults to false.
.RE
.RS 4
.RE
.SH CHANGES
.IX Header "CHANGES"
.SS "Version 1.04 (dpkg 1.20.0)"
.IX Subsection "Version 1.04 (dpkg 1.20.0)"
Remove warning: For obsolete property \*(Aqprogram\*(Aq.
.SS "Version 1.03 (dpkg 1.18.5)"
.IX Subsection "Version 1.03 (dpkg 1.18.5)"
New property: Add new \*(Aqstrong\*(Aq property.
.PP
New member: \f(CW$ck\fR\->\fBhas_strong_checksums()\fR.
.SS "Version 1.02 (dpkg 1.18.0)"
.IX Subsection "Version 1.02 (dpkg 1.18.0)"
Obsolete property: Getting the \*(Aqprogram\*(Aq checksum property will warn and
return undef, the Digest module is used internally now.
.PP
New property: Add new \*(Aqname\*(Aq property with the name of the Digest algorithm
to use.
.SS "Version 1.01 (dpkg 1.17.6)"
.IX Subsection "Version 1.01 (dpkg 1.17.6)"
New argument: Accept an options argument in \f(CW$ck\fR\->\fBexport_to_string()\fR.
.PP
New option: Accept new option \*(Aqupdate\*(Aq in \f(CW$ck\fR\->\fBadd_from_file()\fR and
\&\f(CW$ck\fR\->\fBadd_from_control()\fR.
.SS "Version 1.00 (dpkg 1.15.6)"
.IX Subsection "Version 1.00 (dpkg 1.15.6)"
Mark the module as public.