.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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 "Debbugs::Status 3pm"
.TH Debbugs::Status 3pm "2010-08-06" "perl v5.10.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"
Debbugs::Status \-\- Routines for dealing with summary and status files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use Debbugs::Status;
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is a replacement for the parts of errorlib.pl which write
and read status and summary files.
.PP
It also contains generic routines for returning information about the
status of a particular bug
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "readbug"
.IX Subsection "readbug"
.Vb 2
\&     readbug($bug_num,$location)
\&     readbug($bug_num)
.Ve
.PP
Reads a summary file from the archive given a bug number and a bug
location. Valid locations are those understood by \*(L"getbugcomponent\*(R"
.SS "read_bug"
.IX Subsection "read_bug"
.Vb 5
\&     read_bug(bug => $bug_num,
\&              location => \*(Aqarchive\*(Aq,
\&             );
\&     read_bug(summary => \*(Aqpath/to/bugnum.summary\*(Aq);
\&     read_bug($bug_num);
.Ve
.PP
A more complete function than readbug; it enables you to pass a full
path to the summary file instead of the bug number and/or location.
.PP
\fIOptions\fR
.IX Subsection "Options"
.IP "bug \*(-- the bug number" 4
.IX Item "bug  the bug number"
.PD 0
.IP "location \*(-- optional location which is passed to getbugcomponent" 4
.IX Item "location  optional location which is passed to getbugcomponent"
.IP "summary \*(-- complete path to the .summary file which will be read" 4
.IX Item "summary  complete path to the .summary file which will be read"
.ie n .IP "lock \*(-- whether to obtain a lock for the bug to prevent something modifying it while the bug has been read. You \fBmust\fR call ""unfilelock();"" if something not undef is returned from read_bug." 4
.el .IP "lock \*(-- whether to obtain a lock for the bug to prevent something modifying it while the bug has been read. You \fBmust\fR call \f(CWunfilelock();\fR if something not undef is returned from read_bug." 4
.IX Item "lock  whether to obtain a lock for the bug to prevent something modifying it while the bug has been read. You must call unfilelock(); if something not undef is returned from read_bug."
.PD
.PP
One of \f(CW\*(C`bug\*(C'\fR or \f(CW\*(C`summary\*(C'\fR must be passed. This function will return
undef on failure, and will die if improper arguments are passed.
.SS "split_status_fields"
.IX Subsection "split_status_fields"
.Vb 1
\&     my @data = split_status_fields(@data);
.Ve
.PP
Splits splittable status fields (like package, tags, blocks,
blockedby, etc.) into arrayrefs (use make_list on these). Keeps the
passed \f(CW@data\fR intact using dclone.
.PP
In scalar context, returns only the first element of \f(CW@data\fR.
.SS "join_status_fields"
.IX Subsection "join_status_fields"
.Vb 1
\&     my @data = join_status_fields(@data);
.Ve
.PP
Handles joining the splitable status fields. (Basically, the inverse
of split_status_fields.
.PP
Primarily called from makestatus, but may be useful for other
functions after calling split_status_fields (or for legacy functions
if we transition to split fields by default).
.SS "lockreadbug"
.IX Subsection "lockreadbug"
.Vb 1
\&     lockreadbug($bug_num,$location)
.Ve
.PP
Performs a filelock, then reads the bug; the bug is unlocked if the
return is undefined, otherwise, you need to call unfilelock or
unlockwritebug.
.PP
See readbug above for information on what this returns
.SS "lockreadbugmerge"
.IX Subsection "lockreadbugmerge"
.Vb 1
\&     my ($locks, $data) = lockreadbugmerge($bug_num,$location);
.Ve
.PP
Performs a filelock, then reads the bug. If the bug is merged, locks
the merge lock. Returns a list of the number of locks and the bug
data.
.SS "lock_read_all_merged_bugs"
.IX Subsection "lock_read_all_merged_bugs"
.Vb 1
\&     my ($locks,@bug_data) = lock_read_all_merged_bugs($bug_num,$location);
.Ve
.PP
Performs a filelock, then reads the bug passed. If the bug is merged,
locks the merge lock, then reads and locks all of the other merged
bugs. Returns a list of the number of locks and the bug data for all
of the merged bugs.
.PP
Will also return undef if any of the merged bugs failed to be read,
even if all of the others were read properly.
.SS "makestatus"
.IX Subsection "makestatus"
.Vb 2
\&     my $content = makestatus($status,$version)
\&     my $content = makestatus($status);
.Ve
.PP
Creates the content for a status file based on the \f(CW$status\fR hashref
passed.
.PP
Really only useful for writebug
.PP
Currently defaults to version 2 (non-encoded rfc1522 names) but will
eventually default to version 3. If you care, you should specify a
version.
.SS "writebug"
.IX Subsection "writebug"
.Vb 1
\&     writebug($bug_num,$status,$location,$minversion,$disablebughook)
.Ve
.PP
Writes the bug status and summary files out.
.PP
Skips writting out a status file if minversion is 2
.PP
Does not call bughook if disablebughook is true.
.SS "unlockwritebug"
.IX Subsection "unlockwritebug"
.Vb 1
\&     unlockwritebug($bug_num,$status,$location,$minversion,$disablebughook);
.Ve
.PP
Writes a bug, then calls unfilelock; see writebug for what these
options mean.
.SH "VERSIONS"
.IX Header "VERSIONS"
The following functions are exported with the :versions tag
.SS "addfoundversions"
.IX Subsection "addfoundversions"
.Vb 1
\&     addfoundversions($status,$package,$version,$isbinary);
.Ve
.PP
All use of this should be phased out in favor of Debbugs::Control::fixed/found
.SS "removefoundversions"
.IX Subsection "removefoundversions"
.Vb 1
\&     removefoundversions($data,$package,$versiontoremove)
.Ve
.PP
Removes found versions from \f(CW$data\fR
.PP
If a version is fully qualified (contains /) only versions matching
exactly are removed. Otherwise, all versions matching the version
number are removed.
.PP
Currently \f(CW$package\fR and \f(CW$isbinary\fR are entirely ignored, but accepted
for backwards compatibilty.
.SS "splitpackages"
.IX Subsection "splitpackages"
.Vb 1
\&     splitpackages($pkgs)
.Ve
.PP
Split a package string from the status file into a list of package names.
.SS "bug_archiveable"
.IX Subsection "bug_archiveable"
.Vb 1
\&     bug_archiveable(bug => $bug_num);
.Ve
.PP
Options
.IP "bug \*(-- bug number (required)" 4
.IX Item "bug  bug number (required)"
.PD 0
.IP "status \*(-- Status hashref returned by read_bug or get_bug_status (optional)" 4
.IX Item "status  Status hashref returned by read_bug or get_bug_status (optional)"
.IP "version \*(-- Debbugs::Version information (optional)" 4
.IX Item "version  Debbugs::Version information (optional)"
.IP "days_until \*(-- return days until the bug can be archived" 4
.IX Item "days_until  return days until the bug can be archived"
.PD
.PP
Returns 1 if the bug can be archived
Returns 0 if the bug cannot be archived
.PP
If days_until is true, returns the number of days until the bug can be
archived, \-1 if it cannot be archived. 0 means that the bug can be
archived the next time the archiver runs.
.PP
Returns undef on failure.
.SS "get_bug_status"
.IX Subsection "get_bug_status"
.Vb 1
\&     my $status = get_bug_status(bug => $nnn);
\&
\&     my $status = get_bug_status($bug_num)
.Ve
.PP
\fIOptions\fR
.IX Subsection "Options"
.IP "bug \*(-- scalar bug number" 4
.IX Item "bug  scalar bug number"
.PD 0
.IP "status \*(-- optional hashref of bug status as returned by readbug (can be passed to avoid rereading the bug information)" 4
.IX Item "status  optional hashref of bug status as returned by readbug (can be passed to avoid rereading the bug information)"
.IP "bug_index \*(-- optional tied index of bug status infomration; currently not correctly implemented." 4
.IX Item "bug_index  optional tied index of bug status infomration; currently not correctly implemented."
.IP "version \*(-- optional version(s) to check package status at" 4
.IX Item "version  optional version(s) to check package status at"
.IP "dist \*(-- optional distribution(s) to check package status at" 4
.IX Item "dist  optional distribution(s) to check package status at"
.IP "arch \*(-- optional architecture(s) to check package status at" 4
.IX Item "arch  optional architecture(s) to check package status at"
.IP "bugusertags \*(-- optional hashref of bugusertags" 4
.IX Item "bugusertags  optional hashref of bugusertags"
.ie n .IP "sourceversion \*(-- optional arrayref of source/version; overrides dist, arch, and version. [The entries in this array must be in the ""source/version"" format.] Eventually this can be used to for caching." 4
.el .IP "sourceversion \*(-- optional arrayref of source/version; overrides dist, arch, and version. [The entries in this array must be in the ``source/version'' format.] Eventually this can be used to for caching." 4
.IX Item "sourceversion  optional arrayref of source/version; overrides dist, arch, and version. [The entries in this array must be in the source/version format.] Eventually this can be used to for caching."
.IP "indicatesource \*(-- if true, indicate which source packages this bug could belong to (or does belong to in the case of bugs assigned to a source package). Defaults to true." 4
.IX Item "indicatesource  if true, indicate which source packages this bug could belong to (or does belong to in the case of bugs assigned to a source package). Defaults to true."
.PD
.PP
Note: Currently the version information is cached; this needs to be
changed before using this function in long lived programs.
.SS "bug_presence"
.IX Subsection "bug_presence"
.Vb 3
\&     my $precence = bug_presence(bug => nnn,
\&                                 ...
\&                                );
.Ve
.PP
Returns 'found', 'absent', 'fixed' or undef based on whether the bug
is found, absent, fixed, or no information is available in the
distribution (dist) and/or architecture (arch) specified.
.PP
\fIOptions\fR
.IX Subsection "Options"
.IP "bug \*(-- scalar bug number" 4
.IX Item "bug  scalar bug number"
.PD 0
.IP "status \*(-- optional hashref of bug status as returned by readbug (can be passed to avoid rereading the bug information)" 4
.IX Item "status  optional hashref of bug status as returned by readbug (can be passed to avoid rereading the bug information)"
.IP "bug_index \*(-- optional tied index of bug status infomration; currently not correctly implemented." 4
.IX Item "bug_index  optional tied index of bug status infomration; currently not correctly implemented."
.IP "version \*(-- optional version to check package status at" 4
.IX Item "version  optional version to check package status at"
.IP "dist \*(-- optional distribution to check package status at" 4
.IX Item "dist  optional distribution to check package status at"
.IP "arch \*(-- optional architecture to check package status at" 4
.IX Item "arch  optional architecture to check package status at"
.ie n .IP "sourceversion \*(-- optional arrayref of source/version; overrides dist, arch, and version. [The entries in this array must be in the ""source/version"" format.] Eventually this can be used to for caching." 4
.el .IP "sourceversion \*(-- optional arrayref of source/version; overrides dist, arch, and version. [The entries in this array must be in the ``source/version'' format.] Eventually this can be used to for caching." 4
.IX Item "sourceversion  optional arrayref of source/version; overrides dist, arch, and version. [The entries in this array must be in the source/version format.] Eventually this can be used to for caching."
.PD
.SS "max_buggy"
.IX Subsection "max_buggy"
.Vb 1
\&     max_buggy()
.Ve
.PP
\fIOptions\fR
.IX Subsection "Options"
.IP "bug \*(-- scalar bug number" 4
.IX Item "bug  scalar bug number"
.PD 0
.ie n .IP "sourceversion \*(-- optional arrayref of source/version; overrides dist, arch, and version. [The entries in this array must be in the ""source/version"" format.] Eventually this can be used to for caching." 4
.el .IP "sourceversion \*(-- optional arrayref of source/version; overrides dist, arch, and version. [The entries in this array must be in the ``source/version'' format.] Eventually this can be used to for caching." 4
.IX Item "sourceversion  optional arrayref of source/version; overrides dist, arch, and version. [The entries in this array must be in the source/version format.] Eventually this can be used to for caching."
.PD
.PP
Note: Currently the version information is cached; this needs to be
changed before using this function in long lived programs.
.SS "buggy"
.IX Subsection "buggy"
.Vb 6
\&     buggy(bug => nnn,
\&           found => \e@found,
\&           fixed => \e@fixed,
\&           package => \*(Aqfoo\*(Aq,
\&           version => \*(Aq1.0\*(Aq,
\&          );
.Ve
.PP
Returns the output of Debbugs::Versions::buggy for a particular
package, version and found/fixed set. Automatically turns found, fixed
and version into source/version strings.
.PP
Caching can be had by using the version_cache, but no attempt to check
to see if the on disk information is more recent than the cache is
made. [This will need to be fixed for long-lived processes.]
.SH "PRIVATE FUNCTIONS"
.IX Header "PRIVATE FUNCTIONS"