be defensive about setting {host,group,pass}cat (from Andy Dougherty)
[p5sagit/p5-mst-13.2.git] / pod / perlfaq.pod
CommitLineData
68dc0745 1=head1 NAME
2
d92eb7b0 3perlfaq - frequently asked questions about Perl ($Date: 1999/05/23 20:38:02 $)
68dc0745 4
5=head1 DESCRIPTION
6
7This document is structured into the following sections:
8
9=over
10
11=item perlfaq: Structural overview of the FAQ.
12
13This document.
14
15=item L<perlfaq1>: General Questions About Perl
16
17Very general, high-level information about Perl.
18
65acb1b1 19=over 4
20
21=item * What is Perl?
22
23=item * Who supports Perl? Who develops it? Why is it free?
24
25=item * Which version of Perl should I use?
26
27=item * What are perl4 and perl5?
28
29=item * What is perl6?
30
31=item * How stable is Perl?
32
33=item * Is Perl difficult to learn?
34
35=item * How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl?
36
37=item * Can I do [task] in Perl?
38
39=item * When shouldn't I program in Perl?
40
41=item * What's the difference between "perl" and "Perl"?
42
43=item * Is it a Perl program or a Perl script?
44
45=item * What is a JAPH?
46
47=item * Where can I get a list of Larry Wall witticisms?
48
49=item * How can I convince my sysadmin/supervisor/employees to use version (5/5.005/Perl instead of some other language)?
50
51=back
52
53
68dc0745 54=item L<perlfaq2>: Obtaining and Learning about Perl
55
92c2ed05 56Where to find source and documentation to Perl, support,
68dc0745 57and related matters.
58
65acb1b1 59=over 4
60
61=item * What machines support Perl? Where do I get it?
62
63=item * How can I get a binary version of Perl?
64
65=item * I don't have a C compiler on my system. How can I compile perl?
66
67=item * I copied the Perl binary from one machine to another, but scripts don't work.
68
69=item * I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?
70
71=item * What modules and extensions are available for Perl? What is CPAN? What does CPAN/src/... mean?
72
73=item * Is there an ISO or ANSI certified version of Perl?
74
75=item * Where can I get information on Perl?
76
77=item * What are the Perl newsgroups on USENET? Where do I post questions?
78
79=item * Where should I post source code?
80
81=item * Perl Books
82
83=item * Perl in Magazines
84
85=item * Perl on the Net: FTP and WWW Access
86
87=item * What mailing lists are there for perl?
88
89=item * Archives of comp.lang.perl.misc
90
91=item * Where can I buy a commercial version of Perl?
92
93=item * Where do I send bug reports?
94
95=item * What is perl.com?
96
97=back
98
99
68dc0745 100=item L<perlfaq3>: Programming Tools
101
102Programmer tools and programming support.
103
65acb1b1 104=over 4
105
106=item * How do I do (anything)?
107
108=item * How can I use Perl interactively?
109
110=item * Is there a Perl shell?
111
112=item * How do I debug my Perl programs?
113
114=item * How do I profile my Perl programs?
115
116=item * How do I cross-reference my Perl programs?
117
118=item * Is there a pretty-printer (formatter) for Perl?
119
120=item * Is there a ctags for Perl?
121
122=item * Is there an IDE or Windows Perl Editor?
123
124=item * Where can I get Perl macros for vi?
125
126=item * Where can I get perl-mode for emacs?
127
128=item * How can I use curses with Perl?
129
130=item * How can I use X or Tk with Perl?
131
132=item * How can I generate simple menus without using CGI or Tk?
133
134=item * What is undump?
135
136=item * How can I make my Perl program run faster?
137
138=item * How can I make my Perl program take less memory?
139
140=item * Is it unsafe to return a pointer to local data?
141
142=item * How can I free an array or hash so my program shrinks?
143
144=item * How can I make my CGI script more efficient?
145
146=item * How can I hide the source for my Perl program?
147
148=item * How can I compile my Perl program into byte code or C?
149
150=item * How can I compile Perl into Java?
151
152=item * How can I get C<#!perl> to work on [MS-DOS,NT,...]?
153
154=item * Can I write useful perl programs on the command line?
155
156=item * Why don't perl one-liners work on my DOS/Mac/VMS system?
157
158=item * Where can I learn about CGI or Web programming in Perl?
159
160=item * Where can I learn about object-oriented Perl programming?
161
162=item * Where can I learn about linking C with Perl? [h2xs, xsubpp]
163
164=item * I've read perlembed, perlguts, etc., but I can't embed perl in
165my C program, what am I doing wrong?
166
167=item * When I tried to run my script, I got this message. What does it
168mean?
169
170=item * What's MakeMaker?
171
172=back
173
174
68dc0745 175=item L<perlfaq4>: Data Manipulation
176
177Manipulating numbers, dates, strings, arrays, hashes, and
178miscellaneous data issues.
179
65acb1b1 180=over 4
181
182=item * Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?
183
184=item * Why isn't my octal data interpreted correctly?
185
186=item * Does Perl have a round() function? What about ceil() and floor()? Trig functions?
187
188=item * How do I convert bits into ints?
189
190=item * Why doesn't & work the way I want it to?
191
192=item * How do I multiply matrices?
193
194=item * How do I perform an operation on a series of integers?
195
196=item * How can I output Roman numerals?
197
198=item * Why aren't my random numbers random?
199
200=item * How do I find the week-of-the-year/day-of-the-year?
201
d92eb7b0 202=item * How do I find the current century or millennium?
203
65acb1b1 204=item * How can I compare two dates and find the difference?
205
206=item * How can I take a string and turn it into epoch seconds?
207
208=item * How can I find the Julian Day?
209
210=item * How do I find yesterday's date?
211
212=item * Does Perl have a year 2000 problem? Is Perl Y2K compliant?
213
214=item * How do I validate input?
215
216=item * How do I unescape a string?
217
218=item * How do I remove consecutive pairs of characters?
219
220=item * How do I expand function calls in a string?
221
222=item * How do I find matching/nesting anything?
223
224=item * How do I reverse a string?
225
226=item * How do I expand tabs in a string?
227
228=item * How do I reformat a paragraph?
229
230=item * How can I access/change the first N letters of a string?
231
232=item * How do I change the Nth occurrence of something?
233
234=item * How can I count the number of occurrences of a substring within a string?
235
236=item * How do I capitalize all the words on one line?
237
238=item * How can I split a [character] delimited string except when inside
239[character]? (Comma-separated files)
240
241=item * How do I strip blank space from the beginning/end of a string?
242
243=item * How do I pad a string with blanks or pad a number with zeroes?
244
245=item * How do I extract selected columns from a string?
246
247=item * How do I find the soundex value of a string?
248
249=item * How can I expand variables in text strings?
250
251=item * What's wrong with always quoting "$vars"?
252
253=item * Why don't my E<lt>E<lt>HERE documents work?
254
255=item * What is the difference between a list and an array?
256
257=item * What is the difference between $array[1] and @array[1]?
258
d92eb7b0 259=item * How can I remove duplicate elements from a list or array?
65acb1b1 260
261=item * How can I tell whether a list or array contains a certain element?
262
263=item * How do I compute the difference of two arrays? How do I compute the intersection of two arrays?
264
265=item * How do I test whether two arrays or hashes are equal?
266
267=item * How do I find the first array element for which a condition is true?
268
269=item * How do I handle linked lists?
270
271=item * How do I handle circular lists?
272
273=item * How do I shuffle an array randomly?
274
275=item * How do I process/modify each element of an array?
276
277=item * How do I select a random element from an array?
278
279=item * How do I permute N elements of a list?
280
281=item * How do I sort an array by (anything)?
282
283=item * How do I manipulate arrays of bits?
284
285=item * Why does defined() return true on empty arrays and hashes?
286
287=item * How do I process an entire hash?
288
289=item * What happens if I add or remove keys from a hash while iterating over it?
290
291=item * How do I look up a hash element by value?
292
293=item * How can I know how many entries are in a hash?
294
295=item * How do I sort a hash (optionally by value instead of key)?
296
297=item * How can I always keep my hash sorted?
298
299=item * What's the difference between "delete" and "undef" with hashes?
300
301=item * Why don't my tied hashes make the defined/exists distinction?
302
303=item * How do I reset an each() operation part-way through?
304
305=item * How can I get the unique keys from two hashes?
306
307=item * How can I store a multidimensional array in a DBM file?
308
309=item * How can I make my hash remember the order I put elements into it?
310
311=item * Why does passing a subroutine an undefined element in a hash create it?
312
313=item * How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?
314
315=item * How can I use a reference as a hash key?
316
317=item * How do I handle binary data correctly?
318
319=item * How do I determine whether a scalar is a number/whole/integer/float?
320
321=item * How do I keep persistent data across program calls?
322
323=item * How do I print out or copy a recursive data structure?
324
325=item * How do I define methods for every class/object?
326
327=item * How do I verify a credit card checksum?
328
329=item * How do I pack arrays of doubles or floats for XS code?
330
331=back
332
333
68dc0745 334=item L<perlfaq5>: Files and Formats
335
336I/O and the "f" issues: filehandles, flushing, formats and footers.
337
65acb1b1 338=over 4
339
340=item * How do I flush/unbuffer an output filehandle? Why must I do this?
341
342=item * How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file?
343
344=item * How do I count the number of lines in a file?
345
346=item * How do I make a temporary file name?
347
348=item * How can I manipulate fixed-record-length files?
349
350=item * How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles?
351
352=item * How can I use a filehandle indirectly?
353
354=item * How can I set up a footer format to be used with write()?
355
356=item * How can I write() into a string?
357
358=item * How can I output my numbers with commas added?
359
360=item * How can I translate tildes (~) in a filename?
361
362=item * How come when I open a file read-write it wipes it out?
363
364=item * Why do I sometimes get an "Argument list too long" when I use E<lt>*E<gt>?
365
366=item * Is there a leak/bug in glob()?
367
368=item * How can I open a file with a leading "E<gt>" or trailing blanks?
369
370=item * How can I reliably rename a file?
371
372=item * How can I lock a file?
373
374=item * Why can't I just open(FH, ">file.lock")?
375
376=item * I still don't get locking. I just want to increment the number in the file. How can I do this?
377
378=item * How do I randomly update a binary file?
379
380=item * How do I get a file's timestamp in perl?
381
382=item * How do I set a file's timestamp in perl?
383
384=item * How do I print to more than one file at once?
385
d92eb7b0 386=item * How can I read in an entire file all at once?
387
65acb1b1 388=item * How can I read in a file by paragraphs?
389
390=item * How can I read a single character from a file? From the keyboard?
391
392=item * How can I tell whether there's a character waiting on a filehandle?
393
394=item * How do I do a C<tail -f> in perl?
395
396=item * How do I dup() a filehandle in Perl?
397
398=item * How do I close a file descriptor by number?
399
400=item * Why can't I use "C:\temp\foo" in DOS paths? What doesn't `C:\temp\foo.exe` work?
401
402=item * Why doesn't glob("*.*") get all the files?
403
404=item * Why does Perl let me delete read-only files? Why does C<-i> clobber protected files? Isn't this a bug in Perl?
405
406=item * How do I select a random line from a file?
407
408=item * Why do I get weird spaces when I print an array of lines?
409
410=back
411
412
68dc0745 413=item L<perlfaq6>: Regexps
414
415Pattern matching and regular expressions.
416
65acb1b1 417=over 4
418
419=item * How can I hope to use regular expressions without creating illegible and unmaintainable code?
420
421=item * I'm having trouble matching over more than one line. What's wrong?
422
423=item * How can I pull out lines between two patterns that are themselves on different lines?
424
425=item * I put a regular expression into $/ but it didn't work. What's wrong?
426
427=item * How do I substitute case insensitively on the LHS, but preserving case on the RHS?
428
429=item * How can I make C<\w> match national character sets?
430
431=item * How can I match a locale-smart version of C</[a-zA-Z]/>?
432
d92eb7b0 433=item * How can I quote a variable to use in a regex?
65acb1b1 434
435=item * What is C</o> really for?
436
437=item * How do I use a regular expression to strip C style comments from a file?
438
439=item * Can I use Perl regular expressions to match balanced text?
440
d92eb7b0 441=item * What does it mean that regexes are greedy? How can I get around it?
65acb1b1 442
443=item * How do I process each word on each line?
444
445=item * How can I print out a word-frequency or line-frequency summary?
446
447=item * How can I do approximate matching?
448
449=item * How do I efficiently match many regular expressions at once?
450
451=item * Why don't word-boundary searches with C<\b> work for me?
452
453=item * Why does using $&, $`, or $' slow my program down?
454
455=item * What good is C<\G> in a regular expression?
456
d92eb7b0 457=item * Are Perl regexes DFAs or NFAs? Are they POSIX compliant?
65acb1b1 458
459=item * What's wrong with using grep or map in a void context?
460
461=item * How can I match strings with multibyte characters?
462
463=item * How do I match a pattern that is supplied by the user?
464
465=back
466
467
68dc0745 468=item L<perlfaq7>: General Perl Language Issues
469
470General Perl language issues that don't clearly fit into any of the
471other sections.
472
65acb1b1 473=over 4
474
475=item * Can I get a BNF/yacc/RE for the Perl language?
476
d92eb7b0 477=item * What are all these $@%&* punctuation signs, and how do I know when to use them?
65acb1b1 478
479=item * Do I always/never have to quote my strings or use semicolons and commas?
480
481=item * How do I skip some return values?
482
483=item * How do I temporarily block warnings?
484
485=item * What's an extension?
486
487=item * Why do Perl operators have different precedence than C operators?
488
489=item * How do I declare/create a structure?
490
491=item * How do I create a module?
492
493=item * How do I create a class?
494
495=item * How can I tell if a variable is tainted?
496
497=item * What's a closure?
498
499=item * What is variable suicide and how can I prevent it?
500
d92eb7b0 501=item * How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?
65acb1b1 502
503=item * How do I create a static variable?
504
505=item * What's the difference between dynamic and lexical (static) scoping? Between local() and my()?
506
507=item * How can I access a dynamic variable while a similarly named lexical is in scope?
508
509=item * What's the difference between deep and shallow binding?
510
511=item * Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right?
512
513=item * How do I redefine a builtin function, operator, or method?
514
515=item * What's the difference between calling a function as &foo and foo()?
516
517=item * How do I create a switch or case statement?
518
519=item * How can I catch accesses to undefined variables/functions/methods?
520
521=item * Why can't a method included in this same file be found?
522
523=item * How can I find out my current package?
524
525=item * How can I comment out a large block of perl code?
526
527=item * How do I clear a package?
528
d92eb7b0 529=item * How can I use a variable as a variable name?
530
65acb1b1 531=back
532
533
68dc0745 534=item L<perlfaq8>: System Interaction
535
536Interprocess communication (IPC), control over the user-interface
537(keyboard, screen and pointing devices).
538
65acb1b1 539=over 4
540
541=item * How do I find out which operating system I'm running under?
542
543=item * How come exec() doesn't return?
544
545=item * How do I do fancy stuff with the keyboard/screen/mouse?
546
547=item * How do I print something out in color?
548
549=item * How do I read just one key without waiting for a return key?
550
551=item * How do I check whether input is ready on the keyboard?
552
553=item * How do I clear the screen?
554
555=item * How do I get the screen size?
556
557=item * How do I ask the user for a password?
558
559=item * How do I read and write the serial port?
560
561=item * How do I decode encrypted password files?
562
563=item * How do I start a process in the background?
564
565=item * How do I trap control characters/signals?
566
567=item * How do I modify the shadow password file on a Unix system?
568
569=item * How do I set the time and date?
570
571=item * How can I sleep() or alarm() for under a second?
572
573=item * How can I measure time under a second?
574
575=item * How can I do an atexit() or setjmp()/longjmp()? (Exception handling)
576
577=item * Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean?
578
579=item * How can I call my system's unique C functions from Perl?
580
581=item * Where do I get the include files to do ioctl() or syscall()?
582
583=item * Why do setuid perl scripts complain about kernel problems?
584
585=item * How can I open a pipe both to and from a command?
586
587=item * Why can't I get the output of a command with system()?
588
589=item * How can I capture STDERR from an external command?
590
591=item * Why doesn't open() return an error when a pipe open fails?
592
593=item * What's wrong with using backticks in a void context?
594
595=item * How can I call backticks without shell processing?
596
597=item * Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?
598
599=item * How can I convert my shell script to perl?
600
601=item * Can I use perl to run a telnet or ftp session?
602
603=item * How can I write expect in Perl?
604
605=item * Is there a way to hide perl's command line from programs such as "ps"?
606
607=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?
608
609=item * How do I close a process's filehandle without waiting for it to complete?
610
611=item * How do I fork a daemon process?
612
613=item * How do I make my program run with sh and csh?
614
615=item * How do I find out if I'm running interactively or not?
616
617=item * How do I timeout a slow event?
618
619=item * How do I set CPU limits?
620
621=item * How do I avoid zombies on a Unix system?
622
623=item * How do I use an SQL database?
624
625=item * How do I make a system() exit on control-C?
626
627=item * How do I open a file without blocking?
628
d92eb7b0 629=item * How do I install a module from CPAN?
65acb1b1 630
631=item * What's the difference between require and use?
632
633=item * How do I keep my own module/library directory?
634
635=item * How do I add the directory my program lives in to the module/library search path?
636
637=item * How do I add a directory to my include path at runtime?
638
639=item * What is socket.ph and where do I get it?
640
641=back
642
643
68dc0745 644=item L<perlfaq9>: Networking
645
646Networking, the Internet, and a few on the web.
647
65acb1b1 648=over 4
649
650=item * My CGI script runs from the command line but not the browser. (500 Server Error)
651
652=item * How can I get better error messages from a CGI program?
653
654=item * How do I remove HTML from a string?
655
656=item * How do I extract URLs?
657
658=item * How do I download a file from the user's machine? How do I open a file on another machine?
659
660=item * How do I make a pop-up menu in HTML?
661
662=item * How do I fetch an HTML file?
663
664=item * How do I automate an HTML form submission?
665
666=item * How do I decode or create those %-encodings on the web?
667
668=item * How do I redirect to another page?
669
670=item * How do I put a password on my web pages?
671
672=item * How do I edit my .htpasswd and .htgroup files with Perl?
673
674=item * How do I make sure users can't enter values into a form that cause my CGI script to do bad things?
675
676=item * How do I parse a mail header?
677
678=item * How do I decode a CGI form?
679
680=item * How do I check a valid mail address?
681
682=item * How do I decode a MIME/BASE64 string?
683
684=item * How do I return the user's mail address?
685
686=item * How do I send mail?
687
688=item * How do I read mail?
689
690=item * How do I find out my hostname/domainname/IP address?
691
692=item * How do I fetch a news article or the active newsgroups?
693
694=item * How do I fetch/put an FTP file?
695
696=item * How can I do RPC in Perl?
697
698=back
699
700
68dc0745 701=back
702
703=head2 Where to get this document
704
705This document is posted regularly to comp.lang.perl.announce and
706several other related newsgroups. It is available in a variety of
707formats from CPAN in the /CPAN/doc/FAQs/FAQ/ directory, or on the web
708at http://www.perl.com/perl/faq/ .
709
710=head2 How to contribute to this document
711
712You may mail corrections, additions, and suggestions to
c8db1d39 713perlfaq-suggestions@perl.com . This alias should not be
714used to I<ask> FAQs. It's for fixing the current FAQ.
65acb1b1 715Send questions to the comp.lang.perl.misc newsgroup.
68dc0745 716
717=head2 What will happen if you mail your Perl programming problems to the authors
718
719Your questions will probably go unread, unless they're suggestions of
720new questions to add to the FAQ, in which case they should have gone
721to the perlfaq-suggestions@perl.com instead.
722
723You should have read section 2 of this faq. There you would have
724learned that comp.lang.perl.misc is the appropriate place to go for
725free advice. If your question is really important and you require a
726prompt and correct answer, you should hire a consultant.
727
728=head1 Credits
729
730When I first began the Perl FAQ in the late 80s, I never realized it
731would have grown to over a hundred pages, nor that Perl would ever become
732so popular and widespread. This document could not have been written
733without the tremendous help provided by Larry Wall and the rest of the
734Perl Porters.
735
736=head1 Author and Copyright Information
737
65acb1b1 738Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington.
68dc0745 739All rights reserved.
740
c8db1d39 741=head2 Bundled Distributions
68dc0745 742
c8db1d39 743When included as part of the Standard Version of Perl, or as part of
744its complete documentation whether printed or otherwise, this work
745may be distributed only under the terms of Perl's Artistic License.
746Any distribution of this file or derivatives thereof I<outside>
747of that package require that special arrangements be made with
748copyright holder.
68dc0745 749
c8db1d39 750Irrespective of its distribution, all code examples in these files
751are hereby placed into the public domain. You are permitted and
752encouraged to use this code in your own programs for fun
753or for profit as you see fit. A simple comment in the code giving
754credit would be courteous but is not required.
68dc0745 755
756=head2 Disclaimer
757
758This information is offered in good faith and in the hope that it may
759be of use, but is not guaranteed to be correct, up to date, or suitable
760for any particular purpose whatsoever. The authors accept no liability
761in respect of this information or its use.
762
763=head1 Changes
764
765=over 4
766
d92eb7b0 767=item 23/May/99
768
87275199 769Extensive updates from the net in preparation for 5.6 release.
d92eb7b0 770
771=item 13/April/99
772
773More minor touch-ups. Added new question at the end
774of perlfaq7 on variable names within variables.
775
65acb1b1 776=item 7/January/99
777
778Small touchups here and there. Added all questions in this
779document as a sort of table of contents.
780
707102d0 781=item 22/June/98
c8db1d39 782
783Significant changes throughout in preparation for the 5.005
784release.
785
fc36a67e 786=item 24/April/97
787
788Style and whitespace changes from Chip, new question on reading one
789character at a time from a terminal using POSIX from Tom.
790
46fc3d4c 791=item 23/April/97
792
793Added http://www.oasis.leo.org/perl/ to L<perlfaq2>. Style fix to
794L<perlfaq3>. Added floating point precision, fixed complex number
795arithmetic, cross-references, caveat for Text::Wrap, alternative
796answer for initial capitalizing, fixed incorrect regexp, added example
797of Tie::IxHash to L<perlfaq4>. Added example of passing and storing
798filehandles, added commify to L<perlfaq5>. Restored variable suicide,
799and added mass commenting to L<perlfaq7>. Added Net::Telnet, fixed
800backticks, added reader/writer pair to telnet question, added FindBin,
801grouped module questions together in L<perlfaq8>. Expanded caveats
802for the simple URL extractor, gave LWP example, added CGI security
5a964f20 803question, expanded on the mail address answer in L<perlfaq9>.
46fc3d4c 804
3fe9a6f1 805=item 25/March/97
806
807Added more info to the binary distribution section of L<perlfaq2>.
808Added Net::Telnet to L<perlfaq6>. Fixed typos in L<perlfaq8>. Added
809mail sending example to L<perlfaq9>. Added Merlyn's columns to
810L<perlfaq2>.
811
46fc3d4c 812=item 18/March/97
3fe9a6f1 813
814Added the DATE to the NAME section, indicating which sections have
815changed.
816
817Mentioned SIGPIPE and L<perlipc> in the forking open answer in
818L<perlfaq8>.
819
820Fixed description of a regular expression in L<perlfaq4>.
821
68dc0745 822=item 17/March/97 Version
823
824Various typos fixed throughout.
825
826Added new question on Perl BNF on L<perlfaq7>.
827
828=item Initial Release: 11/March/97
829
830This is the initial release of version 3 of the FAQ; consequently there
831have been no changes since its initial release.
832
833=back