Use perlvms to Check Perl's OpenVMS Assumptions

You will finish with a local, version-aware reading of Perl's VMS notes: you will confirm which document is installed, check the Perl version it belongs to, and locate the sections that affect paths, extensions, pipes and environment variables. This is a reading and verification workflow. perlvms is a manual page, not a command that runs a Perl script.

Allow about 10 minutes for a first pass. You need a shell, the perl-doc package, and access to the Perl installation you are investigating. The commands below are ordinary user commands; none needs sudo.

1. Confirm that the document is installed

Start by asking the manual database for the page and checking the package that supplied it.

$ man -w perlvms
/usr/share/man/man1/perlvms.1.gz
$ dpkg-query -W -f='${Package} ${Version}\n' perl-doc

On an Ubuntu installation matching this guide, the package reports perl-doc 5.38.2-3.2ubuntu0.6. Your package revision may differ. Keep the result with any bug report or build note: documentation from one Perl release is not proof of identical behaviour in another.

2. Check the Perl version separately

The page header records the Perl release for which the documentation was generated, but check the interpreter you will actually use.

$ perl -e 'printf "perl %s\n", $^V; printf "perl executable: %s\n", $^X'
perl v5.38.2
perl executable: /usr/bin/perl

The exact executable path and version are machine-specific. If they do not match the package or the page header, stop and investigate the PATH, local Perl builds and documentation package before drawing compatibility conclusions.

3. Read the page as a supplement, not a general Perl tutorial

Open the page normally first.

$ man perlvms

The page describes how Perl 5 differs on OpenVMS from Unix. It deliberately does not replace the main Perl manual. On Linux, the useful outcome is usually a design or porting decision, not an attempt to execute the VMS examples in a POSIX shell.

For a non-interactive copy that is easy to search or attach to a review, use the compressed source directly:

$ zcat /usr/share/man/man1/perlvms.1.gz | less

Do not edit the decompressed output. It is generated manual-page input, and any changes would disappear when perl-doc is upgraded.

4. Find the file and extension rules first

When porting a script, begin with the sections that change how ordinary Perl code meets the operating system.

$ zcat /usr/share/man/man1/perlvms.1.gz | grep -n -E '^\.SH |^\.SS '
$ zcat /usr/share/man/man1/perlvms.1.gz | grep -n -E 'File specifications|Wildcard expansion|Pipes|PERL5LIB|Perl Extensions'

The first command lists the roff headings, while the second points to likely starting places. The source says that VMS Perl can work with VMS-style and Unix-style file specifications, but a single file specification must not mix the two syntaxes. It also documents explicit conversion through VMS::Filespec.

That distinction matters when reviewing code on Linux: a Unix path that looks harmless in a test is not evidence that the same string has the same meaning under VMS. Search for path construction, wildcard handling and assumptions about / before changing the script.

5. Review extensions without installing anything

Next, read the extension sections to decide whether a VMS build uses static or dynamic code.

$ man -P cat perlvms | sed -n '/Perl Extensions/,/File specifications/p' | less

The page describes static extensions as code linked into PerlShr.Exe. Dynamic extensions use a separate shareable image and are located through documented VMS library locations or a logical name. The example build tools are Makefile.PL and mmk, not a promise that a Linux make invocation will reproduce the build.

6. Check the environment details before changing code

Use the page's headings to find environment-sensitive behaviour, then compare it with the assumptions in your program.

$ man -P cat perlvms | grep -n -A18 -B3 'PERL5LIB and PERLLIB'
$ man -P cat perlvms | grep -n -A20 -B3 'PERL_VMS_EXCEPTION_DEBUG'

Among the documented differences, PERL5LIB and PERLLIB use | as the default element separator on VMS, while a Unix shell context uses :. The page also documents VMS logical names such as PERL_MBX_SIZE for pipe mailbox sizing and DECC$FILENAME_UNIX_REPORT for filename conversion behaviour.

These are names and rules to account for in VMS code, not Linux configuration instructions. Setting them in your current shell will not turn Linux Perl into VMS Perl. Avoid exporting a copied setting globally; if you need to test an environment change, scope it to one command and record the before-and-after result.

7. Recheck after an upgrade or a port

Repeat the version and page-path checks after changing Perl, switching containers or moving between distributions.

$ command -v perl
/usr/bin/perl
$ perl -v | sed -n '1,4p'
$ man -w perlvms
/usr/share/man/man1/perlvms.1.gz

If man reports that the page is missing, install the documentation package approved for that host or consult the matching Perl source tree. Do not silently substitute an online page from a different release when investigating a version-specific issue.