This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
update Math-Complex to CPAN version 1.59
[perl5.git] / pod / perlfunc.pod
1 =head1 NAME
2 X<function>
3
4 perlfunc - Perl builtin functions
5
6 =head1 DESCRIPTION
7
8 The functions in this section can serve as terms in an expression.
9 They fall into two major categories: list operators and named unary
10 operators.  These differ in their precedence relationship with a
11 following comma.  (See the precedence table in L<perlop>.)  List
12 operators take more than one argument, while unary operators can never
13 take more than one argument.  Thus, a comma terminates the argument of
14 a unary operator, but merely separates the arguments of a list
15 operator.  A unary operator generally provides scalar context to its
16 argument, while a list operator may provide either scalar or list
17 contexts for its arguments.  If it does both, scalar arguments 
18 come first and list argument follow, and there can only ever
19 be one such list argument.  For instance, splice() has three scalar
20 arguments followed by a list, whereas gethostbyname() has four scalar
21 arguments.
22
23 In the syntax descriptions that follow, list operators that expect a
24 list (and provide list context for elements of the list) are shown
25 with LIST as an argument.  Such a list may consist of any combination
26 of scalar arguments or list values; the list values will be included
27 in the list as if each individual element were interpolated at that
28 point in the list, forming a longer single-dimensional list value.
29 Commas should separate literal elements of the LIST.
30
31 Any function in the list below may be used either with or without
32 parentheses around its arguments.  (The syntax descriptions omit the
33 parentheses.)  If you use parentheses, the simple but occasionally 
34 surprising rule is this: It I<looks> like a function, therefore it I<is> a
35 function, and precedence doesn't matter.  Otherwise it's a list
36 operator or unary operator, and precedence does matter.  Whitespace
37 between the function and left parenthesis doesn't count, so sometimes
38 you need to be careful:
39
40     print 1+2+4;      # Prints 7.
41     print(1+2) + 4;   # Prints 3.
42     print (1+2)+4;    # Also prints 3!
43     print +(1+2)+4;   # Prints 7.
44     print ((1+2)+4);  # Prints 7.
45
46 If you run Perl with the B<-w> switch it can warn you about this.  For
47 example, the third line above produces:
48
49     print (...) interpreted as function at - line 1.
50     Useless use of integer addition in void context at - line 1.
51
52 A few functions take no arguments at all, and therefore work as neither
53 unary nor list operators.  These include such functions as C<time>
54 and C<endpwent>.  For example, C<time+86_400> always means
55 C<time() + 86_400>.
56
57 For functions that can be used in either a scalar or list context,
58 nonabortive failure is generally indicated in scalar context by
59 returning the undefined value, and in list context by returning the
60 empty list.
61
62 Remember the following important rule: There is B<no rule> that relates
63 the behavior of an expression in list context to its behavior in scalar
64 context, or vice versa.  It might do two totally different things.
65 Each operator and function decides which sort of value would be most
66 appropriate to return in scalar context.  Some operators return the
67 length of the list that would have been returned in list context.  Some
68 operators return the first value in the list.  Some operators return the
69 last value in the list.  Some operators return a count of successful
70 operations.  In general, they do what you want, unless you want
71 consistency.
72 X<context>
73
74 A named array in scalar context is quite different from what would at
75 first glance appear to be a list in scalar context.  You can't get a list
76 like C<(1,2,3)> into being in scalar context, because the compiler knows
77 the context at compile time.  It would generate the scalar comma operator
78 there, not the list construction version of the comma.  That means it
79 was never a list to start with.
80
81 In general, functions in Perl that serve as wrappers for system calls ("syscalls")
82 of the same name (like chown(2), fork(2), closedir(2), etc.) return
83 true when they succeed and C<undef> otherwise, as is usually mentioned
84 in the descriptions below.  This is different from the C interfaces,
85 which return C<-1> on failure.  Exceptions to this rule include C<wait>,
86 C<waitpid>, and C<syscall>.  System calls also set the special C<$!>
87 variable on failure.  Other functions do not, except accidentally.
88
89 Extension modules can also hook into the Perl parser to define new
90 kinds of keyword-headed expression.  These may look like functions, but
91 may also look completely different.  The syntax following the keyword
92 is defined entirely by the extension.  If you are an implementor, see
93 L<perlapi/PL_keyword_plugin> for the mechanism.  If you are using such
94 a module, see the module's documentation for details of the syntax that
95 it defines.
96
97 =head2 Perl Functions by Category
98 X<function>
99
100 Here are Perl's functions (including things that look like
101 functions, like some keywords and named operators)
102 arranged by category.  Some functions appear in more
103 than one place.
104
105 =over 4
106
107 =item Functions for SCALARs or strings
108 X<scalar> X<string> X<character>
109
110 C<chomp>, C<chop>, C<chr>, C<crypt>, C<fc>, C<hex>, C<index>, C<lc>,
111 C<lcfirst>, C<length>, C<oct>, C<ord>, C<pack>, C<q//>, C<qq//>, C<reverse>,
112 C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y///>
113
114 =item Regular expressions and pattern matching
115 X<regular expression> X<regex> X<regexp>
116
117 C<m//>, C<pos>, C<quotemeta>, C<s///>, C<split>, C<study>, C<qr//>
118
119 =item Numeric functions
120 X<numeric> X<number> X<trigonometric> X<trigonometry>
121
122 C<abs>, C<atan2>, C<cos>, C<exp>, C<hex>, C<int>, C<log>, C<oct>, C<rand>,
123 C<sin>, C<sqrt>, C<srand>
124
125 =item Functions for real @ARRAYs
126 X<array>
127
128 C<each>, C<keys>, C<pop>, C<push>, C<shift>, C<splice>, C<unshift>, C<values>
129
130 =item Functions for list data
131 X<list>
132
133 C<grep>, C<join>, C<map>, C<qw//>, C<reverse>, C<sort>, C<unpack>
134
135 =item Functions for real %HASHes
136 X<hash>
137
138 C<delete>, C<each>, C<exists>, C<keys>, C<values>
139
140 =item Input and output functions
141 X<I/O> X<input> X<output> X<dbm>
142
143 C<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>,
144 C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>,
145 C<readdir>, C<rewinddir>, C<say>, C<seek>, C<seekdir>, C<select>, C<syscall>,
146 C<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>, C<truncate>,
147 C<warn>, C<write>
148
149 =item Functions for fixed-length data or records
150
151 C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec>
152
153 =item Functions for filehandles, files, or directories
154 X<file> X<filehandle> X<directory> X<pipe> X<link> X<symlink>
155
156 C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
157 C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
158 C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<sysopen>,
159 C<umask>, C<unlink>, C<utime>
160
161 =item Keywords related to the control flow of your Perl program
162 X<control flow>
163
164 C<caller>, C<continue>, C<die>, C<do>,
165 C<dump>, C<eval>, C<evalbytes> C<exit>,
166 C<__FILE__>, C<goto>, C<last>, C<__LINE__>, C<next>, C<__PACKAGE__>,
167 C<redo>, C<return>, C<sub>, C<__SUB__>, C<wantarray>
168
169 C<__SUB__> is only available with a C<use v5.16> (or higher) declaration or
170 with the C<"current_sub"> feature (see L<feature>).
171
172 =item Keywords related to the switch feature
173
174 C<break>, C<continue>, C<default>, C<given>, C<when>
175
176 Except for C<continue>, these are available only if you enable the
177 C<"switch"> feature or use the C<CORE::> prefix.
178 See L<feature> and L<perlsyn/"Switch Statements">.  
179 Alternately, include a C<use v5.10> or later to the current scope.  In Perl
180 5.14 and earlier, C<continue> required the C<"switch"> feature, like the
181 other keywords.
182
183 =item Keywords related to scoping
184
185 C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<state>, C<use>
186
187 C<state> is available only if the C<"state"> feature
188 is enabled or if it is prefixed with C<CORE::>.  See
189 L<feature>.  Alternately, include a C<use v5.10> or later to the current scope.
190
191 =item Miscellaneous functions
192
193 C<defined>, C<dump>, C<eval>, C<evalbytes>,
194 C<formline>, C<local>, C<my>, C<our>,
195 C<reset>, C<scalar>, C<state>, C<undef>, C<wantarray>
196
197 =item Functions for processes and process groups
198 X<process> X<pid> X<process id>
199
200 C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>,
201 C<pipe>, C<qx//>, C<readpipe>, C<setpgrp>,
202 C<setpriority>, C<sleep>, C<system>,
203 C<times>, C<wait>, C<waitpid>
204
205 =item Keywords related to Perl modules
206 X<module>
207
208 C<do>, C<import>, C<no>, C<package>, C<require>, C<use>
209
210 =item Keywords related to classes and object-orientation
211 X<object> X<class> X<package>
212
213 C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>,
214 C<untie>, C<use>
215
216 =item Low-level socket functions
217 X<socket> X<sock>
218
219 C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
220 C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
221 C<socket>, C<socketpair>
222
223 =item System V interprocess communication functions
224 X<IPC> X<System V> X<semaphore> X<shared memory> X<memory> X<message>
225
226 C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>,
227 C<shmctl>, C<shmget>, C<shmread>, C<shmwrite>
228
229 =item Fetching user and group info
230 X<user> X<group> X<password> X<uid> X<gid>  X<passwd> X</etc/passwd>
231
232 C<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>,
233 C<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>,
234 C<getpwuid>, C<setgrent>, C<setpwent>
235
236 =item Fetching network info
237 X<network> X<protocol> X<host> X<hostname> X<IP> X<address> X<service>
238
239 C<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>,
240 C<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
241 C<getprotobyname>, C<getprotobynumber>, C<getprotoent>,
242 C<getservbyname>, C<getservbyport>, C<getservent>, C<sethostent>,
243 C<setnetent>, C<setprotoent>, C<setservent>
244
245 =item Time-related functions
246 X<time> X<date>
247
248 C<gmtime>, C<localtime>, C<time>, C<times>
249
250 =back
251
252 =head2 Portability
253 X<portability> X<Unix> X<portable>
254
255 Perl was born in Unix and can therefore access all common Unix
256 system calls.  In non-Unix environments, the functionality of some
257 Unix system calls may not be available or details of the available
258 functionality may differ slightly.  The Perl functions affected
259 by this are:
260
261 C<-X>, C<binmode>, C<chmod>, C<chown>, C<chroot>, C<crypt>,
262 C<dbmclose>, C<dbmopen>, C<dump>, C<endgrent>, C<endhostent>,
263 C<endnetent>, C<endprotoent>, C<endpwent>, C<endservent>, C<exec>,
264 C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostbyname>,
265 C<gethostent>, C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
266 C<getppid>, C<getpgrp>, C<getpriority>, C<getprotobynumber>,
267 C<getprotoent>, C<getpwent>, C<getpwnam>, C<getpwuid>,
268 C<getservbyport>, C<getservent>, C<getsockopt>, C<glob>, C<ioctl>,
269 C<kill>, C<link>, C<lstat>, C<msgctl>, C<msgget>, C<msgrcv>,
270 C<msgsnd>, C<open>, C<pipe>, C<readlink>, C<rename>, C<select>, C<semctl>,
271 C<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>,
272 C<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>,
273 C<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>,
274 C<shmwrite>, C<socket>, C<socketpair>,
275 C<stat>, C<symlink>, C<syscall>, C<sysopen>, C<system>,
276 C<times>, C<truncate>, C<umask>, C<unlink>,
277 C<utime>, C<wait>, C<waitpid>
278
279 For more information about the portability of these functions, see
280 L<perlport> and other available platform-specific documentation.
281
282 =head2 Alphabetical Listing of Perl Functions
283
284 =over 
285
286 =item -X FILEHANDLE
287 X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p>
288 X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
289
290 =item -X EXPR
291
292 =item -X DIRHANDLE
293
294 =item -X
295
296 A file test, where X is one of the letters listed below.  This unary
297 operator takes one argument, either a filename, a filehandle, or a dirhandle, 
298 and tests the associated file to see if something is true about it.  If the
299 argument is omitted, tests C<$_>, except for C<-t>, which tests STDIN.
300 Unless otherwise documented, it returns C<1> for true and C<''> for false, or
301 the undefined value if the file doesn't exist.  Despite the funny
302 names, precedence is the same as any other named unary operator.  The
303 operator may be any of:
304
305     -r  File is readable by effective uid/gid.
306     -w  File is writable by effective uid/gid.
307     -x  File is executable by effective uid/gid.
308     -o  File is owned by effective uid.
309
310     -R  File is readable by real uid/gid.
311     -W  File is writable by real uid/gid.
312     -X  File is executable by real uid/gid.
313     -O  File is owned by real uid.
314
315     -e  File exists.
316     -z  File has zero size (is empty).
317     -s  File has nonzero size (returns size in bytes).
318
319     -f  File is a plain file.
320     -d  File is a directory.
321     -l  File is a symbolic link.
322     -p  File is a named pipe (FIFO), or Filehandle is a pipe.
323     -S  File is a socket.
324     -b  File is a block special file.
325     -c  File is a character special file.
326     -t  Filehandle is opened to a tty.
327
328     -u  File has setuid bit set.
329     -g  File has setgid bit set.
330     -k  File has sticky bit set.
331
332     -T  File is an ASCII text file (heuristic guess).
333     -B  File is a "binary" file (opposite of -T).
334
335     -M  Script start time minus file modification time, in days.
336     -A  Same for access time.
337     -C  Same for inode change time (Unix, may differ for other platforms)
338
339 Example:
340
341     while (<>) {
342         chomp;
343         next unless -f $_;  # ignore specials
344         #...
345     }
346
347 Note that C<-s/a/b/> does not do a negated substitution.  Saying
348 C<-exp($foo)> still works as expected, however: only single letters
349 following a minus are interpreted as file tests.
350
351 These operators are exempt from the "looks like a function rule" described
352 above.  That is, an opening parenthesis after the operator does not affect
353 how much of the following code constitutes the argument.  Put the opening
354 parentheses before the operator to separate it from code that follows (this
355 applies only to operators with higher precedence than unary operators, of
356 course):
357
358     -s($file) + 1024   # probably wrong; same as -s($file + 1024)
359     (-s $file) + 1024  # correct
360
361 The interpretation of the file permission operators C<-r>, C<-R>,
362 C<-w>, C<-W>, C<-x>, and C<-X> is by default based solely on the mode
363 of the file and the uids and gids of the user.  There may be other
364 reasons you can't actually read, write, or execute the file: for
365 example network filesystem access controls, ACLs (access control lists),
366 read-only filesystems, and unrecognized executable formats.  Note
367 that the use of these six specific operators to verify if some operation
368 is possible is usually a mistake, because it may be open to race
369 conditions.
370
371 Also note that, for the superuser on the local filesystems, the C<-r>,
372 C<-R>, C<-w>, and C<-W> tests always return 1, and C<-x> and C<-X> return 1
373 if any execute bit is set in the mode.  Scripts run by the superuser
374 may thus need to do a stat() to determine the actual mode of the file,
375 or temporarily set their effective uid to something else.
376
377 If you are using ACLs, there is a pragma called C<filetest> that may
378 produce more accurate results than the bare stat() mode bits.
379 When under C<use filetest 'access'> the above-mentioned filetests
380 test whether the permission can(not) be granted using the
381 access(2) family of system calls.  Also note that the C<-x> and C<-X> may
382 under this pragma return true even if there are no execute permission
383 bits set (nor any extra execute permission ACLs).  This strangeness is
384 due to the underlying system calls' definitions.  Note also that, due to
385 the implementation of C<use filetest 'access'>, the C<_> special
386 filehandle won't cache the results of the file tests when this pragma is
387 in effect.  Read the documentation for the C<filetest> pragma for more
388 information.
389
390 The C<-T> and C<-B> switches work as follows.  The first block or so of the
391 file is examined for odd characters such as strange control codes or
392 characters with the high bit set.  If too many strange characters (>30%)
393 are found, it's a C<-B> file; otherwise it's a C<-T> file.  Also, any file
394 containing a zero byte in the first block is considered a binary file.  If C<-T>
395 or C<-B> is used on a filehandle, the current IO buffer is examined
396 rather than the first block.  Both C<-T> and C<-B> return true on an empty
397 file, or a file at EOF when testing a filehandle.  Because you have to
398 read a file to do the C<-T> test, on most occasions you want to use a C<-f>
399 against the file first, as in C<next unless -f $file && -T $file>.
400
401 If any of the file tests (or either the C<stat> or C<lstat> operator) is given
402 the special filehandle consisting of a solitary underline, then the stat
403 structure of the previous file test (or stat operator) is used, saving
404 a system call.  (This doesn't work with C<-t>, and you need to remember
405 that lstat() and C<-l> leave values in the stat structure for the
406 symbolic link, not the real file.)  (Also, if the stat buffer was filled by
407 an C<lstat> call, C<-T> and C<-B> will reset it with the results of C<stat _>).
408 Example:
409
410     print "Can do.\n" if -r $a || -w _ || -x _;
411
412     stat($filename);
413     print "Readable\n" if -r _;
414     print "Writable\n" if -w _;
415     print "Executable\n" if -x _;
416     print "Setuid\n" if -u _;
417     print "Setgid\n" if -g _;
418     print "Sticky\n" if -k _;
419     print "Text\n" if -T _;
420     print "Binary\n" if -B _;
421
422 As of Perl 5.9.1, as a form of purely syntactic sugar, you can stack file
423 test operators, in a way that C<-f -w -x $file> is equivalent to
424 C<-x $file && -w _ && -f _>.  (This is only fancy fancy: if you use
425 the return value of C<-f $file> as an argument to another filetest
426 operator, no special magic will happen.)
427
428 Portability issues: L<perlport/-X>.
429
430 To avoid confusing would-be users of your code with mysterious
431 syntax errors, put something like this at the top of your script:
432
433     use 5.010;  # so filetest ops can stack
434
435 =item abs VALUE
436 X<abs> X<absolute>
437
438 =item abs
439
440 Returns the absolute value of its argument.
441 If VALUE is omitted, uses C<$_>.
442
443 =item accept NEWSOCKET,GENERICSOCKET
444 X<accept>
445
446 Accepts an incoming socket connect, just as accept(2) 
447 does.  Returns the packed address if it succeeded, false otherwise.
448 See the example in L<perlipc/"Sockets: Client/Server Communication">.
449
450 On systems that support a close-on-exec flag on files, the flag will
451 be set for the newly opened file descriptor, as determined by the
452 value of $^F.  See L<perlvar/$^F>.
453
454 =item alarm SECONDS
455 X<alarm>
456 X<SIGALRM>
457 X<timer>
458
459 =item alarm
460
461 Arranges to have a SIGALRM delivered to this process after the
462 specified number of wallclock seconds has elapsed.  If SECONDS is not
463 specified, the value stored in C<$_> is used.  (On some machines,
464 unfortunately, the elapsed time may be up to one second less or more
465 than you specified because of how seconds are counted, and process
466 scheduling may delay the delivery of the signal even further.)
467
468 Only one timer may be counting at once.  Each call disables the
469 previous timer, and an argument of C<0> may be supplied to cancel the
470 previous timer without starting a new one.  The returned value is the
471 amount of time remaining on the previous timer.
472
473 For delays of finer granularity than one second, the Time::HiRes module
474 (from CPAN, and starting from Perl 5.8 part of the standard
475 distribution) provides ualarm().  You may also use Perl's four-argument
476 version of select() leaving the first three arguments undefined, or you
477 might be able to use the C<syscall> interface to access setitimer(2) if
478 your system supports it.  See L<perlfaq8> for details.
479
480 It is usually a mistake to intermix C<alarm> and C<sleep> calls, because
481 C<sleep> may be internally implemented on your system with C<alarm>.
482
483 If you want to use C<alarm> to time out a system call you need to use an
484 C<eval>/C<die> pair.  You can't rely on the alarm causing the system call to
485 fail with C<$!> set to C<EINTR> because Perl sets up signal handlers to
486 restart system calls on some systems.  Using C<eval>/C<die> always works,
487 modulo the caveats given in L<perlipc/"Signals">.
488
489     eval {
490         local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
491         alarm $timeout;
492         $nread = sysread SOCKET, $buffer, $size;
493         alarm 0;
494     };
495     if ($@) {
496         die unless $@ eq "alarm\n";   # propagate unexpected errors
497         # timed out
498     }
499     else {
500         # didn't
501     }
502
503 For more information see L<perlipc>.
504
505 Portability issues: L<perlport/alarm>.
506
507 =item atan2 Y,X
508 X<atan2> X<arctangent> X<tan> X<tangent>
509
510 Returns the arctangent of Y/X in the range -PI to PI.
511
512 For the tangent operation, you may use the C<Math::Trig::tan>
513 function, or use the familiar relation:
514
515     sub tan { sin($_[0]) / cos($_[0])  }
516
517 The return value for C<atan2(0,0)> is implementation-defined; consult
518 your atan2(3) manpage for more information.
519
520 Portability issues: L<perlport/atan2>.
521
522 =item bind SOCKET,NAME
523 X<bind>
524
525 Binds a network address to a socket, just as bind(2)
526 does.  Returns true if it succeeded, false otherwise.  NAME should be a
527 packed address of the appropriate type for the socket.  See the examples in
528 L<perlipc/"Sockets: Client/Server Communication">.
529
530 =item binmode FILEHANDLE, LAYER
531 X<binmode> X<binary> X<text> X<DOS> X<Windows>
532
533 =item binmode FILEHANDLE
534
535 Arranges for FILEHANDLE to be read or written in "binary" or "text"
536 mode on systems where the run-time libraries distinguish between
537 binary and text files.  If FILEHANDLE is an expression, the value is
538 taken as the name of the filehandle.  Returns true on success,
539 otherwise it returns C<undef> and sets C<$!> (errno).
540
541 On some systems (in general, DOS- and Windows-based systems) binmode()
542 is necessary when you're not working with a text file.  For the sake
543 of portability it is a good idea always to use it when appropriate,
544 and never to use it when it isn't appropriate.  Also, people can
545 set their I/O to be by default UTF8-encoded Unicode, not bytes.
546
547 In other words: regardless of platform, use binmode() on binary data,
548 like images, for example.
549
550 If LAYER is present it is a single string, but may contain multiple
551 directives.  The directives alter the behaviour of the filehandle.
552 When LAYER is present, using binmode on a text file makes sense.
553
554 If LAYER is omitted or specified as C<:raw> the filehandle is made
555 suitable for passing binary data.  This includes turning off possible CRLF
556 translation and marking it as bytes (as opposed to Unicode characters).
557 Note that, despite what may be implied in I<"Programming Perl"> (the
558 Camel, 3rd edition) or elsewhere, C<:raw> is I<not> simply the inverse of C<:crlf>.
559 Other layers that would affect the binary nature of the stream are
560 I<also> disabled.  See L<PerlIO>, L<perlrun>, and the discussion about the
561 PERLIO environment variable.
562
563 The C<:bytes>, C<:crlf>, C<:utf8>, and any other directives of the
564 form C<:...>, are called I/O I<layers>.  The C<open> pragma can be used to
565 establish default I/O layers.  See L<open>.
566
567 I<The LAYER parameter of the binmode() function is described as "DISCIPLINE"
568 in "Programming Perl, 3rd Edition".  However, since the publishing of this
569 book, by many known as "Camel III", the consensus of the naming of this
570 functionality has moved from "discipline" to "layer".  All documentation
571 of this version of Perl therefore refers to "layers" rather than to
572 "disciplines".  Now back to the regularly scheduled documentation...>
573
574 To mark FILEHANDLE as UTF-8, use C<:utf8> or C<:encoding(UTF-8)>.
575 C<:utf8> just marks the data as UTF-8 without further checking,
576 while C<:encoding(UTF-8)> checks the data for actually being valid
577 UTF-8.  More details can be found in L<PerlIO::encoding>.
578
579 In general, binmode() should be called after open() but before any I/O
580 is done on the filehandle.  Calling binmode() normally flushes any
581 pending buffered output data (and perhaps pending input data) on the
582 handle.  An exception to this is the C<:encoding> layer that
583 changes the default character encoding of the handle; see L</open>.
584 The C<:encoding> layer sometimes needs to be called in
585 mid-stream, and it doesn't flush the stream.  The C<:encoding>
586 also implicitly pushes on top of itself the C<:utf8> layer because
587 internally Perl operates on UTF8-encoded Unicode characters.
588
589 The operating system, device drivers, C libraries, and Perl run-time
590 system all conspire to let the programmer treat a single
591 character (C<\n>) as the line terminator, irrespective of external
592 representation.  On many operating systems, the native text file
593 representation matches the internal representation, but on some
594 platforms the external representation of C<\n> is made up of more than
595 one character.
596
597 All variants of Unix, Mac OS (old and new), and Stream_LF files on VMS use
598 a single character to end each line in the external representation of text
599 (even though that single character is CARRIAGE RETURN on old, pre-Darwin
600 flavors of Mac OS, and is LINE FEED on Unix and most VMS files).  In other
601 systems like OS/2, DOS, and the various flavors of MS-Windows, your program
602 sees a C<\n> as a simple C<\cJ>, but what's stored in text files are the
603 two characters C<\cM\cJ>.  That means that if you don't use binmode() on
604 these systems, C<\cM\cJ> sequences on disk will be converted to C<\n> on
605 input, and any C<\n> in your program will be converted back to C<\cM\cJ> on
606 output.  This is what you want for text files, but it can be disastrous for
607 binary files.
608
609 Another consequence of using binmode() (on some systems) is that
610 special end-of-file markers will be seen as part of the data stream.
611 For systems from the Microsoft family this means that, if your binary
612 data contain C<\cZ>, the I/O subsystem will regard it as the end of
613 the file, unless you use binmode().
614
615 binmode() is important not only for readline() and print() operations,
616 but also when using read(), seek(), sysread(), syswrite() and tell()
617 (see L<perlport> for more details).  See the C<$/> and C<$\> variables
618 in L<perlvar> for how to manually set your input and output
619 line-termination sequences.
620
621 Portability issues: L<perlport/binmode>.
622
623 =item bless REF,CLASSNAME
624 X<bless>
625
626 =item bless REF
627
628 This function tells the thingy referenced by REF that it is now an object
629 in the CLASSNAME package.  If CLASSNAME is omitted, the current package
630 is used.  Because a C<bless> is often the last thing in a constructor,
631 it returns the reference for convenience.  Always use the two-argument
632 version if a derived class might inherit the function doing the blessing.
633 SeeL<perlobj> for more about the blessing (and blessings) of objects.
634
635 Consider always blessing objects in CLASSNAMEs that are mixed case.
636 Namespaces with all lowercase names are considered reserved for
637 Perl pragmata.  Builtin types have all uppercase names.  To prevent
638 confusion, you may wish to avoid such package names as well.  Make sure
639 that CLASSNAME is a true value.
640
641 See L<perlmod/"Perl Modules">.
642
643 =item break
644
645 Break out of a C<given()> block.
646
647 This keyword is enabled by the C<"switch"> feature: see
648 L<feature> for more information.  You can also access it by
649 prefixing it with C<CORE::>.  Alternately, include a C<use
650 v5.10> or later to the current scope.
651
652 =item caller EXPR
653 X<caller> X<call stack> X<stack> X<stack trace>
654
655 =item caller
656
657 Returns the context of the current subroutine call.  In scalar context,
658 returns the caller's package name if there I<is> a caller (that is, if
659 we're in a subroutine or C<eval> or C<require>) and the undefined value
660 otherwise.  In list context, returns
661
662     # 0         1          2
663     ($package, $filename, $line) = caller;
664
665 With EXPR, it returns some extra information that the debugger uses to
666 print a stack trace.  The value of EXPR indicates how many call frames
667 to go back before the current one.
668
669     #  0         1          2      3            4
670     ($package, $filename, $line, $subroutine, $hasargs,
671
672     #  5          6          7            8       9         10
673     $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
674      = caller($i);
675
676 Here $subroutine may be C<(eval)> if the frame is not a subroutine
677 call, but an C<eval>.  In such a case additional elements $evaltext and
678 C<$is_require> are set: C<$is_require> is true if the frame is created by a
679 C<require> or C<use> statement, $evaltext contains the text of the
680 C<eval EXPR> statement.  In particular, for an C<eval BLOCK> statement,
681 $subroutine is C<(eval)>, but $evaltext is undefined.  (Note also that
682 each C<use> statement creates a C<require> frame inside an C<eval EXPR>
683 frame.)  $subroutine may also be C<(unknown)> if this particular
684 subroutine happens to have been deleted from the symbol table.
685 C<$hasargs> is true if a new instance of C<@_> was set up for the frame.
686 C<$hints> and C<$bitmask> contain pragmatic hints that the caller was
687 compiled with.  The C<$hints> and C<$bitmask> values are subject to change
688 between versions of Perl, and are not meant for external use.
689
690 C<$hinthash> is a reference to a hash containing the value of C<%^H> when the
691 caller was compiled, or C<undef> if C<%^H> was empty.  Do not modify the values
692 of this hash, as they are the actual values stored in the optree.
693
694 Furthermore, when called from within the DB package in
695 list context, and with an argument, caller returns more
696 detailed information: it sets the list variable C<@DB::args> to be the
697 arguments with which the subroutine was invoked.
698
699 Be aware that the optimizer might have optimized call frames away before
700 C<caller> had a chance to get the information.  That means that C<caller(N)>
701 might not return information about the call frame you expect it to, for
702 C<< N > 1 >>.  In particular, C<@DB::args> might have information from the
703 previous time C<caller> was called.
704
705 Be aware that setting C<@DB::args> is I<best effort>, intended for
706 debugging or generating backtraces, and should not be relied upon.  In
707 particular, as C<@_> contains aliases to the caller's arguments, Perl does
708 not take a copy of C<@_>, so C<@DB::args> will contain modifications the
709 subroutine makes to C<@_> or its contents, not the original values at call
710 time.  C<@DB::args>, like C<@_>, does not hold explicit references to its
711 elements, so under certain cases its elements may have become freed and
712 reallocated for other variables or temporary values.  Finally, a side effect
713 of the current implementation is that the effects of C<shift @_> can
714 I<normally> be undone (but not C<pop @_> or other splicing, I<and> not if a
715 reference to C<@_> has been taken, I<and> subject to the caveat about reallocated
716 elements), so C<@DB::args> is actually a hybrid of the current state and
717 initial state of C<@_>.  Buyer beware.
718
719 =item chdir EXPR
720 X<chdir>
721 X<cd>
722 X<directory, change>
723
724 =item chdir FILEHANDLE
725
726 =item chdir DIRHANDLE
727
728 =item chdir
729
730 Changes the working directory to EXPR, if possible.  If EXPR is omitted,
731 changes to the directory specified by C<$ENV{HOME}>, if set; if not,
732 changes to the directory specified by C<$ENV{LOGDIR}>.  (Under VMS, the
733 variable C<$ENV{SYS$LOGIN}> is also checked, and used if it is set.)  If
734 neither is set, C<chdir> does nothing.  It returns true on success,
735 false otherwise.  See the example under C<die>.
736
737 On systems that support fchdir(2), you may pass a filehandle or
738 directory handle as the argument.  On systems that don't support fchdir(2),
739 passing handles raises an exception.
740
741 =item chmod LIST
742 X<chmod> X<permission> X<mode>
743
744 Changes the permissions of a list of files.  The first element of the
745 list must be the numeric mode, which should probably be an octal
746 number, and which definitely should I<not> be a string of octal digits:
747 C<0644> is okay, but C<"0644"> is not.  Returns the number of files
748 successfully changed.  See also L</oct> if all you have is a string.
749
750     $cnt = chmod 0755, "foo", "bar";
751     chmod 0755, @executables;
752     $mode = "0644"; chmod $mode, "foo";      # !!! sets mode to
753                                              # --w----r-T
754     $mode = "0644"; chmod oct($mode), "foo"; # this is better
755     $mode = 0644;   chmod $mode, "foo";      # this is best
756
757 On systems that support fchmod(2), you may pass filehandles among the
758 files.  On systems that don't support fchmod(2), passing filehandles raises
759 an exception.  Filehandles must be passed as globs or glob references to be
760 recognized; barewords are considered filenames.
761
762     open(my $fh, "<", "foo");
763     my $perm = (stat $fh)[2] & 07777;
764     chmod($perm | 0600, $fh);
765
766 You can also import the symbolic C<S_I*> constants from the C<Fcntl>
767 module:
768
769     use Fcntl qw( :mode );
770     chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
771     # Identical to the chmod 0755 of the example above.
772
773 Portability issues: L<perlport/chmod>.
774
775 =item chomp VARIABLE
776 X<chomp> X<INPUT_RECORD_SEPARATOR> X<$/> X<newline> X<eol>
777
778 =item chomp( LIST )
779
780 =item chomp
781
782 This safer version of L</chop> removes any trailing string
783 that corresponds to the current value of C<$/> (also known as
784 $INPUT_RECORD_SEPARATOR in the C<English> module).  It returns the total
785 number of characters removed from all its arguments.  It's often used to
786 remove the newline from the end of an input record when you're worried
787 that the final record may be missing its newline.  When in paragraph
788 mode (C<$/ = "">), it removes all trailing newlines from the string.
789 When in slurp mode (C<$/ = undef>) or fixed-length record mode (C<$/> is
790 a reference to an integer or the like; see L<perlvar>) chomp() won't
791 remove anything.
792 If VARIABLE is omitted, it chomps C<$_>.  Example:
793
794     while (<>) {
795         chomp;  # avoid \n on last field
796         @array = split(/:/);
797         # ...
798     }
799
800 If VARIABLE is a hash, it chomps the hash's values, but not its keys.
801
802 You can actually chomp anything that's an lvalue, including an assignment:
803
804     chomp($cwd = `pwd`);
805     chomp($answer = <STDIN>);
806
807 If you chomp a list, each element is chomped, and the total number of
808 characters removed is returned.
809
810 Note that parentheses are necessary when you're chomping anything
811 that is not a simple variable.  This is because C<chomp $cwd = `pwd`;>
812 is interpreted as C<(chomp $cwd) = `pwd`;>, rather than as
813 C<chomp( $cwd = `pwd` )> which you might expect.  Similarly,
814 C<chomp $a, $b> is interpreted as C<chomp($a), $b> rather than
815 as C<chomp($a, $b)>.
816
817 =item chop VARIABLE
818 X<chop>
819
820 =item chop( LIST )
821
822 =item chop
823
824 Chops off the last character of a string and returns the character
825 chopped.  It is much more efficient than C<s/.$//s> because it neither
826 scans nor copies the string.  If VARIABLE is omitted, chops C<$_>.
827 If VARIABLE is a hash, it chops the hash's values, but not its keys.
828
829 You can actually chop anything that's an lvalue, including an assignment.
830
831 If you chop a list, each element is chopped.  Only the value of the
832 last C<chop> is returned.
833
834 Note that C<chop> returns the last character.  To return all but the last
835 character, use C<substr($string, 0, -1)>.
836
837 See also L</chomp>.
838
839 =item chown LIST
840 X<chown> X<owner> X<user> X<group>
841
842 Changes the owner (and group) of a list of files.  The first two
843 elements of the list must be the I<numeric> uid and gid, in that
844 order.  A value of -1 in either position is interpreted by most
845 systems to leave that value unchanged.  Returns the number of files
846 successfully changed.
847
848     $cnt = chown $uid, $gid, 'foo', 'bar';
849     chown $uid, $gid, @filenames;
850
851 On systems that support fchown(2), you may pass filehandles among the
852 files.  On systems that don't support fchown(2), passing filehandles raises
853 an exception.  Filehandles must be passed as globs or glob references to be
854 recognized; barewords are considered filenames.
855
856 Here's an example that looks up nonnumeric uids in the passwd file:
857
858     print "User: ";
859     chomp($user = <STDIN>);
860     print "Files: ";
861     chomp($pattern = <STDIN>);
862
863     ($login,$pass,$uid,$gid) = getpwnam($user)
864         or die "$user not in passwd file";
865
866     @ary = glob($pattern);  # expand filenames
867     chown $uid, $gid, @ary;
868
869 On most systems, you are not allowed to change the ownership of the
870 file unless you're the superuser, although you should be able to change
871 the group to any of your secondary groups.  On insecure systems, these
872 restrictions may be relaxed, but this is not a portable assumption.
873 On POSIX systems, you can detect this condition this way:
874
875     use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
876     $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
877
878 Portability issues: L<perlport/chmod>.
879
880 =item chr NUMBER
881 X<chr> X<character> X<ASCII> X<Unicode>
882
883 =item chr
884
885 Returns the character represented by that NUMBER in the character set.
886 For example, C<chr(65)> is C<"A"> in either ASCII or Unicode, and
887 chr(0x263a) is a Unicode smiley face.  
888
889 Negative values give the Unicode replacement character (chr(0xfffd)),
890 except under the L<bytes> pragma, where the low eight bits of the value
891 (truncated to an integer) are used.
892
893 If NUMBER is omitted, uses C<$_>.
894
895 For the reverse, use L</ord>.
896
897 Note that characters from 128 to 255 (inclusive) are by default
898 internally not encoded as UTF-8 for backward compatibility reasons.
899
900 See L<perlunicode> for more about Unicode.
901
902 =item chroot FILENAME
903 X<chroot> X<root>
904
905 =item chroot
906
907 This function works like the system call by the same name: it makes the
908 named directory the new root directory for all further pathnames that
909 begin with a C</> by your process and all its children.  (It doesn't
910 change your current working directory, which is unaffected.)  For security
911 reasons, this call is restricted to the superuser.  If FILENAME is
912 omitted, does a C<chroot> to C<$_>.
913
914 Portability issues: L<perlport/chroot>.
915
916 =item close FILEHANDLE
917 X<close>
918
919 =item close
920
921 Closes the file or pipe associated with the filehandle, flushes the IO
922 buffers, and closes the system file descriptor.  Returns true if those
923 operations succeed and if no error was reported by any PerlIO
924 layer.  Closes the currently selected filehandle if the argument is
925 omitted.
926
927 You don't have to close FILEHANDLE if you are immediately going to do
928 another C<open> on it, because C<open> closes it for you.  (See
929 L<open|/open FILEHANDLE>.)  However, an explicit C<close> on an input file resets the line
930 counter (C<$.>), while the implicit close done by C<open> does not.
931
932 If the filehandle came from a piped open, C<close> returns false if one of
933 the other syscalls involved fails or if its program exits with non-zero
934 status.  If the only problem was that the program exited non-zero, C<$!>
935 will be set to C<0>.  Closing a pipe also waits for the process executing
936 on the pipe to exit--in case you wish to look at the output of the pipe
937 afterwards--and implicitly puts the exit status value of that command into
938 C<$?> and C<${^CHILD_ERROR_NATIVE}>.
939
940 If there are multiple threads running, C<close> on a filehandle from a
941 piped open returns true without waiting for the child process to terminate,
942 if the filehandle is still open in another thread.
943
944 Closing the read end of a pipe before the process writing to it at the
945 other end is done writing results in the writer receiving a SIGPIPE.  If
946 the other end can't handle that, be sure to read all the data before
947 closing the pipe.
948
949 Example:
950
951     open(OUTPUT, '|sort >foo')  # pipe to sort
952         or die "Can't start sort: $!";
953     #...                        # print stuff to output
954     close OUTPUT                # wait for sort to finish
955         or warn $! ? "Error closing sort pipe: $!"
956                    : "Exit status $? from sort";
957     open(INPUT, 'foo')          # get sort's results
958         or die "Can't open 'foo' for input: $!";
959
960 FILEHANDLE may be an expression whose value can be used as an indirect
961 filehandle, usually the real filehandle name or an autovivified handle.
962
963 =item closedir DIRHANDLE
964 X<closedir>
965
966 Closes a directory opened by C<opendir> and returns the success of that
967 system call.
968
969 =item connect SOCKET,NAME
970 X<connect>
971
972 Attempts to connect to a remote socket, just like connect(2).
973 Returns true if it succeeded, false otherwise.  NAME should be a
974 packed address of the appropriate type for the socket.  See the examples in
975 L<perlipc/"Sockets: Client/Server Communication">.
976
977 =item continue BLOCK
978 X<continue>
979
980 =item continue
981
982 When followed by a BLOCK, C<continue> is actually a
983 flow control statement rather than a function.  If
984 there is a C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
985 C<foreach>), it is always executed just before the conditional is about to
986 be evaluated again, just like the third part of a C<for> loop in C.  Thus
987 it can be used to increment a loop variable, even when the loop has been
988 continued via the C<next> statement (which is similar to the C C<continue>
989 statement).
990
991 C<last>, C<next>, or C<redo> may appear within a C<continue>
992 block; C<last> and C<redo> behave as if they had been executed within
993 the main block.  So will C<next>, but since it will execute a C<continue>
994 block, it may be more entertaining.
995
996     while (EXPR) {
997         ### redo always comes here
998         do_something;
999     } continue {
1000         ### next always comes here
1001         do_something_else;
1002         # then back the top to re-check EXPR
1003     }
1004     ### last always comes here
1005
1006 Omitting the C<continue> section is equivalent to using an
1007 empty one, logically enough, so C<next> goes directly back
1008 to check the condition at the top of the loop.
1009
1010 When there is no BLOCK, C<continue> is a function that
1011 falls through the current C<when> or C<default> block instead of iterating
1012 a dynamically enclosing C<foreach> or exiting a lexically enclosing C<given>.
1013 In Perl 5.14 and earlier, this form of C<continue> was
1014 only available when the C<"switch"> feature was enabled.
1015 See L<feature> and L<perlsyn/"Switch Statements"> for more
1016 information.
1017
1018 =item cos EXPR
1019 X<cos> X<cosine> X<acos> X<arccosine>
1020
1021 =item cos
1022
1023 Returns the cosine of EXPR (expressed in radians).  If EXPR is omitted,
1024 takes the cosine of C<$_>.
1025
1026 For the inverse cosine operation, you may use the C<Math::Trig::acos()>
1027 function, or use this relation:
1028
1029     sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
1030
1031 =item crypt PLAINTEXT,SALT
1032 X<crypt> X<digest> X<hash> X<salt> X<plaintext> X<password>
1033 X<decrypt> X<cryptography> X<passwd> X<encrypt>
1034
1035 Creates a digest string exactly like the crypt(3) function in the C
1036 library (assuming that you actually have a version there that has not
1037 been extirpated as a potential munition).
1038
1039 crypt() is a one-way hash function.  The PLAINTEXT and SALT are turned
1040 into a short string, called a digest, which is returned.  The same
1041 PLAINTEXT and SALT will always return the same string, but there is no
1042 (known) way to get the original PLAINTEXT from the hash.  Small
1043 changes in the PLAINTEXT or SALT will result in large changes in the
1044 digest.
1045
1046 There is no decrypt function.  This function isn't all that useful for
1047 cryptography (for that, look for F<Crypt> modules on your nearby CPAN
1048 mirror) and the name "crypt" is a bit of a misnomer.  Instead it is
1049 primarily used to check if two pieces of text are the same without
1050 having to transmit or store the text itself.  An example is checking
1051 if a correct password is given.  The digest of the password is stored,
1052 not the password itself.  The user types in a password that is
1053 crypt()'d with the same salt as the stored digest.  If the two digests
1054 match, the password is correct.
1055
1056 When verifying an existing digest string you should use the digest as
1057 the salt (like C<crypt($plain, $digest) eq $digest>).  The SALT used
1058 to create the digest is visible as part of the digest.  This ensures
1059 crypt() will hash the new string with the same salt as the digest.
1060 This allows your code to work with the standard L<crypt|/crypt> and
1061 with more exotic implementations.  In other words, assume
1062 nothing about the returned string itself nor about how many bytes 
1063 of SALT may matter.
1064
1065 Traditionally the result is a string of 13 bytes: two first bytes of
1066 the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only
1067 the first eight bytes of PLAINTEXT mattered.  But alternative
1068 hashing schemes (like MD5), higher level security schemes (like C2),
1069 and implementations on non-Unix platforms may produce different
1070 strings.
1071
1072 When choosing a new salt create a random two character string whose
1073 characters come from the set C<[./0-9A-Za-z]> (like C<join '', ('.',
1074 '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>).  This set of
1075 characters is just a recommendation; the characters allowed in
1076 the salt depend solely on your system's crypt library, and Perl can't
1077 restrict what salts C<crypt()> accepts.
1078
1079 Here's an example that makes sure that whoever runs this program knows
1080 their password:
1081
1082     $pwd = (getpwuid($<))[1];
1083
1084     system "stty -echo";
1085     print "Password: ";
1086     chomp($word = <STDIN>);
1087     print "\n";
1088     system "stty echo";
1089
1090     if (crypt($word, $pwd) ne $pwd) {
1091         die "Sorry...\n";
1092     } else {
1093         print "ok\n";
1094     }
1095
1096 Of course, typing in your own password to whoever asks you
1097 for it is unwise.
1098
1099 The L<crypt|/crypt> function is unsuitable for hashing large quantities
1100 of data, not least of all because you can't get the information
1101 back.  Look at the L<Digest> module for more robust algorithms.
1102
1103 If using crypt() on a Unicode string (which I<potentially> has
1104 characters with codepoints above 255), Perl tries to make sense
1105 of the situation by trying to downgrade (a copy of)
1106 the string back to an eight-bit byte string before calling crypt()
1107 (on that copy).  If that works, good.  If not, crypt() dies with
1108 C<Wide character in crypt>.
1109
1110 Portability issues: L<perlport/crypt>.
1111
1112 =item dbmclose HASH
1113 X<dbmclose>
1114
1115 [This function has been largely superseded by the C<untie> function.]
1116
1117 Breaks the binding between a DBM file and a hash.
1118
1119 Portability issues: L<perlport/dbmclose>.
1120
1121 =item dbmopen HASH,DBNAME,MASK
1122 X<dbmopen> X<dbm> X<ndbm> X<sdbm> X<gdbm>
1123
1124 [This function has been largely superseded by the
1125 L<tie|/tie VARIABLE,CLASSNAME,LIST> function.]
1126
1127 This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a
1128 hash.  HASH is the name of the hash.  (Unlike normal C<open>, the first
1129 argument is I<not> a filehandle, even though it looks like one).  DBNAME
1130 is the name of the database (without the F<.dir> or F<.pag> extension if
1131 any).  If the database does not exist, it is created with protection
1132 specified by MASK (as modified by the C<umask>).  To prevent creation of
1133 the database if it doesn't exist, you may specify a MODE
1134 of 0, and the function will return a false value if it
1135 can't find an existing database.  If your system supports
1136 only the older DBM functions, you may make only one C<dbmopen> call in your
1137 program.  In older versions of Perl, if your system had neither DBM nor
1138 ndbm, calling C<dbmopen> produced a fatal error; it now falls back to
1139 sdbm(3).
1140
1141 If you don't have write access to the DBM file, you can only read hash
1142 variables, not set them.  If you want to test whether you can write,
1143 either use file tests or try setting a dummy hash entry inside an C<eval> 
1144 to trap the error.
1145
1146 Note that functions such as C<keys> and C<values> may return huge lists
1147 when used on large DBM files.  You may prefer to use the C<each>
1148 function to iterate over large DBM files.  Example:
1149
1150     # print out history file offsets
1151     dbmopen(%HIST,'/usr/lib/news/history',0666);
1152     while (($key,$val) = each %HIST) {
1153         print $key, ' = ', unpack('L',$val), "\n";
1154     }
1155     dbmclose(%HIST);
1156
1157 See also L<AnyDBM_File> for a more general description of the pros and
1158 cons of the various dbm approaches, as well as L<DB_File> for a particularly
1159 rich implementation.
1160
1161 You can control which DBM library you use by loading that library
1162 before you call dbmopen():
1163
1164     use DB_File;
1165     dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
1166         or die "Can't open netscape history file: $!";
1167
1168 Portability issues: L<perlport/dbmopen>.
1169
1170 =item default BLOCK
1171
1172 Within a C<foreach> or a C<given>, a C<default> BLOCK acts like a C<when>
1173 that's always true.  Only available after Perl 5.10, and only if the
1174 C<switch> feature has been requested or if the keyword is prefixed with
1175 C<CORE::>.  See L</when>.
1176
1177 =item defined EXPR
1178 X<defined> X<undef> X<undefined>
1179
1180 =item defined
1181
1182 Returns a Boolean value telling whether EXPR has a value other than
1183 the undefined value C<undef>.  If EXPR is not present, C<$_> is
1184 checked.
1185
1186 Many operations return C<undef> to indicate failure, end of file,
1187 system error, uninitialized variable, and other exceptional
1188 conditions.  This function allows you to distinguish C<undef> from
1189 other values.  (A simple Boolean test will not distinguish among
1190 C<undef>, zero, the empty string, and C<"0">, which are all equally
1191 false.)  Note that since C<undef> is a valid scalar, its presence
1192 doesn't I<necessarily> indicate an exceptional condition: C<pop>
1193 returns C<undef> when its argument is an empty array, I<or> when the
1194 element to return happens to be C<undef>.
1195
1196 You may also use C<defined(&func)> to check whether subroutine C<&func>
1197 has ever been defined.  The return value is unaffected by any forward
1198 declarations of C<&func>.  A subroutine that is not defined
1199 may still be callable: its package may have an C<AUTOLOAD> method that
1200 makes it spring into existence the first time that it is called; see
1201 L<perlsub>.
1202
1203 Use of C<defined> on aggregates (hashes and arrays) is deprecated.  It
1204 used to report whether memory for that aggregate had ever been
1205 allocated.  This behavior may disappear in future versions of Perl.
1206 You should instead use a simple test for size:
1207
1208     if (@an_array) { print "has array elements\n" }
1209     if (%a_hash)   { print "has hash members\n"   }
1210
1211 When used on a hash element, it tells you whether the value is defined,
1212 not whether the key exists in the hash.  Use L</exists> for the latter
1213 purpose.
1214
1215 Examples:
1216
1217     print if defined $switch{D};
1218     print "$val\n" while defined($val = pop(@ary));
1219     die "Can't readlink $sym: $!"
1220         unless defined($value = readlink $sym);
1221     sub foo { defined &$bar ? &$bar(@_) : die "No bar"; }
1222     $debugging = 0 unless defined $debugging;
1223
1224 Note:  Many folks tend to overuse C<defined> and are then surprised to
1225 discover that the number C<0> and C<""> (the zero-length string) are, in fact,
1226 defined values.  For example, if you say
1227
1228     "ab" =~ /a(.*)b/;
1229
1230 The pattern match succeeds and C<$1> is defined, although it
1231 matched "nothing".  It didn't really fail to match anything.  Rather, it
1232 matched something that happened to be zero characters long.  This is all
1233 very above-board and honest.  When a function returns an undefined value,
1234 it's an admission that it couldn't give you an honest answer.  So you
1235 should use C<defined> only when questioning the integrity of what
1236 you're trying to do.  At other times, a simple comparison to C<0> or C<""> is
1237 what you want.
1238
1239 See also L</undef>, L</exists>, L</ref>.
1240
1241 =item delete EXPR
1242 X<delete>
1243
1244 Given an expression that specifies an element or slice of a hash, C<delete>
1245 deletes the specified elements from that hash so that exists() on that element
1246 no longer returns true.  Setting a hash element to the undefined value does
1247 not remove its key, but deleting it does; see L</exists>.
1248
1249 In list context, returns the value or values deleted, or the last such
1250 element in scalar context.  The return list's length always matches that of
1251 the argument list: deleting non-existent elements returns the undefined value
1252 in their corresponding positions.
1253
1254 delete() may also be used on arrays and array slices, but its behavior is less
1255 straightforward.  Although exists() will return false for deleted entries,
1256 deleting array elements never changes indices of existing values; use shift()
1257 or splice() for that.  However, if all deleted elements fall at the end of an
1258 array, the array's size shrinks to the position of the highest element that
1259 still tests true for exists(), or to 0 if none do.
1260
1261 B<WARNING:> Calling delete on array values is deprecated and likely to
1262 be removed in a future version of Perl.
1263
1264 Deleting from C<%ENV> modifies the environment.  Deleting from a hash tied to
1265 a DBM file deletes the entry from the DBM file.  Deleting from a C<tied> hash
1266 or array may not necessarily return anything; it depends on the implementation
1267 of the C<tied> package's DELETE method, which may do whatever it pleases.
1268
1269 The C<delete local EXPR> construct localizes the deletion to the current
1270 block at run time.  Until the block exits, elements locally deleted
1271 temporarily no longer exist.  See L<perlsub/"Localized deletion of elements
1272 of composite types">.
1273
1274     %hash = (foo => 11, bar => 22, baz => 33);
1275     $scalar = delete $hash{foo};             # $scalar is 11
1276     $scalar = delete @hash{qw(foo bar)};     # $scalar is 22
1277     @array  = delete @hash{qw(foo bar baz)}; # @array  is (undef,undef,33)
1278
1279 The following (inefficiently) deletes all the values of %HASH and @ARRAY:
1280
1281     foreach $key (keys %HASH) {
1282         delete $HASH{$key};
1283     }
1284
1285     foreach $index (0 .. $#ARRAY) {
1286         delete $ARRAY[$index];
1287     }
1288
1289 And so do these:
1290
1291     delete @HASH{keys %HASH};
1292
1293     delete @ARRAY[0 .. $#ARRAY];
1294
1295 But both are slower than assigning the empty list
1296 or undefining %HASH or @ARRAY, which is the customary 
1297 way to empty out an aggregate:
1298
1299     %HASH = ();     # completely empty %HASH
1300     undef %HASH;    # forget %HASH ever existed
1301
1302     @ARRAY = ();    # completely empty @ARRAY
1303     undef @ARRAY;   # forget @ARRAY ever existed
1304
1305 The EXPR can be arbitrarily complicated provided its
1306 final operation is an element or slice of an aggregate:
1307
1308     delete $ref->[$x][$y]{$key};
1309     delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};
1310
1311     delete $ref->[$x][$y][$index];
1312     delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
1313
1314 =item die LIST
1315 X<die> X<throw> X<exception> X<raise> X<$@> X<abort>
1316
1317 C<die> raises an exception.  Inside an C<eval> the error message is stuffed
1318 into C<$@> and the C<eval> is terminated with the undefined value.
1319 If the exception is outside of all enclosing C<eval>s, then the uncaught
1320 exception prints LIST to C<STDERR> and exits with a non-zero value.  If you
1321 need to exit the process with a specific exit code, see L</exit>.
1322
1323 Equivalent examples:
1324
1325     die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
1326     chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
1327
1328 If the last element of LIST does not end in a newline, the current
1329 script line number and input line number (if any) are also printed,
1330 and a newline is supplied.  Note that the "input line number" (also
1331 known as "chunk") is subject to whatever notion of "line" happens to
1332 be currently in effect, and is also available as the special variable
1333 C<$.>.  See L<perlvar/"$/"> and L<perlvar/"$.">.
1334
1335 Hint: sometimes appending C<", stopped"> to your message will cause it
1336 to make better sense when the string C<"at foo line 123"> is appended.
1337 Suppose you are running script "canasta".
1338
1339     die "/etc/games is no good";
1340     die "/etc/games is no good, stopped";
1341
1342 produce, respectively
1343
1344     /etc/games is no good at canasta line 123.
1345     /etc/games is no good, stopped at canasta line 123.
1346
1347 If the output is empty and C<$@> already contains a value (typically from a
1348 previous eval) that value is reused after appending C<"\t...propagated">.
1349 This is useful for propagating exceptions:
1350
1351     eval { ... };
1352     die unless $@ =~ /Expected exception/;
1353
1354 If the output is empty and C<$@> contains an object reference that has a
1355 C<PROPAGATE> method, that method will be called with additional file
1356 and line number parameters.  The return value replaces the value in
1357 C<$@>;  i.e., as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >>
1358 were called.
1359
1360 If C<$@> is empty then the string C<"Died"> is used.
1361
1362 If an uncaught exception results in interpreter exit, the exit code is
1363 determined from the values of C<$!> and C<$?> with this pseudocode:
1364
1365     exit $! if $!;              # errno
1366     exit $? >> 8 if $? >> 8;    # child exit status
1367     exit 255;                   # last resort
1368
1369 The intent is to squeeze as much possible information about the likely cause
1370 into the limited space of the system exit
1371 code.  However, as C<$!> is the value
1372 of C's C<errno>, which can be set by any system call, this means that the value
1373 of the exit code used by C<die> can be non-predictable, so should not be relied
1374 upon, other than to be non-zero.
1375
1376 You can also call C<die> with a reference argument, and if this is trapped
1377 within an C<eval>, C<$@> contains that reference.  This permits more
1378 elaborate exception handling using objects that maintain arbitrary state
1379 about the exception.  Such a scheme is sometimes preferable to matching
1380 particular string values of C<$@> with regular expressions.  Because C<$@> 
1381 is a global variable and C<eval> may be used within object implementations,
1382 be careful that analyzing the error object doesn't replace the reference in
1383 the global variable.  It's easiest to make a local copy of the reference
1384 before any manipulations.  Here's an example:
1385
1386     use Scalar::Util "blessed";
1387
1388     eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
1389     if (my $ev_err = $@) {
1390         if (blessed($ev_err) && $ev_err->isa("Some::Module::Exception")) {
1391             # handle Some::Module::Exception
1392         }
1393         else {
1394             # handle all other possible exceptions
1395         }
1396     }
1397
1398 Because Perl stringifies uncaught exception messages before display,
1399 you'll probably want to overload stringification operations on
1400 exception objects.  See L<overload> for details about that.
1401
1402 You can arrange for a callback to be run just before the C<die>
1403 does its deed, by setting the C<$SIG{__DIE__}> hook.  The associated
1404 handler is called with the error text and can change the error
1405 message, if it sees fit, by calling C<die> again.  See
1406 L<perlvar/%SIG> for details on setting C<%SIG> entries, and
1407 L<"eval BLOCK"> for some examples.  Although this feature was 
1408 to be run only right before your program was to exit, this is not
1409 currently so: the C<$SIG{__DIE__}> hook is currently called
1410 even inside eval()ed blocks/strings!  If one wants the hook to do
1411 nothing in such situations, put
1412
1413     die @_ if $^S;
1414
1415 as the first line of the handler (see L<perlvar/$^S>).  Because
1416 this promotes strange action at a distance, this counterintuitive
1417 behavior may be fixed in a future release.
1418
1419 See also exit(), warn(), and the Carp module.
1420
1421 =item do BLOCK
1422 X<do> X<block>
1423
1424 Not really a function.  Returns the value of the last command in the
1425 sequence of commands indicated by BLOCK.  When modified by the C<while> or
1426 C<until> loop modifier, executes the BLOCK once before testing the loop
1427 condition.  (On other statements the loop modifiers test the conditional
1428 first.)
1429
1430 C<do BLOCK> does I<not> count as a loop, so the loop control statements
1431 C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
1432 See L<perlsyn> for alternative strategies.
1433
1434 =item do SUBROUTINE(LIST)
1435 X<do>
1436
1437 This form of subroutine call is deprecated.  SUBROUTINE can be a bareword,
1438 a scalar variable or a subroutine beginning with C<&>.
1439
1440 =item do EXPR
1441 X<do>
1442
1443 Uses the value of EXPR as a filename and executes the contents of the
1444 file as a Perl script.
1445
1446     do 'stat.pl';
1447
1448 is just like
1449
1450     eval `cat stat.pl`;
1451
1452 except that it's more efficient and concise, keeps track of the current
1453 filename for error messages, searches the C<@INC> directories, and updates
1454 C<%INC> if the file is found.  See L<perlvar/@INC> and L<perlvar/%INC> for
1455 these variables.  It also differs in that code evaluated with C<do FILENAME>
1456 cannot see lexicals in the enclosing scope; C<eval STRING> does.  It's the
1457 same, however, in that it does reparse the file every time you call it,
1458 so you probably don't want to do this inside a loop.
1459
1460 If C<do> can read the file but cannot compile it, it returns C<undef> and sets
1461 an error message in C<$@>.  If C<do> cannot read the file, it returns undef
1462 and sets C<$!> to the error.  Always check C<$@> first, as compilation
1463 could fail in a way that also sets C<$!>.  If the file is successfully
1464 compiled, C<do> returns the value of the last expression evaluated.
1465
1466 Inclusion of library modules is better done with the
1467 C<use> and C<require> operators, which also do automatic error checking
1468 and raise an exception if there's a problem.
1469
1470 You might like to use C<do> to read in a program configuration
1471 file.  Manual error checking can be done this way:
1472
1473     # read in config files: system first, then user
1474     for $file ("/share/prog/defaults.rc",
1475                "$ENV{HOME}/.someprogrc")
1476     {
1477         unless ($return = do $file) {
1478             warn "couldn't parse $file: $@" if $@;
1479             warn "couldn't do $file: $!"    unless defined $return;
1480             warn "couldn't run $file"       unless $return;
1481         }
1482     }
1483
1484 =item dump LABEL
1485 X<dump> X<core> X<undump>
1486
1487 =item dump
1488
1489 This function causes an immediate core dump.  See also the B<-u>
1490 command-line switch in L<perlrun>, which does the same thing.
1491 Primarily this is so that you can use the B<undump> program (not
1492 supplied) to turn your core dump into an executable binary after
1493 having initialized all your variables at the beginning of the
1494 program.  When the new binary is executed it will begin by executing
1495 a C<goto LABEL> (with all the restrictions that C<goto> suffers).
1496 Think of it as a goto with an intervening core dump and reincarnation.
1497 If C<LABEL> is omitted, restarts the program from the top.
1498
1499 B<WARNING>: Any files opened at the time of the dump will I<not>
1500 be open any more when the program is reincarnated, with possible
1501 resulting confusion by Perl.
1502
1503 This function is now largely obsolete, mostly because it's very hard to
1504 convert a core file into an executable.  That's why you should now invoke
1505 it as C<CORE::dump()>, if you don't want to be warned against a possible
1506 typo.
1507
1508 Portability issues: L<perlport/dump>.
1509
1510 =item each HASH
1511 X<each> X<hash, iterator>
1512
1513 =item each ARRAY
1514 X<array, iterator>
1515
1516 =item each EXPR
1517
1518 When called on a hash in list context, returns a 2-element list
1519 consisting of the key and value for the next element of a hash.  In Perl
1520 5.12 and later only, it will also return the index and value for the next
1521 element of an array so that you can iterate over it; older Perls consider
1522 this a syntax error.  When called in scalar context, returns only the key
1523 (not the value) in a hash, or the index in an array.
1524
1525 Hash entries are returned in an apparently random order.  The actual random
1526 order is subject to change in future versions of Perl, but it is
1527 guaranteed to be in the same order as either the C<keys> or C<values>
1528 function would produce on the same (unmodified) hash.  Since Perl
1529 5.8.2 the ordering can be different even between different runs of Perl
1530 for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
1531
1532 After C<each> has returned all entries from the hash or array, the next
1533 call to C<each> returns the empty list in list context and C<undef> in
1534 scalar context; the next call following I<that> one restarts iteration.
1535 Each hash or array has its own internal iterator, accessed by C<each>,
1536 C<keys>, and C<values>.  The iterator is implicitly reset when C<each> has
1537 reached the end as just described; it can be explicitly reset by calling
1538 C<keys> or C<values> on the hash or array.  If you add or delete a hash's
1539 elements while iterating over it, entries may be skipped or duplicated--so
1540 don't do that.  Exception: In the current implementation, it is always safe
1541 to delete the item most recently returned by C<each()>, so the following
1542 code works properly:
1543
1544         while (($key, $value) = each %hash) {
1545           print $key, "\n";
1546           delete $hash{$key};   # This is safe
1547         }
1548
1549 This prints out your environment like the printenv(1) program,
1550 but in a different order:
1551
1552     while (($key,$value) = each %ENV) {
1553         print "$key=$value\n";
1554     }
1555
1556 Starting with Perl 5.14, C<each> can take a scalar EXPR, which must hold
1557 reference to an unblessed hash or array.  The argument will be dereferenced
1558 automatically.  This aspect of C<each> is considered highly experimental.
1559 The exact behaviour may change in a future version of Perl.
1560
1561     while (($key,$value) = each $hashref) { ... }
1562
1563 To avoid confusing would-be users of your code who are running earlier
1564 versions of Perl with mysterious syntax errors, put this sort of thing at
1565 the top of your file to signal that your code will work I<only> on Perls of
1566 a recent vintage:
1567
1568     use 5.012;  # so keys/values/each work on arrays
1569     use 5.014;  # so keys/values/each work on scalars (experimental)
1570
1571 See also C<keys>, C<values>, and C<sort>.
1572
1573 =item eof FILEHANDLE
1574 X<eof>
1575 X<end of file>
1576 X<end-of-file>
1577
1578 =item eof ()
1579
1580 =item eof
1581
1582 Returns 1 if the next read on FILEHANDLE will return end of file I<or> if
1583 FILEHANDLE is not open.  FILEHANDLE may be an expression whose value
1584 gives the real filehandle.  (Note that this function actually
1585 reads a character and then C<ungetc>s it, so isn't useful in an
1586 interactive context.)  Do not read from a terminal file (or call
1587 C<eof(FILEHANDLE)> on it) after end-of-file is reached.  File types such
1588 as terminals may lose the end-of-file condition if you do.
1589
1590 An C<eof> without an argument uses the last file read.  Using C<eof()>
1591 with empty parentheses is different.  It refers to the pseudo file
1592 formed from the files listed on the command line and accessed via the
1593 C<< <> >> operator.  Since C<< <> >> isn't explicitly opened,
1594 as a normal filehandle is, an C<eof()> before C<< <> >> has been
1595 used will cause C<@ARGV> to be examined to determine if input is
1596 available.   Similarly, an C<eof()> after C<< <> >> has returned
1597 end-of-file will assume you are processing another C<@ARGV> list,
1598 and if you haven't set C<@ARGV>, will read input from C<STDIN>;
1599 see L<perlop/"I/O Operators">.
1600
1601 In a C<< while (<>) >> loop, C<eof> or C<eof(ARGV)> can be used to
1602 detect the end of each file, whereas C<eof()> will detect the end 
1603 of the very last file only.  Examples:
1604
1605     # reset line numbering on each input file
1606     while (<>) {
1607         next if /^\s*#/;  # skip comments
1608         print "$.\t$_";
1609     } continue {
1610         close ARGV if eof;  # Not eof()!
1611     }
1612
1613     # insert dashes just before last line of last file
1614     while (<>) {
1615         if (eof()) {  # check for end of last file
1616             print "--------------\n";
1617         }
1618         print;
1619         last if eof();      # needed if we're reading from a terminal
1620     }
1621
1622 Practical hint: you almost never need to use C<eof> in Perl, because the
1623 input operators typically return C<undef> when they run out of data or 
1624 encounter an error.
1625
1626 =item eval EXPR
1627 X<eval> X<try> X<catch> X<evaluate> X<parse> X<execute>
1628 X<error, handling> X<exception, handling>
1629
1630 =item eval BLOCK
1631
1632 =item eval
1633
1634 In the first form, the return value of EXPR is parsed and executed as if it
1635 were a little Perl program.  The value of the expression (which is itself
1636 determined within scalar context) is first parsed, and if there were no
1637 errors, executed as a block within the lexical context of the current Perl
1638 program.  This means, that in particular, any outer lexical variables are
1639 visible to it, and any package variable settings or subroutine and format
1640 definitions remain afterwards.
1641
1642 Note that the value is parsed every time the C<eval> executes.
1643 If EXPR is omitted, evaluates C<$_>.  This form is typically used to
1644 delay parsing and subsequent execution of the text of EXPR until run time.
1645
1646 If the C<unicode_eval> feature is enabled (which is the default under a
1647 C<use 5.16> or higher declaration), EXPR or C<$_> is treated as a string of
1648 characters, so C<use utf8> declarations have no effect, and source filters
1649 are forbidden.  In the absence of the C<unicode_eval> feature, the string
1650 will sometimes be treated as characters and sometimes as bytes, depending
1651 on the internal encoding, and source filters activated within the C<eval>
1652 exhibit the erratic, but historical, behaviour of affecting some outer file
1653 scope that is still compiling.  See also the L</evalbytes> keyword, which
1654 always treats its input as a byte stream and works properly with source
1655 filters, and the L<feature> pragma.
1656
1657 In the second form, the code within the BLOCK is parsed only once--at the
1658 same time the code surrounding the C<eval> itself was parsed--and executed
1659 within the context of the current Perl program.  This form is typically
1660 used to trap exceptions more efficiently than the first (see below), while
1661 also providing the benefit of checking the code within BLOCK at compile
1662 time.
1663
1664 The final semicolon, if any, may be omitted from the value of EXPR or within
1665 the BLOCK.
1666
1667 In both forms, the value returned is the value of the last expression
1668 evaluated inside the mini-program; a return statement may be also used, just
1669 as with subroutines.  The expression providing the return value is evaluated
1670 in void, scalar, or list context, depending on the context of the C<eval> 
1671 itself.  See L</wantarray> for more on how the evaluation context can be 
1672 determined.
1673
1674 If there is a syntax error or runtime error, or a C<die> statement is
1675 executed, C<eval> returns C<undef> in scalar context
1676 or an empty list in list context, and C<$@> is set to the error
1677 message.  (Prior to 5.16, a bug caused C<undef> to be returned
1678 in list context for syntax errors, but not for runtime errors.)
1679 If there was no error, C<$@> is set to the empty string.  A
1680 control flow operator like C<last> or C<goto> can bypass the setting of
1681 C<$@>.  Beware that using C<eval> neither silences Perl from printing
1682 warnings to STDERR, nor does it stuff the text of warning messages into C<$@>.
1683 To do either of those, you have to use the C<$SIG{__WARN__}> facility, or
1684 turn off warnings inside the BLOCK or EXPR using S<C<no warnings 'all'>>.
1685 See L</warn>, L<perlvar>, L<warnings> and L<perllexwarn>.
1686
1687 Note that, because C<eval> traps otherwise-fatal errors, it is useful for
1688 determining whether a particular feature (such as C<socket> or C<symlink>)
1689 is implemented.  It is also Perl's exception-trapping mechanism, where
1690 the die operator is used to raise exceptions.
1691
1692 If you want to trap errors when loading an XS module, some problems with
1693 the binary interface (such as Perl version skew) may be fatal even with
1694 C<eval> unless C<$ENV{PERL_DL_NONLAZY}> is set.  See L<perlrun>.
1695
1696 If the code to be executed doesn't vary, you may use the eval-BLOCK
1697 form to trap run-time errors without incurring the penalty of
1698 recompiling each time.  The error, if any, is still returned in C<$@>.
1699 Examples:
1700
1701     # make divide-by-zero nonfatal
1702     eval { $answer = $a / $b; }; warn $@ if $@;
1703
1704     # same thing, but less efficient
1705     eval '$answer = $a / $b'; warn $@ if $@;
1706
1707     # a compile-time error
1708     eval { $answer = }; # WRONG
1709
1710     # a run-time error
1711     eval '$answer =';   # sets $@
1712
1713 Using the C<eval{}> form as an exception trap in libraries does have some
1714 issues.  Due to the current arguably broken state of C<__DIE__> hooks, you
1715 may wish not to trigger any C<__DIE__> hooks that user code may have installed.
1716 You can use the C<local $SIG{__DIE__}> construct for this purpose,
1717 as this example shows:
1718
1719     # a private exception trap for divide-by-zero
1720     eval { local $SIG{'__DIE__'}; $answer = $a / $b; };
1721     warn $@ if $@;
1722
1723 This is especially significant, given that C<__DIE__> hooks can call
1724 C<die> again, which has the effect of changing their error messages:
1725
1726     # __DIE__ hooks may modify error messages
1727     {
1728        local $SIG{'__DIE__'} =
1729               sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
1730        eval { die "foo lives here" };
1731        print $@ if $@;                # prints "bar lives here"
1732     }
1733
1734 Because this promotes action at a distance, this counterintuitive behavior
1735 may be fixed in a future release.
1736
1737 With an C<eval>, you should be especially careful to remember what's
1738 being looked at when:
1739
1740     eval $x;        # CASE 1
1741     eval "$x";      # CASE 2
1742
1743     eval '$x';      # CASE 3
1744     eval { $x };    # CASE 4
1745
1746     eval "\$$x++";  # CASE 5
1747     $$x++;          # CASE 6
1748
1749 Cases 1 and 2 above behave identically: they run the code contained in
1750 the variable $x.  (Although case 2 has misleading double quotes making
1751 the reader wonder what else might be happening (nothing is).)  Cases 3
1752 and 4 likewise behave in the same way: they run the code C<'$x'>, which
1753 does nothing but return the value of $x.  (Case 4 is preferred for
1754 purely visual reasons, but it also has the advantage of compiling at
1755 compile-time instead of at run-time.)  Case 5 is a place where
1756 normally you I<would> like to use double quotes, except that in this
1757 particular situation, you can just use symbolic references instead, as
1758 in case 6.
1759
1760 Before Perl 5.14, the assignment to C<$@> occurred before restoration 
1761 of localized variables, which means that for your code to run on older
1762 versions, a temporary is required if you want to mask some but not all
1763 errors:
1764
1765     # alter $@ on nefarious repugnancy only
1766     {
1767        my $e;
1768        {
1769           local $@; # protect existing $@
1770           eval { test_repugnancy() };
1771           # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only
1772           $@ =~ /nefarious/ and $e = $@;
1773        }
1774        die $e if defined $e
1775     }
1776
1777 C<eval BLOCK> does I<not> count as a loop, so the loop control statements
1778 C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
1779
1780 An C<eval ''> executed within the C<DB> package doesn't see the usual
1781 surrounding lexical scope, but rather the scope of the first non-DB piece
1782 of code that called it.  You don't normally need to worry about this unless
1783 you are writing a Perl debugger.
1784
1785 =item evalbytes EXPR
1786 X<evalbytes>
1787
1788 =item evalbytes
1789
1790 This function is like L</eval> with a string argument, except it always
1791 parses its argument, or C<$_> if EXPR is omitted, as a string of bytes.  A
1792 string containing characters whose ordinal value exceeds 255 results in an
1793 error.  Source filters activated within the evaluated code apply to the
1794 code itself.
1795
1796 This function is only available under the C<evalbytes> feature, a
1797 C<use v5.16> (or higher) declaration, or with a C<CORE::> prefix.  See
1798 L<feature> for more information.
1799
1800 =item exec LIST
1801 X<exec> X<execute>
1802
1803 =item exec PROGRAM LIST
1804
1805 The C<exec> function executes a system command I<and never returns>;
1806 use C<system> instead of C<exec> if you want it to return.  It fails and
1807 returns false only if the command does not exist I<and> it is executed
1808 directly instead of via your system's command shell (see below).
1809
1810 Since it's a common mistake to use C<exec> instead of C<system>, Perl
1811 warns you if there is a following statement that isn't C<die>, C<warn>,
1812 or C<exit> (if C<-w> is set--but you always do that, right?).   If you
1813 I<really> want to follow an C<exec> with some other statement, you
1814 can use one of these styles to avoid the warning:
1815
1816     exec ('foo')   or print STDERR "couldn't exec foo: $!";
1817     { exec ('foo') }; print STDERR "couldn't exec foo: $!";
1818
1819 If there is more than one argument in LIST, or if LIST is an array
1820 with more than one value, calls execvp(3) with the arguments in LIST.
1821 If there is only one scalar argument or an array with one element in it,
1822 the argument is checked for shell metacharacters, and if there are any,
1823 the entire argument is passed to the system's command shell for parsing
1824 (this is C</bin/sh -c> on Unix platforms, but varies on other platforms).
1825 If there are no shell metacharacters in the argument, it is split into
1826 words and passed directly to C<execvp>, which is more efficient.
1827 Examples:
1828
1829     exec '/bin/echo', 'Your arguments are: ', @ARGV;
1830     exec "sort $outfile | uniq";
1831
1832 If you don't really want to execute the first argument, but want to lie
1833 to the program you are executing about its own name, you can specify
1834 the program you actually want to run as an "indirect object" (without a
1835 comma) in front of the LIST.  (This always forces interpretation of the
1836 LIST as a multivalued list, even if there is only a single scalar in
1837 the list.)  Example:
1838
1839     $shell = '/bin/csh';
1840     exec $shell '-sh';    # pretend it's a login shell
1841
1842 or, more directly,
1843
1844     exec {'/bin/csh'} '-sh';  # pretend it's a login shell
1845
1846 When the arguments get executed via the system shell, results are
1847 subject to its quirks and capabilities.  See L<perlop/"`STRING`">
1848 for details.
1849
1850 Using an indirect object with C<exec> or C<system> is also more
1851 secure.  This usage (which also works fine with system()) forces
1852 interpretation of the arguments as a multivalued list, even if the
1853 list had just one argument.  That way you're safe from the shell
1854 expanding wildcards or splitting up words with whitespace in them.
1855
1856     @args = ( "echo surprise" );
1857
1858     exec @args;               # subject to shell escapes
1859                                 # if @args == 1
1860     exec { $args[0] } @args;  # safe even with one-arg list
1861
1862 The first version, the one without the indirect object, ran the I<echo>
1863 program, passing it C<"surprise"> an argument.  The second version didn't;
1864 it tried to run a program named I<"echo surprise">, didn't find it, and set
1865 C<$?> to a non-zero value indicating failure.
1866
1867 Beginning with v5.6.0, Perl attempts to flush all files opened for
1868 output before the exec, but this may not be supported on some platforms
1869 (see L<perlport>).  To be safe, you may need to set C<$|> ($AUTOFLUSH
1870 in English) or call the C<autoflush()> method of C<IO::Handle> on any
1871 open handles to avoid lost output.
1872
1873 Note that C<exec> will not call your C<END> blocks, nor will it invoke
1874 C<DESTROY> methods on your objects.
1875
1876 Portability issues: L<perlport/exec>.
1877
1878 =item exists EXPR
1879 X<exists> X<autovivification>
1880
1881 Given an expression that specifies an element of a hash, returns true if the
1882 specified element in the hash has ever been initialized, even if the
1883 corresponding value is undefined.
1884
1885     print "Exists\n"    if exists $hash{$key};
1886     print "Defined\n"   if defined $hash{$key};
1887     print "True\n"      if $hash{$key};
1888
1889 exists may also be called on array elements, but its behavior is much less
1890 obvious and is strongly tied to the use of L</delete> on arrays.  B<Be aware>
1891 that calling exists on array values is deprecated and likely to be removed in
1892 a future version of Perl.
1893
1894     print "Exists\n"    if exists $array[$index];
1895     print "Defined\n"   if defined $array[$index];
1896     print "True\n"      if $array[$index];
1897
1898 A hash or array element can be true only if it's defined and defined only if
1899 it exists, but the reverse doesn't necessarily hold true.
1900
1901 Given an expression that specifies the name of a subroutine,
1902 returns true if the specified subroutine has ever been declared, even
1903 if it is undefined.  Mentioning a subroutine name for exists or defined
1904 does not count as declaring it.  Note that a subroutine that does not
1905 exist may still be callable: its package may have an C<AUTOLOAD>
1906 method that makes it spring into existence the first time that it is
1907 called; see L<perlsub>.
1908
1909     print "Exists\n"  if exists &subroutine;
1910     print "Defined\n" if defined &subroutine;
1911
1912 Note that the EXPR can be arbitrarily complicated as long as the final
1913 operation is a hash or array key lookup or subroutine name:
1914
1915     if (exists $ref->{A}->{B}->{$key})  { }
1916     if (exists $hash{A}{B}{$key})       { }
1917
1918     if (exists $ref->{A}->{B}->[$ix])   { }
1919     if (exists $hash{A}{B}[$ix])        { }
1920
1921     if (exists &{$ref->{A}{B}{$key}})   { }
1922
1923 Although the mostly deeply nested array or hash will not spring into
1924 existence just because its existence was tested, any intervening ones will.
1925 Thus C<< $ref->{"A"} >> and C<< $ref->{"A"}->{"B"} >> will spring
1926 into existence due to the existence test for the $key element above.
1927 This happens anywhere the arrow operator is used, including even here:
1928
1929     undef $ref;
1930     if (exists $ref->{"Some key"})    { }
1931     print $ref;  # prints HASH(0x80d3d5c)
1932
1933 This surprising autovivification in what does not at first--or even
1934 second--glance appear to be an lvalue context may be fixed in a future
1935 release.
1936
1937 Use of a subroutine call, rather than a subroutine name, as an argument
1938 to exists() is an error.
1939
1940     exists &sub;    # OK
1941     exists &sub();  # Error
1942
1943 =item exit EXPR
1944 X<exit> X<terminate> X<abort>
1945
1946 =item exit
1947
1948 Evaluates EXPR and exits immediately with that value.    Example:
1949
1950     $ans = <STDIN>;
1951     exit 0 if $ans =~ /^[Xx]/;
1952
1953 See also C<die>.  If EXPR is omitted, exits with C<0> status.  The only
1954 universally recognized values for EXPR are C<0> for success and C<1>
1955 for error; other values are subject to interpretation depending on the
1956 environment in which the Perl program is running.  For example, exiting
1957 69 (EX_UNAVAILABLE) from a I<sendmail> incoming-mail filter will cause
1958 the mailer to return the item undelivered, but that's not true everywhere.
1959
1960 Don't use C<exit> to abort a subroutine if there's any chance that
1961 someone might want to trap whatever error happened.  Use C<die> instead,
1962 which can be trapped by an C<eval>.
1963
1964 The exit() function does not always exit immediately.  It calls any
1965 defined C<END> routines first, but these C<END> routines may not
1966 themselves abort the exit.  Likewise any object destructors that need to
1967 be called are called before the real exit.  C<END> routines and destructors
1968 can change the exit status by modifying C<$?>.  If this is a problem, you
1969 can call C<POSIX:_exit($status)> to avoid END and destructor processing.
1970 See L<perlmod> for details.
1971
1972 Portability issues: L<perlport/exit>.
1973
1974 =item exp EXPR
1975 X<exp> X<exponential> X<antilog> X<antilogarithm> X<e>
1976
1977 =item exp
1978
1979 Returns I<e> (the natural logarithm base) to the power of EXPR.
1980 If EXPR is omitted, gives C<exp($_)>.
1981
1982 =item fc EXPR
1983 X<fc> X<foldcase> X<casefold> X<fold-case> X<case-fold>
1984
1985 =item fc
1986
1987 Returns the casefolded version of EXPR.  This is the internal function
1988 implementing the C<\F> escape in double-quoted strings.
1989
1990 Casefolding is the process of mapping strings to a form where case
1991 differences are erased; comparing two strings in their casefolded
1992 form is effectively a way of asking if two strings are equal,
1993 regardless of case.
1994
1995 Roughly, if you ever found yourself writing this
1996
1997     lc($this) eq lc($that)  # Wrong!
1998         # or
1999     uc($this) eq uc($that)  # Also wrong!
2000         # or
2001     $this =~ /\Q$that/i     # Right!
2002
2003 Now you can write
2004
2005     fc($this) eq fc($that)
2006
2007 And get the correct results.
2008
2009 Perl only implements the full form of casefolding.
2010 For further information on casefolding, refer to
2011 the Unicode Standard, specifically sections 3.13 C<Default Case Operations>,
2012 4.2 C<Case-Normative>, and 5.18 C<Case Mappings>,
2013 available at L<http://www.unicode.org/versions/latest/>, as well as the
2014 Case Charts available at L<http://www.unicode.org/charts/case/>.
2015
2016 If EXPR is omitted, uses C<$_>.
2017
2018 This function behaves the same way under various pragma, such as in a locale,
2019 as L</lc> does.
2020
2021 While the Unicode Standard defines two additional forms of casefolding,
2022 one for Turkic languages and one that never maps one character into multiple
2023 characters, these are not provided by the Perl core; However, the CPAN module
2024 C<Unicode::Casing> may be used to provide an implementation.
2025
2026 This keyword is available only when the C<"fc"> feature is enabled,
2027 or when prefixed with C<CORE::>; See L<feature>. Alternately,
2028 include a C<use v5.16> or later to the current scope.
2029
2030 =item fcntl FILEHANDLE,FUNCTION,SCALAR
2031 X<fcntl>
2032
2033 Implements the fcntl(2) function.  You'll probably have to say
2034
2035     use Fcntl;
2036
2037 first to get the correct constant definitions.  Argument processing and
2038 value returned work just like C<ioctl> below.
2039 For example:
2040
2041     use Fcntl;
2042     fcntl($filehandle, F_GETFL, $packed_return_buffer)
2043         or die "can't fcntl F_GETFL: $!";
2044
2045 You don't have to check for C<defined> on the return from C<fcntl>.
2046 Like C<ioctl>, it maps a C<0> return from the system call into
2047 C<"0 but true"> in Perl.  This string is true in boolean context and C<0>
2048 in numeric context.  It is also exempt from the normal B<-w> warnings
2049 on improper numeric conversions.
2050
2051 Note that C<fcntl> raises an exception if used on a machine that
2052 doesn't implement fcntl(2).  See the Fcntl module or your fcntl(2)
2053 manpage to learn what functions are available on your system.
2054
2055 Here's an example of setting a filehandle named C<REMOTE> to be
2056 non-blocking at the system level.  You'll have to negotiate C<$|>
2057 on your own, though.
2058
2059     use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
2060
2061     $flags = fcntl(REMOTE, F_GETFL, 0)
2062                 or die "Can't get flags for the socket: $!\n";
2063
2064     $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
2065                 or die "Can't set flags for the socket: $!\n";
2066
2067 Portability issues: L<perlport/fcntl>.
2068
2069 =item __FILE__
2070 X<__FILE__>
2071
2072 A special token that returns the name of the file in which it occurs.
2073
2074 =item fileno FILEHANDLE
2075 X<fileno>
2076
2077 Returns the file descriptor for a filehandle, or undefined if the
2078 filehandle is not open.  If there is no real file descriptor at the OS
2079 level, as can happen with filehandles connected to memory objects via
2080 C<open> with a reference for the third argument, -1 is returned.
2081
2082 This is mainly useful for constructing
2083 bitmaps for C<select> and low-level POSIX tty-handling operations.
2084 If FILEHANDLE is an expression, the value is taken as an indirect
2085 filehandle, generally its name.
2086
2087 You can use this to find out whether two handles refer to the
2088 same underlying descriptor:
2089
2090     if (fileno(THIS) == fileno(THAT)) {
2091         print "THIS and THAT are dups\n";
2092     }
2093
2094 =item flock FILEHANDLE,OPERATION
2095 X<flock> X<lock> X<locking>
2096
2097 Calls flock(2), or an emulation of it, on FILEHANDLE.  Returns true
2098 for success, false on failure.  Produces a fatal error if used on a
2099 machine that doesn't implement flock(2), fcntl(2) locking, or lockf(3).
2100 C<flock> is Perl's portable file-locking interface, although it locks
2101 entire files only, not records.
2102
2103 Two potentially non-obvious but traditional C<flock> semantics are
2104 that it waits indefinitely until the lock is granted, and that its locks
2105 are B<merely advisory>.  Such discretionary locks are more flexible, but
2106 offer fewer guarantees.  This means that programs that do not also use
2107 C<flock> may modify files locked with C<flock>.  See L<perlport>, 
2108 your port's specific documentation, and your system-specific local manpages
2109 for details.  It's best to assume traditional behavior if you're writing
2110 portable programs.  (But if you're not, you should as always feel perfectly
2111 free to write for your own system's idiosyncrasies (sometimes called
2112 "features").  Slavish adherence to portability concerns shouldn't get
2113 in the way of your getting your job done.)
2114
2115 OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with
2116 LOCK_NB.  These constants are traditionally valued 1, 2, 8 and 4, but
2117 you can use the symbolic names if you import them from the L<Fcntl> module,
2118 either individually, or as a group using the C<:flock> tag.  LOCK_SH
2119 requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN
2120 releases a previously requested lock.  If LOCK_NB is bitwise-or'ed with
2121 LOCK_SH or LOCK_EX, then C<flock> returns immediately rather than blocking
2122 waiting for the lock; check the return status to see if you got it.
2123
2124 To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE
2125 before locking or unlocking it.
2126
2127 Note that the emulation built with lockf(3) doesn't provide shared
2128 locks, and it requires that FILEHANDLE be open with write intent.  These
2129 are the semantics that lockf(3) implements.  Most if not all systems
2130 implement lockf(3) in terms of fcntl(2) locking, though, so the
2131 differing semantics shouldn't bite too many people.
2132
2133 Note that the fcntl(2) emulation of flock(3) requires that FILEHANDLE
2134 be open with read intent to use LOCK_SH and requires that it be open
2135 with write intent to use LOCK_EX.
2136
2137 Note also that some versions of C<flock> cannot lock things over the
2138 network; you would need to use the more system-specific C<fcntl> for
2139 that.  If you like you can force Perl to ignore your system's flock(2)
2140 function, and so provide its own fcntl(2)-based emulation, by passing
2141 the switch C<-Ud_flock> to the F<Configure> program when you configure
2142 and build a new Perl.
2143
2144 Here's a mailbox appender for BSD systems.
2145
2146     use Fcntl qw(:flock SEEK_END); # import LOCK_* and SEEK_END constants
2147
2148     sub lock {
2149         my ($fh) = @_;
2150         flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n";
2151
2152         # and, in case someone appended while we were waiting...
2153         seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n";
2154     }
2155
2156     sub unlock {
2157         my ($fh) = @_;
2158         flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n";
2159     }
2160
2161     open(my $mbox, ">>", "/usr/spool/mail/$ENV{'USER'}")
2162         or die "Can't open mailbox: $!";
2163
2164     lock($mbox);
2165     print $mbox $msg,"\n\n";
2166     unlock($mbox);
2167
2168 On systems that support a real flock(2), locks are inherited across fork()
2169 calls, whereas those that must resort to the more capricious fcntl(2)
2170 function lose their locks, making it seriously harder to write servers.
2171
2172 See also L<DB_File> for other flock() examples.
2173
2174 Portability issues: L<perlport/flock>.
2175
2176 =item fork
2177 X<fork> X<child> X<parent>
2178
2179 Does a fork(2) system call to create a new process running the
2180 same program at the same point.  It returns the child pid to the
2181 parent process, C<0> to the child process, or C<undef> if the fork is
2182 unsuccessful.  File descriptors (and sometimes locks on those descriptors)
2183 are shared, while everything else is copied.  On most systems supporting
2184 fork(), great care has gone into making it extremely efficient (for
2185 example, using copy-on-write technology on data pages), making it the
2186 dominant paradigm for multitasking over the last few decades.
2187
2188 Beginning with v5.6.0, Perl attempts to flush all files opened for
2189 output before forking the child process, but this may not be supported
2190 on some platforms (see L<perlport>).  To be safe, you may need to set
2191 C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
2192 C<IO::Handle> on any open handles to avoid duplicate output.
2193
2194 If you C<fork> without ever waiting on your children, you will
2195 accumulate zombies.  On some systems, you can avoid this by setting
2196 C<$SIG{CHLD}> to C<"IGNORE">.  See also L<perlipc> for more examples of
2197 forking and reaping moribund children.
2198
2199 Note that if your forked child inherits system file descriptors like
2200 STDIN and STDOUT that are actually connected by a pipe or socket, even
2201 if you exit, then the remote server (such as, say, a CGI script or a
2202 backgrounded job launched from a remote shell) won't think you're done.
2203 You should reopen those to F</dev/null> if it's any issue.
2204
2205 On some platforms such as Windows, where the fork() system call is not available,
2206 Perl can be built to emulate fork() in the Perl interpreter.
2207 The emulation is designed, at the level of the Perl program,
2208 to be as compatible as possible with the "Unix" fork().
2209 However it has limitations that have to be considered in code intended to be portable.
2210 See L<perlfork> for more details.
2211
2212 Portability issues: L<perlport/fork>.
2213
2214 =item format
2215 X<format>
2216
2217 Declare a picture format for use by the C<write> function.  For
2218 example:
2219
2220     format Something =
2221         Test: @<<<<<<<< @||||| @>>>>>
2222               $str,     $%,    '$' . int($num)
2223     .
2224
2225     $str = "widget";
2226     $num = $cost/$quantity;
2227     $~ = 'Something';
2228     write;
2229
2230 See L<perlform> for many details and examples.
2231
2232 =item formline PICTURE,LIST
2233 X<formline>
2234
2235 This is an internal function used by C<format>s, though you may call it,
2236 too.  It formats (see L<perlform>) a list of values according to the
2237 contents of PICTURE, placing the output into the format output
2238 accumulator, C<$^A> (or C<$ACCUMULATOR> in English).
2239 Eventually, when a C<write> is done, the contents of
2240 C<$^A> are written to some filehandle.  You could also read C<$^A>
2241 and then set C<$^A> back to C<"">.  Note that a format typically
2242 does one C<formline> per line of form, but the C<formline> function itself
2243 doesn't care how many newlines are embedded in the PICTURE.  This means
2244 that the C<~> and C<~~> tokens treat the entire PICTURE as a single line.
2245 You may therefore need to use multiple formlines to implement a single
2246 record format, just like the C<format> compiler.
2247
2248 Be careful if you put double quotes around the picture, because an C<@>
2249 character may be taken to mean the beginning of an array name.
2250 C<formline> always returns true.  See L<perlform> for other examples.
2251
2252 If you are trying to use this instead of C<write> to capture the output,
2253 you may find it easier to open a filehandle to a scalar
2254 (C<< open $fh, ">", \$output >>) and write to that instead.
2255
2256 =item getc FILEHANDLE
2257 X<getc> X<getchar> X<character> X<file, read>
2258
2259 =item getc
2260
2261 Returns the next character from the input file attached to FILEHANDLE,
2262 or the undefined value at end of file or if there was an error (in
2263 the latter case C<$!> is set).  If FILEHANDLE is omitted, reads from
2264 STDIN.  This is not particularly efficient.  However, it cannot be
2265 used by itself to fetch single characters without waiting for the user
2266 to hit enter.  For that, try something more like:
2267
2268     if ($BSD_STYLE) {
2269         system "stty cbreak </dev/tty >/dev/tty 2>&1";
2270     }
2271     else {
2272         system "stty", '-icanon', 'eol', "\001";
2273     }
2274
2275     $key = getc(STDIN);
2276
2277     if ($BSD_STYLE) {
2278         system "stty -cbreak </dev/tty >/dev/tty 2>&1";
2279     }
2280     else {
2281         system 'stty', 'icanon', 'eol', '^@'; # ASCII NUL
2282     }
2283     print "\n";
2284
2285 Determination of whether $BSD_STYLE should be set
2286 is left as an exercise to the reader.
2287
2288 The C<POSIX::getattr> function can do this more portably on
2289 systems purporting POSIX compliance.  See also the C<Term::ReadKey>
2290 module from your nearest CPAN site; details on CPAN can be found under
2291 L<perlmodlib/CPAN>.
2292
2293 =item getlogin
2294 X<getlogin> X<login>
2295
2296 This implements the C library function of the same name, which on most
2297 systems returns the current login from F</etc/utmp>, if any.  If it
2298 returns the empty string, use C<getpwuid>.
2299
2300     $login = getlogin || getpwuid($<) || "Kilroy";
2301
2302 Do not consider C<getlogin> for authentication: it is not as
2303 secure as C<getpwuid>.
2304
2305 Portability issues: L<perlport/getlogin>.
2306
2307 =item getpeername SOCKET
2308 X<getpeername> X<peer>
2309
2310 Returns the packed sockaddr address of the other end of the SOCKET
2311 connection.
2312
2313     use Socket;
2314     $hersockaddr    = getpeername(SOCK);
2315     ($port, $iaddr) = sockaddr_in($hersockaddr);
2316     $herhostname    = gethostbyaddr($iaddr, AF_INET);
2317     $herstraddr     = inet_ntoa($iaddr);
2318
2319 =item getpgrp PID
2320 X<getpgrp> X<group>
2321
2322 Returns the current process group for the specified PID.  Use
2323 a PID of C<0> to get the current process group for the
2324 current process.  Will raise an exception if used on a machine that
2325 doesn't implement getpgrp(2).  If PID is omitted, returns the process
2326 group of the current process.  Note that the POSIX version of C<getpgrp>
2327 does not accept a PID argument, so only C<PID==0> is truly portable.
2328
2329 Portability issues: L<perlport/getpgrp>.
2330
2331 =item getppid
2332 X<getppid> X<parent> X<pid>
2333
2334 Returns the process id of the parent process.
2335
2336 Note for Linux users: on Linux, the C functions C<getpid()> and
2337 C<getppid()> return different values from different threads.  In order to
2338 be portable, this behavior is not reflected by the Perl-level function
2339 C<getppid()>, that returns a consistent value across threads.  If you want
2340 to call the underlying C<getppid()>, you may use the CPAN module
2341 C<Linux::Pid>.
2342
2343 Portability issues: L<perlport/getppid>.
2344
2345 =item getpriority WHICH,WHO
2346 X<getpriority> X<priority> X<nice>
2347
2348 Returns the current priority for a process, a process group, or a user.
2349 (See L<getpriority(2)>.)  Will raise a fatal exception if used on a
2350 machine that doesn't implement getpriority(2).
2351
2352 Portability issues: L<perlport/getpriority>.
2353
2354 =item getpwnam NAME
2355 X<getpwnam> X<getgrnam> X<gethostbyname> X<getnetbyname> X<getprotobyname>
2356 X<getpwuid> X<getgrgid> X<getservbyname> X<gethostbyaddr> X<getnetbyaddr>
2357 X<getprotobynumber> X<getservbyport> X<getpwent> X<getgrent> X<gethostent>
2358 X<getnetent> X<getprotoent> X<getservent> X<setpwent> X<setgrent> X<sethostent>
2359 X<setnetent> X<setprotoent> X<setservent> X<endpwent> X<endgrent> X<endhostent>
2360 X<endnetent> X<endprotoent> X<endservent> 
2361
2362 =item getgrnam NAME
2363
2364 =item gethostbyname NAME
2365
2366 =item getnetbyname NAME
2367
2368 =item getprotobyname NAME
2369
2370 =item getpwuid UID
2371
2372 =item getgrgid GID
2373
2374 =item getservbyname NAME,PROTO
2375
2376 =item gethostbyaddr ADDR,ADDRTYPE
2377
2378 =item getnetbyaddr ADDR,ADDRTYPE
2379
2380 =item getprotobynumber NUMBER
2381
2382 =item getservbyport PORT,PROTO
2383
2384 =item getpwent
2385
2386 =item getgrent
2387
2388 =item gethostent
2389
2390 =item getnetent
2391
2392 =item getprotoent
2393
2394 =item getservent
2395
2396 =item setpwent
2397
2398 =item setgrent
2399
2400 =item sethostent STAYOPEN
2401
2402 =item setnetent STAYOPEN
2403
2404 =item setprotoent STAYOPEN
2405
2406 =item setservent STAYOPEN
2407
2408 =item endpwent
2409
2410 =item endgrent
2411
2412 =item endhostent
2413
2414 =item endnetent
2415
2416 =item endprotoent
2417
2418 =item endservent
2419
2420 These routines are the same as their counterparts in the
2421 system C library.  In list context, the return values from the
2422 various get routines are as follows:
2423
2424     ($name,$passwd,$uid,$gid,
2425        $quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
2426     ($name,$passwd,$gid,$members) = getgr*
2427     ($name,$aliases,$addrtype,$length,@addrs) = gethost*
2428     ($name,$aliases,$addrtype,$net) = getnet*
2429     ($name,$aliases,$proto) = getproto*
2430     ($name,$aliases,$port,$proto) = getserv*
2431
2432 (If the entry doesn't exist you get an empty list.)
2433
2434 The exact meaning of the $gcos field varies but it usually contains
2435 the real name of the user (as opposed to the login name) and other
2436 information pertaining to the user.  Beware, however, that in many
2437 system users are able to change this information and therefore it
2438 cannot be trusted and therefore the $gcos is tainted (see
2439 L<perlsec>).  The $passwd and $shell, user's encrypted password and
2440 login shell, are also tainted, for the same reason.
2441
2442 In scalar context, you get the name, unless the function was a
2443 lookup by name, in which case you get the other thing, whatever it is.
2444 (If the entry doesn't exist you get the undefined value.)  For example:
2445
2446     $uid   = getpwnam($name);
2447     $name  = getpwuid($num);
2448     $name  = getpwent();
2449     $gid   = getgrnam($name);
2450     $name  = getgrgid($num);
2451     $name  = getgrent();
2452     #etc.
2453
2454 In I<getpw*()> the fields $quota, $comment, and $expire are special
2455 in that they are unsupported on many systems.  If the
2456 $quota is unsupported, it is an empty scalar.  If it is supported, it
2457 usually encodes the disk quota.  If the $comment field is unsupported,
2458 it is an empty scalar.  If it is supported it usually encodes some
2459 administrative comment about the user.  In some systems the $quota
2460 field may be $change or $age, fields that have to do with password
2461 aging.  In some systems the $comment field may be $class.  The $expire
2462 field, if present, encodes the expiration period of the account or the
2463 password.  For the availability and the exact meaning of these fields
2464 in your system, please consult getpwnam(3) and your system's 
2465 F<pwd.h> file.  You can also find out from within Perl what your
2466 $quota and $comment fields mean and whether you have the $expire field
2467 by using the C<Config> module and the values C<d_pwquota>, C<d_pwage>,
2468 C<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>.  Shadow password
2469 files are supported only if your vendor has implemented them in the
2470 intuitive fashion that calling the regular C library routines gets the
2471 shadow versions if you're running under privilege or if there exists
2472 the shadow(3) functions as found in System V (this includes Solaris
2473 and Linux).  Those systems that implement a proprietary shadow password
2474 facility are unlikely to be supported.
2475
2476 The $members value returned by I<getgr*()> is a space-separated list of
2477 the login names of the members of the group.
2478
2479 For the I<gethost*()> functions, if the C<h_errno> variable is supported in
2480 C, it will be returned to you via C<$?> if the function call fails.  The
2481 C<@addrs> value returned by a successful call is a list of raw
2482 addresses returned by the corresponding library call.  In the
2483 Internet domain, each address is four bytes long; you can unpack it
2484 by saying something like:
2485
2486     ($a,$b,$c,$d) = unpack('W4',$addr[0]);
2487
2488 The Socket library makes this slightly easier:
2489
2490     use Socket;
2491     $iaddr = inet_aton("127.1"); # or whatever address
2492     $name  = gethostbyaddr($iaddr, AF_INET);
2493
2494     # or going the other way
2495     $straddr = inet_ntoa($iaddr);
2496
2497 In the opposite way, to resolve a hostname to the IP address
2498 you can write this:
2499
2500     use Socket;
2501     $packed_ip = gethostbyname("www.perl.org");
2502     if (defined $packed_ip) {
2503         $ip_address = inet_ntoa($packed_ip);
2504     }
2505
2506 Make sure C<gethostbyname()> is called in SCALAR context and that
2507 its return value is checked for definedness.
2508
2509 The C<getprotobynumber> function, even though it only takes one argument,
2510 has the precedence of a list operator, so beware:
2511
2512     getprotobynumber $number eq 'icmp'   # WRONG
2513     getprotobynumber($number eq 'icmp')  # actually means this
2514     getprotobynumber($number) eq 'icmp'  # better this way
2515
2516 If you get tired of remembering which element of the return list
2517 contains which return value, by-name interfaces are provided
2518 in standard modules: C<File::stat>, C<Net::hostent>, C<Net::netent>,
2519 C<Net::protoent>, C<Net::servent>, C<Time::gmtime>, C<Time::localtime>,
2520 and C<User::grent>.  These override the normal built-ins, supplying
2521 versions that return objects with the appropriate names
2522 for each field.  For example:
2523
2524    use File::stat;
2525    use User::pwent;
2526    $is_his = (stat($filename)->uid == pwent($whoever)->uid);
2527
2528 Even though it looks as though they're the same method calls (uid),
2529 they aren't, because a C<File::stat> object is different from
2530 a C<User::pwent> object.
2531
2532 Portability issues: L<perlport/getpwnam> to L<perlport/endservent>.
2533
2534 =item getsockname SOCKET
2535 X<getsockname>
2536
2537 Returns the packed sockaddr address of this end of the SOCKET connection,
2538 in case you don't know the address because you have several different
2539 IPs that the connection might have come in on.
2540
2541     use Socket;
2542     $mysockaddr = getsockname(SOCK);
2543     ($port, $myaddr) = sockaddr_in($mysockaddr);
2544     printf "Connect to %s [%s]\n",
2545        scalar gethostbyaddr($myaddr, AF_INET),
2546        inet_ntoa($myaddr);
2547
2548 =item getsockopt SOCKET,LEVEL,OPTNAME
2549 X<getsockopt>
2550
2551 Queries the option named OPTNAME associated with SOCKET at a given LEVEL.
2552 Options may exist at multiple protocol levels depending on the socket
2553 type, but at least the uppermost socket level SOL_SOCKET (defined in the
2554 C<Socket> module) will exist.  To query options at another level the
2555 protocol number of the appropriate protocol controlling the option
2556 should be supplied.  For example, to indicate that an option is to be
2557 interpreted by the TCP protocol, LEVEL should be set to the protocol
2558 number of TCP, which you can get using C<getprotobyname>.
2559
2560 The function returns a packed string representing the requested socket
2561 option, or C<undef> on error, with the reason for the error placed in
2562 C<$!>.  Just what is in the packed string depends on LEVEL and OPTNAME;
2563 consult getsockopt(2) for details.  A common case is that the option is an
2564 integer, in which case the result is a packed integer, which you can decode
2565 using C<unpack> with the C<i> (or C<I>) format.
2566
2567 Here's an example to test whether Nagle's algorithm is enabled on a socket:
2568
2569     use Socket qw(:all);
2570
2571     defined(my $tcp = getprotobyname("tcp"))
2572         or die "Could not determine the protocol number for tcp";
2573     # my $tcp = IPPROTO_TCP; # Alternative
2574     my $packed = getsockopt($socket, $tcp, TCP_NODELAY)
2575         or die "getsockopt TCP_NODELAY: $!";
2576     my $nodelay = unpack("I", $packed);
2577     print "Nagle's algorithm is turned ", $nodelay ? "off\n" : "on\n";
2578
2579 Portability issues: L<perlport/getsockopt>.
2580
2581 =item given EXPR BLOCK
2582 X<given>
2583
2584 =item given BLOCK
2585
2586 C<given> is analogous to the C<switch>
2587 keyword in other languages.  C<given>
2588 and C<when> are used in Perl to implement C<switch>/C<case> like statements.
2589 Only available after Perl 5.10.  For example:
2590
2591     use v5.10;
2592     given ($fruit) {
2593         when (/apples?/) {
2594             print "I like apples."
2595         }
2596         when (/oranges?/) {
2597             print "I don't like oranges."
2598         }
2599         default {
2600             print "I don't like anything"
2601         }
2602     }
2603
2604 See L<perlsyn/"Switch Statements"> for detailed information.
2605
2606 =item glob EXPR
2607 X<glob> X<wildcard> X<filename, expansion> X<expand>
2608
2609 =item glob
2610
2611 In list context, returns a (possibly empty) list of filename expansions on
2612 the value of EXPR such as the standard Unix shell F</bin/csh> would do.  In
2613 scalar context, glob iterates through such filename expansions, returning
2614 undef when the list is exhausted.  This is the internal function
2615 implementing the C<< <*.c> >> operator, but you can use it directly.  If
2616 EXPR is omitted, C<$_> is used.  The C<< <*.c> >> operator is discussed in
2617 more detail in L<perlop/"I/O Operators">.
2618
2619 Note that C<glob> splits its arguments on whitespace and treats
2620 each segment as separate pattern.  As such, C<glob("*.c *.h")> 
2621 matches all files with a F<.c> or F<.h> extension.  The expression
2622 C<glob(".* *")> matches all files in the current working directory.
2623 If you want to glob filenames that might contain whitespace, you'll
2624 have to use extra quotes around the spacey filename to protect it.
2625 For example, to glob filenames that have an C<e> followed by a space
2626 followed by an C<f>, use either of:
2627
2628     @spacies = <"*e f*">;
2629     @spacies = glob '"*e f*"';
2630     @spacies = glob q("*e f*");
2631
2632 If you had to get a variable through, you could do this:
2633
2634     @spacies = glob "'*${var}e f*'";
2635     @spacies = glob qq("*${var}e f*");
2636
2637 If non-empty braces are the only wildcard characters used in the
2638 C<glob>, no filenames are matched, but potentially many strings
2639 are returned.  For example, this produces nine strings, one for
2640 each pairing of fruits and colors:
2641
2642     @many =  glob "{apple,tomato,cherry}={green,yellow,red}";
2643
2644 Beginning with v5.6.0, this operator is implemented using the standard
2645 C<File::Glob> extension.  See L<File::Glob> for details, including
2646 C<bsd_glob> which does not treat whitespace as a pattern separator.
2647
2648 Portability issues: L<perlport/glob>.
2649
2650 =item gmtime EXPR
2651 X<gmtime> X<UTC> X<Greenwich>
2652
2653 =item gmtime
2654
2655 Works just like L</localtime> but the returned values are
2656 localized for the standard Greenwich time zone.
2657
2658 Note: When called in list context, $isdst, the last value
2659 returned by gmtime, is always C<0>.  There is no
2660 Daylight Saving Time in GMT.
2661
2662 Portability issues: L<perlport/gmtime>.
2663
2664 =item goto LABEL
2665 X<goto> X<jump> X<jmp>
2666
2667 =item goto EXPR
2668
2669 =item goto &NAME
2670
2671 The C<goto-LABEL> form finds the statement labeled with LABEL and
2672 resumes execution there.  It can't be used to get out of a block or
2673 subroutine given to C<sort>.  It can be used to go almost anywhere
2674 else within the dynamic scope, including out of subroutines, but it's
2675 usually better to use some other construct such as C<last> or C<die>.
2676 The author of Perl has never felt the need to use this form of C<goto>
2677 (in Perl, that is; C is another matter).  (The difference is that C
2678 does not offer named loops combined with loop control.  Perl does, and
2679 this replaces most structured uses of C<goto> in other languages.)
2680
2681 The C<goto-EXPR> form expects a label name, whose scope will be resolved
2682 dynamically.  This allows for computed C<goto>s per FORTRAN, but isn't
2683 necessarily recommended if you're optimizing for maintainability:
2684
2685     goto ("FOO", "BAR", "GLARCH")[$i];
2686
2687 As shown in this example, C<goto-EXPR> is exempt from the "looks like a
2688 function" rule.  A pair of parentheses following it does not (necessarily)
2689 delimit its argument.  C<goto("NE")."XT"> is equivalent to C<goto NEXT>.
2690
2691 Use of C<goto-LABEL> or C<goto-EXPR> to jump into a construct is
2692 deprecated and will issue a warning.  Even then, it may not be used to
2693 go into any construct that requires initialization, such as a
2694 subroutine or a C<foreach> loop.  It also can't be used to go into a
2695 construct that is optimized away.
2696
2697 The C<goto-&NAME> form is quite different from the other forms of
2698 C<goto>.  In fact, it isn't a goto in the normal sense at all, and
2699 doesn't have the stigma associated with other gotos.  Instead, it
2700 exits the current subroutine (losing any changes set by local()) and
2701 immediately calls in its place the named subroutine using the current
2702 value of @_.  This is used by C<AUTOLOAD> subroutines that wish to
2703 load another subroutine and then pretend that the other subroutine had
2704 been called in the first place (except that any modifications to C<@_>
2705 in the current subroutine are propagated to the other subroutine.)
2706 After the C<goto>, not even C<caller> will be able to tell that this
2707 routine was called first.
2708
2709 NAME needn't be the name of a subroutine; it can be a scalar variable
2710 containing a code reference or a block that evaluates to a code
2711 reference.
2712
2713 =item grep BLOCK LIST
2714 X<grep>
2715
2716 =item grep EXPR,LIST
2717
2718 This is similar in spirit to, but not the same as, grep(1) and its
2719 relatives.  In particular, it is not limited to using regular expressions.
2720
2721 Evaluates the BLOCK or EXPR for each element of LIST (locally setting
2722 C<$_> to each element) and returns the list value consisting of those
2723 elements for which the expression evaluated to true.  In scalar
2724 context, returns the number of times the expression was true.
2725
2726     @foo = grep(!/^#/, @bar);    # weed out comments
2727
2728 or equivalently,
2729
2730     @foo = grep {!/^#/} @bar;    # weed out comments
2731
2732 Note that C<$_> is an alias to the list value, so it can be used to
2733 modify the elements of the LIST.  While this is useful and supported,
2734 it can cause bizarre results if the elements of LIST are not variables.
2735 Similarly, grep returns aliases into the original list, much as a for
2736 loop's index variable aliases the list elements.  That is, modifying an
2737 element of a list returned by grep (for example, in a C<foreach>, C<map>
2738 or another C<grep>) actually modifies the element in the original list.
2739 This is usually something to be avoided when writing clear code.
2740
2741 If C<$_> is lexical in the scope where the C<grep> appears (because it has
2742 been declared with C<my $_>) then, in addition to being locally aliased to
2743 the list elements, C<$_> keeps being lexical inside the block; i.e., it
2744 can't be seen from the outside, avoiding any potential side-effects.
2745
2746 See also L</map> for a list composed of the results of the BLOCK or EXPR.
2747
2748 =item hex EXPR
2749 X<hex> X<hexadecimal>
2750
2751 =item hex
2752
2753 Interprets EXPR as a hex string and returns the corresponding value.
2754 (To convert strings that might start with either C<0>, C<0x>, or C<0b>, see
2755 L</oct>.)  If EXPR is omitted, uses C<$_>.
2756
2757     print hex '0xAf'; # prints '175'
2758     print hex 'aF';   # same
2759
2760 Hex strings may only represent integers.  Strings that would cause
2761 integer overflow trigger a warning.  Leading whitespace is not stripped,
2762 unlike oct().  To present something as hex, look into L</printf>,
2763 L</sprintf>, and L</unpack>.
2764
2765 =item import LIST
2766 X<import>
2767
2768 There is no builtin C<import> function.  It is just an ordinary
2769 method (subroutine) defined (or inherited) by modules that wish to export
2770 names to another module.  The C<use> function calls the C<import> method
2771 for the package used.  See also L</use>, L<perlmod>, and L<Exporter>.
2772
2773 =item index STR,SUBSTR,POSITION
2774 X<index> X<indexOf> X<InStr>
2775
2776 =item index STR,SUBSTR
2777
2778 The index function searches for one string within another, but without
2779 the wildcard-like behavior of a full regular-expression pattern match.
2780 It returns the position of the first occurrence of SUBSTR in STR at
2781 or after POSITION.  If POSITION is omitted, starts searching from the
2782 beginning of the string.  POSITION before the beginning of the string
2783 or after its end is treated as if it were the beginning or the end,
2784 respectively.  POSITION and the return value are based at zero.
2785 If the substring is not found, C<index> returns -1.
2786
2787 =item int EXPR
2788 X<int> X<integer> X<truncate> X<trunc> X<floor>
2789
2790 =item int
2791
2792 Returns the integer portion of EXPR.  If EXPR is omitted, uses C<$_>.
2793 You should not use this function for rounding: one because it truncates
2794 towards C<0>, and two because machine representations of floating-point
2795 numbers can sometimes produce counterintuitive results.  For example,
2796 C<int(-6.725/0.025)> produces -268 rather than the correct -269; that's
2797 because it's really more like -268.99999999999994315658 instead.  Usually,
2798 the C<sprintf>, C<printf>, or the C<POSIX::floor> and C<POSIX::ceil>
2799 functions will serve you better than will int().
2800
2801 =item ioctl FILEHANDLE,FUNCTION,SCALAR
2802 X<ioctl>
2803
2804 Implements the ioctl(2) function.  You'll probably first have to say
2805
2806     require "sys/ioctl.ph";  # probably in $Config{archlib}/sys/ioctl.ph
2807
2808 to get the correct function definitions.  If F<sys/ioctl.ph> doesn't
2809 exist or doesn't have the correct definitions you'll have to roll your
2810 own, based on your C header files such as F<< <sys/ioctl.h> >>.
2811 (There is a Perl script called B<h2ph> that comes with the Perl kit that
2812 may help you in this, but it's nontrivial.)  SCALAR will be read and/or
2813 written depending on the FUNCTION; a C pointer to the string value of SCALAR
2814 will be passed as the third argument of the actual C<ioctl> call.  (If SCALAR
2815 has no string value but does have a numeric value, that value will be
2816 passed rather than a pointer to the string value.  To guarantee this to be
2817 true, add a C<0> to the scalar before using it.)  The C<pack> and C<unpack>
2818 functions may be needed to manipulate the values of structures used by
2819 C<ioctl>.
2820
2821 The return value of C<ioctl> (and C<fcntl>) is as follows:
2822
2823     if OS returns:      then Perl returns:
2824         -1               undefined value
2825          0              string "0 but true"
2826     anything else           that number
2827
2828 Thus Perl returns true on success and false on failure, yet you can
2829 still easily determine the actual value returned by the operating
2830 system:
2831
2832     $retval = ioctl(...) || -1;
2833     printf "System returned %d\n", $retval;
2834
2835 The special string C<"0 but true"> is exempt from B<-w> complaints
2836 about improper numeric conversions.
2837
2838 Portability issues: L<perlport/ioctl>.
2839
2840 =item join EXPR,LIST
2841 X<join>
2842
2843 Joins the separate strings of LIST into a single string with fields
2844 separated by the value of EXPR, and returns that new string.  Example:
2845
2846     $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
2847
2848 Beware that unlike C<split>, C<join> doesn't take a pattern as its
2849 first argument.  Compare L</split>.
2850
2851 =item keys HASH
2852 X<keys> X<key>
2853
2854 =item keys ARRAY
2855
2856 =item keys EXPR
2857
2858 Called in list context, returns a list consisting of all the keys of the
2859 named hash, or in Perl 5.12 or later only, the indices of an array.  Perl
2860 releases prior to 5.12 will produce a syntax error if you try to use an
2861 array argument.  In scalar context, returns the number of keys or indices.
2862
2863 The keys of a hash are returned in an apparently random order.  The actual
2864 random order is subject to change in future versions of Perl, but it
2865 is guaranteed to be the same order as either the C<values> or C<each>
2866 function produces (given that the hash has not been modified).  Since
2867 Perl 5.8.1 the ordering can be different even between different runs of
2868 Perl for security reasons (see L<perlsec/"Algorithmic Complexity
2869 Attacks">).
2870
2871 As a side effect, calling keys() resets the internal interator of the HASH or ARRAY
2872 (see L</each>).  In particular, calling keys() in void context resets
2873 the iterator with no other overhead.
2874
2875 Here is yet another way to print your environment:
2876
2877     @keys = keys %ENV;
2878     @values = values %ENV;
2879     while (@keys) {
2880         print pop(@keys), '=', pop(@values), "\n";
2881     }
2882
2883 or how about sorted by key:
2884
2885     foreach $key (sort(keys %ENV)) {
2886         print $key, '=', $ENV{$key}, "\n";
2887     }
2888
2889 The returned values are copies of the original keys in the hash, so
2890 modifying them will not affect the original hash.  Compare L</values>.
2891
2892 To sort a hash by value, you'll need to use a C<sort> function.
2893 Here's a descending numeric sort of a hash by its values:
2894
2895     foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
2896         printf "%4d %s\n", $hash{$key}, $key;
2897     }
2898
2899 Used as an lvalue, C<keys> allows you to increase the number of hash buckets
2900 allocated for the given hash.  This can gain you a measure of efficiency if
2901 you know the hash is going to get big.  (This is similar to pre-extending
2902 an array by assigning a larger number to $#array.)  If you say
2903
2904     keys %hash = 200;
2905
2906 then C<%hash> will have at least 200 buckets allocated for it--256 of them,
2907 in fact, since it rounds up to the next power of two.  These
2908 buckets will be retained even if you do C<%hash = ()>, use C<undef
2909 %hash> if you want to free the storage while C<%hash> is still in scope.
2910 You can't shrink the number of buckets allocated for the hash using
2911 C<keys> in this way (but you needn't worry about doing this by accident,
2912 as trying has no effect).  C<keys @array> in an lvalue context is a syntax
2913 error.
2914
2915 Starting with Perl 5.14, C<keys> can take a scalar EXPR, which must contain
2916 a reference to an unblessed hash or array.  The argument will be
2917 dereferenced automatically.  This aspect of C<keys> is considered highly
2918 experimental.  The exact behaviour may change in a future version of Perl.
2919
2920     for (keys $hashref) { ... }
2921     for (keys $obj->get_arrayref) { ... }
2922
2923 To avoid confusing would-be users of your code who are running earlier
2924 versions of Perl with mysterious syntax errors, put this sort of thing at
2925 the top of your file to signal that your code will work I<only> on Perls of
2926 a recent vintage:
2927
2928     use 5.012;  # so keys/values/each work on arrays
2929     use 5.014;  # so keys/values/each work on scalars (experimental)
2930
2931 See also C<each>, C<values>, and C<sort>.
2932
2933 =item kill SIGNAL, LIST
2934
2935 =item kill SIGNAL
2936 X<kill> X<signal>
2937
2938 Sends a signal to a list of processes.  Returns the number of
2939 processes successfully signaled (which is not necessarily the
2940 same as the number actually killed).
2941
2942     $cnt = kill 1, $child1, $child2;
2943     kill 9, @goners;
2944
2945 If SIGNAL is zero, no signal is sent to the process, but C<kill>
2946 checks whether it's I<possible> to send a signal to it (that
2947 means, to be brief, that the process is owned by the same user, or we are
2948 the super-user).  This is useful to check that a child process is still
2949 alive (even if only as a zombie) and hasn't changed its UID.  See
2950 L<perlport> for notes on the portability of this construct.
2951
2952 Unlike in the shell, if SIGNAL is negative, it kills process groups instead
2953 of processes.  That means you usually
2954 want to use positive not negative signals.
2955 You may also use a signal name in quotes.
2956
2957 The behavior of kill when a I<PROCESS> number is zero or negative depends on
2958 the operating system.  For example, on POSIX-conforming systems, zero will
2959 signal the current process group and -1 will signal all processes.
2960
2961 See L<perlipc/"Signals"> for more details.
2962
2963 On some platforms such as Windows where the fork() system call is not available.
2964 Perl can be built to emulate fork() at the interpreter level.
2965 This emulation has limitations related to kill that have to be considered,
2966 for code running on Windows and in code intended to be portable.
2967
2968 See L<perlfork> for more details.
2969
2970 If there is no I<LIST> of processes, no signal is sent, and the return
2971 value is 0.  This form is sometimes used, however, because it causes
2972 tainting checks to be run.  But see
2973 L<perlsec/Laundering and Detecting Tainted Data>.
2974
2975 Portability issues: L<perlport/kill>.
2976
2977 =item last LABEL
2978 X<last> X<break>
2979
2980 =item last
2981
2982 The C<last> command is like the C<break> statement in C (as used in
2983 loops); it immediately exits the loop in question.  If the LABEL is
2984 omitted, the command refers to the innermost enclosing loop.  The
2985 C<continue> block, if any, is not executed:
2986
2987     LINE: while (<STDIN>) {
2988         last LINE if /^$/;  # exit when done with header
2989         #...
2990     }
2991
2992 C<last> cannot be used to exit a block that returns a value such as
2993 C<eval {}>, C<sub {}>, or C<do {}>, and should not be used to exit
2994 a grep() or map() operation.
2995
2996 Note that a block by itself is semantically identical to a loop
2997 that executes once.  Thus C<last> can be used to effect an early
2998 exit out of such a block.
2999
3000 See also L</continue> for an illustration of how C<last>, C<next>, and
3001 C<redo> work.
3002
3003 =item lc EXPR
3004 X<lc> X<lowercase>
3005
3006 =item lc
3007
3008 Returns a lowercased version of EXPR.  This is the internal function
3009 implementing the C<\L> escape in double-quoted strings.
3010
3011 If EXPR is omitted, uses C<$_>.
3012
3013 What gets returned depends on several factors:
3014
3015 =over
3016
3017 =item If C<use bytes> is in effect:
3018
3019 =over
3020
3021 =item On EBCDIC platforms
3022
3023 The results are what the C language system call C<tolower()> returns.
3024
3025 =item On ASCII platforms
3026
3027 The results follow ASCII semantics.  Only characters C<A-Z> change, to C<a-z>
3028 respectively.
3029
3030 =back
3031
3032 =item Otherwise, if C<use locale> (but not C<use locale ':not_characters'>) is in effect:
3033
3034 Respects current LC_CTYPE locale for code points < 256; and uses Unicode
3035 semantics for the remaining code points (this last can only happen if
3036 the UTF8 flag is also set).  See L<perllocale>.
3037
3038 A deficiency in this is that case changes that cross the 255/256
3039 boundary are not well-defined.  For example, the lower case of LATIN CAPITAL
3040 LETTER SHARP S (U+1E9E) in Unicode semantics is U+00DF (on ASCII
3041 platforms).   But under C<use locale>, the lower case of U+1E9E is
3042 itself, because 0xDF may not be LATIN SMALL LETTER SHARP S in the
3043 current locale, and Perl has no way of knowing if that character even
3044 exists in the locale, much less what code point it is.  Perl returns
3045 the input character unchanged, for all instances (and there aren't
3046 many) where the 255/256 boundary would otherwise be crossed.
3047
3048 =item Otherwise, If EXPR has the UTF8 flag set:
3049
3050 Unicode semantics are used for the case change.
3051
3052 =item Otherwise, if C<use feature 'unicode_strings'> or C<use locale ':not_characters'>) is in effect:
3053
3054 Unicode semantics are used for the case change.
3055
3056 =item Otherwise:
3057
3058 =over
3059
3060 =item On EBCDIC platforms
3061
3062 The results are what the C language system call C<tolower()> returns.
3063
3064 =item On ASCII platforms
3065
3066 ASCII semantics are used for the case change.  The lowercase of any character
3067 outside the ASCII range is the character itself.
3068
3069 =back
3070
3071 =back
3072
3073 =item lcfirst EXPR
3074 X<lcfirst> X<lowercase>
3075
3076 =item lcfirst
3077
3078 Returns the value of EXPR with the first character lowercased.  This
3079 is the internal function implementing the C<\l> escape in
3080 double-quoted strings.
3081
3082 If EXPR is omitted, uses C<$_>.
3083
3084 This function behaves the same way under various pragmata, such as in a locale,
3085 as L</lc> does.
3086
3087 =item length EXPR
3088 X<length> X<size>
3089
3090 =item length
3091
3092 Returns the length in I<characters> of the value of EXPR.  If EXPR is
3093 omitted, returns the length of C<$_>.  If EXPR is undefined, returns
3094 C<undef>.
3095
3096 This function cannot be used on an entire array or hash to find out how
3097 many elements these have.  For that, use C<scalar @array> and C<scalar keys
3098 %hash>, respectively.
3099
3100 Like all Perl character operations, length() normally deals in logical
3101 characters, not physical bytes.  For how many bytes a string encoded as
3102 UTF-8 would take up, use C<length(Encode::encode_utf8(EXPR))> (you'll have
3103 to C<use Encode> first).  See L<Encode> and L<perlunicode>.
3104
3105 =item __LINE__
3106 X<__LINE__>
3107
3108 A special token that compiles to the current line number.
3109
3110 =item link OLDFILE,NEWFILE
3111 X<link>
3112
3113 Creates a new filename linked to the old filename.  Returns true for
3114 success, false otherwise.
3115
3116 Portability issues: L<perlport/link>.
3117
3118 =item listen SOCKET,QUEUESIZE
3119 X<listen>
3120
3121 Does the same thing that the listen(2) system call does.  Returns true if
3122 it succeeded, false otherwise.  See the example in
3123 L<perlipc/"Sockets: Client/Server Communication">.
3124
3125 =item local EXPR
3126 X<local>
3127
3128 You really probably want to be using C<my> instead, because C<local> isn't
3129 what most people think of as "local".  See
3130 L<perlsub/"Private Variables via my()"> for details.
3131
3132 A local modifies the listed variables to be local to the enclosing
3133 block, file, or eval.  If more than one value is listed, the list must
3134 be placed in parentheses.  See L<perlsub/"Temporary Values via local()">
3135 for details, including issues with tied arrays and hashes.
3136
3137 The C<delete local EXPR> construct can also be used to localize the deletion
3138 of array/hash elements to the current block.
3139 See L<perlsub/"Localized deletion of elements of composite types">.
3140
3141 =item localtime EXPR
3142 X<localtime> X<ctime>
3143
3144 =item localtime
3145
3146 Converts a time as returned by the time function to a 9-element list
3147 with the time analyzed for the local time zone.  Typically used as
3148 follows:
3149
3150     #  0    1    2     3     4    5     6     7     8
3151     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
3152                                                 localtime(time);
3153
3154 All list elements are numeric and come straight out of the C `struct
3155 tm'.  C<$sec>, C<$min>, and C<$hour> are the seconds, minutes, and hours
3156 of the specified time.
3157
3158 C<$mday> is the day of the month and C<$mon> the month in
3159 the range C<0..11>, with 0 indicating January and 11 indicating December.
3160 This makes it easy to get a month name from a list:
3161
3162     my @abbr = qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec );
3163     print "$abbr[$mon] $mday";
3164     # $mon=9, $mday=18 gives "Oct 18"
3165
3166 C<$year> contains the number of years since 1900.  To get a 4-digit
3167 year write:
3168
3169     $year += 1900;
3170
3171 To get the last two digits of the year (e.g., "01" in 2001) do:
3172
3173     $year = sprintf("%02d", $year % 100);
3174
3175 C<$wday> is the day of the week, with 0 indicating Sunday and 3 indicating
3176 Wednesday.  C<$yday> is the day of the year, in the range C<0..364>
3177 (or C<0..365> in leap years.)
3178
3179 C<$isdst> is true if the specified time occurs during Daylight Saving
3180 Time, false otherwise.
3181
3182 If EXPR is omitted, C<localtime()> uses the current time (as returned
3183 by time(3)).
3184
3185 In scalar context, C<localtime()> returns the ctime(3) value:
3186
3187     $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"
3188
3189 The format of this scalar value is B<not> locale-dependent
3190 but built into Perl.  For GMT instead of local
3191 time use the L</gmtime> builtin.  See also the
3192 C<Time::Local> module (for converting seconds, minutes, hours, and such back to
3193 the integer value returned by time()), and the L<POSIX> module's strftime(3)
3194 and mktime(3) functions.
3195
3196 To get somewhat similar but locale-dependent date strings, set up your
3197 locale environment variables appropriately (please see L<perllocale>) and
3198 try for example:
3199
3200     use POSIX qw(strftime);
3201     $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
3202     # or for GMT formatted appropriately for your locale:
3203     $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
3204
3205 Note that the C<%a> and C<%b>, the short forms of the day of the week
3206 and the month of the year, may not necessarily be three characters wide.
3207
3208 The L<Time::gmtime> and L<Time::localtime> modules provide a convenient,
3209 by-name access mechanism to the gmtime() and localtime() functions,
3210 respectively.
3211
3212 For a comprehensive date and time representation look at the
3213 L<DateTime> module on CPAN.
3214
3215 Portability issues: L<perlport/localtime>.
3216
3217 =item lock THING
3218 X<lock>
3219
3220 This function places an advisory lock on a shared variable or referenced
3221 object contained in I<THING> until the lock goes out of scope.
3222
3223 The value returned is the scalar itself, if the argument is a scalar, or a
3224 reference, if the argument is a hash, array or subroutine.
3225
3226 lock() is a "weak keyword" : this means that if you've defined a function
3227 by this name (before any calls to it), that function will be called
3228 instead.  If you are not under C<use threads::shared> this does nothing.
3229 See L<threads::shared>.
3230
3231 =item log EXPR
3232 X<log> X<logarithm> X<e> X<ln> X<base>
3233
3234 =item log
3235
3236 Returns the natural logarithm (base I<e>) of EXPR.  If EXPR is omitted,
3237 returns the log of C<$_>.  To get the
3238 log of another base, use basic algebra:
3239 The base-N log of a number is equal to the natural log of that number
3240 divided by the natural log of N.  For example:
3241
3242     sub log10 {
3243         my $n = shift;
3244         return log($n)/log(10);
3245     }
3246
3247 See also L</exp> for the inverse operation.
3248
3249 =item lstat FILEHANDLE
3250 X<lstat>
3251
3252 =item lstat EXPR
3253
3254 =item lstat DIRHANDLE
3255
3256 =item lstat
3257
3258 Does the same thing as the C<stat> function (including setting the
3259 special C<_> filehandle) but stats a symbolic link instead of the file
3260 the symbolic link points to.  If symbolic links are unimplemented on
3261 your system, a normal C<stat> is done.  For much more detailed
3262 information, please see the documentation for C<stat>.
3263
3264 If EXPR is omitted, stats C<$_>.
3265
3266 Portability issues: L<perlport/lstat>.
3267
3268 =item m//
3269
3270 The match operator.  See L<perlop/"Regexp Quote-Like Operators">.
3271
3272 =item map BLOCK LIST
3273 X<map>
3274
3275 =item map EXPR,LIST
3276
3277 Evaluates the BLOCK or EXPR for each element of LIST (locally setting
3278 C<$_> to each element) and returns the list value composed of the
3279 results of each such evaluation.  In scalar context, returns the
3280 total number of elements so generated.  Evaluates BLOCK or EXPR in
3281 list context, so each element of LIST may produce zero, one, or
3282 more elements in the returned value.
3283
3284     @chars = map(chr, @numbers);
3285
3286 translates a list of numbers to the corresponding characters.
3287
3288     my @squares = map { $_ * $_ } @numbers;
3289
3290 translates a list of numbers to their squared values.
3291
3292     my @squares = map { $_ > 5 ? ($_ * $_) : () } @numbers;
3293
3294 shows that number of returned elements can differ from the number of
3295 input elements.  To omit an element, return an empty list ().
3296 This could also be achieved by writing
3297
3298     my @squares = map { $_ * $_ } grep { $_ > 5 } @numbers;
3299
3300 which makes the intention more clear.
3301
3302 Map always returns a list, which can be
3303 assigned to a hash such that the elements
3304 become key/value pairs.  See L<perldata> for more details.
3305
3306     %hash = map { get_a_key_for($_) => $_ } @array;
3307
3308 is just a funny way to write
3309
3310     %hash = ();
3311     foreach (@array) {
3312         $hash{get_a_key_for($_)} = $_;
3313     }
3314
3315 Note that C<$_> is an alias to the list value, so it can be used to
3316 modify the elements of the LIST.  While this is useful and supported,
3317 it can cause bizarre results if the elements of LIST are not variables.
3318 Using a regular C<foreach> loop for this purpose would be clearer in
3319 most cases.  See also L</grep> for an array composed of those items of
3320 the original list for which the BLOCK or EXPR evaluates to true.
3321
3322 If C<$_> is lexical in the scope where the C<map> appears (because it has
3323 been declared with C<my $_>), then, in addition to being locally aliased to
3324 the list elements, C<$_> keeps being lexical inside the block; that is, it
3325 can't be seen from the outside, avoiding any potential side-effects.
3326
3327 C<{> starts both hash references and blocks, so C<map { ...> could be either
3328 the start of map BLOCK LIST or map EXPR, LIST.  Because Perl doesn't look
3329 ahead for the closing C<}> it has to take a guess at which it's dealing with
3330 based on what it finds just after the
3331 C<{>.  Usually it gets it right, but if it
3332 doesn't it won't realize something is wrong until it gets to the C<}> and
3333 encounters the missing (or unexpected) comma.  The syntax error will be
3334 reported close to the C<}>, but you'll need to change something near the C<{>
3335 such as using a unary C<+> to give Perl some help:
3336
3337     %hash = map {  "\L$_" => 1  } @array  # perl guesses EXPR.  wrong
3338     %hash = map { +"\L$_" => 1  } @array  # perl guesses BLOCK. right
3339     %hash = map { ("\L$_" => 1) } @array  # this also works
3340     %hash = map {  lc($_) => 1  } @array  # as does this.
3341     %hash = map +( lc($_) => 1 ), @array  # this is EXPR and works!
3342
3343     %hash = map  ( lc($_), 1 ),   @array  # evaluates to (1, @array)
3344
3345 or to force an anon hash constructor use C<+{>:
3346
3347    @hashes = map +{ lc($_) => 1 }, @array # EXPR, so needs comma at end
3348
3349 to get a list of anonymous hashes each with only one entry apiece.
3350
3351 =item mkdir FILENAME,MASK
3352 X<mkdir> X<md> X<directory, create>
3353
3354 =item mkdir FILENAME
3355
3356 =item mkdir
3357
3358 Creates the directory specified by FILENAME, with permissions
3359 specified by MASK (as modified by C<umask>).  If it succeeds it
3360 returns true; otherwise it returns false and sets C<$!> (errno).
3361 MASK defaults to 0777 if omitted, and FILENAME defaults
3362 to C<$_> if omitted.
3363
3364 In general, it is better to create directories with a permissive MASK
3365 and let the user modify that with their C<umask> than it is to supply
3366 a restrictive MASK and give the user no way to be more permissive.
3367 The exceptions to this rule are when the file or directory should be
3368 kept private (mail files, for instance).  The perlfunc(1) entry on
3369 C<umask> discusses the choice of MASK in more detail.
3370
3371 Note that according to the POSIX 1003.1-1996 the FILENAME may have any
3372 number of trailing slashes.  Some operating and filesystems do not get
3373 this right, so Perl automatically removes all trailing slashes to keep
3374 everyone happy.
3375
3376 To recursively create a directory structure, look at
3377 the C<mkpath> function of the L<File::Path> module.
3378
3379 =item msgctl ID,CMD,ARG
3380 X<msgctl>
3381
3382 Calls the System V IPC function msgctl(2).  You'll probably have to say
3383
3384     use IPC::SysV;
3385
3386 first to get the correct constant definitions.  If CMD is C<IPC_STAT>,
3387 then ARG must be a variable that will hold the returned C<msqid_ds>
3388 structure.  Returns like C<ioctl>: the undefined value for error,
3389 C<"0 but true"> for zero, or the actual return value otherwise.  See also
3390 L<perlipc/"SysV IPC"> and the documentation for C<IPC::SysV> and
3391 C<IPC::Semaphore>.
3392
3393 Portability issues: L<perlport/msgctl>.
3394
3395 =item msgget KEY,FLAGS
3396 X<msgget>
3397
3398 Calls the System V IPC function msgget(2).  Returns the message queue
3399 id, or C<undef> on error.  See also
3400 L<perlipc/"SysV IPC"> and the documentation for C<IPC::SysV> and
3401 C<IPC::Msg>.
3402
3403 Portability issues: L<perlport/msgget>.
3404
3405 =item msgrcv ID,VAR,SIZE,TYPE,FLAGS
3406 X<msgrcv>
3407
3408 Calls the System V IPC function msgrcv to receive a message from
3409 message queue ID into variable VAR with a maximum message size of
3410 SIZE.  Note that when a message is received, the message type as a
3411 native long integer will be the first thing in VAR, followed by the
3412 actual message.  This packing may be opened with C<unpack("l! a*")>.
3413 Taints the variable.  Returns true if successful, false 
3414 on error.  See also L<perlipc/"SysV IPC"> and the documentation for
3415 C<IPC::SysV> and C<IPC::SysV::Msg>.
3416
3417 Portability issues: L<perlport/msgrcv>.
3418
3419 =item msgsnd ID,MSG,FLAGS
3420 X<msgsnd>
3421
3422 Calls the System V IPC function msgsnd to send the message MSG to the
3423 message queue ID.  MSG must begin with the native long integer message
3424 type, be followed by the length of the actual message, and then finally
3425 the message itself.  This kind of packing can be achieved with
3426 C<pack("l! a*", $type, $message)>.  Returns true if successful,
3427 false on error.  See also the C<IPC::SysV>
3428 and C<IPC::SysV::Msg> documentation.
3429
3430 Portability issues: L<perlport/msgsnd>.
3431
3432 =item my EXPR
3433 X<my>
3434
3435 =item my TYPE EXPR
3436
3437 =item my EXPR : ATTRS
3438
3439 =item my TYPE EXPR : ATTRS
3440
3441 A C<my> declares the listed variables to be local (lexically) to the
3442 enclosing block, file, or C<eval>.  If more than one value is listed,
3443 the list must be placed in parentheses.
3444
3445 The exact semantics and interface of TYPE and ATTRS are still
3446 evolving.  TYPE is currently bound to the use of the C<fields> pragma,
3447 and attributes are handled using the C<attributes> pragma, or starting
3448 from Perl 5.8.0 also via the C<Attribute::Handlers> module.  See
3449 L<perlsub/"Private Variables via my()"> for details, and L<fields>,
3450 L<attributes>, and L<Attribute::Handlers>.
3451
3452 =item next LABEL
3453 X<next> X<continue>
3454
3455 =item next
3456
3457 The C<next> command is like the C<continue> statement in C; it starts
3458 the next iteration of the loop:
3459
3460     LINE: while (<STDIN>) {
3461         next LINE if /^#/;  # discard comments
3462         #...
3463     }
3464
3465 Note that if there were a C<continue> block on the above, it would get
3466 executed even on discarded lines.  If LABEL is omitted, the command
3467 refers to the innermost enclosing loop.
3468
3469 C<next> cannot be used to exit a block which returns a value such as
3470 C<eval {}>, C<sub {}>, or C<do {}>, and should not be used to exit
3471 a grep() or map() operation.
3472
3473 Note that a block by itself is semantically identical to a loop
3474 that executes once.  Thus C<next> will exit such a block early.
3475
3476 See also L</continue> for an illustration of how C<last>, C<next>, and
3477 C<redo> work.
3478
3479 =item no MODULE VERSION LIST
3480 X<no declarations>
3481 X<unimporting>
3482
3483 =item no MODULE VERSION
3484
3485 =item no MODULE LIST
3486
3487 =item no MODULE
3488
3489 =item no VERSION
3490
3491 See the C<use> function, of which C<no> is the opposite.
3492
3493 =item oct EXPR
3494 X<oct> X<octal> X<hex> X<hexadecimal> X<binary> X<bin>
3495
3496 =item oct
3497
3498 Interprets EXPR as an octal string and returns the corresponding
3499 value.  (If EXPR happens to start off with C<0x>, interprets it as a
3500 hex string.  If EXPR starts off with C<0b>, it is interpreted as a
3501 binary string.  Leading whitespace is ignored in all three cases.)
3502 The following will handle decimal, binary, octal, and hex in standard
3503 Perl notation:
3504
3505     $val = oct($val) if $val =~ /^0/;
3506
3507 If EXPR is omitted, uses C<$_>.   To go the other way (produce a number
3508 in octal), use sprintf() or printf():
3509
3510     $dec_perms = (stat("filename"))[2] & 07777;
3511     $oct_perm_str = sprintf "%o", $perms;
3512
3513 The oct() function is commonly used when a string such as C<644> needs
3514 to be converted into a file mode, for example.  Although Perl 
3515 automatically converts strings into numbers as needed, this automatic
3516 conversion assumes base 10.
3517
3518 Leading white space is ignored without warning, as too are any trailing 
3519 non-digits, such as a decimal point (C<oct> only handles non-negative
3520 integers, not negative integers or floating point).
3521
3522 =item open FILEHANDLE,EXPR
3523 X<open> X<pipe> X<file, open> X<fopen>
3524
3525 =item open FILEHANDLE,MODE,EXPR
3526
3527 =item open FILEHANDLE,MODE,EXPR,LIST
3528
3529 =item open FILEHANDLE,MODE,REFERENCE
3530
3531 =item open FILEHANDLE
3532
3533 Opens the file whose filename is given by EXPR, and associates it with
3534 FILEHANDLE.
3535
3536 Simple examples to open a file for reading:
3537
3538     open(my $fh, "<", "input.txt") 
3539         or die "cannot open < input.txt: $!";
3540
3541 and for writing:
3542
3543     open(my $fh, ">", "output.txt") 
3544         or die "cannot open > output.txt: $!";
3545
3546 (The following is a comprehensive reference to open(): for a gentler
3547 introduction you may consider L<perlopentut>.)
3548
3549 If FILEHANDLE is an undefined scalar variable (or array or hash element), a
3550 new filehandle is autovivified, meaning that the variable is assigned a
3551 reference to a newly allocated anonymous filehandle.  Otherwise if
3552 FILEHANDLE is an expression, its value is the real filehandle.  (This is
3553 considered a symbolic reference, so C<use strict "refs"> should I<not> be
3554 in effect.)
3555
3556 If EXPR is omitted, the global (package) scalar variable of the same
3557 name as the FILEHANDLE contains the filename.  (Note that lexical 
3558 variables--those declared with C<my> or C<state>--will not work for this
3559 purpose; so if you're using C<my> or C<state>, specify EXPR in your
3560 call to open.)
3561
3562 If three (or more) arguments are specified, the open mode (including
3563 optional encoding) in the second argument are distinct from the filename in
3564 the third.  If MODE is C<< < >> or nothing, the file is opened for input.
3565 If MODE is C<< > >>, the file is opened for output, with existing files
3566 first being truncated ("clobbered") and nonexisting files newly created.
3567 If MODE is C<<< >> >>>, the file is opened for appending, again being
3568 created if necessary.
3569
3570 You can put a C<+> in front of the C<< > >> or C<< < >> to
3571 indicate that you want both read and write access to the file; thus
3572 C<< +< >> is almost always preferred for read/write updates--the 
3573 C<< +> >> mode would clobber the file first.  You can't usually use
3574 either read-write mode for updating textfiles, since they have
3575 variable-length records.  See the B<-i> switch in L<perlrun> for a
3576 better approach.  The file is created with permissions of C<0666>
3577 modified by the process's C<umask> value.
3578
3579 These various prefixes correspond to the fopen(3) modes of C<r>,
3580 C<r+>, C<w>, C<w+>, C<a>, and C<a+>.
3581
3582 In the one- and two-argument forms of the call, the mode and filename
3583 should be concatenated (in that order), preferably separated by white
3584 space.  You can--but shouldn't--omit the mode in these forms when that mode
3585 is C<< < >>.  It is always safe to use the two-argument form of C<open> if
3586 the filename argument is a known literal.
3587
3588 For three or more arguments if MODE is C<|->, the filename is
3589 interpreted as a command to which output is to be piped, and if MODE
3590 is C<-|>, the filename is interpreted as a command that pipes
3591 output to us.  In the two-argument (and one-argument) form, one should
3592 replace dash (C<->) with the command.
3593 See L<perlipc/"Using open() for IPC"> for more examples of this.
3594 (You are not allowed to C<open> to a command that pipes both in I<and>
3595 out, but see L<IPC::Open2>, L<IPC::Open3>, and
3596 L<perlipc/"Bidirectional Communication with Another Process"> for
3597 alternatives.)
3598
3599 In the form of pipe opens taking three or more arguments, if LIST is specified
3600 (extra arguments after the command name) then LIST becomes arguments
3601 to the command invoked if the platform supports it.  The meaning of
3602 C<open> with more than three arguments for non-pipe modes is not yet
3603 defined, but experimental "layers" may give extra LIST arguments
3604 meaning.
3605
3606 In the two-argument (and one-argument) form, opening C<< <- >> 
3607 or C<-> opens STDIN and opening C<< >- >> opens STDOUT.
3608
3609 You may (and usually should) use the three-argument form of open to specify
3610 I/O layers (sometimes referred to as "disciplines") to apply to the handle
3611 that affect how the input and output are processed (see L<open> and
3612 L<PerlIO> for more details).  For example:
3613
3614   open(my $fh, "<:encoding(UTF-8)", "filename")
3615     || die "can't open UTF-8 encoded filename: $!";
3616
3617 opens the UTF8-encoded file containing Unicode characters;
3618 see L<perluniintro>.  Note that if layers are specified in the
3619 three-argument form, then default layers stored in ${^OPEN} (see L<perlvar>;
3620 usually set by the B<open> pragma or the switch B<-CioD>) are ignored.
3621 Those layers will also be ignored if you specifying a colon with no name
3622 following it.  In that case the default layer for the operating system
3623 (:raw on Unix, :crlf on Windows) is used.
3624
3625 Open returns nonzero on success, the undefined value otherwise.  If
3626 the C<open> involved a pipe, the return value happens to be the pid of
3627 the subprocess.
3628
3629 If you're running Perl on a system that distinguishes between text
3630 files and binary files, then you should check out L</binmode> for tips
3631 for dealing with this.  The key distinction between systems that need
3632 C<binmode> and those that don't is their text file formats.  Systems
3633 like Unix, Mac OS, and Plan 9, that end lines with a single
3634 character and encode that character in C as C<"\n"> do not
3635 need C<binmode>.  The rest need it.
3636
3637 When opening a file, it's seldom a good idea to continue 
3638 if the request failed, so C<open> is frequently used with
3639 C<die>.  Even if C<die> won't do what you want (say, in a CGI script,
3640 where you want to format a suitable error message (but there are
3641 modules that can help with that problem)) always check
3642 the return value from opening a file.  
3643
3644 As a special case the three-argument form with a read/write mode and the third
3645 argument being C<undef>:
3646
3647     open(my $tmp, "+>", undef) or die ...
3648
3649 opens a filehandle to an anonymous temporary file.  Also using C<< +< >>
3650 works for symmetry, but you really should consider writing something
3651 to the temporary file first.  You will need to seek() to do the
3652 reading.
3653
3654 Since v5.8.0, Perl has built using PerlIO by default.  Unless you've
3655 changed this (such as building Perl with C<Configure -Uuseperlio>), you can
3656 open filehandles directly to Perl scalars via:
3657
3658     open($fh, ">", \$variable) || ..
3659
3660 To (re)open C<STDOUT> or C<STDERR> as an in-memory file, close it first:
3661
3662     close STDOUT;
3663     open(STDOUT, ">", \$variable)
3664         or die "Can't open STDOUT: $!";
3665
3666 General examples:
3667
3668     $ARTICLE = 100;
3669     open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";
3670     while (<ARTICLE>) {...
3671
3672     open(LOG, ">>/usr/spool/news/twitlog");  # (log is reserved)
3673     # if the open fails, output is discarded
3674
3675     open(my $dbase, "+<", "dbase.mine")      # open for update
3676         or die "Can't open 'dbase.mine' for update: $!";
3677
3678     open(my $dbase, "+<dbase.mine")          # ditto
3679         or die "Can't open 'dbase.mine' for update: $!";
3680
3681     open(ARTICLE, "-|", "caesar <$article")  # decrypt article
3682         or die "Can't start caesar: $!";
3683
3684     open(ARTICLE, "caesar <$article |")      # ditto
3685         or die "Can't start caesar: $!";
3686
3687     open(EXTRACT, "|sort >Tmp$$")            # $$ is our process id
3688         or die "Can't start sort: $!";
3689
3690     # in-memory files
3691     open(MEMORY, ">", \$var)
3692         or die "Can't open memory file: $!";
3693     print MEMORY "foo!\n";                   # output will appear in $var
3694
3695     # process argument list of files along with any includes
3696
3697     foreach $file (@ARGV) {
3698         process($file, "fh00");
3699     }
3700
3701     sub process {
3702         my($filename, $input) = @_;
3703         $input++;    # this is a string increment
3704         unless (open($input, "<", $filename)) {
3705             print STDERR "Can't open $filename: $!\n";
3706             return;
3707         }
3708
3709         local $_;
3710         while (<$input>) {    # note use of indirection
3711             if (/^#include "(.*)"/) {
3712                 process($1, $input);
3713                 next;
3714             }
3715             #...          # whatever
3716         }
3717     }
3718
3719 See L<perliol> for detailed info on PerlIO.
3720
3721 You may also, in the Bourne shell tradition, specify an EXPR beginning
3722 with C<< >& >>, in which case the rest of the string is interpreted
3723 as the name of a filehandle (or file descriptor, if numeric) to be
3724 duped (as C<dup(2)>) and opened.  You may use C<&> after C<< > >>,
3725 C<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>.
3726 The mode you specify should match the mode of the original filehandle.
3727 (Duping a filehandle does not take into account any existing contents
3728 of IO buffers.)  If you use the three-argument
3729 form, then you can pass either a
3730 number, the name of a filehandle, or the normal "reference to a glob".
3731
3732 Here is a script that saves, redirects, and restores C<STDOUT> and
3733 C<STDERR> using various methods:
3734
3735     #!/usr/bin/perl
3736     open(my $oldout, ">&STDOUT")     or die "Can't dup STDOUT: $!";
3737     open(OLDERR,     ">&", \*STDERR) or die "Can't dup STDERR: $!";
3738
3739     open(STDOUT, '>', "foo.out") or die "Can't redirect STDOUT: $!";
3740     open(STDERR, ">&STDOUT")     or die "Can't dup STDOUT: $!";
3741
3742     select STDERR; $| = 1;  # make unbuffered
3743     select STDOUT; $| = 1;  # make unbuffered
3744
3745     print STDOUT "stdout 1\n";  # this works for
3746     print STDERR "stderr 1\n";  # subprocesses too
3747
3748     open(STDOUT, ">&", $oldout) or die "Can't dup \$oldout: $!";
3749     open(STDERR, ">&OLDERR")    or die "Can't dup OLDERR: $!";
3750
3751     print STDOUT "stdout 2\n";
3752     print STDERR "stderr 2\n";
3753
3754 If you specify C<< '<&=X' >>, where C<X> is a file descriptor number
3755 or a filehandle, then Perl will do an equivalent of C's C<fdopen> of
3756 that file descriptor (and not call C<dup(2)>); this is more
3757 parsimonious of file descriptors.  For example:
3758
3759     # open for input, reusing the fileno of $fd
3760     open(FILEHANDLE, "<&=$fd")
3761
3762 or
3763
3764     open(FILEHANDLE, "<&=", $fd)
3765
3766 or
3767
3768     # open for append, using the fileno of OLDFH
3769     open(FH, ">>&=", OLDFH)
3770
3771 or
3772
3773     open(FH, ">>&=OLDFH")
3774
3775 Being parsimonious on filehandles is also useful (besides being
3776 parsimonious) for example when something is dependent on file
3777 descriptors, like for example locking using flock().  If you do just
3778 C<< open(A, ">>&B") >>, the filehandle A will not have the same file
3779 descriptor as B, and therefore flock(A) will not flock(B) nor vice
3780 versa.  But with C<< open(A, ">>&=B") >>, the filehandles will share
3781 the same underlying system file descriptor.
3782
3783 Note that under Perls older than 5.8.0, Perl uses the standard C library's'
3784 fdopen() to implement the C<=> functionality.  On many Unix systems,
3785 fdopen() fails when file descriptors exceed a certain value, typically 255.
3786 For Perls 5.8.0 and later, PerlIO is (most often) the default.
3787
3788 You can see whether your Perl was built with PerlIO by running C<perl -V>
3789 and looking for the C<useperlio=> line.  If C<useperlio> is C<define>, you
3790 have PerlIO; otherwise you don't.
3791
3792 If you open a pipe on the command C<-> (that is, specify either C<|-> or C<-|>
3793 with the one- or two-argument forms of C<open>), 
3794 an implicit C<fork> is done, so C<open> returns twice: in the parent
3795 process it returns the pid
3796 of the child process, and in the child process it returns (a defined) C<0>.
3797 Use C<defined($pid)> or C<//> to determine whether the open was successful.
3798
3799 For example, use either
3800
3801     $child_pid = open(FROM_KID, "-|")   // die "can't fork: $!";
3802
3803 or
3804     $child_pid = open(TO_KID,   "|-")   // die "can't fork: $!";
3805
3806 followed by 
3807
3808     if ($child_pid) {
3809         # am the parent:
3810         # either write TO_KID or else read FROM_KID
3811         ...
3812         wait $child_pid;
3813     } else {
3814         # am the child; use STDIN/STDOUT normally
3815         ...
3816         exit;
3817     } 
3818
3819 The filehandle behaves normally for the parent, but I/O to that
3820 filehandle is piped from/to the STDOUT/STDIN of the child process.
3821 In the child process, the filehandle isn't opened--I/O happens from/to
3822 the new STDOUT/STDIN.  Typically this is used like the normal
3823 piped open when you want to exercise more control over just how the
3824 pipe command gets executed, such as when running setuid and
3825 you don't want to have to scan shell commands for metacharacters.
3826
3827 The following blocks are more or less equivalent:
3828
3829     open(FOO, "|tr '[a-z]' '[A-Z]'");
3830     open(FOO, "|-", "tr '[a-z]' '[A-Z]'");
3831     open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]';
3832     open(FOO, "|-", "tr", '[a-z]', '[A-Z]');
3833
3834     open(FOO, "cat -n '$file'|");
3835     open(FOO, "-|", "cat -n '$file'");
3836     open(FOO, "-|") || exec "cat", "-n", $file;
3837     open(FOO, "-|", "cat", "-n", $file);
3838
3839 The last two examples in each block show the pipe as "list form", which is
3840 not yet supported on all platforms.  A good rule of thumb is that if
3841 your platform has a real C<fork()> (in other words, if your platform is
3842 Unix, including Linux and MacOS X), you can use the list form.  You would 
3843 want to use the list form of the pipe so you can pass literal arguments
3844 to the command without risk of the shell interpreting any shell metacharacters
3845 in them.  However, this also bars you from opening pipes to commands
3846 that intentionally contain shell metacharacters, such as:
3847
3848     open(FOO, "|cat -n | expand -4 | lpr")
3849         // die "Can't open pipeline to lpr: $!";
3850
3851 See L<perlipc/"Safe Pipe Opens"> for more examples of this.
3852
3853 Beginning with v5.6.0, Perl will attempt to flush all files opened for
3854 output before any operation that may do a fork, but this may not be
3855 supported on some platforms (see L<perlport>).  To be safe, you may need
3856 to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
3857 of C<IO::Handle> on any open handles.
3858
3859 On systems that support a close-on-exec flag on files, the flag will
3860 be set for the newly opened file descriptor as determined by the value
3861 of C<$^F>.  See L<perlvar/$^F>.
3862
3863 Closing any piped filehandle causes the parent process to wait for the
3864 child to finish, then returns the status value in C<$?> and
3865 C<${^CHILD_ERROR_NATIVE}>.
3866
3867 The filename passed to the one- and two-argument forms of open() will
3868 have leading and trailing whitespace deleted and normal
3869 redirection characters honored.  This property, known as "magic open",
3870 can often be used to good effect.  A user could specify a filename of
3871 F<"rsh cat file |">, or you could change certain filenames as needed:
3872
3873     $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
3874     open(FH, $filename) or die "Can't open $filename: $!";
3875
3876 Use the three-argument form to open a file with arbitrary weird characters in it,
3877
3878     open(FOO, "<", $file)
3879         || die "can't open < $file: $!";
3880
3881 otherwise it's necessary to protect any leading and trailing whitespace:
3882
3883     $file =~ s#^(\s)#./$1#;
3884     open(FOO, "< $file\0")
3885         || die "open failed: $!";
3886
3887 (this may not work on some bizarre filesystems).  One should
3888 conscientiously choose between the I<magic> and I<three-argument> form
3889 of open():
3890
3891     open(IN, $ARGV[0]) || die "can't open $ARGV[0]: $!";
3892
3893 will allow the user to specify an argument of the form C<"rsh cat file |">,
3894 but will not work on a filename that happens to have a trailing space, while
3895
3896     open(IN, "<", $ARGV[0])
3897         || die "can't open < $ARGV[0]: $!";
3898
3899 will have exactly the opposite restrictions.
3900
3901 If you want a "real" C C<open> (see L<open(2)> on your system), then you
3902 should use the C<sysopen> function, which involves no such magic (but may
3903 use subtly different filemodes than Perl open(), which is mapped to C
3904 fopen()).  This is another way to protect your filenames from
3905 interpretation.  For example:
3906
3907     use IO::Handle;
3908     sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL)
3909         or die "sysopen $path: $!";
3910     $oldfh = select(HANDLE); $| = 1; select($oldfh);
3911     print HANDLE "stuff $$\n";
3912     seek(HANDLE, 0, 0);
3913     print "File contains: ", <HANDLE>;
3914
3915 Using the constructor from the C<IO::Handle> package (or one of its
3916 subclasses, such as C<IO::File> or C<IO::Socket>), you can generate anonymous
3917 filehandles that have the scope of the variables used to hold them, then
3918 automatically (but silently) close once their reference counts become
3919 zero, typically at scope exit:
3920
3921     use IO::File;
3922     #...
3923     sub read_myfile_munged {
3924         my $ALL = shift;
3925         # or just leave it undef to autoviv
3926         my $handle = IO::File->new;
3927         open($handle, "<", "myfile") or die "myfile: $!";
3928         $first = <$handle>
3929             or return ();     # Automatically closed here.
3930         mung($first) or die "mung failed";  # Or here.
3931         return (first, <$handle>) if $ALL;  # Or here.
3932         return $first;                      # Or here.
3933     }
3934
3935 B<WARNING:> The previous example has a bug because the automatic
3936 close that happens when the refcount on C<handle> does not
3937 properly detect and report failures.  I<Always> close the handle
3938 yourself and inspect the return value.
3939
3940     close($handle) 
3941         || warn "close failed: $!";
3942
3943 See L</seek> for some details about mixing reading and writing.
3944
3945 Portability issues: L<perlport/open>.
3946
3947 =item opendir DIRHANDLE,EXPR
3948 X<opendir>
3949
3950 Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
3951 C<seekdir>, C<rewinddir>, and C<closedir>.  Returns true if successful.
3952 DIRHANDLE may be an expression whose value can be used as an indirect
3953 dirhandle, usually the real dirhandle name.  If DIRHANDLE is an undefined
3954 scalar variable (or array or hash element), the variable is assigned a
3955 reference to a new anonymous dirhandle; that is, it's autovivified.
3956 DIRHANDLEs have their own namespace separate from FILEHANDLEs.
3957
3958 See the example at C<readdir>.
3959
3960 =item ord EXPR
3961 X<ord> X<encoding>
3962
3963 =item ord
3964
3965 Returns the numeric value of the first character of EXPR.
3966 If EXPR is an empty string, returns 0.  If EXPR is omitted, uses C<$_>.
3967 (Note I<character>, not byte.)
3968
3969 For the reverse, see L</chr>.
3970 See L<perlunicode> for more about Unicode.
3971
3972 =item our EXPR
3973 X<our> X<global>
3974
3975 =item our TYPE EXPR
3976
3977 =item our EXPR : ATTRS
3978
3979 =item our TYPE EXPR : ATTRS
3980
3981 C<our> associates a simple name with a package variable in the current
3982 package for use within the current scope.  When C<use strict 'vars'> is in
3983 effect, C<our> lets you use declared global variables without qualifying
3984 them with package names, within the lexical scope of the C<our> declaration.
3985 In this way C<our> differs from C<use vars>, which is package-scoped.
3986
3987 Unlike C<my> or C<state>, which allocates storage for a variable and
3988 associates a simple name with that storage for use within the current
3989 scope, C<our> associates a simple name with a package (read: global)
3990 variable in the current package, for use within the current lexical scope.
3991 In other words, C<our> has the same scoping rules as C<my> or C<state>, but
3992 does not necessarily create a variable.
3993
3994 If more than one value is listed, the list must be placed
3995 in parentheses.
3996
3997     our $foo;
3998     our($bar, $baz);
3999
4000 An C<our> declaration declares a global variable that will be visible
4001 across its entire lexical scope, even across package boundaries.  The
4002 package in which the variable is entered is determined at the point
4003 of the declaration, not at the point of use.  This means the following
4004 behavior holds:
4005
4006     package Foo;
4007     our $bar;      # declares $Foo::bar for rest of lexical scope
4008     $bar = 20;
4009
4010     package Bar;
4011     print $bar;    # prints 20, as it refers to $Foo::bar
4012
4013 Multiple C<our> declarations with the same name in the same lexical
4014 scope are allowed if they are in different packages.  If they happen
4015 to be in the same package, Perl will emit warnings if you have asked
4016 for them, just like multiple C<my> declarations.  Unlike a second
4017 C<my> declaration, which will bind the name to a fresh variable, a
4018 second C<our> declaration in the same package, in the same scope, is
4019 merely redundant.
4020
4021     use warnings;
4022     package Foo;
4023     our $bar;      # declares $Foo::bar for rest of lexical scope
4024     $bar = 20;
4025
4026     package Bar;
4027     our $bar = 30; # declares $Bar::bar for rest of lexical scope
4028     print $bar;    # prints 30
4029
4030     our $bar;      # emits warning but has no other effect
4031     print $bar;    # still prints 30
4032
4033 An C<our> declaration may also have a list of attributes associated
4034 with it.
4035
4036 The exact semantics and interface of TYPE and ATTRS are still
4037 evolving.  TYPE is currently bound to the use of the C<fields> pragma,
4038 and attributes are handled using the C<attributes> pragma, or, starting
4039 from Perl 5.8.0, also via the C<Attribute::Handlers> module.  See
4040 L<perlsub/"Private Variables via my()"> for details, and L<fields>,
4041 L<attributes>, and L<Attribute::Handlers>.
4042
4043 =item pack TEMPLATE,LIST
4044 X<pack>
4045
4046 Takes a LIST of values and converts it into a string using the rules
4047 given by the TEMPLATE.  The resulting string is the concatenation of
4048 the converted values.  Typically, each converted value looks
4049 like its machine-level representation.  For example, on 32-bit machines
4050 an integer may be represented by a sequence of 4 bytes, which  will in
4051 Perl be presented as a string that's 4 characters long. 
4052
4053 See L<perlpacktut> for an introduction to this function.
4054
4055 The TEMPLATE is a sequence of characters that give the order and type
4056 of values, as follows:
4057
4058     a  A string with arbitrary binary data, will be null padded.
4059     A  A text (ASCII) string, will be space padded.
4060     Z  A null-terminated (ASCIZ) string, will be null padded.
4061
4062     b  A bit string (ascending bit order inside each byte,
4063        like vec()).
4064     B  A bit string (descending bit order inside each byte).
4065     h  A hex string (low nybble first).
4066     H  A hex string (high nybble first).
4067
4068     c  A signed char (8-bit) value.
4069     C  An unsigned char (octet) value.
4070     W  An unsigned char value (can be greater than 255).
4071
4072     s  A signed short (16-bit) value.
4073     S  An unsigned short value.
4074
4075     l  A signed long (32-bit) value.
4076     L  An unsigned long value.
4077
4078     q  A signed quad (64-bit) value.
4079     Q  An unsigned quad value.
4080          (Quads are available only if your system supports 64-bit
4081           integer values _and_ if Perl has been compiled to support
4082           those.  Raises an exception otherwise.)
4083
4084     i  A signed integer value.
4085     I  A unsigned integer value.
4086          (This 'integer' is _at_least_ 32 bits wide.  Its exact
4087           size depends on what a local C compiler calls 'int'.)
4088
4089     n  An unsigned short (16-bit) in "network" (big-endian) order.
4090     N  An unsigned long (32-bit) in "network" (big-endian) order.
4091     v  An unsigned short (16-bit) in "VAX" (little-endian) order.
4092     V  An unsigned long (32-bit) in "VAX" (little-endian) order.
4093
4094     j  A Perl internal signed integer value (IV).
4095     J  A Perl internal unsigned integer value (UV).
4096
4097     f  A single-precision float in native format.
4098     d  A double-precision float in native format.
4099
4100     F  A Perl internal floating-point value (NV) in native format
4101     D  A float of long-double precision in native format.
4102          (Long doubles are available only if your system supports
4103           long double values _and_ if Perl has been compiled to
4104           support those.  Raises an exception otherwise.)
4105
4106     p  A pointer to a null-terminated string.
4107     P  A pointer to a structure (fixed-length string).
4108
4109     u  A uuencoded string.
4110     U  A Unicode character number.  Encodes to a character in char-
4111        acter mode and UTF-8 (or UTF-EBCDIC in EBCDIC platforms) in
4112        byte mode.
4113
4114     w  A BER compressed integer (not an ASN.1 BER, see perlpacktut
4115        for details).  Its bytes represent an unsigned integer in
4116        base 128, most significant digit first, with as few digits
4117        as possible.  Bit eight (the high bit) is set on each byte
4118        except the last.
4119
4120     x  A null byte (a.k.a ASCII NUL, "\000", chr(0))
4121     X  Back up a byte.
4122     @  Null-fill or truncate to absolute position, counted from the
4123        start of the innermost ()-group.
4124     .  Null-fill or truncate to absolute position specified by
4125        the value.
4126     (  Start of a ()-group.
4127
4128 One or more modifiers below may optionally follow certain letters in the
4129 TEMPLATE (the second column lists letters for which the modifier is valid):
4130
4131     !   sSlLiI     Forces native (short, long, int) sizes instead
4132                    of fixed (16-/32-bit) sizes.
4133
4134         xX         Make x and X act as alignment commands.
4135
4136         nNvV       Treat integers as signed instead of unsigned.
4137
4138         @.         Specify position as byte offset in the internal
4139                    representation of the packed string.  Efficient
4140                    but dangerous.
4141
4142     >   sSiIlLqQ   Force big-endian byte-order on the type.
4143         jJfFdDpP   (The "big end" touches the construct.)
4144
4145     <   sSiIlLqQ   Force little-endian byte-order on the type.
4146         jJfFdDpP   (The "little end" touches the construct.)
4147
4148 The C<< > >> and C<< < >> modifiers can also be used on C<()> groups 
4149 to force a particular byte-order on all components in that group, 
4150 including all its subgroups.
4151
4152 The following rules apply:
4153
4154 =over 
4155
4156 =item *
4157
4158 Each letter may optionally be followed by a number indicating the repeat
4159 count.  A numeric repeat count may optionally be enclosed in brackets, as
4160 in C<pack("C[80]", @arr)>.  The repeat count gobbles that many values from
4161 the LIST when used with all format types other than C<a>, C<A>, C<Z>, C<b>,
4162 C<B>, C<h>, C<H>, C<@>, C<.>, C<x>, C<X>, and C<P>, where it means
4163 something else, described below.  Supplying a C<*> for the repeat count
4164 instead of a number means to use however many items are left, except for:
4165
4166 =over 
4167
4168 =item * 
4169
4170 C<@>, C<x>, and C<X>, where it is equivalent to C<0>.
4171
4172 =item * 
4173
4174 <.>, where it means relative to the start of the string.
4175
4176 =item * 
4177
4178 C<u>, where it is equivalent to 1 (or 45, which here is equivalent).
4179
4180 =back 
4181
4182 One can replace a numeric repeat count with a template letter enclosed in
4183 brackets to use the packed byte length of the bracketed template for the
4184 repeat count.
4185
4186 For example, the template C<x[L]> skips as many bytes as in a packed long,
4187 and the template C<"$t X[$t] $t"> unpacks twice whatever $t (when
4188 variable-expanded) unpacks.  If the template in brackets contains alignment
4189 commands (such as C<x![d]>), its packed length is calculated as if the
4190 start of the template had the maximal possible alignment.
4191
4192 When used with C<Z>, a C<*> as the repeat count is guaranteed to add a
4193 trailing null byte, so the resulting string is always one byte longer than
4194 the byte length of the item itself.
4195
4196 When used with C<@>, the repeat count represents an offset from the start
4197 of the innermost C<()> group.
4198
4199 When used with C<.>, the repeat count determines the starting position to
4200 calculate the value offset as follows:
4201
4202 =over 
4203
4204 =item *
4205
4206 If the repeat count is C<0>, it's relative to the current position.
4207
4208 =item *
4209
4210 If the repeat count is C<*>, the offset is relative to the start of the
4211 packed string.
4212
4213 =item *
4214
4215 And if it's an integer I<n>, the offset is relative to the start of the
4216 I<n>th innermost C<( )> group, or to the start of the string if I<n> is
4217 bigger then the group level.
4218
4219 =back
4220
4221 The repeat count for C<u> is interpreted as the maximal number of bytes
4222 to encode per line of output, with 0, 1 and 2 replaced by 45.  The repeat 
4223 count should not be more than 65.
4224
4225 =item *
4226
4227 The C<a>, C<A>, and C<Z> types gobble just one value, but pack it as a
4228 string of length count, padding with nulls or spaces as needed.  When
4229 unpacking, C<A> strips trailing whitespace and nulls, C<Z> strips everything
4230 after the first null, and C<a> returns data with no stripping at all.
4231
4232 If the value to pack is too long, the result is truncated.  If it's too
4233 long and an explicit count is provided, C<Z> packs only C<$count-1> bytes,
4234 followed by a null byte.  Thus C<Z> always packs a trailing null, except
4235 when the count is 0.
4236
4237 =item *
4238
4239 Likewise, the C<b> and C<B> formats pack a string that's that many bits long.
4240 Each such format generates 1 bit of the result.  These are typically followed
4241 by a repeat count like C<B8> or C<B64>.
4242
4243 Each result bit is based on the least-significant bit of the corresponding
4244 input character, i.e., on C<ord($char)%2>.  In particular, characters C<"0">
4245 and C<"1"> generate bits 0 and 1, as do characters C<"\000"> and C<"\001">.
4246
4247 Starting from the beginning of the input string, each 8-tuple
4248 of characters is converted to 1 character of output.  With format C<b>,
4249 the first character of the 8-tuple determines the least-significant bit of a
4250 character; with format C<B>, it determines the most-significant bit of
4251 a character.
4252
4253 If the length of the input string is not evenly divisible by 8, the
4254 remainder is packed as if the input string were padded by null characters
4255 at the end.  Similarly during unpacking, "extra" bits are ignored.
4256
4257 If the input string is longer than needed, remaining characters are ignored.
4258
4259 A C<*> for the repeat count uses all characters of the input field.  
4260 On unpacking, bits are converted to a string of C<0>s and C<1>s.
4261
4262 =item *
4263
4264 The C<h> and C<H> formats pack a string that many nybbles (4-bit groups,
4265 representable as hexadecimal digits, C<"0".."9"> C<"a".."f">) long.
4266
4267 For each such format, pack() generates 4 bits of result.
4268 With non-alphabetical characters, the result is based on the 4 least-significant
4269 bits of the input character, i.e., on C<ord($char)%16>.  In particular,
4270 characters C<"0"> and C<"1"> generate nybbles 0 and 1, as do bytes
4271 C<"\000"> and C<"\001">.  For characters C<"a".."f"> and C<"A".."F">, the result
4272 is compatible with the usual hexadecimal digits, so that C<"a"> and
4273 C<"A"> both generate the nybble C<0xA==10>.  Use only these specific hex 
4274 characters with this format.
4275
4276 Starting from the beginning of the template to pack(), each pair
4277 of characters is converted to 1 character of output.  With format C<h>, the
4278 first character of the pair determines the least-significant nybble of the
4279 output character; with format C<H>, it determines the most-significant
4280 nybble.
4281
4282 If the length of the input string is not even, it behaves as if padded by
4283 a null character at the end.  Similarly, "extra" nybbles are ignored during
4284 unpacking.
4285
4286 If the input string is longer than needed, extra characters are ignored.
4287
4288 A C<*> for the repeat count uses all characters of the input field.  For
4289 unpack(), nybbles are converted to a string of hexadecimal digits.
4290
4291 =item *
4292
4293 The C<p> format packs a pointer to a null-terminated string.  You are
4294 responsible for ensuring that the string is not a temporary value, as that
4295 could potentially get deallocated before you got around to using the packed
4296 result.  The C<P> format packs a pointer to a structure of the size indicated
4297 by the length.  A null pointer is created if the corresponding value for
4298 C<p> or C<P> is C<undef>; similarly with unpack(), where a null pointer
4299 unpacks into C<undef>.
4300
4301 If your system has a strange pointer size--meaning a pointer is neither as
4302 big as an int nor as big as a long--it may not be possible to pack or
4303 unpack pointers in big- or little-endian byte order.  Attempting to do
4304 so raises an exception.
4305
4306 =item *
4307
4308 The C</> template character allows packing and unpacking of a sequence of
4309 items where the packed structure contains a packed item count followed by
4310 the packed items themselves.  This is useful when the structure you're
4311 unpacking has encoded the sizes or repeat counts for some of its fields
4312 within the structure itself as separate fields.
4313
4314 For C<pack>, you write I<length-item>C</>I<sequence-item>, and the
4315 I<length-item> describes how the length value is packed.  Formats likely
4316 to be of most use are integer-packing ones like C<n> for Java strings,
4317 C<w> for ASN.1 or SNMP, and C<N> for Sun XDR.
4318
4319 For C<pack>, I<sequence-item> may have a repeat count, in which case
4320 the minimum of that and the number of available items is used as the argument
4321 for I<length-item>.  If it has no repeat count or uses a '*', the number
4322 of available items is used.
4323
4324 For C<unpack>, an internal stack of integer arguments unpacked so far is
4325 used.  You write C</>I<sequence-item> and the repeat count is obtained by
4326 popping off the last element from the stack.  The I<sequence-item> must not
4327 have a repeat count.
4328
4329 If I<sequence-item> refers to a string type (C<"A">, C<"a">, or C<"Z">),
4330 the I<length-item> is the string length, not the number of strings.  With
4331 an explicit repeat count for pack, the packed string is adjusted to that
4332 length.  For example:
4333
4334  This code:                              gives this result:
4335  
4336   unpack("W/a", "\004Gurusamy")          ("Guru")
4337   unpack("a3/A A*", "007 Bond  J ")      (" Bond", "J")
4338   unpack("a3 x2 /A A*", "007: Bond, J.") ("Bond, J", ".")
4339
4340   pack("n/a* w/a","hello,","world")     "\000\006hello,\005world"
4341   pack("a/W2", ord("a") .. ord("z"))    "2ab"
4342
4343 The I<length-item> is not returned explicitly from C<unpack>.
4344
4345 Supplying a count to the I<length-item> format letter is only useful with
4346 C<A>, C<a>, or C<Z>.  Packing with a I<length-item> of C<a> or C<Z> may
4347 introduce C<"\000"> characters, which Perl does not regard as legal in
4348 numeric strings.
4349
4350 =item *
4351
4352 The integer types C<s>, C<S>, C<l>, and C<L> may be
4353 followed by a C<!> modifier to specify native shorts or
4354 longs.  As shown in the example above, a bare C<l> means
4355 exactly 32 bits, although the native C<long> as seen by the local C compiler
4356 may be larger.  This is mainly an issue on 64-bit platforms.  You can
4357 see whether using C<!> makes any difference this way:
4358
4359     printf "format s is %d, s! is %d\n", 
4360         length pack("s"), length pack("s!");
4361
4362     printf "format l is %d, l! is %d\n", 
4363         length pack("l"), length pack("l!");
4364
4365
4366 C<i!> and C<I!> are also allowed, but only for completeness' sake:
4367 they are identical to C<i> and C<I>.
4368
4369 The actual sizes (in bytes) of native shorts, ints, longs, and long
4370 longs on the platform where Perl was built are also available from
4371 the command line:
4372
4373     $ perl -V:{short,int,long{,long}}size
4374     shortsize='2';
4375     intsize='4';
4376     longsize='4';
4377     longlongsize='8';
4378
4379 or programmatically via the C<Config> module:
4380
4381        use Config;
4382        print $Config{shortsize},    "\n";
4383        print $Config{intsize},      "\n";
4384        print $Config{longsize},     "\n";
4385        print $Config{longlongsize}, "\n";
4386
4387 C<$Config{longlongsize}> is undefined on systems without 
4388 long long support.
4389
4390 =item *
4391
4392 The integer formats C<s>, C<S>, C<i>, C<I>, C<l>, C<L>, C<j>, and C<J> are
4393 inherently non-portable between processors and operating systems because
4394 they obey native byteorder and endianness.  For example, a 4-byte integer
4395 0x12345678 (305419896 decimal) would be ordered natively (arranged in and
4396 handled by the CPU registers) into bytes as
4397
4398     0x12 0x34 0x56 0x78  # big-endian
4399     0x78 0x56 0x34 0x12  # little-endian
4400
4401 Basically, Intel and VAX CPUs are little-endian, while everybody else,
4402 including Motorola m68k/88k, PPC, Sparc, HP PA, Power, and Cray, are
4403 big-endian.  Alpha and MIPS can be either: Digital/Compaq uses (well, used) 
4404 them in little-endian mode, but SGI/Cray uses them in big-endian mode.
4405
4406 The names I<big-endian> and I<little-endian> are comic references to the
4407 egg-eating habits of the little-endian Lilliputians and the big-endian
4408 Blefuscudians from the classic Jonathan Swift satire, I<Gulliver's Travels>.
4409 This entered computer lingo via the paper "On Holy Wars and a Plea for
4410 Peace" by Danny Cohen, USC/ISI IEN 137, April 1, 1980.
4411
4412 Some systems may have even weirder byte orders such as
4413
4414    0x56 0x78 0x12 0x34
4415    0x34 0x12 0x78 0x56
4416
4417 You can determine your system endianness with this incantation:
4418
4419    printf("%#02x ", $_) for unpack("W*", pack L=>0x12345678); 
4420
4421 The byteorder on the platform where Perl was built is also available
4422 via L<Config>:
4423
4424     use Config;
4425     print "$Config{byteorder}\n";
4426
4427 or from the command line:
4428
4429     $ perl -V:byteorder
4430
4431 Byteorders C<"1234"> and C<"12345678"> are little-endian; C<"4321">
4432 and C<"87654321"> are big-endian.
4433
4434 For portably packed integers, either use the formats C<n>, C<N>, C<v>, 
4435 and C<V> or else use the C<< > >> and C<< < >> modifiers described
4436 immediately below.  See also L<perlport>.
4437
4438 =item *
4439
4440 Starting with Perl 5.9.2, integer and floating-point formats, along with
4441 the C<p> and C<P> formats and C<()> groups, may all be followed by the 
4442 C<< > >> or C<< < >> endianness modifiers to respectively enforce big-
4443 or little-endian byte-order.  These modifiers are especially useful 
4444 given how C<n>, C<N>, C<v>, and C<V> don't cover signed integers, 
4445 64-bit integers, or floating-point values.
4446
4447 Here are some concerns to keep in mind when using an endianness modifier:
4448
4449 =over
4450
4451 =item * 
4452
4453 Exchanging signed integers between different platforms works only 
4454 when all platforms store them in the same format.  Most platforms store
4455 signed integers in two's-complement notation, so usually this is not an issue.
4456
4457 =item * 
4458
4459 The C<< > >> or C<< < >> modifiers can only be used on floating-point
4460 formats on big- or little-endian machines.  Otherwise, attempting to
4461 use them raises an exception.
4462
4463 =item * 
4464
4465 Forcing big- or little-endian byte-order on floating-point values for
4466 data exchange can work only if all platforms use the same
4467 binary representation such as IEEE floating-point.  Even if all
4468 platforms are using IEEE, there may still be subtle differences.  Being able
4469 to use C<< > >> or C<< < >> on floating-point values can be useful,
4470 but also dangerous if you don't know exactly what you're doing.
4471 It is not a general way to portably store floating-point values.
4472
4473 =item * 
4474
4475 When using C<< > >> or C<< < >> on a C<()> group, this affects
4476 all types inside the group that accept byte-order modifiers,
4477 including all subgroups.  It is silently ignored for all other
4478 types.  You are not allowed to override the byte-order within a group
4479 that already has a byte-order modifier suffix.
4480
4481 =back
4482
4483 =item *
4484
4485 Real numbers (floats and doubles) are in native machine format only.
4486 Due to the multiplicity of floating-point formats and the lack of a
4487 standard "network" representation for them, no facility for interchange has been
4488 made.  This means that packed floating-point data written on one machine
4489 may not be readable on another, even if both use IEEE floating-point
4490 arithmetic (because the endianness of the memory representation is not part
4491 of the IEEE spec).  See also L<perlport>.
4492
4493 If you know I<exactly> what you're doing, you can use the C<< > >> or C<< < >>
4494 modifiers to force big- or little-endian byte-order on floating-point values.
4495
4496 Because Perl uses doubles (or long doubles, if configured) internally for
4497 all numeric calculation, converting from double into float and thence 
4498 to double again loses precision, so C<unpack("f", pack("f", $foo)>)
4499 will not in general equal $foo.
4500
4501 =item *
4502
4503 Pack and unpack can operate in two modes: character mode (C<C0> mode) where
4504 the packed string is processed per character, and UTF-8 mode (C<U0> mode)
4505 where the packed string is processed in its UTF-8-encoded Unicode form on
4506 a byte-by-byte basis.  Character mode is the default
4507 unless the format string starts with C<U>.  You
4508 can always switch mode mid-format with an explicit 
4509 C<C0> or C<U0> in the format.  This mode remains in effect until the next 
4510 mode change, or until the end of the C<()> group it (directly) applies to.
4511
4512 Using C<C0> to get Unicode characters while using C<U0> to get I<non>-Unicode 
4513 bytes is not necessarily obvious.   Probably only the first of these
4514 is what you want:
4515
4516     $ perl -CS -E 'say "\x{3B1}\x{3C9}"' | 
4517       perl -CS -ne 'printf "%v04X\n", $_ for unpack("C0A*", $_)'
4518     03B1.03C9
4519     $ perl -CS -E 'say "\x{3B1}\x{3C9}"' | 
4520       perl -CS -ne 'printf "%v02X\n", $_ for unpack("U0A*", $_)'
4521     CE.B1.CF.89
4522     $ perl -CS -E 'say "\x{3B1}\x{3C9}"' | 
4523       perl -C0 -ne 'printf "%v02X\n", $_ for unpack("C0A*", $_)'
4524     CE.B1.CF.89
4525     $ perl -CS -E 'say "\x{3B1}\x{3C9}"' | 
4526       perl -C0 -ne 'printf "%v02X\n", $_ for unpack("U0A*", $_)'
4527     C3.8E.C2.B1.C3.8F.C2.89
4528
4529 Those examples also illustrate that you should not try to use
4530 C<pack>/C<unpack> as a substitute for the L<Encode> module.
4531
4532 =item *
4533
4534 You must yourself do any alignment or padding by inserting, for example,
4535 enough C<"x">es while packing.  There is no way for pack() and unpack()
4536 to know where characters are going to or coming from, so they 
4537 handle their output and input as flat sequences of characters.
4538
4539 =item *
4540
4541 A C<()> group is a sub-TEMPLATE enclosed in parentheses.  A group may
4542 take a repeat count either as postfix, or for unpack(), also via the C</>
4543 template character.  Within each repetition of a group, positioning with
4544 C<@> starts over at 0.  Therefore, the result of
4545
4546     pack("@1A((@2A)@3A)", qw[X Y Z])
4547
4548 is the string C<"\0X\0\0YZ">.
4549
4550 =item *
4551
4552 C<x> and C<X> accept the C<!> modifier to act as alignment commands: they
4553 jump forward or back to the closest position aligned at a multiple of C<count>
4554 characters.  For example, to pack() or unpack() a C structure like
4555
4556     struct {
4557         char   c;    /* one signed, 8-bit character */
4558         double d; 
4559         char   cc[2];
4560     }
4561
4562 one may need to use the template C<c x![d] d c[2]>.  This assumes that
4563 doubles must be aligned to the size of double.
4564
4565 For alignment commands, a C<count> of 0 is equivalent to a C<count> of 1;
4566 both are no-ops.
4567
4568 =item *
4569
4570 C<n>, C<N>, C<v> and C<V> accept the C<!> modifier to
4571 represent signed 16-/32-bit integers in big-/little-endian order.
4572 This is portable only when all platforms sharing packed data use the
4573 same binary representation for signed integers; for example, when all
4574 platforms use two's-complement representation.
4575
4576 =item *
4577
4578 Comments can be embedded in a TEMPLATE using C<#> through the end of line.
4579 White space can separate pack codes from each other, but modifiers and
4580 repeat counts must follow immediately.  Breaking complex templates into
4581 individual line-by-line components, suitably annotated, can do as much to
4582 improve legibility and maintainability of pack/unpack formats as C</x> can
4583 for complicated pattern matches.
4584
4585 =item *
4586
4587 If TEMPLATE requires more arguments than pack() is given, pack()
4588 assumes additional C<""> arguments.  If TEMPLATE requires fewer arguments
4589 than given, extra arguments are ignored.
4590
4591 =back
4592
4593 Examples:
4594
4595     $foo = pack("WWWW",65,66,67,68);
4596     # foo eq "ABCD"
4597     $foo = pack("W4",65,66,67,68);
4598     # same thing
4599     $foo = pack("W4",0x24b6,0x24b7,0x24b8,0x24b9);
4600     # same thing with Unicode circled letters.
4601     $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9);
4602     # same thing with Unicode circled letters.  You don't get the
4603     # UTF-8 bytes because the U at the start of the format caused
4604     # a switch to U0-mode, so the UTF-8 bytes get joined into
4605     # characters
4606     $foo = pack("C0U4",0x24b6,0x24b7,0x24b8,0x24b9);
4607     # foo eq "\xe2\x92\xb6\xe2\x92\xb7\xe2\x92\xb8\xe2\x92\xb9"
4608     # This is the UTF-8 encoding of the string in the
4609     # previous example
4610
4611     $foo = pack("ccxxcc",65,66,67,68);
4612     # foo eq "AB\0\0CD"
4613
4614     # NOTE: The examples above featuring "W" and "c" are true
4615     # only on ASCII and ASCII-derived systems such as ISO Latin 1
4616     # and UTF-8.  On EBCDIC systems, the first example would be
4617     #      $foo = pack("WWWW",193,194,195,196);
4618
4619     $foo = pack("s2",1,2);
4620     # "\001\000\002\000" on little-endian
4621     # "\000\001\000\002" on big-endian
4622
4623     $foo = pack("a4","abcd","x","y","z");
4624     # "abcd"
4625
4626     $foo = pack("aaaa","abcd","x","y","z");
4627     # "axyz"
4628
4629     $foo = pack("a14","abcdefg");
4630     # "abcdefg\0\0\0\0\0\0\0"
4631
4632     $foo = pack("i9pl", gmtime);
4633     # a real struct tm (on my system anyway)
4634
4635     $utmp_template = "Z8 Z8 Z16 L";
4636     $utmp = pack($utmp_template, @utmp1);
4637     # a struct utmp (BSDish)
4638
4639     @utmp2 = unpack($utmp_template, $utmp);
4640     # "@utmp1" eq "@utmp2"
4641
4642     sub bintodec {
4643         unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
4644     }
4645
4646     $foo = pack('sx2l', 12, 34);
4647     # short 12, two zero bytes padding, long 34
4648     $bar = pack('s@4l', 12, 34);
4649     # short 12, zero fill to position 4, long 34
4650     # $foo eq $bar
4651     $baz = pack('s.l', 12, 4, 34);
4652     # short 12, zero fill to position 4, long 34
4653
4654     $foo = pack('nN', 42, 4711);
4655     # pack big-endian 16- and 32-bit unsigned integers
4656     $foo = pack('S>L>', 42, 4711);
4657     # exactly the same
4658     $foo = pack('s<l<', -42, 4711);
4659     # pack little-endian 16- and 32-bit signed integers
4660     $foo = pack('(sl)<', -42, 4711);
4661     # exactly the same
4662
4663 The same template may generally also be used in unpack().
4664
4665 =item package NAMESPACE
4666
4667 =item package NAMESPACE VERSION
4668 X<package> X<module> X<namespace> X<version>
4669
4670 =item package NAMESPACE BLOCK
4671
4672 =item package NAMESPACE VERSION BLOCK
4673 X<package> X<module> X<namespace> X<version>
4674
4675 Declares the BLOCK or the rest of the compilation unit as being in the