man pages section 1: User Commands

Exit Print View

Updated: July 2014

perlutil (1)


perlutil - utilities packaged with the Perl distribution


Please see following description for synopsis


Perl Programmers Reference Guide                      PERLUTIL(1)

     perlutil - utilities packaged with the Perl distribution

     Along with the Perl interpreter itself, the Perl
     distribution installs a range of utilities on your system.
     There are also several utilities which are used by the Perl
     distribution itself as part of the install process. This
     document exists to list all of these utilities, explain what
     they are for and provide pointers to each module's
     documentation, if appropriate.

        The main interface to Perl's documentation is "perldoc",
        although if you're reading this, it's more than likely
        that you've already found it. perldoc will extract and
        format the documentation from any file in the current
        directory, any Perl module installed on the system, or
        any of the standard documentation pages, such as this
        one. Use "perldoc <name>" to get information on any of
        the utilities described in this document.

     pod2man and pod2text
        If it's run from a terminal, perldoc will usually call
        pod2man to translate POD (Plain Old Documentation - see
        perlpod for an explanation) into a manpage, and then run
        man to display it; if man isn't available, pod2text will
        be used instead and the output piped through your
        favourite pager.

     pod2html and pod2latex
        As well as these two, there are two other converters:
        pod2html will produce HTML pages from POD, and pod2latex,
        which produces LaTeX files.

        If you just want to know how to use the utilities
        described here, pod2usage will just extract the "USAGE"
        section; some of the utilities will automatically call
        pod2usage on themselves when you call them with "-help".

        pod2usage is a special case of podselect, a utility to
        extract named sections from documents written in POD. For
        instance, while utilities have "USAGE" sections, Perl
        modules usually have "SYNOPSIS" sections: "podselect -s
        "SYNOPSIS" ..." will extract this section for a given


perl v5.12.5         Last change: 2012-11-03                    1

