Find and Save Perl Documentation with perldoc

Half the battle with Perl is remembering which page has the answer, and perldoc is the tool that finds it for you without a web search. This guide covers locating module and function documentation, searching FAQ questions, inspecting a module's source, and saving output to a file. These examples target perldoc v3.2801 from Perl v5.38.2 on Linux, supplied by the perl-doc package.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Check the installed command
2. Read a module or named documentation page
3. Look up a function, variable or FAQ question
4. Find the file without opening its documentation
5. Inspect source, or show raw Pod
6. Save documentation to a file
7. Keep the security boundary clear

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.
Watch for the wrong switch. A common distraction is trying perldoc --version; this installed command treats that as an unknown option and prints help instead.

Checkpoint

Continue when command -v finds the executable and perldoc -V prints a version.

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

Tip

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 built-in functions. It covers Perl's own function documentation.
-v searches predefined variables. Quote shell-sensitive values such as $".
-q searches FAQ questions. It treats its argument as a regular expression and searches question headings in perlfaq1 through perlfaq9, so use a distinctive word from the heading, not the answer.
-a searches the Perl C API. Follow it with 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

Warning

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

Security warning

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

Done means

Version identified. perldoc -V reported the installed version.
Lookup and location both work. You can read a module page with -T and locate its file with -l.
Switches understood. You know when to use -f, -v, -q and -a.
Source inspected safely. You can view source or raw Pod without treating it as an executable script.
Output saved cleanly. You saved output to a checked destination and removed the disposable file.
Root avoided. You steered clear of root, unexplained environment settings and the risky -U option.