=head1 NAME
-perlfaq - frequently asked questions about Perl ($Date: 2002/03/11 21:32:23 $)
+perlfaq - frequently asked questions about Perl ($Revision: 3606 $)
=head1 DESCRIPTION
-The perlfaq is structured into the following documents:
+The perlfaq comprises several documents that answer the most commonly
+asked questions about Perl and Perl programming. It's divided by topic
+into nine major sections outlined in this document.
+=head2 Where to get the perlfaq
+
+The perlfaq comes with the standard Perl distribution, so if you have Perl
+you should have the perlfaq. You should also have the C<perldoc> tool
+that let's you read the L<perlfaq>:
+
+ $ perldoc perlfaq
+
+Besides your local system, you can find the perlfaq on the web, including
+at http://perldoc.perl.org/ .
+
+The perlfaq is an evolving document and you can read the latest version
+at http://faq.perl.org/ . The perlfaq-workers periodically post extracts
+of the latest perlfaq to comp.lang.perl.misc.
+
+You can view the source tree at
+https://svn.perl.org/modules/perlfaq/trunk/ (which is outside of the
+main Perl source tree). The SVN repository notes all changes to the FAQ
+and holds the latest version of the working documents and may vary
+significantly from the version distributed with the latest version of
+Perl. Check the repository before sending your corrections.
+
+=head2 How to contribute to the perlfaq
+
+You can mail corrections, additions, and suggestions to
+C<< <perlfaq-workers AT perl DOT org> >>. The perlfaq volunteers use this
+address to coordinate their efforts and track the perlfaq development.
+They appreciate your contributions to the FAQ but do not have time to
+provide individual help, so don't use this address to ask FAQs.
+
+The perlfaq server posts extracts of the perlfaq to that newsgroup every
+6 hours (or so), and the community of volunteers reviews and updates the
+answers. If you'd like to help review and update the answers, check out
+comp.lang.perl.misc.
+
+=head2 What will happen if you mail your Perl programming problems to the authors?
+
+The perlfaq-workers like to keep all traffic on the perlfaq-workers list
+so that everyone can see the work being done (and the work that needs to
+be done). The mailing list serves as an official record. If you email the
+authors or maintainers directly, you'll probably get a reply asking you
+to post to the mailing list. If you don't get a reply, it probably means
+that the person never saw the message or didn't have time to deal with
+it. Posting to the list allows the volunteers with time to deal with it
+when others are busy.
+
+If you have a question that isn't in the FAQ and you would like help with
+it, try the resources in L<perlfaq2>.
+
+=head1 CREDITS
+
+Tom Christiansen wrote the original perlfaq then expanded it with the
+help of Nat Torkington. The perlfaq-workers maintain current document
+and the dezinens of comp.lang.perl.misc regularly review and update the
+FAQ. Several people have contributed answers, corrections, and comments,
+and the perlfaq notes those contributions wherever appropriate.
+
+=head1 AUTHOR AND COPYRIGHT
+
+Tom Christainsen wrote the original version of this document.
+brian d foy C<< <bdfoy@cpan.org> >> wrote this version. See the
+individual perlfaq documents for additional copyright information.
+
+This document is available under the same terms as Perl itself. Code
+examples in all the perlfaq documents are in the public domain. Use
+them as you see fit (and at your own risk with no warranty from anyone).
+
+=head1 Table of Contents
+
+=over 4
+
+=item perlfaq - this document
+
+=item perlfaq1 - General Questions About Perl
+
+=item perlfaq2 - Obtaining and Learning about Perl
+
+=item perlfaq3 - Programming Tools
+
+=item perlfaq4 - Data Manipulation
+
+=item perlfaq5 - Files and Formats
-=head2 perlfaq: Structural overview of the FAQ.
+=item perlfaq6 - Regular Expressions
-This document.
+=item perlfaq7 - General Perl Language Issues
+
+=item perlfaq8 - System Interaction
+
+=item perlfaq9 - Networking
+
+=back
+
+=head1 The Questions
=head2 L<perlfaq1>: General Questions About Perl
=item *
-What are perl4 and perl5?
+What are perl4, perl5, or perl6?
+
+=item *
+
+What is Ponie?
=item *
=head2 L<perlfaq2>: Obtaining and Learning about Perl
-Where to find source and documentation for Perl, support,
-and related matters.
+Where to find source and documentation for Perl, support, and related matters.
=over 4
=item *
-What machines support Perl? Where do I get it?
+What machines support perl? Where do I get it?
=item *
-How can I get a binary version of Perl?
+How can I get a binary version of perl?
=item *
-I don't have a C compiler on my system. How can I compile perl?
+I don't have a C compiler. How can I build my own Perl interpreter?
=item *
-I copied the Perl binary from one machine to another, but scripts don't work.
+I copied the perl binary from one machine to another, but scripts don't work.
=item *
=item *
-Perl in Magazines
-
-=item *
-
-Perl on the Net: FTP and WWW Access
+Which magazines have Perl content?
=item *
=item *
-Archives of comp.lang.perl.misc
+Where are the archives for comp.lang.perl.misc?
=item *
-Where can I buy a commercial version of Perl?
+Where can I buy a commercial version of perl?
=item *
=item *
+How do I find which modules are installed on my system?
+
+=item *
+
How do I debug my Perl programs?
=item *
=item *
-How can I generate simple menus without using CGI or Tk?
-
-=item *
-
How can I make my Perl program run faster?
=item *
=item *
-Is it unsafe to return a pointer to local data?
+Is it safe to return a reference to local or lexical data?
=item *
=item *
-Where can I learn about linking C with Perl? [h2xs, xsubpp]
+Where can I learn about linking C with Perl?
=item *
-I've read perlembed, perlguts, etc., but I can't embed perl in
-my C program; what am I doing wrong?
+I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?
=item *
=head2 L<perlfaq4>: Data Manipulation
-Manipulating numbers, dates, strings, arrays, hashes, and
-miscellaneous data issues.
+Manipulating numbers, dates, strings, arrays, hashes, and miscellaneous data issues.
=over 4
=item *
+Why is int() broken?
+
+=item *
+
Why isn't my octal data interpreted correctly?
=item *
=item *
-How do I convert between numeric representations?
+How do I convert between numeric representations/bases/radixes?
=item *
=item *
-How do I find the week-of-the-year/day-of-the-year?
+How do I find the day or week of the year?
=item *
=item *
-How can I access/change the first N letters of a string?
+How can I access or change N characters of a string?
=item *
=item *
-How can I split a [character] delimited string except when inside
-[character]? (Comma-separated files)
+How can I split a [character] delimited string except when inside [character]?
=item *
=item *
-Why don't my <<HERE documents work?
+Why don't my E<lt>E<lt>HERE documents work?
=item *
=item *
+How can I use Perl's C<-i> option from within a program?
+
+=item *
+
+How can I copy a file?
+
+=item *
+
How do I make a temporary file name?
=item *
=item *
-Why do I sometimes get an "Argument list too long" when I use <*>?
+Why do I sometimes get an "Argument list too long" when I use E<lt>*E<gt>?
=item *
=item *
-Why can't I just open(FH, ">file.lock")?
+Why can't I just open(FH, "E<gt>file.lock")?
=item *
=item *
-Why can't I use "C:\temp\foo" in DOS paths? What doesn't `C:\temp\foo.exe` work?
+Why can't I use "C:\temp\foo" in DOS paths? Why doesn't `C:\temp\foo.exe` work?
=item *
=head2 L<perlfaq6>: Regular Expressions
-Pattern matching and regular expressions.
+This section is surprisingly small because the rest of the FAQ is littered with answers involving regular expressions. For example, decoding a URL and checking whether something is a number are handled with regular expressions, but those answers are found elsewhere in this document (in L<perlfaq9>: "How do I decode or create those %-encodings on the web" and L<perlfaq4>: "How do I determine whether a scalar is a number/whole/integer/float", to be precise).
=over 4
=item *
-What's wrong with using grep or map in a void context?
+What's wrong with using grep in a void context?
=item *
=head2 L<perlfaq7>: General Perl Language Issues
-General Perl language issues that don't clearly fit into any of the
-other sections.
+General Perl language issues that don't clearly fit into any of the other sections.
=over 4
=item *
-Why doesn't "my($foo) = <FILE>;" work right?
+Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right?
=item *
=item *
-How can I catch accesses to undefined variables/functions/methods?
+How can I catch accesses to undefined variables, functions, or methods?
=item *
How can I use a variable as a variable name?
+=item *
+
+What does "bad interpreter" mean?
+
=back
=head2 L<perlfaq8>: System Interaction
-Interprocess communication (IPC), control over the user-interface
-(keyboard, screen and pointing devices).
+This section of the Perl FAQ covers questions involving operating system interaction. Topics include interprocess communication (IPC), control over the user-interface (keyboard, screen and pointing devices), and most anything else not related to data manipulation. Read the FAQs and documentation specific to the port of perl to your operating system (eg, L<perlvms>, L<perlplan9>, ...). These should contain more detailed information on the vagaries of your perl.
=over 4
=item *
+How do I tell the difference between errors from the shell and perl?
+
+=item *
+
How do I install a module from CPAN?
=item *
=item *
-How do I add a directory to my include path at runtime?
+How do I add a directory to my include path (@INC) at runtime?
=item *
=item *
-How do I find out my hostname/domainname/IP address?
+How do I find out my hostname, domainname, or IP address?
=item *
=back
-=head1 About the perlfaq documents
-
-=head2 Where to get the perlfaq
-
-This document is posted regularly to comp.lang.perl.announce and
-several other related newsgroups. It is available on many
-web sites: http://www.perldoc.com/ and http://perlfaq.cpan.org/ .
-
-=head2 How to contribute to the perlfaq
-
-You may mail corrections, additions, and suggestions to
-perlfaq-workers@perl.org . This alias should not be
-used to I<ask> FAQs. It's for fixing the current FAQ.
-Send questions to the comp.lang.perl.misc newsgroup.
-
-=head2 What will happen if you mail your Perl programming problems to the authors
-
-Your questions will probably go unread, unless they're suggestions of
-new questions to add to the FAQ, in which case they should have gone
-to the perlfaq-workers@perl.org instead.
-
-You should have read section 2 of this faq. There you would have
-learned that comp.lang.perl.misc is the appropriate place to go for
-free advice. If your question is really important and you require a
-prompt and correct answer, you should hire a consultant.
-
-=head1 Credits
-
-When I first began the Perl FAQ in the late 80s, I never realized it
-would have grown to over a hundred pages, nor that Perl would ever become
-so popular and widespread. This document could not have been written
-without the tremendous help provided by Larry Wall and the rest of the
-Perl Porters.
-
-=head1 Author and Copyright Information
-
-Copyright (c) 1997-2002 Tom Christiansen and Nathan Torkington.
-All rights reserved.
-
-=head2 Bundled Distributions
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples in these files
-are hereby placed into the public domain. You are permitted and
-encouraged to use this code in your own programs for fun
-or for profit as you see fit. A simple comment in the code giving
-credit would be courteous but is not required.
-
-=head2 Disclaimer
-
-This information is offered in good faith and in the hope that it may
-be of use, but is not guaranteed to be correct, up to date, or suitable
-for any particular purpose whatsoever. The authors accept no liability
-in respect of this information or its use.
-
-=head1 Changes
-
-=over 4
-
-=item 1/November/2000
-
-A few grammatical fixes and updates implemented by John Borwick.
-
-=item 23/May/99
-
-Extensive updates from the net in preparation for 5.6 release.
-
-=item 13/April/99
-
-More minor touch-ups. Added new question at the end
-of perlfaq7 on variable names within variables.
-
-=item 7/January/99
-
-Small touch ups here and there. Added all questions in this
-document as a sort of table of contents.
-
-=item 22/June/98
-
-Significant changes throughout in preparation for the 5.005
-release.
-
-=item 24/April/97
-
-Style and whitespace changes from Chip, new question on reading one
-character at a time from a terminal using POSIX from Tom.
-
-=item 23/April/97
-
-Added http://www.oasis.leo.org/perl/ to L<perlfaq2>. Style fix to
-L<perlfaq3>. Added floating point precision, fixed complex number
-arithmetic, cross-references, caveat for Text::Wrap, alternative
-answer for initial capitalizing, fixed incorrect regexp, added example
-of Tie::IxHash to L<perlfaq4>. Added example of passing and storing
-filehandles, added commify to L<perlfaq5>. Restored variable suicide,
-and added mass commenting to L<perlfaq7>. Added Net::Telnet, fixed
-backticks, added reader/writer pair to telnet question, added FindBin,
-grouped module questions together in L<perlfaq8>. Expanded caveats
-for the simple URL extractor, gave LWP example, added CGI security
-question, expanded on the mail address answer in L<perlfaq9>.
-
-=item 25/March/97
-
-Added more info to the binary distribution section of L<perlfaq2>.
-Added Net::Telnet to L<perlfaq6>. Fixed typos in L<perlfaq8>. Added
-mail sending example to L<perlfaq9>. Added Merlyn's columns to
-L<perlfaq2>.
-
-=item 18/March/97
-
-Added the DATE to the NAME section, indicating which sections have
-changed.
-
-Mentioned SIGPIPE and L<perlipc> in the forking open answer in
-L<perlfaq8>.
-
-Fixed description of a regular expression in L<perlfaq4>.
-
-=item 17/March/97 Version
-
-Various typos fixed throughout.
-
-Added new question on Perl BNF on L<perlfaq7>.
-
-=item Initial Release: 11/March/97
-
-This is the initial release of version 3 of the FAQ; consequently there
-have been no changes since its initial release.
-
-=back
https://perl5.git.perl.org / perl5.git / blobdiff