Debbugs::Common(3pm)

💖 Debbugs::Common 💖

okay so bestie, you're looking at the manual for Debbugs::Common — that's Debbugs::Common(3pm) in the User Contributed Perl Documentation set, and yes, this is the module that's basically the shared brain cell for all of Debbugs. Pinned it for you 💅

---

🌸 NAME 🌸

Debbugs::Common — the common routines for all of Debbugs. like, everybody uses these. main character shared code, periodt.

---

✨ SYNOPSIS ✨

use Debbugs::Common qw(:url :html);

that's it. that's the whole vibe. import some tags and go 🦋

---

🎀 DESCRIPTION 🎀

So this module is a replacement for the general parts of errorlib.pl. the subroutines in errorlib.pl are gonna be gradually phased out and swapped for equivalent (or honestly, better) functionality in here. so if you see errorlib.pl still hanging around, no you didn't, it's on its way out 🫶

---

👑 FUNCTIONS 👑

🧰 UTILITIES 🧰

these ones are exported by the :util tag. little toolbox, love that for you.

💜 getbugcomponent

my $file = getbugcomponent($bug_number,$extension,$location)

returns the path to the bug file. you give it a location in $location, a bug number in $bugnumber, and an $extension, and it hands you the path. slay.

💜 getbuglocation

getbuglocation($bug_number,$extension)

returns the location where a particular bug exists. the valid locations it can return right now are archive, db-h, or db. and if the bug doesn't exist? returns undef. ghosted 😭

💜 getlocationpath

getlocationpath($location)

returns the path to a specific location. simple. clean. iconic.

💜 get_hashname

get_hashname

returns the hash of the bug — that's the location within the archive, iykyk.

💜 buglog

buglog($bugnum);

returns the path to the logfile that corresponds to the bug.

returns undef if the bug does not exist. no bug, no log, no problem 💀

💜 bug_status

bug_status($bugnum)

returns the path to the summary file corresponding to the bug.

returns undef if the bug does not exist. same energy fr fr.

💜 appendfile

appendfile($file,'data','to','append');

opens a file for appending and writes data to it. that's the whole thing bestie 🍓

💜 overwritefile

ovewritefile($file,'data','to','append');

⚠️ yes, the function name is spelled ovewritefile in the synopsis. I am NOT fixing it. facts are facts.

opens file.new, writes data to it, then moves file.new to file. so it's the sneaky-replace move. very demure, very atomic ✨

💜 open_compressed_file

my $fh = open_compressed_file('foo.gz') or
     die "Unable to open compressed file: $!";

opens a file — and here's the cute part — if the file ends in .gz, .xz, or .bz2, the appropriate decompression program gets forked and its output is read. team effort 💖

by default this routine opens the file with UTF-8 encoding. want some other encoding? specify it with the second option. we support your journey 🌈

💜 getparsedaddrs

my $address = getparsedaddrs($address);
my @address = getparsedaddrs($address);

returns the output from Mail::Address->parse, or the cached output if this address has already been parsed before. caching?? we love a queen who remembers 😌

in SCALAR context it returns the first address parsed.

💜 getmaintainers

my $maintainer = getmaintainers()->{debbugs}

returns a hashref of package => maintainer pairs. look up a package, get the person. matchmaker behavior 💅

💜 getmaintainers_reverse

my @packages = @{getmaintainers_reverse->{'don@debian.org'}||[]};

returns a hashref of maintainer => [qw(list of packages)] pairs. so the reverse. look up a person, get the packages. obsessed 🔥

💜 package_maintainer

my @s = package_maintainer(source => [qw(foo bar baz)],
                           binary => [qw(bleh blah)],
                          );

the options, bestie:

• source — scalar or arrayref of source package names to return maintainers for; defaults to the empty arrayref.
• binary — scalar or arrayref of binary package names to return maintainers for; automatically returns the source package maintainer if the package name starts with 'src:', defaults to the empty arrayref.
• reverse — whether to return the source/binary packages a maintainer maintains instead.
• rehash — whether to reread the maintainer and source maintainer files; defaults to 0.

not the rehash option doing unpaid labor 🫠

💜 getpseudodesc

my $pseudopkgdesc = getpseudodesc(...);

returns the entry for a pseudo package from the $config{pseudo_desc_file}. and in cases where pseudo_desc_file is not defined? returns an empty arrayref. no drama.

this function can also be used to see if a particular package is a pseudopackage or not. vibe check for pseudopackages ✅

💜 sort_versions

sort_versions('1.0-2','1.1-2');

sorts versions using AptPkg::Versions::compare if it is available, or Debbugs::Versions::Dpkg::vercmp if it isn't. backup plan AND a slay plan 💖