Perl Programmers Reference Guide                      PERLUTIL(1)

        If you're writing your own documentation in POD, the
        podchecker utility will look for errors in your markup.

        splain is an interface to perldiag - paste in your error
        message to it, and it'll explain it for you.

        The "roffitall" utility is not installed on your system
        but lives in the pod/ directory of your Perl source kit;
        it converts all the documentation from the distribution
        to *roff format, and produces a typeset PostScript or
        text file of the whole lot.

     To help you convert legacy programs to Perl, we've included
     three conversion filters:

        a2p converts awk scripts to Perl programs; for example,
        "a2p -F:" on the simple awk script "{print $2}" will
        produce a Perl program based around this code:

            while (<>) {
                ($Fld1,$Fld2) = split(/[:\n]/, $_, -1);
                print $Fld2;

     s2p and psed
        Similarly, s2p converts sed scripts to Perl programs. s2p
        run on "s/foo/bar" will produce a Perl program based
        around this:

            while (<>) {
                print if $printit;

        When invoked as psed, it behaves as a sed implementation,
        written in Perl.

        Finally, find2perl translates "find" commands to Perl
        equivalents which use the File::Find module. As an
        example, "find2perl . -user root -perm 4000 -print"
        produces the following callback subroutine for

perl v5.12.5         Last change: 2012-11-03                    2

Perl Programmers Reference Guide                      PERLUTIL(1)

            sub wanted {
                my ($dev,$ino,$mode,$nlink,$uid,$gid);
                (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) &&
                $uid == $uid{'root'}) &&
                (($mode & 0777) == 04000);

     As well as these filters for converting other languages, the
     pl2pm utility will help you convert old-style Perl 4
     libraries to new-style Perl5 modules.

        Query or change configuration of Perl modules that use
        Module::Build-based configuration files for features and
        config data.

        To display and change the libnet configuration run the
        libnetcfg command.

        The perlivp program is set up at Perl source code build
        time to test the Perl version it was built under.  It can
        be used after running "make install" (or your platform's
        equivalent procedure) to verify that perl and its
        libraries have been installed correctly.

     There are a set of utilities which help you in developing
     Perl programs, and in particular, extending Perl with C.

        perlbug is the recommended way to report bugs in the perl
        interpreter itself or any of the standard library modules
        back to the developers; please read through the
        documentation for perlbug thoroughly before using it to
        submit a bug report.

        This program provides an easy way to send a thank-you
        message back to the authors and maintainers of perl. It's
        just perlbug installed under another name.

        Back before Perl had the XS system for connecting with C
        libraries, programmers used to get library constants by
        reading through the C header files. You may still see
        "require ''" or similar around - the .ph file
        should be created by running h2ph on the corresponding .h
        file. See the h2ph documentation for more on how to

perl v5.12.5         Last change: 2012-11-03                    3

Perl Programmers Reference Guide                      PERLUTIL(1)

        convert a whole bunch of header files at once.

     c2ph and pstruct
        c2ph and pstruct, which are actually the same program but
        behave differently depending on how they are called,
        provide another way of getting at C with Perl - they'll
        convert C structures and union declarations to Perl code.
        This is deprecated in favour of h2xs these days.

        h2xs converts C header files into XS modules, and will
        try and write as much glue between C libraries and Perl
        modules as it can. It's also very useful for creating
        skeletons of pure Perl modules.

        enc2xs builds a Perl extension for use by Encode from
        either Unicode Character Mapping files (.ucm) or Tcl
        Encoding Files (.enc).  Besides being used internally
        during the build process of the Encode module, you can
        use enc2xs to add your own encoding to perl.  No
        knowledge of XS is necessary.

        xsubpp is a compiler to convert Perl XS code into C code.
        It is typically run by the makefiles created by

        xsubpp will compile XS code into C code by embedding the
        constructs necessary to let C functions manipulate Perl
        values and creates the glue necessary to let Perl access
        those functions.

        Perl comes with a profiler, the Devel::DProf module. The
        dprofpp utility analyzes the output of this profiler and
        tells you which subroutines are taking up the most run
        time. See Devel::DProf for more information.

        prove is a command-line interface to the test-running
        functionality of Test::Harness.  It's an alternative to
        "make test".

        A command-line front-end to "Module::CoreList", to query
        what modules were shipped with given versions of perl.

  General tools
     A few general-purpose tools are shipped with perl, mostly
     because they came along modules included in the perl

perl v5.12.5         Last change: 2012-11-03                    4

Perl Programmers Reference Guide                      PERLUTIL(1)

        piconv is a Perl version of iconv, a character encoding
        converter widely available for various Unixen today.
        This script was primarily a technology demonstrator for
        Perl 5.8.0, but you can use piconv in the place of iconv
        for virtually any case.

        ptar is a tar-like program, written in pure Perl.

        ptardiff is a small utility that produces a diff between
        an extracted archive and an unextracted one. (Note that
        this utility requires the "Text::Diff" module to function
        properly; this module isn't distributed with perl, but is
        available from the CPAN.)

        This utility, that comes with the "Digest::SHA" module,
        is used to print or verify SHA checksums.

     These utilities help manage extra Perl modules that don't
     come with the perl distribution.

        cpan is a command-line interface to  It allows
        you to install modules or distributions from CPAN, or
        just get information about them, and a lot more.  It is
        similar to the command line mode of the CPAN module,

            perl -MCPAN -e shell

        cpanp is, like cpan, a command-line interface to the
        CPAN, using the "CPANPLUS" module as a back-end. It can
        be used interactively or imperatively.

        cpan2dist is a tool to create distributions (or packages)
        from CPAN modules, then suitable for your package manager
        of choice. Support for specific formats are available
        from CPAN as "CPANPLUS::Dist::*" modules.

        A little interface to ExtUtils::Installed to examine
        installed modules, validate your packlists and even
        create a tarball from an installed module.

     See attributes(5) for descriptions of the following

perl v5.12.5         Last change: 2012-11-03                    5

Perl Programmers Reference Guide                      PERLUTIL(1)


     |Availability   | runtime/perl-512 |
     |Stability      | Uncommitted      |
     perldoc, pod2man, perlpod, pod2html, pod2usage, podselect,
     podchecker, splain, perldiag, roffitall, a2p, s2p,
     find2perl, File::Find, pl2pm, perlbug, h2ph, c2ph, h2xs,
     dprofpp, Devel::DProf, enc2xs, xsubpp, cpan, cpanp,
     cpan2dist, instmodsh, piconv, prove, corelist, ptar,
     ptardiff, shasum

     This software was built from source available at  The original
     community source was downloaded from

     Further information about this software can be found on the
     open source community website at

perl v5.12.5         Last change: 2012-11-03                    6