Use perldoc to Find, Inspect and Save Perl Documentation

By the end of this guide you will be able to use the installed perldoc command to locate Perl documentation, search built-in functions and FAQ questions, inspect a module's source, and save output for later use. These examples target perldoc v3.2801 from Perl v5.38.2 on Linux, supplied by the perl-doc package.

You need a shell and a Perl installation. Most commands need no elevated privileges. Allow about 10 minutes for the first pass. The examples read documentation; only the save-to-file example creates a file, and it uses a disposable path.

1. Check the installed command

Start by checking which executable will run and asking perldoc for its version. The version switch is -V, with a capital letter.

$ command -v perldoc
/usr/bin/perldoc
$ perldoc -V
Perldoc v3.2801, under perl v5.038002 for linux

Your version may differ. Keep that detail when comparing output with another machine. A common distraction is trying perldoc --version; this installed command treats that as an unknown option and prints help instead.

2. Read a module or named documentation page

Give perldoc a module name, program name, or page name. Nested module names may use either :: or a slash. The -T option sends plain output directly to standard output instead of opening a pager, which makes commands predictable in scripts and logs.

$ perldoc -T File::Basename
$ perldoc -T perlfunc
$ perldoc -T File/Basename

A simple name gets a useful fallback search: perldoc intro can find perlintro when the direct lookup does not find a page. If you omit -T in an interactive terminal, perldoc may use a pager selected from PERLDOC_PAGER, MANPAGER or PAGER. Press the pager's quit key when you are done.

3. Look up a function, variable or FAQ question

Use the specialised switches when you know what kind of Perl item you need. They avoid a broad page search and make the intent clear.

$ perldoc -T -f sprintf
$ perldoc -T -v '$"'
$ perldoc -T -q shuffle

-f searches Perl's built-in function documentation. -v searches predefined variables, so quote shell-sensitive values such as $". -q treats its argument as a regular expression and searches question headings in perlfaq1 through perlfaq9. It searches the questions, not the answers, so use a distinctive word from the heading.

For the Perl C API, use -a followed by an API function name:

$ perldoc -T -a newHV

If a lookup fails, first check spelling and whether the relevant documentation package is installed. A missing page is not evidence that the module itself is absent.

4. Find the file without opening its documentation

Use -l when you need the installed path to a module. This is useful before reviewing local source or checking which installation a process will use.

$ perldoc -T -l File::Basename
/usr/share/perl/5.38/File/Basename.pm

The result is a path, not a copy. Treat it as read-only unless you have a specific development reason to edit an installed file. A local project can affect lookup: in a directory containing Makefile.PL or Build.PL, perldoc searches project directories such as lib early, and may include blib for a non-root user.

5. Inspect source, or show raw Pod

Use -m to display a module's complete file, including its code and embedded documentation. Use -u when you want the raw, unformatted Pod instead.

$ perldoc -T -m File::Basename
$ perldoc -T -u File::Basename

These modes can produce much more output than a normal documentation page. Do not pipe an unfamiliar module into a shell or an editor command that writes automatically. Read it as text. If you use -m interactively, the source pager can be selected with PERLDOC_SRC_PAGER; leave that variable unset unless you understand the command it invokes.

6. Save documentation to a file

The -d option writes output to a named file instead of standard output or a pager. The destination is created or replaced, so choose a new path or check it first.

$ tmp_doc="$(mktemp /tmp/perldoc.XXXXXX)"
$ perldoc -o text -d "$tmp_doc" File::Basename
$ test -s "$tmp_doc" && printf 'saved: %s\n' "$tmp_doc"
saved: /tmp/perldoc.ab12CD
$ rm -- "$tmp_doc"

The random suffix will differ. The final command removes only the temporary file created by this example. If you need a durable file, replace the path with an explicit destination after checking that it does not contain valuable data. No sudo is required for a file you can write.

7. Keep the security boundary clear

Do not run perldoc as root just to read documentation. The manpage says that, because perldoc is not properly taint-safe and has known security issues, it attempts to drop privileges when run as the superuser. If you use -U, it will not attempt that drop, and the documented security risks are significant. The -F option treats arguments as file names and implies -U for the superuser.

For ordinary lookups, use an unprivileged account and avoid placing untrusted directories first in PERL5LIB, PERLLIB or PATH. Those variables influence where perldoc searches. Also remember that switches in the PERLDOC environment variable are applied before command-line arguments. If output seems inexplicably different, inspect that variable:

$ printf 'PERLDOC=%s\n' "${PERLDOC-}"
$ env -u PERLDOC perldoc -T -V
Perldoc v3.2801, under perl v5.038002 for linux