---

📅 DATE 📅

my $english = secs_to_english($seconds);
my ($days,$english) = secs_to_english($seconds);

XXX This should probably be changed to use Date::Calc

noted. leaving the note exactly where it is because the original said it and we do not editorialize on the facts 🙈

---

🔒 LOCK 🔒

these functions are exported with the :lock tag. concurrency besties, gather round 🧚

🔐 filelock

filelock($lockfile);
filelock($lockfile,$locks);

FLOCKs the passed file. use unfilelock to unlock it.

can be passed an optional $locks hashref, which is used to track which files are locked (and how many times they have been locked) to allow for cooperative locking. teamwork makes the dream work 💜

🔐 simple_filelock

my ($fh,$t_lockfile,$errors) =
    simple_filelock($lockfile,$count,$wait);

does a flock of lockfile. if $count is zero, does a blocking lock. otherwise, does a non-blocking lock $count times, waiting $wait seconds in between. patience is a virtue, apparently ⏳

in list context, returns the lockfile filehandle, lockfile name, and any errors which occured.

when the lockfile filehandle is undef, locking failed. sad!

⚠️ these lockfiles must be unlocked manually at process end. nobody's coming to save you, bestie. you gotta do it 💅

🔐 simple_unlockfile

simple_unlockfile($fh,$lockfile);

🔐 unfilelock

unfilelock()
unfilelock($locks);

unlocks the file most recently locked.

note that it is not currently possible to unlock a specific file locked with filelock. so it's a stack, basically. LIFO girlies rise 😭

🔐 lockpid

lockpid('/path/to/pidfile');

creates a pidfile '/path/to/pidfile' if one doesn't exist or if the pid in the file does not respond to kill 0.

returns 1 on success, false on failure; dies on unusual errors. dramatic but fair 🎀

🔐 checkpid

checkpid('/path/to/pidfile');

checks a pid file and determines if the process listed in the pidfile is still running.

returns the pid if it is, 0 if it isn't running, and undef if the pidfile doesn't exist or cannot be read. three outcomes, three moods 🌸

---

🚪 QUIT 🚪

these functions are exported with the :quit tag.

💀 quit

quit()

exits the program by calling die.

Usage of quit is deprecated; just call die instead. it's giving legacy. it's giving retirement party. don't use it, bestie 💀

---

🎲 MISC 🎲

these functions are exported with the :misc tag. the grab bag!! the little treats!! 🍓

🌟 make_list

LIST = make_list(@_);

turns a scalar or an arrayref into a list; expands a list of arrayrefs into a list.

that is, make_list([qw(a b c)]); returns qw(a b c); make_list([qw(a b)],[qw(c d)] returns qw(a b c d); — flattening like it's nothing, no cap 🔥

🌟 english_join

print english_join(list => \@list);
print english_join(\@list);

joins list properly to make an english phrase. grammatically correct AND cute, we stan 🎀

• normal — how to separate most values; defaults to ', '
• last — how to separate the last two values; defaults to ', and '
• only_two — how to separate only two values; defaults to ' and '
• list — ARRAYREF values to join; if the first argument is an ARRAYREF, it's assumed to be the list of values to join

in cases where "list" is empty, returns ''; when there is only one element, returns that element. special cases handled, queen behavior 👑

🌟 globify_scalar

my $handle = globify_scalar(\$foo);

if $foo isn't already a glob or a globref, turn it into one using IO::Scalar. gives a new handle to /dev/null if $foo isn't defined.

will carp if given a scalar which isn't a scalarref or a glob (or globref), and return /dev/null. may return undef if IO::Scalar or IO::File fails. (Check $!) 👀

⚠️ the scalar will fill with octets, not perl's internal encoding, so you must use decode_utf8() after on the scalar, and encode_utf8() on it before. This appears to be a bug in the underlying modules. not us, not our fault, but we're telling you anyway 🫶

🌟 cleanup_eval_fail()

print "Something failed with: ".cleanup_eval_fail($@);

does various bits of cleanup on the failure message from an eval (or any other die message).

takes at most two options; the first is the actual failure message (usually $@ and defaults to $@), the second is the debug level (defaults to $DEBUG).

if debug is non-zero, the code at which the failure occured is output. receipts!! we love receipts 🔍

🌟 hash_slice

hash_slice(%hash,qw(key1 key2 key3))

for each key, returns matching values and keys of the hash if they exist. if it's not there, it's not there 💅

---

and that's the whole page, bestie!! this manual page was served up by perl v5.40.1, dated 2026-04-27, and it's the Debbugs::Common(3pm) page from the User Contributed Perl Documentation 💖✨🦋 you read the whole thing, that's main character energy, go drink some water 🌸