1*0Sstevel@tonic-gate=head1 NAME 2*0Sstevel@tonic-gate 3*0Sstevel@tonic-gateperlutil - utilities packaged with the Perl distribution 4*0Sstevel@tonic-gate 5*0Sstevel@tonic-gate=head1 DESCRIPTION 6*0Sstevel@tonic-gate 7*0Sstevel@tonic-gateAlong with the Perl interpreter itself, the Perl distribution installs a 8*0Sstevel@tonic-gaterange of utilities on your system. There are also several utilities 9*0Sstevel@tonic-gatewhich are used by the Perl distribution itself as part of the install 10*0Sstevel@tonic-gateprocess. This document exists to list all of these utilities, explain 11*0Sstevel@tonic-gatewhat they are for and provide pointers to each module's documentation, 12*0Sstevel@tonic-gateif appropriate. 13*0Sstevel@tonic-gate 14*0Sstevel@tonic-gate=head2 DOCUMENTATION 15*0Sstevel@tonic-gate 16*0Sstevel@tonic-gate=over 3 17*0Sstevel@tonic-gate 18*0Sstevel@tonic-gate=item L<perldoc|perldoc> 19*0Sstevel@tonic-gate 20*0Sstevel@tonic-gateThe main interface to Perl's documentation is C<perldoc>, although 21*0Sstevel@tonic-gateif you're reading this, it's more than likely that you've already found 22*0Sstevel@tonic-gateit. F<perldoc> will extract and format the documentation from any file 23*0Sstevel@tonic-gatein the current directory, any Perl module installed on the system, or 24*0Sstevel@tonic-gateany of the standard documentation pages, such as this one. Use 25*0Sstevel@tonic-gateC<perldoc E<lt>nameE<gt>> to get information on any of the utilities 26*0Sstevel@tonic-gatedescribed in this document. 27*0Sstevel@tonic-gate 28*0Sstevel@tonic-gate=item L<pod2man|pod2man> and L<pod2text|pod2text> 29*0Sstevel@tonic-gate 30*0Sstevel@tonic-gateIf it's run from a terminal, F<perldoc> will usually call F<pod2man> to 31*0Sstevel@tonic-gatetranslate POD (Plain Old Documentation - see L<perlpod> for an 32*0Sstevel@tonic-gateexplanation) into a manpage, and then run F<man> to display it; if 33*0Sstevel@tonic-gateF<man> isn't available, F<pod2text> will be used instead and the output 34*0Sstevel@tonic-gatepiped through your favourite pager. 35*0Sstevel@tonic-gate 36*0Sstevel@tonic-gate=item L<pod2html|pod2html> and L<pod2latex|pod2latex> 37*0Sstevel@tonic-gate 38*0Sstevel@tonic-gateAs well as these two, there are two other converters: F<pod2html> will 39*0Sstevel@tonic-gateproduce HTML pages from POD, and F<pod2latex>, which produces LaTeX 40*0Sstevel@tonic-gatefiles. 41*0Sstevel@tonic-gate 42*0Sstevel@tonic-gate=item L<pod2usage|pod2usage> 43*0Sstevel@tonic-gate 44*0Sstevel@tonic-gateIf you just want to know how to use the utilities described here, 45*0Sstevel@tonic-gateF<pod2usage> will just extract the "USAGE" section; some of 46*0Sstevel@tonic-gatethe utilities will automatically call F<pod2usage> on themselves when 47*0Sstevel@tonic-gateyou call them with C<-help>. 48*0Sstevel@tonic-gate 49*0Sstevel@tonic-gate=item L<podselect|podselect> 50*0Sstevel@tonic-gate 51*0Sstevel@tonic-gateF<pod2usage> is a special case of F<podselect>, a utility to extract 52*0Sstevel@tonic-gatenamed sections from documents written in POD. For instance, while 53*0Sstevel@tonic-gateutilities have "USAGE" sections, Perl modules usually have "SYNOPSIS" 54*0Sstevel@tonic-gatesections: C<podselect -s "SYNOPSIS" ...> will extract this section for 55*0Sstevel@tonic-gatea given file. 56*0Sstevel@tonic-gate 57*0Sstevel@tonic-gate=item L<podchecker|podchecker> 58*0Sstevel@tonic-gate 59*0Sstevel@tonic-gateIf you're writing your own documentation in POD, the F<podchecker> 60*0Sstevel@tonic-gateutility will look for errors in your markup. 61*0Sstevel@tonic-gate 62*0Sstevel@tonic-gate=item L<splain|splain> 63*0Sstevel@tonic-gate 64*0Sstevel@tonic-gateF<splain> is an interface to L<perldiag> - paste in your error message 65*0Sstevel@tonic-gateto it, and it'll explain it for you. 66*0Sstevel@tonic-gate 67*0Sstevel@tonic-gate=item L<roffitall|roffitall> 68*0Sstevel@tonic-gate 69*0Sstevel@tonic-gateThe C<roffitall> utility is not installed on your system but lives in 70*0Sstevel@tonic-gatethe F<pod/> directory of your Perl source kit; it converts all the 71*0Sstevel@tonic-gatedocumentation from the distribution to F<*roff> format, and produces a 72*0Sstevel@tonic-gatetypeset PostScript or text file of the whole lot. 73*0Sstevel@tonic-gate 74*0Sstevel@tonic-gate=back 75*0Sstevel@tonic-gate 76*0Sstevel@tonic-gate=head2 CONVERTORS 77*0Sstevel@tonic-gate 78*0Sstevel@tonic-gateTo help you convert legacy programs to Perl, we've included three 79*0Sstevel@tonic-gateconversion filters: 80*0Sstevel@tonic-gate 81*0Sstevel@tonic-gate=over 3 82*0Sstevel@tonic-gate 83*0Sstevel@tonic-gate=item L<a2p|a2p> 84*0Sstevel@tonic-gate 85*0Sstevel@tonic-gateF<a2p> converts F<awk> scripts to Perl programs; for example, C<a2p -F:> 86*0Sstevel@tonic-gateon the simple F<awk> script C<{print $2}> will produce a Perl program 87*0Sstevel@tonic-gatebased around this code: 88*0Sstevel@tonic-gate 89*0Sstevel@tonic-gate while (<>) { 90*0Sstevel@tonic-gate ($Fld1,$Fld2) = split(/[:\n]/, $_, 9999); 91*0Sstevel@tonic-gate print $Fld2; 92*0Sstevel@tonic-gate } 93*0Sstevel@tonic-gate 94*0Sstevel@tonic-gate=item L<s2p|s2p> 95*0Sstevel@tonic-gate 96*0Sstevel@tonic-gateSimilarly, F<s2p> converts F<sed> scripts to Perl programs. F<s2p> run 97*0Sstevel@tonic-gateon C<s/foo/bar> will produce a Perl program based around this: 98*0Sstevel@tonic-gate 99*0Sstevel@tonic-gate while (<>) { 100*0Sstevel@tonic-gate chomp; 101*0Sstevel@tonic-gate s/foo/bar/g; 102*0Sstevel@tonic-gate print if $printit; 103*0Sstevel@tonic-gate } 104*0Sstevel@tonic-gate 105*0Sstevel@tonic-gate=item L<find2perl|find2perl> 106*0Sstevel@tonic-gate 107*0Sstevel@tonic-gateFinally, F<find2perl> translates C<find> commands to Perl equivalents which 108*0Sstevel@tonic-gateuse the L<File::Find|File::Find> module. As an example, 109*0Sstevel@tonic-gateC<find2perl . -user root -perm 4000 -print> produces the following callback 110*0Sstevel@tonic-gatesubroutine for C<File::Find>: 111*0Sstevel@tonic-gate 112*0Sstevel@tonic-gate sub wanted { 113*0Sstevel@tonic-gate my ($dev,$ino,$mode,$nlink,$uid,$gid); 114*0Sstevel@tonic-gate (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) && 115*0Sstevel@tonic-gate $uid == $uid{'root'}) && 116*0Sstevel@tonic-gate (($mode & 0777) == 04000); 117*0Sstevel@tonic-gate print("$name\n"); 118*0Sstevel@tonic-gate } 119*0Sstevel@tonic-gate 120*0Sstevel@tonic-gate=back 121*0Sstevel@tonic-gate 122*0Sstevel@tonic-gateAs well as these filters for converting other languages, the 123*0Sstevel@tonic-gateL<pl2pm|pl2pm> utility will help you convert old-style Perl 4 libraries to 124*0Sstevel@tonic-gatenew-style Perl5 modules. 125*0Sstevel@tonic-gate 126*0Sstevel@tonic-gate=head2 Administration 127*0Sstevel@tonic-gate 128*0Sstevel@tonic-gate=over 3 129*0Sstevel@tonic-gate 130*0Sstevel@tonic-gate=item L<libnetcfg|libnetcfg> 131*0Sstevel@tonic-gate 132*0Sstevel@tonic-gateTo display and change the libnet configuration run the libnetcfg command. 133*0Sstevel@tonic-gate 134*0Sstevel@tonic-gate=back 135*0Sstevel@tonic-gate 136*0Sstevel@tonic-gate=head2 Development 137*0Sstevel@tonic-gate 138*0Sstevel@tonic-gateThere are a set of utilities which help you in developing Perl programs, 139*0Sstevel@tonic-gateand in particular, extending Perl with C. 140*0Sstevel@tonic-gate 141*0Sstevel@tonic-gate=over 3 142*0Sstevel@tonic-gate 143*0Sstevel@tonic-gate=item L<perlbug|perlbug> 144*0Sstevel@tonic-gate 145*0Sstevel@tonic-gateF<perlbug> is the recommended way to report bugs in the perl interpreter 146*0Sstevel@tonic-gateitself or any of the standard library modules back to the developers; 147*0Sstevel@tonic-gateplease read through the documentation for F<perlbug> thoroughly before 148*0Sstevel@tonic-gateusing it to submit a bug report. 149*0Sstevel@tonic-gate 150*0Sstevel@tonic-gate=item L<h2ph|h2ph> 151*0Sstevel@tonic-gate 152*0Sstevel@tonic-gateBack before Perl had the XS system for connecting with C libraries, 153*0Sstevel@tonic-gateprogrammers used to get library constants by reading through the C 154*0Sstevel@tonic-gateheader files. You may still see C<require 'syscall.ph'> or similar 155*0Sstevel@tonic-gatearound - the F<.ph> file should be created by running F<h2ph> on the 156*0Sstevel@tonic-gatecorresponding F<.h> file. See the F<h2ph> documentation for more on how 157*0Sstevel@tonic-gateto convert a whole bunch of header files at once. 158*0Sstevel@tonic-gate 159*0Sstevel@tonic-gate=item L<c2ph|c2ph> and L<pstruct|pstruct> 160*0Sstevel@tonic-gate 161*0Sstevel@tonic-gateF<c2ph> and F<pstruct>, which are actually the same program but behave 162*0Sstevel@tonic-gatedifferently depending on how they are called, provide another way of 163*0Sstevel@tonic-gategetting at C with Perl - they'll convert C structures and union declarations 164*0Sstevel@tonic-gateto Perl code. This is deprecated in favour of F<h2xs> these days. 165*0Sstevel@tonic-gate 166*0Sstevel@tonic-gate=item L<h2xs|h2xs> 167*0Sstevel@tonic-gate 168*0Sstevel@tonic-gateF<h2xs> converts C header files into XS modules, and will try and write 169*0Sstevel@tonic-gateas much glue between C libraries and Perl modules as it can. It's also 170*0Sstevel@tonic-gatevery useful for creating skeletons of pure Perl modules. 171*0Sstevel@tonic-gate 172*0Sstevel@tonic-gate=item L<dprofpp|dprofpp> 173*0Sstevel@tonic-gate 174*0Sstevel@tonic-gatePerl comes with a profiler, the F<Devel::DProf> module. The 175*0Sstevel@tonic-gateF<dprofpp> utility analyzes the output of this profiler and tells you 176*0Sstevel@tonic-gatewhich subroutines are taking up the most run time. See L<Devel::DProf> 177*0Sstevel@tonic-gatefor more information. 178*0Sstevel@tonic-gate 179*0Sstevel@tonic-gate=item L<perlcc|perlcc> 180*0Sstevel@tonic-gate 181*0Sstevel@tonic-gateF<perlcc> is the interface to the experimental Perl compiler suite. 182*0Sstevel@tonic-gate 183*0Sstevel@tonic-gate=back 184*0Sstevel@tonic-gate 185*0Sstevel@tonic-gate=head2 SEE ALSO 186*0Sstevel@tonic-gate 187*0Sstevel@tonic-gateL<perldoc|perldoc>, L<pod2man|pod2man>, L<perlpod>, 188*0Sstevel@tonic-gateL<pod2html|pod2html>, L<pod2usage|pod2usage>, L<podselect|podselect>, 189*0Sstevel@tonic-gateL<podchecker|podchecker>, L<splain|splain>, L<perldiag>, 190*0Sstevel@tonic-gateL<roffitall|roffitall>, L<a2p|a2p>, L<s2p|s2p>, L<find2perl|find2perl>, 191*0Sstevel@tonic-gateL<File::Find|File::Find>, L<pl2pm|pl2pm>, L<perlbug|perlbug>, 192*0Sstevel@tonic-gateL<h2ph|h2ph>, L<c2ph|c2ph>, L<h2xs|h2xs>, L<dprofpp|dprofpp>, 193*0Sstevel@tonic-gateL<Devel::DProf>, L<perlcc|perlcc> 194*0Sstevel@tonic-gate 195*0Sstevel@tonic-gate=cut 196