=head1 NAME
-perlfaq - frequently asked questions about Perl ($Date: 1999/05/23 20:38:02 $)
+perlfaq - frequently asked questions about Perl ($Date: 2005/03/27 07:21:21 $)
=head1 DESCRIPTION
-The perlfaq is structured into the following documents:
+The perlfaq is divided into several documents based on topics. A table
+of contents is at the end of this document.
+=head2 Where to get the perlfaq
+
+Extracts of the perlfaq are posted regularly to
+comp.lang.perl.misc. It is available on many web sites:
+http://www.perldoc.com/ and http://faq.perl.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. You can
+view the source tree at http://cvs.perl.org/cvsweb/perlfaq/
+(which is outside of the main Perl source tree). The CVS
+repository notes all changes to the FAQ.
+
+=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
+
+The original perlfaq was written by Tom Christiansen, then expanded
+by collaboration between Tom and Nathan Torkington. The current
+document is maintained by the perlfaq-workers (perlfaq-workers@perl.org).
+Several people have contributed answers, corrections, and comments.
+
+=head1 Author and Copyright Information
+
+Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and
+other contributors noted in the answers.
+
+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 Table of Contents
+
+=over 4
+
+=item perlfaq - this document
-=head2 perlfaq: Structural overview of the FAQ.
+=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
+
+=item perlfaq6 - Regular Expressions
+
+=item perlfaq7 - General Perl Language Issues
+
+=item perlfaq8 - System Interaction
+
+=item perlfaq9 - Networking
+
+
+=back
+
+
+=head1 The Questions
-This document.
=head2 L<perlfaq1>: General Questions About Perl
-Very general, high-level information about Perl.
+Very general, high-level questions about Perl.
=over 4
=item *
-What are perl4 and perl5?
+What are perl4, perl5, or perl6?
+
+=item *
+
+What is Ponie?
=item *
=item *
-How can I convince my sysadmin/supervisor/employees to use version 5/5.005/Perl instead of some other language?
+How can I convince my sysadmin/supervisor/employees to use version 5/5.6.1/Perl instead of some other language?
=back
=head2 L<perlfaq2>: Obtaining and Learning about Perl
-Where to find source and documentation to Perl, support,
-and related matters.
+Where to find source and documentation for Perl, support, and related matters.
=over 4
=item *
-What is perl.com? Perl Mongers? pm.org? perl.org?
+What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?
=back
=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 *
-
-What is undump?
-
-=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 *
-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 *
-When I tried to run my script, I got this message. What does it
-mean?
+When I tried to run my script, I got this message. What does it mean?
=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 C<int()> broken?
+
+=item *
+
Why isn't my octal data interpreted correctly?
=item *
-Does Perl have a round() function? What about ceil() and floor()? Trig functions?
+Does Perl have a C<round()> function? What about C<ceil()> and C<floor()>? Trig functions?
=item *
-How do I convert bits into ints?
+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 get a random number between X and Y?
+
+=item *
+
+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 *
-What is the difference between $array[1] and @array[1]?
+What is the difference between C<$array[1]> and C<@array[1]>?
=item *
=item *
-How can I tell whether a list or array contains a certain element?
+How can I tell whether a certain element is contained in a list or array?
=item *
=item *
-Why does defined() return true on empty arrays and hashes?
+Why does C<defined()> return true on empty arrays and hashes?
=item *
=item *
-How do I reset an each() operation part-way through?
+How do I reset an C<each()> operation part-way through?
=item *
=head2 L<perlfaq5>: Files and Formats
-I/O and the "f" issues: filehandles, flushing, formats and footers.
+I/O and the "f" issues: filehandles, flushing, formats, and footers.
=over 4
=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 *
-How can I set up a footer format to be used with write()?
+How can I set up a footer format to be used with C<write()>?
=item *
-How can I write() into a string?
+How can I C<write()> into a string?
=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 *
-Is there a leak/bug in glob()?
+Is there a leak/bug in C<glob()>?
=item *
=item *
-Why can't I just open(FH, ">file.lock")?
+Why can't I just C<< open(FH, ">file.lock") >>?
=item *
=item *
-How do I dup() a filehandle in Perl?
+How do I C<dup()> a filehandle in Perl?
=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 *
-Why doesn't glob("*.*") get all the files?
+Why doesn't C<glob("*.*")> get all the files?
=item *
=back
-=head2 L<perlfaq6>: Regexps
+=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 *
-I put a regular expression into $/ but it didn't work. What's wrong?
+I put a regular expression into C<$/> but it didn't work. What's wrong?
=item *
=item *
-Why does using $&, $`, or $' slow my program down?
+Why does using C<$&>, C<$`>, or C<$'> slow my program down?
=item *
=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 C<< my($foo) = <FILE>; >> work right?
=item *
=item *
-What's the difference between calling a function as &foo and foo()?
+What's the difference between calling a function as C<&foo> and C<foo()>?
=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 come exec() doesn't return?
+How come C<exec()> doesn't return?
=item *
=item *
-How can I sleep() or alarm() for under a second?
+How can I C<sleep()> or C<alarm()> for under a second?
=item *
=item *
-How can I do an atexit() or setjmp()/longjmp()? (Exception handling)
+How can I do an C<atexit()> or C<setjmp()>/C<longjmp()>? (Exception handling)
=item *
=item *
-Where do I get the include files to do ioctl() or syscall()?
+Where do I get the include files to do C<ioctl()> or C<syscall()>?
=item *
=item *
-Why can't I get the output of a command with system()?
+Why can't I get the output of a command with C<system()>?
=item *
=item *
-Why doesn't open() return an error when a pipe open fails?
+Why doesn't C<open()> return an error when a pipe open fails?
=item *
=item *
-I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?
+I {changed directory, modified my environment} in a perl script. How come
+the change disappeared when I exited the script? How do I get my changes
+to be visible?
=item *
=item *
-How do I make a system() exit on control-C?
+How do I make a C<system()> exit on control-C?
=item *
=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 (C<@INC>) at runtime?
=item *
-What is socket.ph and where do I get it?
+What is F<socket.ph> and where do I get it?
=back
=head2 L<perlfaq9>: Networking
-Networking, the Internet, and a few on the web.
+Networking, the internet, and a few on the web.
=over 4
=item *
+What is the correct form of response from a CGI script?
+
+=item *
+
My CGI script runs from the command line but not the browser. (500 Server Error)
=item *
=item *
-How do I edit my .htpasswd and .htgroup files with Perl?
+How do I edit my F<.htpasswd> and F<.htgroup> files with Perl?
=item *
=item *
+How do I use MIME to make an attachment to a mail message?
+
+=item *
+
How do I read mail?
=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 in a variety of
-formats from CPAN in the /CPAN/doc/FAQs/FAQ/ directory or on the web
-at http://www.perl.com/perl/faq/ .
-
-=head2 How to contribute to the perlfaq
-
-You may mail corrections, additions, and suggestions to
-perlfaq-suggestions@perl.com . 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-suggestions@perl.com 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-1999 Tom Christiansen and Nathan Torkington.
-All rights reserved.
-
-=head2 Bundled Distributions
-
-When included as part of the Standard Version of Perl or as part of
-its complete documentation whether printed or otherwise, this work
-may be distributed only under the terms of Perl's Artistic License.
-Any distribution of this file or derivatives thereof I<outside>
-of that package requires that special arrangements be made with
-copyright holder.
-
-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 touchups 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
projects / p5sagit/p5-mst-13.2.git / blobdiff