Check Perl and Hurd Compatibility Before Running the Test Suite

You will finish with a quick way to identify the Perl and operating system you are actually running, read the perlhurd documentation in the right context, and separate expected Hurd test limitations from a broken Perl installation. The installed page comes from perl-doc 5.38.2-3.2ubuntu0.6 and describes Perl 5 on GNU/Hurd. It is documentation, not an executable command.

Allow about fifteen minutes. You need a shell and the perl-doc package for the manual checks. The first five steps are ordinary, read-only commands. Network translator changes in the final section are for a GNU/Hurd machine only, can interrupt networking, and need an administrator's maintenance plan.

1. Confirm that the documentation is installed

Ask man where it found the page, then read it without changing the system:

$ man -w perlhurd
/usr/share/man/man1/perlhurd.1.gz
$ man perlhurd

The page heading is PERLHURD(1), but that section number does not make perlhurd a program. Do not type perlhurd as if it were a shell command. Use man perlhurd or perldoc perlhurd to open the documentation.

Checkpoint: if man -w perlhurd prints nothing, install the documentation through your normal package-management process. Do not copy a random manual page into /usr/share/man; its advice may belong to another Perl release.

2. Record the Perl build and operating system

Run these read-only checks before interpreting any test result:

$ command -v perl
/usr/bin/perl
$ perl -V:version -V:osname -V:archname
version='5.38.2';
osname='linux';
archname='x86_64-linux-gnu-thread-multi';

Your paths and architecture can differ. On this Linux installation, the result is Perl 5.38.2 built for Linux, not a GNU/Hurd Perl. The local manual itself has a 2026 generated header, but its prose retains an old example for Perl 5.005_62 and says it was last updated in 1999. Treat that test table as historical evidence, not as a current pass or fail target.

A shorter runtime check is useful in scripts:

$ perl -MConfig -e 'print "os=$Config{osname} perl=$^V\n"'
os=linux perl=v5.38.2

3. Run a small Perl smoke test

Check that the interpreter can execute a basic program before investigating platform-specific behaviour:

$ perl -e 'print "perl-smoke-ok\n"'
perl-smoke-ok
$ printf 'exit status: %s\n' "$?"
exit status: 0

This proves only that this Perl process started, ran the statement and returned success. It does not exercise Hurd translators, sockets or the complete Perl test suite. If this command fails, inspect the interpreter path, package state and error text first. Running it with sudo will not repair a broken Perl installation and can hide a permissions mistake.

4. Interpret the test-suite warnings in perlhurd

The manual says that some tests may fail on Hurd. It specifically names lib/anydbm and pragma/warnings as likely failures, while explaining that those failures are not necessarily Hurd-specific. It also says socket tests can fail when the network is not configured, and lists op/stat, lib/io_pipe, lib/io_sock, lib/io_udp and lib/time as possible failures on a particular Hurd snapshot.

Do not convert that list into an automatic allow-list. Capture the exact Perl version, Hurd version, failed test names and full diagnostics. A failure outside the documented candidates deserves investigation, but a documented candidate still needs checking against the current machine. The page recommends upgrading Hurd before reporting failures that go beyond its examples.

Checkpoint: classify the result before changing anything.

• A smoke test failure is an interpreter or local environment problem.
• A documented Hurd test failure may be an environment or platform limitation.
• A socket failure may indicate missing Hurd network configuration, not a Perl socket defect.
• The 5.005_62 statistics are not evidence about Perl 5.38.2.

5. Check the Hurd networking boundary

The socket advice applies only when Perl is running on GNU/Hurd. The Hurd uses a translator for this part of the system. The relevant translator is /hurd/pfinet, attached to /servers/socket/2. On an ordinary Linux host, that path is not expected to exist:

$ test -x /hurd/pfinet
$ printf 'pfinet executable status: %s\n' "$?"
pfinet executable status: 1

That result is a useful boundary check, not a reason to create the path. Do not run a Hurd settrans command on Linux. On GNU/Hurd, first ask the installed translator for its own supported arguments:

$ /hurd/pfinet --help

Only after identifying the correct interface, address, gateway and netmask should an administrator consider attaching it. The operation changes the system's socket translator and can disrupt every networked process. Work from the machine's Hurd documentation and keep a recovery path. The GNU Hurd documentation describes the shape of the operation as:

# settrans -fgap /servers/socket/2 /hurd/pfinet \
    -i INTERFACE -a IP_ADDRESS -g GATEWAY -m NETMASK

The values above are placeholders, not safe defaults. Do not paste them unchanged. Record the existing translator state before a planned change and use the distribution's documented method to restore it if networking stops. No Hurd networking change is needed for the Linux smoke tests in this guide.