Where to find the perlfaq¶

The perlfaq is an evolving document. Read the latest version at <https://perldoc.perl.org/perlfaq>. It is also included in the standard Perl distribution.

How to use the perlfaq¶

The "perldoc" command line tool is part of the standard Perl distribution. To read the perlfaq:

    $ perldoc perlfaq

To search the perlfaq question headings:

    $ perldoc -q open

How to contribute to the perlfaq¶

Review <https://github.com/perl-doc-cats/perlfaq/wiki>. If you don't find your suggestion create an issue or pull request against <https://github.com/perl-doc-cats/perlfaq>.

Once approved, changes will be distributed with the next Perl release and subsequently appear at <https://perldoc.perl.org/perlfaq>.

What if my question isn't answered in the FAQ?¶

Try the resources in perlfaq2.

perlfaq1: General Questions About Perl¶

This section of the FAQ answers very general, high-level questions about Perl.

• What is Perl?
• Who supports Perl? Who develops it? Why is it free?
• Which version of Perl should I use?
• What are Perl 4, Perl 5, or Raku (Perl 6)?
• What is Raku (Perl 6)?
• How stable is Perl?
• How often are new versions of Perl released?
• Is Perl difficult to learn?
• How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl?
• Can I do [task] in Perl?
• When shouldn't I program in Perl?
• What's the difference between "perl" and "Perl"?
• What is a JAPH?
• How can I convince others to use Perl?

perlfaq2: Obtaining and Learning about Perl¶

This section of the FAQ answers questions about where to find source and documentation for Perl, support, and related matters.

• What machines support Perl? Where do I get it?
• How can I get a binary version of Perl?
• I don't have a C compiler. How can I build my own Perl interpreter?
• I copied the Perl binary from one machine to another, but scripts don't work.
• I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?
• What modules and extensions are available for Perl? What is CPAN?
• Where can I get information on Perl?
• What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?
• Where can I post questions?
• Perl Books
• Which magazines have Perl content?
• Which Perl blogs should I read?
• What mailing lists are there for Perl?
• Where can I buy a commercial version of Perl?
• Where do I send bug reports?

perlfaq3: Programming Tools¶

This section of the FAQ answers questions related to programmer tools and programming support.

• How do I do (anything)?
• How can I use Perl interactively?
• How do I find which modules are installed on my system?
• How do I debug my Perl programs?
• How do I profile my Perl programs?
• How do I cross-reference my Perl programs?
• Is there a pretty-printer (formatter) for Perl?
• Is there an IDE or Windows Perl Editor?
• Where can I get Perl macros for vi?
• Where can I get perl-mode or cperl-mode for emacs?
• How can I use curses with Perl?
• How can I write a GUI (X, Tk, Gtk, etc.) in Perl?
• How can I make my Perl program run faster?
• How can I make my Perl program take less memory?
• Is it safe to return a reference to local or lexical data?
• How can I free an array or hash so my program shrinks?
• How can I make my CGI script more efficient?
• How can I hide the source for my Perl program?
• How can I compile my Perl program into byte code or C?
• How can I get "#!perl" to work on [MS-DOS,NT,...]?
• Can I write useful Perl programs on the command line?
• Why don't Perl one-liners work on my DOS/Mac/VMS system?
• Where can I learn about CGI or Web programming in Perl?
• Where can I learn about object-oriented Perl programming?
• Where can I learn about linking C with Perl?
• I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?
• When I tried to run my script, I got this message. What does it mean?
• What's MakeMaker?

perlfaq4: Data Manipulation¶

This section of the FAQ answers questions related to manipulating numbers, dates, strings, arrays, hashes, and miscellaneous data issues.

• Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?
• Why is int() broken?
• Why isn't my octal data interpreted correctly?
• Does Perl have a round() function? What about ceil() and floor()? Trig functions?
• How do I convert between numeric representations/bases/radixes?
• Why doesn't & work the way I want it to?
• How do I multiply matrices?
• How do I perform an operation on a series of integers?
• How can I output Roman numerals?
• Why aren't my random numbers random?
• How do I get a random number between X and Y?
• How do I find the day or week of the year?
• How do I find the current century or millennium?
• How can I compare two dates and find the difference?
• How can I take a string and turn it into epoch seconds?
• How can I find the Julian Day?
• How do I find yesterday's date?
• Does Perl have a Year 2000 or 2038 problem? Is Perl Y2K compliant?
• How do I validate input?
• How do I unescape a string?
• How do I remove consecutive pairs of characters?
• How do I expand function calls in a string?
• How do I find matching/nesting anything?
• How do I reverse a string?
• How do I expand tabs in a string?
• How do I reformat a paragraph?
• How can I access or change N characters of a string?
• How do I change the Nth occurrence of something?
• How can I count the number of occurrences of a substring within a string?
• How do I capitalize all the words on one line?
• How can I split a [character]-delimited string except when inside [character]?
• How do I strip blank space from the beginning/end of a string?
• How do I pad a string with blanks or pad a number with zeroes?
• How do I extract selected columns from a string?
• How do I find the soundex value of a string?
• How can I expand variables in text strings?
• Does Perl have anything like Ruby's #{} or Python's f string?
• What's wrong with always quoting "$vars"?
• Why don't my <<HERE documents work?
• What is the difference between a list and an array?
• What is the difference between $array[1] and @array[1]?
• How can I remove duplicate elements from a list or array?
• How can I tell whether a certain element is contained in a list or array?
• How do I compute the difference of two arrays? How do I compute the intersection of two arrays?
• How do I test whether two arrays or hashes are equal?
• How do I find the first array element for which a condition is true?
• How do I handle linked lists?
• How do I handle circular lists?
• How do I shuffle an array randomly?
• How do I process/modify each element of an array?
• How do I select a random element from an array?
• How do I permute N elements of a list?
• How do I sort an array by (anything)?
• How do I manipulate arrays of bits?
• Why does defined() return true on empty arrays and hashes?
• How do I process an entire hash?
• How do I merge two hashes?
• What happens if I add or remove keys from a hash while iterating over it?
• How do I look up a hash element by value?
• How can I know how many entries are in a hash?
• How do I sort a hash (optionally by value instead of key)?
• How can I always keep my hash sorted?
• What's the difference between "delete" and "undef" with hashes?
• Why don't my tied hashes make the defined/exists distinction?
• How do I reset an each() operation part-way through?
• How can I get the unique keys from two hashes?
• How can I store a multidimensional array in a DBM file?
• How can I make my hash remember the order I put elements into it?
• Why does passing a subroutine an undefined element in a hash create it?
• How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?
• How can I use a reference as a hash key?
• How can I check if a key exists in a multilevel hash?
• How can I prevent addition of unwanted keys into a hash?
• How do I handle binary data correctly?
• How do I determine whether a scalar is a number/whole/integer/float?
• How do I keep persistent data across program calls?
• How do I print out or copy a recursive data structure?
• How do I define methods for every class/object?
• How do I verify a credit card checksum?
• How do I pack arrays of doubles or floats for XS code?

perlfaq5: Files and Formats¶

This section deals with I/O and the "f" issues: filehandles, flushing, formats, and footers.

• How do I flush/unbuffer an output filehandle? Why must I do this?
• How do I change, delete, or insert a line in a file, or append to the beginning of a file?
• How do I count the number of lines in a file?
• How do I delete the last N lines from a file?
• How can I use Perl's "-i" option from within a program?
• How can I copy a file?
• How do I make a temporary file name?
• How can I manipulate fixed-record-length files?
• 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?
• How can I use a filehandle indirectly?
• How can I open a filehandle to a string?
• How can I set up a footer format to be used with write()?
• How can I write() into a string?
• How can I output my numbers with commas added?
• How can I translate tildes (~) in a filename?
• How come when I open a file read-write it wipes it out?
• Why do I sometimes get an "Argument list too long" when I use <*>?
• How can I open a file named with a leading ">" or trailing blanks?
• How can I reliably rename a file?
• How can I lock a file?
• Why can't I just open(FH, ">file.lock")?
• I still don't get locking. I just want to increment the number in the file. How can I do this?
• All I want to do is append a small amount of text to the end of a file. Do I still have to use locking?
• How do I randomly update a binary file?
• How do I get a file's timestamp in perl?
• How do I set a file's timestamp in perl?
• How do I print to more than one file at once?
• How can I read in an entire file all at once?
• How can I read in a file by paragraphs?
• How can I read a single character from a file? From the keyboard?
• How can I tell whether there's a character waiting on a filehandle?
• How do I do a "tail -f" in perl?
• How do I dup() a filehandle in Perl?
• How do I close a file descriptor by number?
• Why can't I use "C:\temp\foo" in DOS paths? Why doesn't `C:\temp\foo.exe` work?
• Why doesn't glob("*.*") get all the files?
• Why does Perl let me delete read-only files? Why does "-i" clobber protected files? Isn't this a bug in Perl?
• How do I select a random line from a file?
• Why do I get weird spaces when I print an array of lines?
• How do I traverse a directory tree?
• How do I delete a directory tree?
• How do I copy an entire directory?

perlfaq6: 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 can be handled with regular expressions, but those answers are found elsewhere in this document (in perlfaq9 : "How do I decode or create those %-encodings on the web" and perlfaq4 : "How do I determine whether a scalar is a number/whole/integer/float", to be precise).

