PERLDOC(1)       Perl Programmers Reference Guide      PERLDOC(1)



NAME
       perldoc - Look up Perl documentation in pod format.

SYNOPSIS
       perldoc [-h] [-v] [-t] [-u] [-m] [-l] [-F]  [-X] Page-
       Name|ModuleName|ProgramName

       perldoc -f BuiltinFunction

       perldoc -q FAQ Keyword

DESCRIPTION
       perldoc looks up a piece of documentation in .pod format
       that is embedded in the perl installation tree or in a
       perl script, and displays it via `pod2man | nroff -man |
       $PAGER'. (In addition, if running under HP-UX, `col -x'
       will be used.) This is primarily used for the documenta-
       tion for the perl library modules.

       Your system may also have man pages installed for those
       modules, in which case you can probably just use the
       man(1) command.

OPTIONS
       -h help
            Prints out a brief help message.

       -v verbose
            Describes search for the item in detail.

       -t text output
            Display docs using plain text converter, instead of
            nroff. This may be faster, but it won't look as nice.

       -u unformatted
            Find docs only; skip reformatting by pod2*

       -m module
            Display the entire module: both code and unformatted
            pod documentation.  This may be useful if the docs
            don't explain a function in the detail you need, and
            you'd like to inspect the code directly; perldoc will
            find the file for you and simply hand it off for dis-
            play.

       -l file name only
            Display the file name of the module found.

       -F file names
            Consider arguments as file names, no search in direc-
            tories will be performed.

       -f perlfunc
            The -f option followed by the name of a perl built in
            function will extract the documentation of this func-
            tion from the perlfunc manpage.

       -q perlfaq
            The -q option takes a regular expression as an argu-
            ment.  It will search the question headings in perl-
            faq[1-9] and print the entries matching the regular
            expression.

       -X use an index if present
            The -X option looks for a entry whose basename
            matches the name given on the command line in the
            file `$Config{archlib}/pod.idx'.  The pod.idx file
            should contain fully qualified filenames, one per
            line.

       -U run insecurely
            Because perldoc does not run properly tainted, and is
            known to have security issues, it will not normally
            execute as the superuser.  If you use the -U flag, it
            will do so, but only after setting the effective and
            real IDs to nobody's or nouser's account, or -2 if
            unavailable.  If it cannot relinguish its privileges,
            it will not run.

       PageName|ModuleName|ProgramName
            The item you want to look up.  Nested modules (such
            as `File::Basename') are specified either as
            `File::Basename' or `File/Basename'.  You may also
            give a descriptive name of a page, such as `perl-
            func'. You may also give a partial or wrong-case
            name, such as "basename" for "File::Basename", but
            this will be slower, if there is more then one page
            with the same partial name, you will only get the
            first one.

ENVIRONMENT
       Any switches in the `PERLDOC' environment variable will be
       used before the command line arguments.  `perldoc' also
       searches directories specified by the `PERL5LIB' (or `PER-
       LLIB' if `PERL5LIB' is not defined) and `PATH' environment
       variables.  (The latter is so that embedded pods for exe-
       cutables, such as `perldoc' itself, are available.)
       `perldoc' will use, in order of preference, the pager
       defined in `PERLDOC_PAGER', `MANPAGER', or `PAGER' before
       trying to find a pager on its own.  (`MANPAGER' is not
       used if `perldoc' was told to display plain text or unfor-
       matted pod.)

       One useful value for `PERLDOC_PAGER' is `less -+C -E'.

VERSION
       This is perldoc v2.01.

AUTHOR
       Kenneth Albanowski <kjahds@kjahds.com>

       Minor updates by Andy Dougherty <doughera@laf-
       col.lafayette.edu>, and others.



2002-07-14                 perl v5.6.0                 PERLDOC(1)