• How can I hope to use regular expressions without creating illegible and unmaintainable code?
• I'm having trouble matching over more than one line. What's wrong?
• How can I pull out lines between two patterns that are themselves on different lines?
• How do I match XML, HTML, or other nasty, ugly things with a regex?
• I put a regular expression into $/ but it didn't work. What's wrong?
• How do I substitute case-insensitively on the LHS while preserving case on the RHS?
• How can I make "\w" match national character sets?
• How can I match a locale-smart version of "/[a-zA-Z]/" ?
• How can I quote a variable to use in a regex?
• What is "/o" really for?
• How do I use a regular expression to strip C-style comments from a file?
• Can I use Perl regular expressions to match balanced text?
• What does it mean that regexes are greedy? How can I get around it?
• How do I process each word on each line?
• How can I print out a word-frequency or line-frequency summary?
• How can I do approximate matching?
• How do I efficiently match many regular expressions at once?
• Why don't word-boundary searches with "\b" work for me?
• Why does using $&, $`, or $' slow my program down?
• What good is "\G" in a regular expression?
• Are Perl regexes DFAs or NFAs? Are they POSIX compliant?
• What's wrong with using grep in a void context?
• How can I match strings with multibyte characters?
• How do I match a regular expression that's in a variable?

perlfaq7: General Perl Language Issues¶

This section deals with general Perl language issues that don't clearly fit into any of the other sections.

• Can I get a BNF/yacc/RE for the Perl language?
• What are all these $@%&* punctuation signs, and how do I know when to use them?
• Do I always/never have to quote my strings or use semicolons and commas?
• How do I skip some return values?
• How do I temporarily block warnings?
• What's an extension?
• Why do Perl operators have different precedence than C operators?
• How do I declare/create a structure?
• How do I create a module?
• How do I adopt or take over a module already on CPAN?
• How do I create a class?
• How can I tell if a variable is tainted?
• What's a closure?
• What is variable suicide and how can I prevent it?
• How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?
• How do I create a static variable?
• What's the difference between dynamic and lexical (static) scoping? Between local() and my()?
• How can I access a dynamic variable while a similarly named lexical is in scope?
• What's the difference between deep and shallow binding?
• Why doesn't "my($foo) = <$fh>;" work right?
• How do I redefine a builtin function, operator, or method?
• What's the difference between calling a function as &foo and foo()?
• How do I create a switch or case statement?
• How can I catch accesses to undefined variables, functions, or methods?
• Why can't a method included in this same file be found?
• How can I find out my current or calling package?
• How can I comment out a large block of Perl code?
• How do I clear a package?
• How can I use a variable as a variable name?
• What does "bad interpreter" mean?
• Do I need to recompile XS modules when there is a change in the C library?

perlfaq8: System Interaction¶

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.

• How do I find out which operating system I'm running under?
• How come exec() doesn't return?
• How do I do fancy stuff with the keyboard/screen/mouse?
• How do I print something out in color?
• How do I read just one key without waiting for a return key?
• How do I check whether input is ready on the keyboard?
• How do I clear the screen?
• How do I get the screen size?
• How do I ask the user for a password?
• How do I read and write the serial port?
• How do I decode encrypted password files?
• How do I start a process in the background?
• How do I trap control characters/signals?
• How do I modify the shadow password file on a Unix system?
• How do I set the time and date?
• How can I sleep() or alarm() for under a second?
• How can I measure time under a second?
• How can I do an atexit() or setjmp()/longjmp()? (Exception handling)
• Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean?
• How can I call my system's unique C functions from Perl?
• Where do I get the include files to do ioctl() or syscall()?
• Why do setuid perl scripts complain about kernel problems?
• How can I open a pipe both to and from a command?
• Why can't I get the output of a command with system()?
• How can I capture STDERR from an external command?
• Why doesn't open() return an error when a pipe open fails?
• What's wrong with using backticks in a void context?
• How can I call backticks without shell processing?
• Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?
• How can I convert my shell script to perl?
• Can I use perl to run a telnet or ftp session?
• How can I write expect in Perl?
• Is there a way to hide perl's command line from programs such as "ps"?
• 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?
• How do I close a process's filehandle without waiting for it to complete?
• How do I fork a daemon process?
• How do I find out if I'm running interactively or not?
• How do I timeout a slow event?
• How do I set CPU limits?
• How do I avoid zombies on a Unix system?
• How do I use an SQL database?
• How do I make a system() exit on control-C?
• How do I open a file without blocking?
• How do I tell the difference between errors from the shell and perl?
• How do I install a module from CPAN?
• What's the difference between require and use?
• How do I keep my own module/library directory?
• How do I add the directory my program lives in to the module/library search path?
• How do I add a directory to my include path (@INC) at runtime?
• Where are modules installed?
• What is socket.ph and where do I get it?

perlfaq9: Web, Email and Networking¶

This section deals with questions related to running web sites, sending and receiving email as well as general networking.

• Should I use a web framework?
• Which web framework should I use?
• What is Plack and PSGI?
• How do I remove HTML from a string?
• How do I extract URLs?
• How do I fetch an HTML file?
• How do I automate an HTML form submission?
• How do I decode or create those %-encodings on the web?
• How do I redirect to another page?
• How do I put a password on my web pages?
• How do I make sure users can't enter values into a form that causes my CGI script to do bad things?
• How do I parse a mail header?
• How do I check a valid mail address?
• How do I decode a MIME/BASE64 string?
• How do I find the user's mail address?
• How do I send email?
• How do I use MIME to make an attachment to a mail message?
• How do I read email?
• How do I find out my hostname, domainname, or IP address?
• How do I fetch/put an (S)FTP file?
• How can I do RPC in Perl?