1PERLFUNC(1)            Perl Programmers Reference Guide            PERLFUNC(1)
2
3
4

NAME

6       perlfunc - Perl builtin functions
7

DESCRIPTION

9       The functions in this section can serve as terms in an expression.
10       They fall into two major categories: list operators and named unary
11       operators.  These differ in their precedence relationship with a
12       following comma.  (See the precedence table in perlop.)  List operators
13       take more than one argument, while unary operators can never take more
14       than one argument.  Thus, a comma terminates the argument of a unary
15       operator, but merely separates the arguments of a list operator.  A
16       unary operator generally provides scalar context to its argument, while
17       a list operator may provide either scalar or list contexts for its
18       arguments.  If it does both, scalar arguments come first and list
19       argument follow, and there can only ever be one such list argument.
20       For instance, "splice" has three scalar arguments followed by a list,
21       whereas "gethostbyname" has four scalar 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 with
25       LIST as an argument.  Such a list may consist of any combination of
26       scalar arguments or list values; the list values will be included in
27       the list as if each individual element were interpolated at that point
28       in the list, forming a longer single-dimensional list value.  Commas
29       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 looks like a function, therefore it 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 "use warnings" pragma, it can warn you about
47       this.  For 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 "time" and
54       "endpwent".  For example, "time+86_400" always means "time() + 86_400".
55
56       For functions that can be used in either a scalar or list context,
57       nonabortive failure is generally indicated in scalar context by
58       returning the undefined value, and in list context by returning the
59       empty list.
60
61       Remember the following important rule: There is no rule that relates
62       the behavior of an expression in list context to its behavior in scalar
63       context, or vice versa.  It might do two totally different things.
64       Each operator and function decides which sort of value would be most
65       appropriate to return in scalar context.  Some operators return the
66       length of the list that would have been returned in list context.  Some
67       operators return the first value in the list.  Some operators return
68       the last value in the list.  Some operators return a count of
69       successful operations.  In general, they do what you want, unless you
70       want consistency.
71
72       A named array in scalar context is quite different from what would at
73       first glance appear to be a list in scalar context.  You can't get a
74       list like "(1,2,3)" into being in scalar context, because the compiler
75       knows the context at compile time.  It would generate the scalar comma
76       operator there, not the list concatenation version of the comma.  That
77       means it was never a list to start with.
78
79       In general, functions in Perl that serve as wrappers for system calls
80       ("syscalls") of the same name (like chown(2), fork(2), closedir(2),
81       etc.) return true when they succeed and "undef" otherwise, as is
82       usually mentioned in the descriptions below.  This is different from
83       the C interfaces, which return "-1" on failure.  Exceptions to this
84       rule include "wait", "waitpid", and "syscall".  System calls also set
85       the special $! variable on failure.  Other functions do not, except
86       accidentally.
87
88       Extension modules can also hook into the Perl parser to define new
89       kinds of keyword-headed expression.  These may look like functions, but
90       may also look completely different.  The syntax following the keyword
91       is defined entirely by the extension.  If you are an implementor, see
92       "PL_keyword_plugin" in perlapi for the mechanism.  If you are using
93       such a module, see the module's documentation for details of the syntax
94       that it defines.
95
96   Perl Functions by Category
97       Here are Perl's functions (including things that look like functions,
98       like some keywords and named operators) arranged by category.  Some
99       functions appear in more than one place.
100
101       Functions for SCALARs or strings
102           "chomp", "chop", "chr", "crypt", "fc", "hex", "index", "lc",
103           "lcfirst", "length", "oct", "ord", "pack", "q//", "qq//",
104           "reverse", "rindex", "sprintf", "substr", "tr///", "uc", "ucfirst",
105           "y///"
106
107           "fc" is available only if the "fc" feature is enabled or if it is
108           prefixed with "CORE::".  The "fc" feature is enabled automatically
109           with a "use v5.16" (or higher) declaration in the current scope.
110
111       Regular expressions and pattern matching
112           "m//", "pos", "qr//", "quotemeta", "s///", "split", "study"
113
114       Numeric functions
115           "abs", "atan2", "cos", "exp", "hex", "int", "log", "oct", "rand",
116           "sin", "sqrt", "srand"
117
118       Functions for real @ARRAYs
119           "each", "keys", "pop", "push", "shift", "splice", "unshift",
120           "values"
121
122       Functions for list data
123           "grep", "join", "map", "qw//", "reverse", "sort", "unpack"
124
125       Functions for real %HASHes
126           "delete", "each", "exists", "keys", "values"
127
128       Input and output functions
129           "binmode", "close", "closedir", "dbmclose", "dbmopen", "die",
130           "eof", "fileno", "flock", "format", "getc", "print", "printf",
131           "read", "readdir", "readline", "rewinddir", "say", "seek",
132           "seekdir", "select", "syscall", "sysread", "sysseek", "syswrite",
133           "tell", "telldir", "truncate", "warn", "write"
134
135           "say" is available only if the "say" feature is enabled or if it is
136           prefixed with "CORE::".  The "say" feature is enabled automatically
137           with a "use v5.10" (or higher) declaration in the current scope.
138
139       Functions for fixed-length data or records
140           "pack", "read", "syscall", "sysread", "sysseek", "syswrite",
141           "unpack", "vec"
142
143       Functions for filehandles, files, or directories
144           "-X", "chdir", "chmod", "chown", "chroot", "fcntl", "glob",
145           "ioctl", "link", "lstat", "mkdir", "open", "opendir", "readlink",
146           "rename", "rmdir", "select", "stat", "symlink", "sysopen", "umask",
147           "unlink", "utime"
148
149       Keywords related to the control flow of your Perl program
150           "break", "caller", "continue", "die", "do", "dump", "eval",
151           "evalbytes", "exit", "__FILE__", "goto", "last", "__LINE__",
152           "next", "__PACKAGE__", "redo", "return", "sub", "__SUB__",
153           "wantarray"
154
155           "break" is available only if you enable the experimental "switch"
156           feature or use the "CORE::" prefix.  The "switch" feature also
157           enables the "default", "given" and "when" statements, which are
158           documented in "Switch Statements" in perlsyn.  The "switch" feature
159           is enabled automatically with a "use v5.10" (or higher) declaration
160           in the current scope.  In Perl v5.14 and earlier, "continue"
161           required the "switch" feature, like the other keywords.
162
163           "evalbytes" is only available with the "evalbytes" feature (see
164           feature) or if prefixed with "CORE::".  "__SUB__" is only available
165           with the "current_sub" feature or if prefixed with "CORE::".  Both
166           the "evalbytes" and "current_sub" features are enabled
167           automatically with a "use v5.16" (or higher) declaration in the
168           current scope.
169
170       Keywords related to scoping
171           "caller", "import", "local", "my", "our", "package", "state", "use"
172
173           "state" is available only if the "state" feature is enabled or if
174           it is prefixed with "CORE::".  The "state" feature is enabled
175           automatically with a "use v5.10" (or higher) declaration in the
176           current scope.
177
178       Miscellaneous functions
179           "defined", "formline", "lock", "prototype", "reset", "scalar",
180           "undef"
181
182       Functions for processes and process groups
183           "alarm", "exec", "fork", "getpgrp", "getppid", "getpriority",
184           "kill", "pipe", "qx//", "readpipe", "setpgrp", "setpriority",
185           "sleep", "system", "times", "wait", "waitpid"
186
187       Keywords related to Perl modules
188           "do", "import", "no", "package", "require", "use"
189
190       Keywords related to classes and object-orientation
191           "bless", "dbmclose", "dbmopen", "package", "ref", "tie", "tied",
192           "untie", "use"
193
194       Low-level socket functions
195           "accept", "bind", "connect", "getpeername", "getsockname",
196           "getsockopt", "listen", "recv", "send", "setsockopt", "shutdown",
197           "socket", "socketpair"
198
199       System V interprocess communication functions
200           "msgctl", "msgget", "msgrcv", "msgsnd", "semctl", "semget",
201           "semop", "shmctl", "shmget", "shmread", "shmwrite"
202
203       Fetching user and group info
204           "endgrent", "endhostent", "endnetent", "endpwent", "getgrent",
205           "getgrgid", "getgrnam", "getlogin", "getpwent", "getpwnam",
206           "getpwuid", "setgrent", "setpwent"
207
208       Fetching network info
209           "endprotoent", "endservent", "gethostbyaddr", "gethostbyname",
210           "gethostent", "getnetbyaddr", "getnetbyname", "getnetent",
211           "getprotobyname", "getprotobynumber", "getprotoent",
212           "getservbyname", "getservbyport", "getservent", "sethostent",
213           "setnetent", "setprotoent", "setservent"
214
215       Time-related functions
216           "gmtime", "localtime", "time", "times"
217
218       Non-function keywords
219           "and", "AUTOLOAD", "BEGIN", "CHECK", "cmp", "CORE", "__DATA__",
220           "default", "DESTROY", "else", "elseif", "elsif", "END", "__END__",
221           "eq", "for", "foreach", "ge", "given", "gt", "if", "INIT", "le",
222           "lt", "ne", "not", "or", "UNITCHECK", "unless", "until", "when",
223           "while", "x", "xor"
224
225   Portability
226       Perl was born in Unix and can therefore access all common Unix system
227       calls.  In non-Unix environments, the functionality of some Unix system
228       calls may not be available or details of the available functionality
229       may differ slightly.  The Perl functions affected by this are:
230
231       "-X", "binmode", "chmod", "chown", "chroot", "crypt", "dbmclose",
232       "dbmopen", "dump", "endgrent", "endhostent", "endnetent",
233       "endprotoent", "endpwent", "endservent", "exec", "fcntl", "flock",
234       "fork", "getgrent", "getgrgid", "gethostbyname", "gethostent",
235       "getlogin", "getnetbyaddr", "getnetbyname", "getnetent", "getppid",
236       "getpgrp", "getpriority", "getprotobynumber", "getprotoent",
237       "getpwent", "getpwnam", "getpwuid", "getservbyport", "getservent",
238       "getsockopt", "glob", "ioctl", "kill", "link", "lstat", "msgctl",
239       "msgget", "msgrcv", "msgsnd", "open", "pipe", "readlink", "rename",
240       "select", "semctl", "semget", "semop", "setgrent", "sethostent",
241       "setnetent", "setpgrp", "setpriority", "setprotoent", "setpwent",
242       "setservent", "setsockopt", "shmctl", "shmget", "shmread", "shmwrite",
243       "socket", "socketpair", "stat", "symlink", "syscall", "sysopen",
244       "system", "times", "truncate", "umask", "unlink", "utime", "wait",
245       "waitpid"
246
247       For more information about the portability of these functions, see
248       perlport and other available platform-specific documentation.
249
250   Alphabetical Listing of Perl Functions
251       -X FILEHANDLE
252       -X EXPR
253       -X DIRHANDLE
254       -X  A file test, where X is one of the letters listed below.  This
255           unary operator takes one argument, either a filename, a filehandle,
256           or a dirhandle, and tests the associated file to see if something
257           is true about it.  If the argument is omitted, tests $_, except for
258           "-t", which tests STDIN.  Unless otherwise documented, it returns 1
259           for true and '' for false.  If the file doesn't exist or can't be
260           examined, it returns "undef" and sets $! (errno).  Despite the
261           funny names, precedence is the same as any other named unary
262           operator.  The operator may be any of:
263
264               -r  File is readable by effective uid/gid.
265               -w  File is writable by effective uid/gid.
266               -x  File is executable by effective uid/gid.
267               -o  File is owned by effective uid.
268
269               -R  File is readable by real uid/gid.
270               -W  File is writable by real uid/gid.
271               -X  File is executable by real uid/gid.
272               -O  File is owned by real uid.
273
274               -e  File exists.
275               -z  File has zero size (is empty).
276               -s  File has nonzero size (returns size in bytes).
277
278               -f  File is a plain file.
279               -d  File is a directory.
280               -l  File is a symbolic link (false if symlinks aren't
281                   supported by the file system).
282               -p  File is a named pipe (FIFO), or Filehandle is a pipe.
283               -S  File is a socket.
284               -b  File is a block special file.
285               -c  File is a character special file.
286               -t  Filehandle is opened to a tty.
287
288               -u  File has setuid bit set.
289               -g  File has setgid bit set.
290               -k  File has sticky bit set.
291
292               -T  File is an ASCII or UTF-8 text file (heuristic guess).
293               -B  File is a "binary" file (opposite of -T).
294
295               -M  Script start time minus file modification time, in days.
296               -A  Same for access time.
297               -C  Same for inode change time (Unix, may differ for other
298                   platforms)
299
300           Example:
301
302               while (<>) {
303                   chomp;
304                   next unless -f $_;  # ignore specials
305                   #...
306               }
307
308           Note that "-s/a/b/" does not do a negated substitution.  Saying
309           "-exp($foo)" still works as expected, however: only single letters
310           following a minus are interpreted as file tests.
311
312           These operators are exempt from the "looks like a function rule"
313           described above.  That is, an opening parenthesis after the
314           operator does not affect how much of the following code constitutes
315           the argument.  Put the opening parentheses before the operator to
316           separate it from code that follows (this applies only to operators
317           with higher precedence than unary operators, of course):
318
319               -s($file) + 1024   # probably wrong; same as -s($file + 1024)
320               (-s $file) + 1024  # correct
321
322           The interpretation of the file permission operators "-r", "-R",
323           "-w", "-W", "-x", and "-X" is by default based solely on the mode
324           of the file and the uids and gids of the user.  There may be other
325           reasons you can't actually read, write, or execute the file: for
326           example network filesystem access controls, ACLs (access control
327           lists), read-only filesystems, and unrecognized executable formats.
328           Note that the use of these six specific operators to verify if some
329           operation is possible is usually a mistake, because it may be open
330           to race conditions.
331
332           Also note that, for the superuser on the local filesystems, the
333           "-r", "-R", "-w", and "-W" tests always return 1, and "-x" and "-X"
334           return 1 if any execute bit is set in the mode.  Scripts run by the
335           superuser may thus need to do a "stat" to determine the actual mode
336           of the file, or temporarily set their effective uid to something
337           else.
338
339           If you are using ACLs, there is a pragma called "filetest" that may
340           produce more accurate results than the bare "stat" mode bits.  When
341           under "use filetest 'access'", the above-mentioned filetests test
342           whether the permission can(not) be granted using the access(2)
343           family of system calls.  Also note that the "-x" and "-X" tests may
344           under this pragma return true even if there are no execute
345           permission bits set (nor any extra execute permission ACLs).  This
346           strangeness is due to the underlying system calls' definitions.
347           Note also that, due to the implementation of "use filetest
348           'access'", the "_" special filehandle won't cache the results of
349           the file tests when this pragma is in effect.  Read the
350           documentation for the "filetest" pragma for more information.
351
352           The "-T" and "-B" tests work as follows.  The first block or so of
353           the file is examined to see if it is valid UTF-8 that includes non-
354           ASCII characters.  If so, it's a "-T" file.  Otherwise, that same
355           portion of the file is examined for odd characters such as strange
356           control codes or characters with the high bit set.  If more than a
357           third of the characters are strange, it's a "-B" file; otherwise
358           it's a "-T" file.  Also, any file containing a zero byte in the
359           examined portion is considered a binary file.  (If executed within
360           the scope of a use locale which includes "LC_CTYPE", odd characters
361           are anything that isn't a printable nor space in the current
362           locale.)  If "-T" or "-B" is used on a filehandle, the current IO
363           buffer is examined rather than the first block.  Both "-T" and "-B"
364           return true on an empty file, or a file at EOF when testing a
365           filehandle.  Because you have to read a file to do the "-T" test,
366           on most occasions you want to use a "-f" against the file first, as
367           in "next unless -f $file && -T $file".
368
369           If any of the file tests (or either the "stat" or "lstat" operator)
370           is given the special filehandle consisting of a solitary underline,
371           then the stat structure of the previous file test (or "stat"
372           operator) is used, saving a system call.  (This doesn't work with
373           "-t", and you need to remember that "lstat" and "-l" leave values
374           in the stat structure for the symbolic link, not the real file.)
375           (Also, if the stat buffer was filled by an "lstat" call, "-T" and
376           "-B" will reset it with the results of "stat _").  Example:
377
378               print "Can do.\n" if -r $a || -w _ || -x _;
379
380               stat($filename);
381               print "Readable\n" if -r _;
382               print "Writable\n" if -w _;
383               print "Executable\n" if -x _;
384               print "Setuid\n" if -u _;
385               print "Setgid\n" if -g _;
386               print "Sticky\n" if -k _;
387               print "Text\n" if -T _;
388               print "Binary\n" if -B _;
389
390           As of Perl 5.10.0, as a form of purely syntactic sugar, you can
391           stack file test operators, in a way that "-f -w -x $file" is
392           equivalent to "-x $file && -w _ && -f _".  (This is only fancy
393           syntax: if you use the return value of "-f $file" as an argument to
394           another filetest operator, no special magic will happen.)
395
396           Portability issues: "-X" in perlport.
397
398           To avoid confusing would-be users of your code with mysterious
399           syntax errors, put something like this at the top of your script:
400
401               use 5.010;  # so filetest ops can stack
402
403       abs VALUE
404       abs Returns the absolute value of its argument.  If VALUE is omitted,
405           uses $_.
406
407       accept NEWSOCKET,GENERICSOCKET
408           Accepts an incoming socket connect, just as accept(2) does.
409           Returns the packed address if it succeeded, false otherwise.  See
410           the example in "Sockets: Client/Server Communication" in perlipc.
411
412           On systems that support a close-on-exec flag on files, the flag
413           will be set for the newly opened file descriptor, as determined by
414           the value of $^F.  See "$^F" in perlvar.
415
416       alarm SECONDS
417       alarm
418           Arranges to have a SIGALRM delivered to this process after the
419           specified number of wallclock seconds has elapsed.  If SECONDS is
420           not specified, the value stored in $_ is used.  (On some machines,
421           unfortunately, the elapsed time may be up to one second less or
422           more than you specified because of how seconds are counted, and
423           process scheduling may delay the delivery of the signal even
424           further.)
425
426           Only one timer may be counting at once.  Each call disables the
427           previous timer, and an argument of 0 may be supplied to cancel the
428           previous timer without starting a new one.  The returned value is
429           the amount of time remaining on the previous timer.
430
431           For delays of finer granularity than one second, the Time::HiRes
432           module (from CPAN, and starting from Perl 5.8 part of the standard
433           distribution) provides "ualarm".  You may also use Perl's four-
434           argument version of "select" leaving the first three arguments
435           undefined, or you might be able to use the "syscall" interface to
436           access setitimer(2) if your system supports it.  See perlfaq8 for
437           details.
438
439           It is usually a mistake to intermix "alarm" and "sleep" calls,
440           because "sleep" may be internally implemented on your system with
441           "alarm".
442
443           If you want to use "alarm" to time out a system call you need to
444           use an "eval"/"die" pair.  You can't rely on the alarm causing the
445           system call to fail with $! set to "EINTR" because Perl sets up
446           signal handlers to restart system calls on some systems.  Using
447           "eval"/"die" always works, modulo the caveats given in "Signals" in
448           perlipc.
449
450               eval {
451                   local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
452                   alarm $timeout;
453                   my $nread = sysread $socket, $buffer, $size;
454                   alarm 0;
455               };
456               if ($@) {
457                   die unless $@ eq "alarm\n";   # propagate unexpected errors
458                   # timed out
459               }
460               else {
461                   # didn't
462               }
463
464           For more information see perlipc.
465
466           Portability issues: "alarm" in perlport.
467
468       atan2 Y,X
469           Returns the arctangent of Y/X in the range -PI to PI.
470
471           For the tangent operation, you may use the "Math::Trig::tan"
472           function, or use the familiar relation:
473
474               sub tan { sin($_[0]) / cos($_[0])  }
475
476           The return value for "atan2(0,0)" is implementation-defined;
477           consult your atan2(3) manpage for more information.
478
479           Portability issues: "atan2" in perlport.
480
481       bind SOCKET,NAME
482           Binds a network address to a socket, just as bind(2) does.  Returns
483           true if it succeeded, false otherwise.  NAME should be a packed
484           address of the appropriate type for the socket.  See the examples
485           in "Sockets: Client/Server Communication" in perlipc.
486
487       binmode FILEHANDLE, LAYER
488       binmode FILEHANDLE
489           Arranges for FILEHANDLE to be read or written in "binary" or "text"
490           mode on systems where the run-time libraries distinguish between
491           binary and text files.  If FILEHANDLE is an expression, the value
492           is taken as the name of the filehandle.  Returns true on success,
493           otherwise it returns "undef" and sets $! (errno).
494
495           On some systems (in general, DOS- and Windows-based systems)
496           "binmode" is necessary when you're not working with a text file.
497           For the sake of portability it is a good idea always to use it when
498           appropriate, and never to use it when it isn't appropriate.  Also,
499           people can set their I/O to be by default UTF8-encoded Unicode, not
500           bytes.
501
502           In other words: regardless of platform, use "binmode" on binary
503           data, like images, for example.
504
505           If LAYER is present it is a single string, but may contain multiple
506           directives.  The directives alter the behaviour of the filehandle.
507           When LAYER is present, using binmode on a text file makes sense.
508
509           If LAYER is omitted or specified as ":raw" the filehandle is made
510           suitable for passing binary data.  This includes turning off
511           possible CRLF translation and marking it as bytes (as opposed to
512           Unicode characters).  Note that, despite what may be implied in
513           "Programming Perl" (the Camel, 3rd edition) or elsewhere, ":raw" is
514           not simply the inverse of ":crlf".  Other layers that would affect
515           the binary nature of the stream are also disabled.  See PerlIO,
516           perlrun, and the discussion about the PERLIO environment variable.
517
518           The ":bytes", ":crlf", ":utf8", and any other directives of the
519           form ":...", are called I/O layers.  The open pragma can be used to
520           establish default I/O layers.
521
522           The LAYER parameter of the "binmode" function is described as
523           "DISCIPLINE" in "Programming Perl, 3rd Edition".  However, since
524           the publishing of this book, by many known as "Camel III", the
525           consensus of the naming of this functionality has moved from
526           "discipline" to "layer".  All documentation of this version of Perl
527           therefore refers to "layers" rather than to "disciplines".  Now
528           back to the regularly scheduled documentation...
529
530           To mark FILEHANDLE as UTF-8, use ":utf8" or ":encoding(UTF-8)".
531           ":utf8" just marks the data as UTF-8 without further checking,
532           while ":encoding(UTF-8)" checks the data for actually being valid
533           UTF-8.  More details can be found in PerlIO::encoding.
534
535           In general, "binmode" should be called after "open" but before any
536           I/O is done on the filehandle.  Calling "binmode" normally flushes
537           any pending buffered output data (and perhaps pending input data)
538           on the handle.  An exception to this is the ":encoding" layer that
539           changes the default character encoding of the handle.  The
540           ":encoding" layer sometimes needs to be called in mid-stream, and
541           it doesn't flush the stream.  ":encoding" also implicitly pushes on
542           top of itself the ":utf8" layer because internally Perl operates on
543           UTF8-encoded Unicode characters.
544
545           The operating system, device drivers, C libraries, and Perl run-
546           time system all conspire to let the programmer treat a single
547           character ("\n") as the line terminator, irrespective of external
548           representation.  On many operating systems, the native text file
549           representation matches the internal representation, but on some
550           platforms the external representation of "\n" is made up of more
551           than one character.
552
553           All variants of Unix, Mac OS (old and new), and Stream_LF files on
554           VMS use a single character to end each line in the external
555           representation of text (even though that single character is
556           CARRIAGE RETURN on old, pre-Darwin flavors of Mac OS, and is LINE
557           FEED on Unix and most VMS files).  In other systems like OS/2, DOS,
558           and the various flavors of MS-Windows, your program sees a "\n" as
559           a simple "\cJ", but what's stored in text files are the two
560           characters "\cM\cJ".  That means that if you don't use "binmode" on
561           these systems, "\cM\cJ" sequences on disk will be converted to "\n"
562           on input, and any "\n" in your program will be converted back to
563           "\cM\cJ" on output.  This is what you want for text files, but it
564           can be disastrous for binary files.
565
566           Another consequence of using "binmode" (on some systems) is that
567           special end-of-file markers will be seen as part of the data
568           stream.  For systems from the Microsoft family this means that, if
569           your binary data contain "\cZ", the I/O subsystem will regard it as
570           the end of the file, unless you use "binmode".
571
572           "binmode" is important not only for "readline" and "print"
573           operations, but also when using "read", "seek", "sysread",
574           "syswrite" and "tell" (see perlport for more details).  See the $/
575           and "$\" variables in perlvar for how to manually set your input
576           and output line-termination sequences.
577
578           Portability issues: "binmode" in perlport.
579
580       bless REF,CLASSNAME
581       bless REF
582           This function tells the thingy referenced by REF that it is now an
583           object in the CLASSNAME package.  If CLASSNAME is omitted, the
584           current package is used.  Because a "bless" is often the last thing
585           in a constructor, it returns the reference for convenience.  Always
586           use the two-argument version if a derived class might inherit the
587           method doing the blessing.  See perlobj for more about the blessing
588           (and blessings) of objects.
589
590           Consider always blessing objects in CLASSNAMEs that are mixed case.
591           Namespaces with all lowercase names are considered reserved for
592           Perl pragmas.  Builtin types have all uppercase names.  To prevent
593           confusion, you may wish to avoid such package names as well.  Make
594           sure that CLASSNAME is a true value.
595
596           See "Perl Modules" in perlmod.
597
598       break
599           Break out of a "given" block.
600
601           "break" is available only if the "switch" feature is enabled or if
602           it is prefixed with "CORE::". The "switch" feature is enabled
603           automatically with a "use v5.10" (or higher) declaration in the
604           current scope.
605
606       caller EXPR
607       caller
608           Returns the context of the current pure perl subroutine call.  In
609           scalar context, returns the caller's package name if there is a
610           caller (that is, if we're in a subroutine or "eval" or "require")
611           and the undefined value otherwise.  caller never returns XS subs
612           and they are skipped.  The next pure perl sub will appear instead
613           of the XS sub in caller's return values.  In list context, caller
614           returns
615
616                  # 0         1          2
617               my ($package, $filename, $line) = caller;
618
619           With EXPR, it returns some extra information that the debugger uses
620           to print a stack trace.  The value of EXPR indicates how many call
621           frames to go back before the current one.
622
623               #  0         1          2      3            4
624            my ($package, $filename, $line, $subroutine, $hasargs,
625
626               #  5          6          7            8       9         10
627               $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
628             = caller($i);
629
630           Here, $subroutine is the function that the caller called (rather
631           than the function containing the caller).  Note that $subroutine
632           may be "(eval)" if the frame is not a subroutine call, but an
633           "eval".  In such a case additional elements $evaltext and
634           $is_require are set: $is_require is true if the frame is created by
635           a "require" or "use" statement, $evaltext contains the text of the
636           "eval EXPR" statement.  In particular, for an "eval BLOCK"
637           statement, $subroutine is "(eval)", but $evaltext is undefined.
638           (Note also that each "use" statement creates a "require" frame
639           inside an "eval EXPR" frame.)  $subroutine may also be "(unknown)"
640           if this particular subroutine happens to have been deleted from the
641           symbol table.  $hasargs is true if a new instance of @_ was set up
642           for the frame.  $hints and $bitmask contain pragmatic hints that
643           the caller was compiled with.  $hints corresponds to $^H, and
644           $bitmask corresponds to "${^WARNING_BITS}".  The $hints and
645           $bitmask values are subject to change between versions of Perl, and
646           are not meant for external use.
647
648           $hinthash is a reference to a hash containing the value of "%^H"
649           when the caller was compiled, or "undef" if "%^H" was empty.  Do
650           not modify the values of this hash, as they are the actual values
651           stored in the optree.
652
653           Furthermore, when called from within the DB package in list
654           context, and with an argument, caller returns more detailed
655           information: it sets the list variable @DB::args to be the
656           arguments with which the subroutine was invoked.
657
658           Be aware that the optimizer might have optimized call frames away
659           before "caller" had a chance to get the information.  That means
660           that caller(N) might not return information about the call frame
661           you expect it to, for "N > 1".  In particular, @DB::args might have
662           information from the previous time "caller" was called.
663
664           Be aware that setting @DB::args is best effort, intended for
665           debugging or generating backtraces, and should not be relied upon.
666           In particular, as @_ contains aliases to the caller's arguments,
667           Perl does not take a copy of @_, so @DB::args will contain
668           modifications the subroutine makes to @_ or its contents, not the
669           original values at call time.  @DB::args, like @_, does not hold
670           explicit references to its elements, so under certain cases its
671           elements may have become freed and reallocated for other variables
672           or temporary values.  Finally, a side effect of the current
673           implementation is that the effects of "shift @_" can normally be
674           undone (but not "pop @_" or other splicing, and not if a reference
675           to @_ has been taken, and subject to the caveat about reallocated
676           elements), so @DB::args is actually a hybrid of the current state
677           and initial state of @_.  Buyer beware.
678
679       chdir EXPR
680       chdir FILEHANDLE
681       chdir DIRHANDLE
682       chdir
683           Changes the working directory to EXPR, if possible.  If EXPR is
684           omitted, changes to the directory specified by $ENV{HOME}, if set;
685           if not, changes to the directory specified by $ENV{LOGDIR}.  (Under
686           VMS, the variable $ENV{'SYS$LOGIN'} is also checked, and used if it
687           is set.)  If neither is set, "chdir" does nothing and fails.  It
688           returns true on success, false otherwise.  See the example under
689           "die".
690
691           On systems that support fchdir(2), you may pass a filehandle or
692           directory handle as the argument.  On systems that don't support
693           fchdir(2), passing handles raises an exception.
694
695       chmod LIST
696           Changes the permissions of a list of files.  The first element of
697           the list must be the numeric mode, which should probably be an
698           octal number, and which definitely should not be a string of octal
699           digits: 0644 is okay, but "0644" is not.  Returns the number of
700           files successfully changed.  See also "oct" if all you have is a
701           string.
702
703               my $cnt = chmod 0755, "foo", "bar";
704               chmod 0755, @executables;
705               my $mode = "0644"; chmod $mode, "foo";      # !!! sets mode to
706                                                           # --w----r-T
707               my $mode = "0644"; chmod oct($mode), "foo"; # this is better
708               my $mode = 0644;   chmod $mode, "foo";      # this is best
709
710           On systems that support fchmod(2), you may pass filehandles among
711           the files.  On systems that don't support fchmod(2), passing
712           filehandles raises an exception.  Filehandles must be passed as
713           globs or glob references to be recognized; barewords are considered
714           filenames.
715
716               open(my $fh, "<", "foo");
717               my $perm = (stat $fh)[2] & 07777;
718               chmod($perm | 0600, $fh);
719
720           You can also import the symbolic "S_I*" constants from the "Fcntl"
721           module:
722
723               use Fcntl qw( :mode );
724               chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
725               # Identical to the chmod 0755 of the example above.
726
727           Portability issues: "chmod" in perlport.
728
729       chomp VARIABLE
730       chomp( LIST )
731       chomp
732           This safer version of "chop" removes any trailing string that
733           corresponds to the current value of $/ (also known as
734           $INPUT_RECORD_SEPARATOR in the "English" module).  It returns the
735           total number of characters removed from all its arguments.  It's
736           often used to remove the newline from the end of an input record
737           when you're worried that the final record may be missing its
738           newline.  When in paragraph mode ("$/ = ''"), it removes all
739           trailing newlines from the string.  When in slurp mode ("$/ =
740           undef") or fixed-length record mode ($/ is a reference to an
741           integer or the like; see perlvar), "chomp" won't remove anything.
742           If VARIABLE is omitted, it chomps $_.  Example:
743
744               while (<>) {
745                   chomp;  # avoid \n on last field
746                   my @array = split(/:/);
747                   # ...
748               }
749
750           If VARIABLE is a hash, it chomps the hash's values, but not its
751           keys, resetting the "each" iterator in the process.
752
753           You can actually chomp anything that's an lvalue, including an
754           assignment:
755
756               chomp(my $cwd = `pwd`);
757               chomp(my $answer = <STDIN>);
758
759           If you chomp a list, each element is chomped, and the total number
760           of characters removed is returned.
761
762           Note that parentheses are necessary when you're chomping anything
763           that is not a simple variable.  This is because "chomp $cwd =
764           `pwd`;" is interpreted as "(chomp $cwd) = `pwd`;", rather than as
765           "chomp( $cwd = `pwd` )" which you might expect.  Similarly, "chomp
766           $a, $b" is interpreted as "chomp($a), $b" rather than as "chomp($a,
767           $b)".
768
769       chop VARIABLE
770       chop( LIST )
771       chop
772           Chops off the last character of a string and returns the character
773           chopped.  It is much more efficient than "s/.$//s" because it
774           neither scans nor copies the string.  If VARIABLE is omitted, chops
775           $_.  If VARIABLE is a hash, it chops the hash's values, but not its
776           keys, resetting the "each" iterator in the process.
777
778           You can actually chop anything that's an lvalue, including an
779           assignment.
780
781           If you chop a list, each element is chopped.  Only the value of the
782           last "chop" is returned.
783
784           Note that "chop" returns the last character.  To return all but the
785           last character, use "substr($string, 0, -1)".
786
787           See also "chomp".
788
789       chown LIST
790           Changes the owner (and group) of a list of files.  The first two
791           elements of the list must be the numeric uid and gid, in that
792           order.  A value of -1 in either position is interpreted by most
793           systems to leave that value unchanged.  Returns the number of files
794           successfully changed.
795
796               my $cnt = chown $uid, $gid, 'foo', 'bar';
797               chown $uid, $gid, @filenames;
798
799           On systems that support fchown(2), you may pass filehandles among
800           the files.  On systems that don't support fchown(2), passing
801           filehandles raises an exception.  Filehandles must be passed as
802           globs or glob references to be recognized; barewords are considered
803           filenames.
804
805           Here's an example that looks up nonnumeric uids in the passwd file:
806
807               print "User: ";
808               chomp(my $user = <STDIN>);
809               print "Files: ";
810               chomp(my $pattern = <STDIN>);
811
812               my ($login,$pass,$uid,$gid) = getpwnam($user)
813                   or die "$user not in passwd file";
814
815               my @ary = glob($pattern);  # expand filenames
816               chown $uid, $gid, @ary;
817
818           On most systems, you are not allowed to change the ownership of the
819           file unless you're the superuser, although you should be able to
820           change the group to any of your secondary groups.  On insecure
821           systems, these restrictions may be relaxed, but this is not a
822           portable assumption.  On POSIX systems, you can detect this
823           condition this way:
824
825               use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
826               my $can_chown_giveaway = ! sysconf(_PC_CHOWN_RESTRICTED);
827
828           Portability issues: "chown" in perlport.
829
830       chr NUMBER
831       chr Returns the character represented by that NUMBER in the character
832           set.  For example, "chr(65)" is "A" in either ASCII or Unicode, and
833           chr(0x263a) is a Unicode smiley face.
834
835           Negative values give the Unicode replacement character
836           (chr(0xfffd)), except under the bytes pragma, where the low eight
837           bits of the value (truncated to an integer) are used.
838
839           If NUMBER is omitted, uses $_.
840
841           For the reverse, use "ord".
842
843           Note that characters from 128 to 255 (inclusive) are by default
844           internally not encoded as UTF-8 for backward compatibility reasons.
845
846           See perlunicode for more about Unicode.
847
848       chroot FILENAME
849       chroot
850           This function works like the system call by the same name: it makes
851           the named directory the new root directory for all further
852           pathnames that begin with a "/" by your process and all its
853           children.  (It doesn't change your current working directory, which
854           is unaffected.)  For security reasons, this call is restricted to
855           the superuser.  If FILENAME is omitted, does a "chroot" to $_.
856
857           NOTE:  It is good security practice to do "chdir("/")" ("chdir" to
858           the root directory) immediately after a "chroot".
859
860           Portability issues: "chroot" in perlport.
861
862       close FILEHANDLE
863       close
864           Closes the file or pipe associated with the filehandle, flushes the
865           IO buffers, and closes the system file descriptor.  Returns true if
866           those operations succeed and if no error was reported by any PerlIO
867           layer.  Closes the currently selected filehandle if the argument is
868           omitted.
869
870           You don't have to close FILEHANDLE if you are immediately going to
871           do another "open" on it, because "open" closes it for you.  (See
872           "open".) However, an explicit "close" on an input file resets the
873           line counter ($.), while the implicit close done by "open" does
874           not.
875
876           If the filehandle came from a piped open, "close" returns false if
877           one of the other syscalls involved fails or if its program exits
878           with non-zero status.  If the only problem was that the program
879           exited non-zero, $! will be set to 0.  Closing a pipe also waits
880           for the process executing on the pipe to exit--in case you wish to
881           look at the output of the pipe afterwards--and implicitly puts the
882           exit status value of that command into $? and
883           "${^CHILD_ERROR_NATIVE}".
884
885           If there are multiple threads running, "close" on a filehandle from
886           a piped open returns true without waiting for the child process to
887           terminate, if the filehandle is still open in another thread.
888
889           Closing the read end of a pipe before the process writing to it at
890           the other end is done writing results in the writer receiving a
891           SIGPIPE.  If the other end can't handle that, be sure to read all
892           the data before closing the pipe.
893
894           Example:
895
896               open(OUTPUT, '|sort >foo')  # pipe to sort
897                   or die "Can't start sort: $!";
898               #...                        # print stuff to output
899               close OUTPUT                # wait for sort to finish
900                   or warn $! ? "Error closing sort pipe: $!"
901                              : "Exit status $? from sort";
902               open(INPUT, 'foo')          # get sort's results
903                   or die "Can't open 'foo' for input: $!";
904
905           FILEHANDLE may be an expression whose value can be used as an
906           indirect filehandle, usually the real filehandle name or an
907           autovivified handle.
908
909       closedir DIRHANDLE
910           Closes a directory opened by "opendir" and returns the success of
911           that system call.
912
913       connect SOCKET,NAME
914           Attempts to connect to a remote socket, just like connect(2).
915           Returns true if it succeeded, false otherwise.  NAME should be a
916           packed address of the appropriate type for the socket.  See the
917           examples in "Sockets: Client/Server Communication" in perlipc.
918
919       continue BLOCK
920       continue
921           When followed by a BLOCK, "continue" is actually a flow control
922           statement rather than a function.  If there is a "continue" BLOCK
923           attached to a BLOCK (typically in a "while" or "foreach"), it is
924           always executed just before the conditional is about to be
925           evaluated again, just like the third part of a "for" loop in C.
926           Thus it can be used to increment a loop variable, even when the
927           loop has been continued via the "next" statement (which is similar
928           to the C "continue" statement).
929
930           "last", "next", or "redo" may appear within a "continue" block;
931           "last" and "redo" behave as if they had been executed within the
932           main block.  So will "next", but since it will execute a "continue"
933           block, it may be more entertaining.
934
935               while (EXPR) {
936                   ### redo always comes here
937                   do_something;
938               } continue {
939                   ### next always comes here
940                   do_something_else;
941                   # then back the top to re-check EXPR
942               }
943               ### last always comes here
944
945           Omitting the "continue" section is equivalent to using an empty
946           one, logically enough, so "next" goes directly back to check the
947           condition at the top of the loop.
948
949           When there is no BLOCK, "continue" is a function that falls through
950           the current "when" or "default" block instead of iterating a
951           dynamically enclosing "foreach" or exiting a lexically enclosing
952           "given".  In Perl 5.14 and earlier, this form of "continue" was
953           only available when the "switch" feature was enabled.  See feature
954           and "Switch Statements" in perlsyn for more information.
955
956       cos EXPR
957       cos Returns the cosine of EXPR (expressed in radians).  If EXPR is
958           omitted, takes the cosine of $_.
959
960           For the inverse cosine operation, you may use the
961           "Math::Trig::acos" function, or use this relation:
962
963               sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
964
965       crypt PLAINTEXT,SALT
966           Creates a digest string exactly like the crypt(3) function in the C
967           library (assuming that you actually have a version there that has
968           not been extirpated as a potential munition).
969
970           "crypt" is a one-way hash function.  The PLAINTEXT and SALT are
971           turned into a short string, called a digest, which is returned.
972           The same PLAINTEXT and SALT will always return the same string, but
973           there is no (known) way to get the original PLAINTEXT from the
974           hash.  Small changes in the PLAINTEXT or SALT will result in large
975           changes in the digest.
976
977           There is no decrypt function.  This function isn't all that useful
978           for cryptography (for that, look for Crypt modules on your nearby
979           CPAN mirror) and the name "crypt" is a bit of a misnomer.  Instead
980           it is primarily used to check if two pieces of text are the same
981           without having to transmit or store the text itself.  An example is
982           checking if a correct password is given.  The digest of the
983           password is stored, not the password itself.  The user types in a
984           password that is "crypt"'d with the same salt as the stored digest.
985           If the two digests match, the password is correct.
986
987           When verifying an existing digest string you should use the digest
988           as the salt (like "crypt($plain, $digest) eq $digest").  The SALT
989           used to create the digest is visible as part of the digest.  This
990           ensures "crypt" will hash the new string with the same salt as the
991           digest.  This allows your code to work with the standard "crypt"
992           and with more exotic implementations.  In other words, assume
993           nothing about the returned string itself nor about how many bytes
994           of SALT may matter.
995
996           Traditionally the result is a string of 13 bytes: two first bytes
997           of the salt, followed by 11 bytes from the set "[./0-9A-Za-z]", and
998           only the first eight bytes of PLAINTEXT mattered.  But alternative
999           hashing schemes (like MD5), higher level security schemes (like
1000           C2), and implementations on non-Unix platforms may produce
1001           different strings.
1002
1003           When choosing a new salt create a random two character string whose
1004           characters come from the set "[./0-9A-Za-z]" (like "join '', ('.',
1005           '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]").  This set of
1006           characters is just a recommendation; the characters allowed in the
1007           salt depend solely on your system's crypt library, and Perl can't
1008           restrict what salts "crypt" accepts.
1009
1010           Here's an example that makes sure that whoever runs this program
1011           knows their password:
1012
1013               my $pwd = (getpwuid($<))[1];
1014
1015               system "stty -echo";
1016               print "Password: ";
1017               chomp(my $word = <STDIN>);
1018               print "\n";
1019               system "stty echo";
1020
1021               if (crypt($word, $pwd) ne $pwd) {
1022                   die "Sorry...\n";
1023               } else {
1024                   print "ok\n";
1025               }
1026
1027           Of course, typing in your own password to whoever asks you for it
1028           is unwise.
1029
1030           The "crypt" function is unsuitable for hashing large quantities of
1031           data, not least of all because you can't get the information back.
1032           Look at the Digest module for more robust algorithms.
1033
1034           If using "crypt" on a Unicode string (which potentially has
1035           characters with codepoints above 255), Perl tries to make sense of
1036           the situation by trying to downgrade (a copy of) the string back to
1037           an eight-bit byte string before calling "crypt" (on that copy).  If
1038           that works, good.  If not, "crypt" dies with "Wide character in
1039           crypt".
1040
1041           Portability issues: "crypt" in perlport.
1042
1043       dbmclose HASH
1044           [This function has been largely superseded by the "untie"
1045           function.]
1046
1047           Breaks the binding between a DBM file and a hash.
1048
1049           Portability issues: "dbmclose" in perlport.
1050
1051       dbmopen HASH,DBNAME,MASK
1052           [This function has been largely superseded by the "tie" function.]
1053
1054           This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file
1055           to a hash.  HASH is the name of the hash.  (Unlike normal "open",
1056           the first argument is not a filehandle, even though it looks like
1057           one).  DBNAME is the name of the database (without the .dir or .pag
1058           extension if any).  If the database does not exist, it is created
1059           with protection specified by MASK (as modified by the "umask").  To
1060           prevent creation of the database if it doesn't exist, you may
1061           specify a MODE of 0, and the function will return a false value if
1062           it can't find an existing database.  If your system supports only
1063           the older DBM functions, you may make only one "dbmopen" call in
1064           your program.  In older versions of Perl, if your system had
1065           neither DBM nor ndbm, calling "dbmopen" produced a fatal error; it
1066           now falls back to sdbm(3).
1067
1068           If you don't have write access to the DBM file, you can only read
1069           hash variables, not set them.  If you want to test whether you can
1070           write, either use file tests or try setting a dummy hash entry
1071           inside an "eval" to trap the error.
1072
1073           Note that functions such as "keys" and "values" may return huge
1074           lists when used on large DBM files.  You may prefer to use the
1075           "each" function to iterate over large DBM files.  Example:
1076
1077               # print out history file offsets
1078               dbmopen(%HIST,'/usr/lib/news/history',0666);
1079               while (($key,$val) = each %HIST) {
1080                   print $key, ' = ', unpack('L',$val), "\n";
1081               }
1082               dbmclose(%HIST);
1083
1084           See also AnyDBM_File for a more general description of the pros and
1085           cons of the various dbm approaches, as well as DB_File for a
1086           particularly rich implementation.
1087
1088           You can control which DBM library you use by loading that library
1089           before you call "dbmopen":
1090
1091               use DB_File;
1092               dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
1093                   or die "Can't open netscape history file: $!";
1094
1095           Portability issues: "dbmopen" in perlport.
1096
1097       defined EXPR
1098       defined
1099           Returns a Boolean value telling whether EXPR has a value other than
1100           the undefined value "undef".  If EXPR is not present, $_ is
1101           checked.
1102
1103           Many operations return "undef" to indicate failure, end of file,
1104           system error, uninitialized variable, and other exceptional
1105           conditions.  This function allows you to distinguish "undef" from
1106           other values.  (A simple Boolean test will not distinguish among
1107           "undef", zero, the empty string, and "0", which are all equally
1108           false.)  Note that since "undef" is a valid scalar, its presence
1109           doesn't necessarily indicate an exceptional condition: "pop"
1110           returns "undef" when its argument is an empty array, or when the
1111           element to return happens to be "undef".
1112
1113           You may also use "defined(&func)" to check whether subroutine
1114           "func" has ever been defined.  The return value is unaffected by
1115           any forward declarations of "func".  A subroutine that is not
1116           defined may still be callable: its package may have an "AUTOLOAD"
1117           method that makes it spring into existence the first time that it
1118           is called; see perlsub.
1119
1120           Use of "defined" on aggregates (hashes and arrays) is no longer
1121           supported. It used to report whether memory for that aggregate had
1122           ever been allocated.  You should instead use a simple test for
1123           size:
1124
1125               if (@an_array) { print "has array elements\n" }
1126               if (%a_hash)   { print "has hash members\n"   }
1127
1128           When used on a hash element, it tells you whether the value is
1129           defined, not whether the key exists in the hash.  Use "exists" for
1130           the latter purpose.
1131
1132           Examples:
1133
1134               print if defined $switch{D};
1135               print "$val\n" while defined($val = pop(@ary));
1136               die "Can't readlink $sym: $!"
1137                   unless defined($value = readlink $sym);
1138               sub foo { defined &$bar ? $bar->(@_) : die "No bar"; }
1139               $debugging = 0 unless defined $debugging;
1140
1141           Note:  Many folks tend to overuse "defined" and are then surprised
1142           to discover that the number 0 and "" (the zero-length string) are,
1143           in fact, defined values.  For example, if you say
1144
1145               "ab" =~ /a(.*)b/;
1146
1147           The pattern match succeeds and $1 is defined, although it matched
1148           "nothing".  It didn't really fail to match anything.  Rather, it
1149           matched something that happened to be zero characters long.  This
1150           is all very above-board and honest.  When a function returns an
1151           undefined value, it's an admission that it couldn't give you an
1152           honest answer.  So you should use "defined" only when questioning
1153           the integrity of what you're trying to do.  At other times, a
1154           simple comparison to 0 or "" is what you want.
1155
1156           See also "undef", "exists", "ref".
1157
1158       delete EXPR
1159           Given an expression that specifies an element or slice of a hash,
1160           "delete" deletes the specified elements from that hash so that
1161           "exists" on that element no longer returns true.  Setting a hash
1162           element to the undefined value does not remove its key, but
1163           deleting it does; see "exists".
1164
1165           In list context, returns the value or values deleted, or the last
1166           such element in scalar context.  The return list's length always
1167           matches that of the argument list: deleting non-existent elements
1168           returns the undefined value in their corresponding positions.
1169
1170           "delete" may also be used on arrays and array slices, but its
1171           behavior is less straightforward.  Although "exists" will return
1172           false for deleted entries, deleting array elements never changes
1173           indices of existing values; use "shift" or "splice" for that.
1174           However, if any deleted elements fall at the end of an array, the
1175           array's size shrinks to the position of the highest element that
1176           still tests true for "exists", or to 0 if none do.  In other words,
1177           an array won't have trailing nonexistent elements after a delete.
1178
1179           WARNING: Calling "delete" on array values is strongly discouraged.
1180           The notion of deleting or checking the existence of Perl array
1181           elements is not conceptually coherent, and can lead to surprising
1182           behavior.
1183
1184           Deleting from %ENV modifies the environment.  Deleting from a hash
1185           tied to a DBM file deletes the entry from the DBM file.  Deleting
1186           from a "tied" hash or array may not necessarily return anything; it
1187           depends on the implementation of the "tied" package's DELETE
1188           method, which may do whatever it pleases.
1189
1190           The "delete local EXPR" construct localizes the deletion to the
1191           current block at run time.  Until the block exits, elements locally
1192           deleted temporarily no longer exist.  See "Localized deletion of
1193           elements of composite types" in perlsub.
1194
1195               my %hash = (foo => 11, bar => 22, baz => 33);
1196               my $scalar = delete $hash{foo};         # $scalar is 11
1197               $scalar = delete @hash{qw(foo bar)}; # $scalar is 22
1198               my @array  = delete @hash{qw(foo baz)}; # @array  is (undef,33)
1199
1200           The following (inefficiently) deletes all the values of %HASH and
1201           @ARRAY:
1202
1203               foreach my $key (keys %HASH) {
1204                   delete $HASH{$key};
1205               }
1206
1207               foreach my $index (0 .. $#ARRAY) {
1208                   delete $ARRAY[$index];
1209               }
1210
1211           And so do these:
1212
1213               delete @HASH{keys %HASH};
1214
1215               delete @ARRAY[0 .. $#ARRAY];
1216
1217           But both are slower than assigning the empty list or undefining
1218           %HASH or @ARRAY, which is the customary way to empty out an
1219           aggregate:
1220
1221               %HASH = ();     # completely empty %HASH
1222               undef %HASH;    # forget %HASH ever existed
1223
1224               @ARRAY = ();    # completely empty @ARRAY
1225               undef @ARRAY;   # forget @ARRAY ever existed
1226
1227           The EXPR can be arbitrarily complicated provided its final
1228           operation is an element or slice of an aggregate:
1229
1230               delete $ref->[$x][$y]{$key};
1231               delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};
1232
1233               delete $ref->[$x][$y][$index];
1234               delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
1235
1236       die LIST
1237           "die" raises an exception.  Inside an "eval" the error message is
1238           stuffed into $@ and the "eval" is terminated with the undefined
1239           value.  If the exception is outside of all enclosing "eval"s, then
1240           the uncaught exception prints LIST to "STDERR" and exits with a
1241           non-zero value.  If you need to exit the process with a specific
1242           exit code, see "exit".
1243
1244           Equivalent examples:
1245
1246               die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
1247               chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
1248
1249           If the last element of LIST does not end in a newline, the current
1250           script line number and input line number (if any) are also printed,
1251           and a newline is supplied.  Note that the "input line number" (also
1252           known as "chunk") is subject to whatever notion of "line" happens
1253           to be currently in effect, and is also available as the special
1254           variable $..  See "$/" in perlvar and "$." in perlvar.
1255
1256           Hint: sometimes appending ", stopped" to your message will cause it
1257           to make better sense when the string "at foo line 123" is appended.
1258           Suppose you are running script "canasta".
1259
1260               die "/etc/games is no good";
1261               die "/etc/games is no good, stopped";
1262
1263           produce, respectively
1264
1265               /etc/games is no good at canasta line 123.
1266               /etc/games is no good, stopped at canasta line 123.
1267
1268           If the output is empty and $@ already contains a value (typically
1269           from a previous "eval") that value is reused after appending
1270           "\t...propagated".  This is useful for propagating exceptions:
1271
1272               eval { ... };
1273               die unless $@ =~ /Expected exception/;
1274
1275           If the output is empty and $@ contains an object reference that has
1276           a "PROPAGATE" method, that method will be called with additional
1277           file and line number parameters.  The return value replaces the
1278           value in $@;  i.e., as if "$@ = eval { $@->PROPAGATE(__FILE__,
1279           __LINE__) };" were called.
1280
1281           If $@ is empty, then the string "Died" is used.
1282
1283           If an uncaught exception results in interpreter exit, the exit code
1284           is determined from the values of $! and $? with this pseudocode:
1285
1286               exit $! if $!;              # errno
1287               exit $? >> 8 if $? >> 8;    # child exit status
1288               exit 255;                   # last resort
1289
1290           As with "exit", $? is set prior to unwinding the call stack; any
1291           "DESTROY" or "END" handlers can then alter this value, and thus
1292           Perl's exit code.
1293
1294           The intent is to squeeze as much possible information about the
1295           likely cause into the limited space of the system exit code.
1296           However, as $! is the value of C's "errno", which can be set by any
1297           system call, this means that the value of the exit code used by
1298           "die" can be non-predictable, so should not be relied upon, other
1299           than to be non-zero.
1300
1301           You can also call "die" with a reference argument, and if this is
1302           trapped within an "eval", $@ contains that reference.  This permits
1303           more elaborate exception handling using objects that maintain
1304           arbitrary state about the exception.  Such a scheme is sometimes
1305           preferable to matching particular string values of $@ with regular
1306           expressions.  Because $@ is a global variable and "eval" may be
1307           used within object implementations, be careful that analyzing the
1308           error object doesn't replace the reference in the global variable.
1309           It's easiest to make a local copy of the reference before any
1310           manipulations.  Here's an example:
1311
1312               use Scalar::Util "blessed";
1313
1314               eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
1315               if (my $ev_err = $@) {
1316                   if (blessed($ev_err)
1317                       && $ev_err->isa("Some::Module::Exception")) {
1318                       # handle Some::Module::Exception
1319                   }
1320                   else {
1321                       # handle all other possible exceptions
1322                   }
1323               }
1324
1325           Because Perl stringifies uncaught exception messages before
1326           display, you'll probably want to overload stringification
1327           operations on exception objects.  See overload for details about
1328           that.
1329
1330           You can arrange for a callback to be run just before the "die" does
1331           its deed, by setting the $SIG{__DIE__} hook.  The associated
1332           handler is called with the error text and can change the error
1333           message, if it sees fit, by calling "die" again.  See "%SIG" in
1334           perlvar for details on setting %SIG entries, and "eval" for some
1335           examples.  Although this feature was to be run only right before
1336           your program was to exit, this is not currently so: the
1337           $SIG{__DIE__} hook is currently called even inside "eval"ed
1338           blocks/strings!  If one wants the hook to do nothing in such
1339           situations, put
1340
1341               die @_ if $^S;
1342
1343           as the first line of the handler (see "$^S" in perlvar).  Because
1344           this promotes strange action at a distance, this counterintuitive
1345           behavior may be fixed in a future release.
1346
1347           See also "exit", "warn", and the Carp module.
1348
1349       do BLOCK
1350           Not really a function.  Returns the value of the last command in
1351           the sequence of commands indicated by BLOCK.  When modified by the
1352           "while" or "until" loop modifier, executes the BLOCK once before
1353           testing the loop condition.  (On other statements the loop
1354           modifiers test the conditional first.)
1355
1356           "do BLOCK" does not count as a loop, so the loop control statements
1357           "next", "last", or "redo" cannot be used to leave or restart the
1358           block.  See perlsyn for alternative strategies.
1359
1360       do EXPR
1361           Uses the value of EXPR as a filename and executes the contents of
1362           the file as a Perl script:
1363
1364               # load the exact specified file (./ and ../ special-cased)
1365               do '/foo/stat.pl';
1366               do './stat.pl';
1367               do '../foo/stat.pl';
1368
1369               # search for the named file within @INC
1370               do 'stat.pl';
1371               do 'foo/stat.pl';
1372
1373           "do './stat.pl'" is largely like
1374
1375               eval `cat stat.pl`;
1376
1377           except that it's more concise, runs no external processes, and
1378           keeps track of the current filename for error messages. It also
1379           differs in that code evaluated with "do FILE" cannot see lexicals
1380           in the enclosing scope; "eval STRING" does.  It's the same,
1381           however, in that it does reparse the file every time you call it,
1382           so you probably don't want to do this inside a loop.
1383
1384           Using "do" with a relative path (except for ./ and ../), like
1385
1386               do 'foo/stat.pl';
1387
1388           will search the @INC directories, and update %INC if the file is
1389           found.  See "@INC" in perlvar and "%INC" in perlvar for these
1390           variables. In particular, note that whilst historically @INC
1391           contained '.' (the current directory) making these two cases
1392           equivalent, that is no longer necessarily the case, as '.' is not
1393           included in @INC by default in perl versions 5.26.0 onwards.
1394           Instead, perl will now warn:
1395
1396               do "stat.pl" failed, '.' is no longer in @INC;
1397               did you mean do "./stat.pl"?
1398
1399           If "do" can read the file but cannot compile it, it returns "undef"
1400           and sets an error message in $@.  If "do" cannot read the file, it
1401           returns undef and sets $! to the error.  Always check $@ first, as
1402           compilation could fail in a way that also sets $!.  If the file is
1403           successfully compiled, "do" returns the value of the last
1404           expression evaluated.
1405
1406           Inclusion of library modules is better done with the "use" and
1407           "require" operators, which also do automatic error checking and
1408           raise an exception if there's a problem.
1409
1410           You might like to use "do" to read in a program configuration file.
1411           Manual error checking can be done this way:
1412
1413               # Read in config files: system first, then user.
1414               # Beware of using relative pathnames here.
1415               for $file ("/share/prog/defaults.rc",
1416                          "$ENV{HOME}/.someprogrc")
1417               {
1418                   unless ($return = do $file) {
1419                       warn "couldn't parse $file: $@" if $@;
1420                       warn "couldn't do $file: $!"    unless defined $return;
1421                       warn "couldn't run $file"       unless $return;
1422                   }
1423               }
1424
1425       dump LABEL
1426       dump EXPR
1427       dump
1428           This function causes an immediate core dump.  See also the -u
1429           command-line switch in perlrun, which does the same thing.
1430           Primarily this is so that you can use the undump program (not
1431           supplied) to turn your core dump into an executable binary after
1432           having initialized all your variables at the beginning of the
1433           program.  When the new binary is executed it will begin by
1434           executing a "goto LABEL" (with all the restrictions that "goto"
1435           suffers).  Think of it as a goto with an intervening core dump and
1436           reincarnation.  If "LABEL" is omitted, restarts the program from
1437           the top.  The "dump EXPR" form, available starting in Perl 5.18.0,
1438           allows a name to be computed at run time, being otherwise identical
1439           to "dump LABEL".
1440
1441           WARNING: Any files opened at the time of the dump will not be open
1442           any more when the program is reincarnated, with possible resulting
1443           confusion by Perl.
1444
1445           This function is now largely obsolete, mostly because it's very
1446           hard to convert a core file into an executable.  That's why you
1447           should now invoke it as "CORE::dump()" if you don't want to be
1448           warned against a possible typo.
1449
1450           Unlike most named operators, this has the same precedence as
1451           assignment.  It is also exempt from the looks-like-a-function rule,
1452           so "dump ("foo")."bar"" will cause "bar" to be part of the argument
1453           to "dump".
1454
1455           Portability issues: "dump" in perlport.
1456
1457       each HASH
1458       each ARRAY
1459           When called on a hash in list context, returns a 2-element list
1460           consisting of the key and value for the next element of a hash.  In
1461           Perl 5.12 and later only, it will also return the index and value
1462           for the next element of an array so that you can iterate over it;
1463           older Perls consider this a syntax error.  When called in scalar
1464           context, returns only the key (not the value) in a hash, or the
1465           index in an array.
1466
1467           Hash entries are returned in an apparently random order.  The
1468           actual random order is specific to a given hash; the exact same
1469           series of operations on two hashes may result in a different order
1470           for each hash.  Any insertion into the hash may change the order,
1471           as will any deletion, with the exception that the most recent key
1472           returned by "each" or "keys" may be deleted without changing the
1473           order.  So long as a given hash is unmodified you may rely on
1474           "keys", "values" and "each" to repeatedly return the same order as
1475           each other.  See "Algorithmic Complexity Attacks" in perlsec for
1476           details on why hash order is randomized.  Aside from the guarantees
1477           provided here the exact details of Perl's hash algorithm and the
1478           hash traversal order are subject to change in any release of Perl.
1479
1480           After "each" has returned all entries from the hash or array, the
1481           next call to "each" returns the empty list in list context and
1482           "undef" in scalar context; the next call following that one
1483           restarts iteration.  Each hash or array has its own internal
1484           iterator, accessed by "each", "keys", and "values".  The iterator
1485           is implicitly reset when "each" has reached the end as just
1486           described; it can be explicitly reset by calling "keys" or "values"
1487           on the hash or array.  If you add or delete a hash's elements while
1488           iterating over it, the effect on the iterator is unspecified; for
1489           example, entries may be skipped or duplicated--so don't do that.
1490           Exception: It is always safe to delete the item most recently
1491           returned by "each", so the following code works properly:
1492
1493               while (my ($key, $value) = each %hash) {
1494                   print $key, "\n";
1495                   delete $hash{$key};   # This is safe
1496               }
1497
1498           Tied hashes may have a different ordering behaviour to perl's hash
1499           implementation.
1500
1501           This prints out your environment like the printenv(1) program, but
1502           in a different order:
1503
1504               while (my ($key,$value) = each %ENV) {
1505                   print "$key=$value\n";
1506               }
1507
1508           Starting with Perl 5.14, an experimental feature allowed "each" to
1509           take a scalar expression. This experiment has been deemed
1510           unsuccessful, and was removed as of Perl 5.24.
1511
1512           As of Perl 5.18 you can use a bare "each" in a "while" loop, which
1513           will set $_ on every iteration.
1514
1515               while (each %ENV) {
1516                   print "$_=$ENV{$_}\n";
1517               }
1518
1519           To avoid confusing would-be users of your code who are running
1520           earlier versions of Perl with mysterious syntax errors, put this
1521           sort of thing at the top of your file to signal that your code will
1522           work only on Perls of a recent vintage:
1523
1524               use 5.012;  # so keys/values/each work on arrays
1525               use 5.018;  # so each assigns to $_ in a lone while test
1526
1527           See also "keys", "values", and "sort".
1528
1529       eof FILEHANDLE
1530       eof ()
1531       eof Returns 1 if the next read on FILEHANDLE will return end of file or
1532           if FILEHANDLE is not open.  FILEHANDLE may be an expression whose
1533           value gives the real filehandle.  (Note that this function actually
1534           reads a character and then "ungetc"s it, so isn't useful in an
1535           interactive context.)  Do not read from a terminal file (or call
1536           "eof(FILEHANDLE)" on it) after end-of-file is reached.  File types
1537           such as terminals may lose the end-of-file condition if you do.
1538
1539           An "eof" without an argument uses the last file read.  Using
1540           "eof()" with empty parentheses is different.  It refers to the
1541           pseudo file formed from the files listed on the command line and
1542           accessed via the "<>" operator.  Since "<>" isn't explicitly
1543           opened, as a normal filehandle is, an "eof()" before "<>" has been
1544           used will cause @ARGV to be examined to determine if input is
1545           available.   Similarly, an "eof()" after "<>" has returned end-of-
1546           file will assume you are processing another @ARGV list, and if you
1547           haven't set @ARGV, will read input from "STDIN"; see "I/O
1548           Operators" in perlop.
1549
1550           In a "while (<>)" loop, "eof" or "eof(ARGV)" can be used to detect
1551           the end of each file, whereas "eof()" will detect the end of the
1552           very last file only.  Examples:
1553
1554               # reset line numbering on each input file
1555               while (<>) {
1556                   next if /^\s*#/;  # skip comments
1557                   print "$.\t$_";
1558               } continue {
1559                   close ARGV if eof;  # Not eof()!
1560               }
1561
1562               # insert dashes just before last line of last file
1563               while (<>) {
1564                   if (eof()) {  # check for end of last file
1565                       print "--------------\n";
1566                   }
1567                   print;
1568                   last if eof();     # needed if we're reading from a terminal
1569               }
1570
1571           Practical hint: you almost never need to use "eof" in Perl, because
1572           the input operators typically return "undef" when they run out of
1573           data or encounter an error.
1574
1575       eval EXPR
1576       eval BLOCK
1577       eval
1578           "eval" in all its forms is used to execute a little Perl program,
1579           trapping any errors encountered so they don't crash the calling
1580           program.
1581
1582           Plain "eval" with no argument is just "eval EXPR", where the
1583           expression is understood to be contained in $_.  Thus there are
1584           only two real "eval" forms; the one with an EXPR is often called
1585           "string eval".  In a string eval, the value of the expression
1586           (which is itself determined within scalar context) is first parsed,
1587           and if there were no errors, executed as a block within the lexical
1588           context of the current Perl program.  This form is typically used
1589           to delay parsing and subsequent execution of the text of EXPR until
1590           run time.  Note that the value is parsed every time the "eval"
1591           executes.
1592
1593           The other form is called "block eval".  It is less general than
1594           string eval, but the code within the BLOCK is parsed only once (at
1595           the same time the code surrounding the "eval" itself was parsed)
1596           and executed within the context of the current Perl program.  This
1597           form is typically used to trap exceptions more efficiently than the
1598           first, while also providing the benefit of checking the code within
1599           BLOCK at compile time.  BLOCK is parsed and compiled just once.
1600           Since errors are trapped, it often is used to check if a given
1601           feature is available.
1602
1603           In both forms, the value returned is the value of the last
1604           expression evaluated inside the mini-program; a return statement
1605           may also be used, just as with subroutines.  The expression
1606           providing the return value is evaluated in void, scalar, or list
1607           context, depending on the context of the "eval" itself.  See
1608           "wantarray" for more on how the evaluation context can be
1609           determined.
1610
1611           If there is a syntax error or runtime error, or a "die" statement
1612           is executed, "eval" returns "undef" in scalar context, or an empty
1613           list in list context, and $@ is set to the error message.  (Prior
1614           to 5.16, a bug caused "undef" to be returned in list context for
1615           syntax errors, but not for runtime errors.) If there was no error,
1616           $@ is set to the empty string.  A control flow operator like "last"
1617           or "goto" can bypass the setting of $@.  Beware that using "eval"
1618           neither silences Perl from printing warnings to STDERR, nor does it
1619           stuff the text of warning messages into $@.  To do either of those,
1620           you have to use the $SIG{__WARN__} facility, or turn off warnings
1621           inside the BLOCK or EXPR using "no warnings 'all'".  See "warn",
1622           perlvar, and warnings.
1623
1624           Note that, because "eval" traps otherwise-fatal errors, it is
1625           useful for determining whether a particular feature (such as
1626           "socket" or "symlink") is implemented.  It is also Perl's
1627           exception-trapping mechanism, where the "die" operator is used to
1628           raise exceptions.
1629
1630           Before Perl 5.14, the assignment to $@ occurred before restoration
1631           of localized variables, which means that for your code to run on
1632           older versions, a temporary is required if you want to mask some,
1633           but not all errors:
1634
1635            # alter $@ on nefarious repugnancy only
1636            {
1637               my $e;
1638               {
1639                 local $@; # protect existing $@
1640                 eval { test_repugnancy() };
1641                 # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only
1642                 $@ =~ /nefarious/ and $e = $@;
1643               }
1644               die $e if defined $e
1645            }
1646
1647           There are some different considerations for each form:
1648
1649           String eval
1650               Since the return value of EXPR is executed as a block within
1651               the lexical context of the current Perl program, any outer
1652               lexical variables are visible to it, and any package variable
1653               settings or subroutine and format definitions remain
1654               afterwards.
1655
1656               Under the "unicode_eval" feature
1657                   If this feature is enabled (which is the default under a
1658                   "use 5.16" or higher declaration), EXPR is considered to be
1659                   in the same encoding as the surrounding program.  Thus if
1660                   "use utf8" is in effect, the string will be treated as
1661                   being UTF-8 encoded.  Otherwise, the string is considered
1662                   to be a sequence of independent bytes.  Bytes that
1663                   correspond to ASCII-range code points will have their
1664                   normal meanings for operators in the string.  The treatment
1665                   of the other bytes depends on if the "'unicode_strings""
1666                   feature is in effect.
1667
1668                   In a plain "eval" without an EXPR argument, being in
1669                   "use utf8" or not is irrelevant; the UTF-8ness of $_ itself
1670                   determines the behavior.
1671
1672                   Any "use utf8" or "no utf8" declarations within the string
1673                   have no effect, and source filters are forbidden.
1674                   ("unicode_strings", however, can appear within the string.)
1675                   See also the "evalbytes" operator, which works properly
1676                   with source filters.
1677
1678                   Variables defined outside the "eval" and used inside it
1679                   retain their original UTF-8ness.  Everything inside the
1680                   string follows the normal rules for a Perl program with the
1681                   given state of "use utf8".
1682
1683               Outside the "unicode_eval" feature
1684                   In this case, the behavior is problematic and is not so
1685                   easily described.  Here are two bugs that cannot easily be
1686                   fixed without breaking existing programs:
1687
1688                   ·   It can lose track of whether something should be
1689                       encoded as UTF-8 or not.
1690
1691                   ·   Source filters activated within "eval" leak out into
1692                       whichever file scope is currently being compiled.  To
1693                       give an example with the CPAN module Semi::Semicolons:
1694
1695                        BEGIN { eval "use Semi::Semicolons; # not filtered" }
1696                        # filtered here!
1697
1698                       "evalbytes" fixes that to work the way one would
1699                       expect:
1700
1701                        use feature "evalbytes";
1702                        BEGIN { evalbytes "use Semi::Semicolons; # filtered" }
1703                        # not filtered
1704
1705               Problems can arise if the string expands a scalar containing a
1706               floating point number.  That scalar can expand to letters, such
1707               as "NaN" or "Infinity"; or, within the scope of a "use locale",
1708               the decimal point character may be something other than a dot
1709               (such as a comma).  None of these are likely to parse as you
1710               are likely expecting.
1711
1712               You should be especially careful to remember what's being
1713               looked at when:
1714
1715                   eval $x;        # CASE 1
1716                   eval "$x";      # CASE 2
1717
1718                   eval '$x';      # CASE 3
1719                   eval { $x };    # CASE 4
1720
1721                   eval "\$$x++";  # CASE 5
1722                   $$x++;          # CASE 6
1723
1724               Cases 1 and 2 above behave identically: they run the code
1725               contained in the variable $x.  (Although case 2 has misleading
1726               double quotes making the reader wonder what else might be
1727               happening (nothing is).)  Cases 3 and 4 likewise behave in the
1728               same way: they run the code '$x', which does nothing but return
1729               the value of $x.  (Case 4 is preferred for purely visual
1730               reasons, but it also has the advantage of compiling at compile-
1731               time instead of at run-time.)  Case 5 is a place where normally
1732               you would like to use double quotes, except that in this
1733               particular situation, you can just use symbolic references
1734               instead, as in case 6.
1735
1736               An "eval ''" executed within a subroutine defined in the "DB"
1737               package doesn't see the usual surrounding lexical scope, but
1738               rather the scope of the first non-DB piece of code that called
1739               it.  You don't normally need to worry about this unless you are
1740               writing a Perl debugger.
1741
1742               The final semicolon, if any, may be omitted from the value of
1743               EXPR.
1744
1745           Block eval
1746               If the code to be executed doesn't vary, you may use the eval-
1747               BLOCK form to trap run-time errors without incurring the
1748               penalty of recompiling each time.  The error, if any, is still
1749               returned in $@.  Examples:
1750
1751                   # make divide-by-zero nonfatal
1752                   eval { $answer = $a / $b; }; warn $@ if $@;
1753
1754                   # same thing, but less efficient
1755                   eval '$answer = $a / $b'; warn $@ if $@;
1756
1757                   # a compile-time error
1758                   eval { $answer = }; # WRONG
1759
1760                   # a run-time error
1761                   eval '$answer =';   # sets $@
1762
1763               If you want to trap errors when loading an XS module, some
1764               problems with the binary interface (such as Perl version skew)
1765               may be fatal even with "eval" unless $ENV{PERL_DL_NONLAZY} is
1766               set.  See perlrun.
1767
1768               Using the "eval {}" form as an exception trap in libraries does
1769               have some issues.  Due to the current arguably broken state of
1770               "__DIE__" hooks, you may wish not to trigger any "__DIE__"
1771               hooks that user code may have installed.  You can use the
1772               "local $SIG{__DIE__}" construct for this purpose, as this
1773               example shows:
1774
1775                   # a private exception trap for divide-by-zero
1776                   eval { local $SIG{'__DIE__'}; $answer = $a / $b; };
1777                   warn $@ if $@;
1778
1779               This is especially significant, given that "__DIE__" hooks can
1780               call "die" again, which has the effect of changing their error
1781               messages:
1782
1783                   # __DIE__ hooks may modify error messages
1784                   {
1785                      local $SIG{'__DIE__'} =
1786                             sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
1787                      eval { die "foo lives here" };
1788                      print $@ if $@;                # prints "bar lives here"
1789                   }
1790
1791               Because this promotes action at a distance, this
1792               counterintuitive behavior may be fixed in a future release.
1793
1794               "eval BLOCK" does not count as a loop, so the loop control
1795               statements "next", "last", or "redo" cannot be used to leave or
1796               restart the block.
1797
1798               The final semicolon, if any, may be omitted from within the
1799               BLOCK.
1800
1801       evalbytes EXPR
1802       evalbytes
1803           This function is similar to a string eval, except it always parses
1804           its argument (or $_ if EXPR is omitted) as a string of independent
1805           bytes.
1806
1807           If called when "use utf8" is in effect, the string will be assumed
1808           to be encoded in UTF-8, and "evalbytes" will make a temporary copy
1809           to work from, downgraded to non-UTF-8.  If this is not possible
1810           (because one or more characters in it require UTF-8), the
1811           "evalbytes" will fail with the error stored in $@.
1812
1813           Bytes that correspond to ASCII-range code points will have their
1814           normal meanings for operators in the string.  The treatment of the
1815           other bytes depends on if the "'unicode_strings"" feature is in
1816           effect.
1817
1818           Of course, variables that are UTF-8 and are referred to in the
1819           string retain that:
1820
1821            my $a = "\x{100}";
1822            evalbytes 'print ord $a, "\n"';
1823
1824           prints
1825
1826            256
1827
1828           and $@ is empty.
1829
1830           Source filters activated within the evaluated code apply to the
1831           code itself.
1832
1833           "evalbytes" is available starting in Perl v5.16.  To access it, you
1834           must say "CORE::evalbytes", but you can omit the "CORE::" if the
1835           "evalbytes" feature is enabled.  This is enabled automatically with
1836           a "use v5.16" (or higher) declaration in the current scope.
1837
1838       exec LIST
1839       exec PROGRAM LIST
1840           The "exec" function executes a system command and never returns;
1841           use "system" instead of "exec" if you want it to return.  It fails
1842           and returns false only if the command does not exist and it is
1843           executed directly instead of via your system's command shell (see
1844           below).
1845
1846           Since it's a common mistake to use "exec" instead of "system", Perl
1847           warns you if "exec" is called in void context and if there is a
1848           following statement that isn't "die", "warn", or "exit" (if
1849           warnings are enabled--but you always do that, right?).  If you
1850           really want to follow an "exec" with some other statement, you can
1851           use one of these styles to avoid the warning:
1852
1853               exec ('foo')   or print STDERR "couldn't exec foo: $!";
1854               { exec ('foo') }; print STDERR "couldn't exec foo: $!";
1855
1856           If there is more than one argument in LIST, this calls execvp(3)
1857           with the arguments in LIST.  If there is only one element in LIST,
1858           the argument is checked for shell metacharacters, and if there are
1859           any, the entire argument is passed to the system's command shell
1860           for parsing (this is "/bin/sh -c" on Unix platforms, but varies on
1861           other platforms).  If there are no shell metacharacters in the
1862           argument, it is split into words and passed directly to "execvp",
1863           which is more efficient.  Examples:
1864
1865               exec '/bin/echo', 'Your arguments are: ', @ARGV;
1866               exec "sort $outfile | uniq";
1867
1868           If you don't really want to execute the first argument, but want to
1869           lie to the program you are executing about its own name, you can
1870           specify the program you actually want to run as an "indirect
1871           object" (without a comma) in front of the LIST, as in "exec PROGRAM
1872           LIST".  (This always forces interpretation of the LIST as a
1873           multivalued list, even if there is only a single scalar in the
1874           list.)  Example:
1875
1876               my $shell = '/bin/csh';
1877               exec $shell '-sh';    # pretend it's a login shell
1878
1879           or, more directly,
1880
1881               exec {'/bin/csh'} '-sh';  # pretend it's a login shell
1882
1883           When the arguments get executed via the system shell, results are
1884           subject to its quirks and capabilities.  See "`STRING`" in perlop
1885           for details.
1886
1887           Using an indirect object with "exec" or "system" is also more
1888           secure.  This usage (which also works fine with "system") forces
1889           interpretation of the arguments as a multivalued list, even if the
1890           list had just one argument.  That way you're safe from the shell
1891           expanding wildcards or splitting up words with whitespace in them.
1892
1893               my @args = ( "echo surprise" );
1894
1895               exec @args;               # subject to shell escapes
1896                                           # if @args == 1
1897               exec { $args[0] } @args;  # safe even with one-arg list
1898
1899           The first version, the one without the indirect object, ran the
1900           echo program, passing it "surprise" an argument.  The second
1901           version didn't; it tried to run a program named "echo surprise",
1902           didn't find it, and set $? to a non-zero value indicating failure.
1903
1904           On Windows, only the "exec PROGRAM LIST" indirect object syntax
1905           will reliably avoid using the shell; "exec LIST", even with more
1906           than one element, will fall back to the shell if the first spawn
1907           fails.
1908
1909           Perl attempts to flush all files opened for output before the exec,
1910           but this may not be supported on some platforms (see perlport).  To
1911           be safe, you may need to set $| ($AUTOFLUSH in English) or call the
1912           "autoflush" method of "IO::Handle" on any open handles to avoid
1913           lost output.
1914
1915           Note that "exec" will not call your "END" blocks, nor will it
1916           invoke "DESTROY" methods on your objects.
1917
1918           Portability issues: "exec" in perlport.
1919
1920       exists EXPR
1921           Given an expression that specifies an element of a hash, returns
1922           true if the specified element in the hash has ever been
1923           initialized, even if the corresponding value is undefined.
1924
1925               print "Exists\n"    if exists $hash{$key};
1926               print "Defined\n"   if defined $hash{$key};
1927               print "True\n"      if $hash{$key};
1928
1929           exists may also be called on array elements, but its behavior is
1930           much less obvious and is strongly tied to the use of "delete" on
1931           arrays.
1932
1933           WARNING: Calling "exists" on array values is strongly discouraged.
1934           The notion of deleting or checking the existence of Perl array
1935           elements is not conceptually coherent, and can lead to surprising
1936           behavior.
1937
1938               print "Exists\n"    if exists $array[$index];
1939               print "Defined\n"   if defined $array[$index];
1940               print "True\n"      if $array[$index];
1941
1942           A hash or array element can be true only if it's defined and
1943           defined only if it exists, but the reverse doesn't necessarily hold
1944           true.
1945
1946           Given an expression that specifies the name of a subroutine,
1947           returns true if the specified subroutine has ever been declared,
1948           even if it is undefined.  Mentioning a subroutine name for exists
1949           or defined does not count as declaring it.  Note that a subroutine
1950           that does not exist may still be callable: its package may have an
1951           "AUTOLOAD" method that makes it spring into existence the first
1952           time that it is called; see perlsub.
1953
1954               print "Exists\n"  if exists &subroutine;
1955               print "Defined\n" if defined &subroutine;
1956
1957           Note that the EXPR can be arbitrarily complicated as long as the
1958           final operation is a hash or array key lookup or subroutine name:
1959
1960               if (exists $ref->{A}->{B}->{$key})  { }
1961               if (exists $hash{A}{B}{$key})       { }
1962
1963               if (exists $ref->{A}->{B}->[$ix])   { }
1964               if (exists $hash{A}{B}[$ix])        { }
1965
1966               if (exists &{$ref->{A}{B}{$key}})   { }
1967
1968           Although the most deeply nested array or hash element will not
1969           spring into existence just because its existence was tested, any
1970           intervening ones will.  Thus "$ref->{"A"}" and "$ref->{"A"}->{"B"}"
1971           will spring into existence due to the existence test for the $key
1972           element above.  This happens anywhere the arrow operator is used,
1973           including even here:
1974
1975               undef $ref;
1976               if (exists $ref->{"Some key"})    { }
1977               print $ref;  # prints HASH(0x80d3d5c)
1978
1979           This surprising autovivification in what does not at first--or even
1980           second--glance appear to be an lvalue context may be fixed in a
1981           future release.
1982
1983           Use of a subroutine call, rather than a subroutine name, as an
1984           argument to "exists" is an error.
1985
1986               exists &sub;    # OK
1987               exists &sub();  # Error
1988
1989       exit EXPR
1990       exit
1991           Evaluates EXPR and exits immediately with that value.    Example:
1992
1993               my $ans = <STDIN>;
1994               exit 0 if $ans =~ /^[Xx]/;
1995
1996           See also "die".  If EXPR is omitted, exits with 0 status.  The only
1997           universally recognized values for EXPR are 0 for success and 1 for
1998           error; other values are subject to interpretation depending on the
1999           environment in which the Perl program is running.  For example,
2000           exiting 69 (EX_UNAVAILABLE) from a sendmail incoming-mail filter
2001           will cause the mailer to return the item undelivered, but that's
2002           not true everywhere.
2003
2004           Don't use "exit" to abort a subroutine if there's any chance that
2005           someone might want to trap whatever error happened.  Use "die"
2006           instead, which can be trapped by an "eval".
2007
2008           The "exit" function does not always exit immediately.  It calls any
2009           defined "END" routines first, but these "END" routines may not
2010           themselves abort the exit.  Likewise any object destructors that
2011           need to be called are called before the real exit.  "END" routines
2012           and destructors can change the exit status by modifying $?.  If
2013           this is a problem, you can call "POSIX::_exit($status)" to avoid
2014           "END" and destructor processing.  See perlmod for details.
2015
2016           Portability issues: "exit" in perlport.
2017
2018       exp EXPR
2019       exp Returns e (the natural logarithm base) to the power of EXPR.  If
2020           EXPR is omitted, gives "exp($_)".
2021
2022       fc EXPR
2023       fc  Returns the casefolded version of EXPR.  This is the internal
2024           function implementing the "\F" escape in double-quoted strings.
2025
2026           Casefolding is the process of mapping strings to a form where case
2027           differences are erased; comparing two strings in their casefolded
2028           form is effectively a way of asking if two strings are equal,
2029           regardless of case.
2030
2031           Roughly, if you ever found yourself writing this
2032
2033               lc($this) eq lc($that)    # Wrong!
2034                   # or
2035               uc($this) eq uc($that)    # Also wrong!
2036                   # or
2037               $this =~ /^\Q$that\E\z/i  # Right!
2038
2039           Now you can write
2040
2041               fc($this) eq fc($that)
2042
2043           And get the correct results.
2044
2045           Perl only implements the full form of casefolding, but you can
2046           access the simple folds using "casefold()" in Unicode::UCD and
2047           "prop_invmap()" in Unicode::UCD.  For further information on
2048           casefolding, refer to the Unicode Standard, specifically sections
2049           3.13 "Default Case Operations", 4.2 "Case-Normative", and 5.18
2050           "Case Mappings", available at
2051           <http://www.unicode.org/versions/latest/>, as well as the Case
2052           Charts available at <http://www.unicode.org/charts/case/>.
2053
2054           If EXPR is omitted, uses $_.
2055
2056           This function behaves the same way under various pragmas, such as
2057           within "use feature 'unicode_strings", as "lc" does, with the
2058           single exception of "fc" of LATIN CAPITAL LETTER SHARP S (U+1E9E)
2059           within the scope of "use locale".  The foldcase of this character
2060           would normally be "ss", but as explained in the "lc" section, case
2061           changes that cross the 255/256 boundary are problematic under
2062           locales, and are hence prohibited.  Therefore, this function under
2063           locale returns instead the string "\x{17F}\x{17F}", which is the
2064           LATIN SMALL LETTER LONG S.  Since that character itself folds to
2065           "s", the string of two of them together should be equivalent to a
2066           single U+1E9E when foldcased.
2067
2068           While the Unicode Standard defines two additional forms of
2069           casefolding, one for Turkic languages and one that never maps one
2070           character into multiple characters, these are not provided by the
2071           Perl core.  However, the CPAN module "Unicode::Casing" may be used
2072           to provide an implementation.
2073
2074           "fc" is available only if the "fc" feature is enabled or if it is
2075           prefixed with "CORE::".  The "fc" feature is enabled automatically
2076           with a "use v5.16" (or higher) declaration in the current scope.
2077
2078       fcntl FILEHANDLE,FUNCTION,SCALAR
2079           Implements the fcntl(2) function.  You'll probably have to say
2080
2081               use Fcntl;
2082
2083           first to get the correct constant definitions.  Argument processing
2084           and value returned work just like "ioctl" below.  For example:
2085
2086               use Fcntl;
2087               my $flags = fcntl($filehandle, F_GETFL, 0)
2088                   or die "Can't fcntl F_GETFL: $!";
2089
2090           You don't have to check for "defined" on the return from "fcntl".
2091           Like "ioctl", it maps a 0 return from the system call into "0 but
2092           true" in Perl.  This string is true in boolean context and 0 in
2093           numeric context.  It is also exempt from the normal "Argument "..."
2094           isn't numeric" warnings on improper numeric conversions.
2095
2096           Note that "fcntl" raises an exception if used on a machine that
2097           doesn't implement fcntl(2).  See the Fcntl module or your fcntl(2)
2098           manpage to learn what functions are available on your system.
2099
2100           Here's an example of setting a filehandle named $REMOTE to be non-
2101           blocking at the system level.  You'll have to negotiate $| on your
2102           own, though.
2103
2104               use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
2105
2106               my $flags = fcntl($REMOTE, F_GETFL, 0)
2107                   or die "Can't get flags for the socket: $!\n";
2108
2109               fcntl($REMOTE, F_SETFL, $flags | O_NONBLOCK)
2110                   or die "Can't set flags for the socket: $!\n";
2111
2112           Portability issues: "fcntl" in perlport.
2113
2114       __FILE__
2115           A special token that returns the name of the file in which it
2116           occurs.
2117
2118       fileno FILEHANDLE
2119           Returns the file descriptor for a filehandle, or undefined if the
2120           filehandle is not open.  If there is no real file descriptor at the
2121           OS level, as can happen with filehandles connected to memory
2122           objects via "open" with a reference for the third argument, -1 is
2123           returned.
2124
2125           This is mainly useful for constructing bitmaps for "select" and
2126           low-level POSIX tty-handling operations.  If FILEHANDLE is an
2127           expression, the value is taken as an indirect filehandle, generally
2128           its name.
2129
2130           You can use this to find out whether two handles refer to the same
2131           underlying descriptor:
2132
2133               if (fileno($this) != -1 && fileno($this) == fileno($that)) {
2134                   print "\$this and \$that are dups\n";
2135               } elsif (fileno($this) != -1 && fileno($that) != -1) {
2136                   print "\$this and \$that have different " .
2137                       "underlying file descriptors\n";
2138               } else {
2139                   print "At least one of \$this and \$that does " .
2140                       "not have a real file descriptor\n";
2141               }
2142
2143           The behavior of "fileno" on a directory handle depends on the
2144           operating system.  On a system with dirfd(3) or similar, "fileno"
2145           on a directory handle returns the underlying file descriptor
2146           associated with the handle; on systems with no such support, it
2147           returns the undefined value, and sets $! (errno).
2148
2149       flock FILEHANDLE,OPERATION
2150           Calls flock(2), or an emulation of it, on FILEHANDLE.  Returns true
2151           for success, false on failure.  Produces a fatal error if used on a
2152           machine that doesn't implement flock(2), fcntl(2) locking, or
2153           lockf(3).  "flock" is Perl's portable file-locking interface,
2154           although it locks entire files only, not records.
2155
2156           Two potentially non-obvious but traditional "flock" semantics are
2157           that it waits indefinitely until the lock is granted, and that its
2158           locks are merely advisory.  Such discretionary locks are more
2159           flexible, but offer fewer guarantees.  This means that programs
2160           that do not also use "flock" may modify files locked with "flock".
2161           See perlport, your port's specific documentation, and your system-
2162           specific local manpages for details.  It's best to assume
2163           traditional behavior if you're writing portable programs.  (But if
2164           you're not, you should as always feel perfectly free to write for
2165           your own system's idiosyncrasies (sometimes called "features").
2166           Slavish adherence to portability concerns shouldn't get in the way
2167           of your getting your job done.)
2168
2169           OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined
2170           with LOCK_NB.  These constants are traditionally valued 1, 2, 8 and
2171           4, but you can use the symbolic names if you import them from the
2172           Fcntl module, either individually, or as a group using the ":flock"
2173           tag.  LOCK_SH requests a shared lock, LOCK_EX requests an exclusive
2174           lock, and LOCK_UN releases a previously requested lock.  If LOCK_NB
2175           is bitwise-or'ed with LOCK_SH or LOCK_EX, then "flock" returns
2176           immediately rather than blocking waiting for the lock; check the
2177           return status to see if you got it.
2178
2179           To avoid the possibility of miscoordination, Perl now flushes
2180           FILEHANDLE before locking or unlocking it.
2181
2182           Note that the emulation built with lockf(3) doesn't provide shared
2183           locks, and it requires that FILEHANDLE be open with write intent.
2184           These are the semantics that lockf(3) implements.  Most if not all
2185           systems implement lockf(3) in terms of fcntl(2) locking, though, so
2186           the differing semantics shouldn't bite too many people.
2187
2188           Note that the fcntl(2) emulation of flock(3) requires that
2189           FILEHANDLE be open with read intent to use LOCK_SH and requires
2190           that it be open with write intent to use LOCK_EX.
2191
2192           Note also that some versions of "flock" cannot lock things over the
2193           network; you would need to use the more system-specific "fcntl" for
2194           that.  If you like you can force Perl to ignore your system's
2195           flock(2) function, and so provide its own fcntl(2)-based emulation,
2196           by passing the switch "-Ud_flock" to the Configure program when you
2197           configure and build a new Perl.
2198
2199           Here's a mailbox appender for BSD systems.
2200
2201               # import LOCK_* and SEEK_END constants
2202               use Fcntl qw(:flock SEEK_END);
2203
2204               sub lock {
2205                   my ($fh) = @_;
2206                   flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n";
2207
2208                   # and, in case someone appended while we were waiting...
2209                   seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n";
2210               }
2211
2212               sub unlock {
2213                   my ($fh) = @_;
2214                   flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n";
2215               }
2216
2217               open(my $mbox, ">>", "/usr/spool/mail/$ENV{'USER'}")
2218                   or die "Can't open mailbox: $!";
2219
2220               lock($mbox);
2221               print $mbox $msg,"\n\n";
2222               unlock($mbox);
2223
2224           On systems that support a real flock(2), locks are inherited across
2225           "fork" calls, whereas those that must resort to the more capricious
2226           fcntl(2) function lose their locks, making it seriously harder to
2227           write servers.
2228
2229           See also DB_File for other "flock" examples.
2230
2231           Portability issues: "flock" in perlport.
2232
2233       fork
2234           Does a fork(2) system call to create a new process running the same
2235           program at the same point.  It returns the child pid to the parent
2236           process, 0 to the child process, or "undef" if the fork is
2237           unsuccessful.  File descriptors (and sometimes locks on those
2238           descriptors) are shared, while everything else is copied.  On most
2239           systems supporting fork(2), great care has gone into making it
2240           extremely efficient (for example, using copy-on-write technology on
2241           data pages), making it the dominant paradigm for multitasking over
2242           the last few decades.
2243
2244           Perl attempts to flush all files opened for output before forking
2245           the child process, but this may not be supported on some platforms
2246           (see perlport).  To be safe, you may need to set $| ($AUTOFLUSH in
2247           English) or call the "autoflush" method of "IO::Handle" on any open
2248           handles to avoid duplicate output.
2249
2250           If you "fork" without ever waiting on your children, you will
2251           accumulate zombies.  On some systems, you can avoid this by setting
2252           $SIG{CHLD} to "IGNORE".  See also perlipc for more examples of
2253           forking and reaping moribund children.
2254
2255           Note that if your forked child inherits system file descriptors
2256           like STDIN and STDOUT that are actually connected by a pipe or
2257           socket, even if you exit, then the remote server (such as, say, a
2258           CGI script or a backgrounded job launched from a remote shell)
2259           won't think you're done.  You should reopen those to /dev/null if
2260           it's any issue.
2261
2262           On some platforms such as Windows, where the fork(2) system call is
2263           not available, Perl can be built to emulate "fork" in the Perl
2264           interpreter.  The emulation is designed, at the level of the Perl
2265           program, to be as compatible as possible with the "Unix" fork(2).
2266           However it has limitations that have to be considered in code
2267           intended to be portable.  See perlfork for more details.
2268
2269           Portability issues: "fork" in perlport.
2270
2271       format
2272           Declare a picture format for use by the "write" function.  For
2273           example:
2274
2275               format Something =
2276                   Test: @<<<<<<<< @||||| @>>>>>
2277                         $str,     $%,    '$' . int($num)
2278               .
2279
2280               $str = "widget";
2281               $num = $cost/$quantity;
2282               $~ = 'Something';
2283               write;
2284
2285           See perlform for many details and examples.
2286
2287       formline PICTURE,LIST
2288           This is an internal function used by "format"s, though you may call
2289           it, too.  It formats (see perlform) a list of values according to
2290           the contents of PICTURE, placing the output into the format output
2291           accumulator, $^A (or $ACCUMULATOR in English).  Eventually, when a
2292           "write" is done, the contents of $^A are written to some
2293           filehandle.  You could also read $^A and then set $^A back to "".
2294           Note that a format typically does one "formline" per line of form,
2295           but the "formline" function itself doesn't care how many newlines
2296           are embedded in the PICTURE.  This means that the "~" and "~~"
2297           tokens treat the entire PICTURE as a single line.  You may
2298           therefore need to use multiple formlines to implement a single
2299           record format, just like the "format" compiler.
2300
2301           Be careful if you put double quotes around the picture, because an
2302           "@" character may be taken to mean the beginning of an array name.
2303           "formline" always returns true.  See perlform for other examples.
2304
2305           If you are trying to use this instead of "write" to capture the
2306           output, you may find it easier to open a filehandle to a scalar
2307           ("open my $fh, ">", \$output") and write to that instead.
2308
2309       getc FILEHANDLE
2310       getc
2311           Returns the next character from the input file attached to
2312           FILEHANDLE, or the undefined value at end of file or if there was
2313           an error (in the latter case $! is set).  If FILEHANDLE is omitted,
2314           reads from STDIN.  This is not particularly efficient.  However, it
2315           cannot be used by itself to fetch single characters without waiting
2316           for the user to hit enter.  For that, try something more like:
2317
2318               if ($BSD_STYLE) {
2319                   system "stty cbreak </dev/tty >/dev/tty 2>&1";
2320               }
2321               else {
2322                   system "stty", '-icanon', 'eol', "\001";
2323               }
2324
2325               my $key = getc(STDIN);
2326
2327               if ($BSD_STYLE) {
2328                   system "stty -cbreak </dev/tty >/dev/tty 2>&1";
2329               }
2330               else {
2331                   system 'stty', 'icanon', 'eol', '^@'; # ASCII NUL
2332               }
2333               print "\n";
2334
2335           Determination of whether $BSD_STYLE should be set is left as an
2336           exercise to the reader.
2337
2338           The "POSIX::getattr" function can do this more portably on systems
2339           purporting POSIX compliance.  See also the "Term::ReadKey" module
2340           on CPAN.
2341
2342       getlogin
2343           This implements the C library function of the same name, which on
2344           most systems returns the current login from /etc/utmp, if any.  If
2345           it returns the empty string, use "getpwuid".
2346
2347               my $login = getlogin || getpwuid($<) || "Kilroy";
2348
2349           Do not consider "getlogin" for authentication: it is not as secure
2350           as "getpwuid".
2351
2352           Portability issues: "getlogin" in perlport.
2353
2354       getpeername SOCKET
2355           Returns the packed sockaddr address of the other end of the SOCKET
2356           connection.
2357
2358               use Socket;
2359               my $hersockaddr    = getpeername($sock);
2360               my ($port, $iaddr) = sockaddr_in($hersockaddr);
2361               my $herhostname    = gethostbyaddr($iaddr, AF_INET);
2362               my $herstraddr     = inet_ntoa($iaddr);
2363
2364       getpgrp PID
2365           Returns the current process group for the specified PID.  Use a PID
2366           of 0 to get the current process group for the current process.
2367           Will raise an exception if used on a machine that doesn't implement
2368           getpgrp(2).  If PID is omitted, returns the process group of the
2369           current process.  Note that the POSIX version of "getpgrp" does not
2370           accept a PID argument, so only "PID==0" is truly portable.
2371
2372           Portability issues: "getpgrp" in perlport.
2373
2374       getppid
2375           Returns the process id of the parent process.
2376
2377           Note for Linux users: Between v5.8.1 and v5.16.0 Perl would work
2378           around non-POSIX thread semantics the minority of Linux systems
2379           (and Debian GNU/kFreeBSD systems) that used LinuxThreads, this
2380           emulation has since been removed.  See the documentation for $$ for
2381           details.
2382
2383           Portability issues: "getppid" in perlport.
2384
2385       getpriority WHICH,WHO
2386           Returns the current priority for a process, a process group, or a
2387           user.  (See getpriority(2).)  Will raise a fatal exception if used
2388           on a machine that doesn't implement getpriority(2).
2389
2390           Portability issues: "getpriority" in perlport.
2391
2392       getpwnam NAME
2393       getgrnam NAME
2394       gethostbyname NAME
2395       getnetbyname NAME
2396       getprotobyname NAME
2397       getpwuid UID
2398       getgrgid GID
2399       getservbyname NAME,PROTO
2400       gethostbyaddr ADDR,ADDRTYPE
2401       getnetbyaddr ADDR,ADDRTYPE
2402       getprotobynumber NUMBER
2403       getservbyport PORT,PROTO
2404       getpwent
2405       getgrent
2406       gethostent
2407       getnetent
2408       getprotoent
2409       getservent
2410       setpwent
2411       setgrent
2412       sethostent STAYOPEN
2413       setnetent STAYOPEN
2414       setprotoent STAYOPEN
2415       setservent STAYOPEN
2416       endpwent
2417       endgrent
2418       endhostent
2419       endnetent
2420       endprotoent
2421       endservent
2422           These routines are the same as their counterparts in the system C
2423           library.  In list context, the return values from the various get
2424           routines are as follows:
2425
2426            #    0        1          2           3         4
2427            my ( $name,   $passwd,   $gid,       $members  ) = getgr*
2428            my ( $name,   $aliases,  $addrtype,  $net      ) = getnet*
2429            my ( $name,   $aliases,  $port,      $proto    ) = getserv*
2430            my ( $name,   $aliases,  $proto                ) = getproto*
2431            my ( $name,   $aliases,  $addrtype,  $length,  @addrs ) = gethost*
2432            my ( $name,   $passwd,   $uid,       $gid,     $quota,
2433               $comment,  $gcos,     $dir,       $shell,   $expire ) = getpw*
2434            #    5        6          7           8         9
2435
2436           (If the entry doesn't exist, the return value is a single
2437           meaningless true value.)
2438
2439           The exact meaning of the $gcos field varies but it usually contains
2440           the real name of the user (as opposed to the login name) and other
2441           information pertaining to the user.  Beware, however, that in many
2442           system users are able to change this information and therefore it
2443           cannot be trusted and therefore the $gcos is tainted (see perlsec).
2444           The $passwd and $shell, user's encrypted password and login shell,
2445           are also tainted, for the same reason.
2446
2447           In scalar context, you get the name, unless the function was a
2448           lookup by name, in which case you get the other thing, whatever it
2449           is.  (If the entry doesn't exist you get the undefined value.)  For
2450           example:
2451
2452               my $uid   = getpwnam($name);
2453               my $name  = getpwuid($num);
2454               my $name  = getpwent();
2455               my $gid   = getgrnam($name);
2456               my $name  = getgrgid($num);
2457               my $name  = getgrent();
2458               # etc.
2459
2460           In getpw*() the fields $quota, $comment, and $expire are special in
2461           that they are unsupported on many systems.  If the $quota is
2462           unsupported, it is an empty scalar.  If it is supported, it usually
2463           encodes the disk quota.  If the $comment field is unsupported, it
2464           is an empty scalar.  If it is supported it usually encodes some
2465           administrative comment about the user.  In some systems the $quota
2466           field may be $change or $age, fields that have to do with password
2467           aging.  In some systems the $comment field may be $class.  The
2468           $expire field, if present, encodes the expiration period of the
2469           account or the password.  For the availability and the exact
2470           meaning of these fields in your system, please consult getpwnam(3)
2471           and your system's pwd.h file.  You can also find out from within
2472           Perl what your $quota and $comment fields mean and whether you have
2473           the $expire field by using the "Config" module and the values
2474           "d_pwquota", "d_pwage", "d_pwchange", "d_pwcomment", and
2475           "d_pwexpire".  Shadow password files are supported only if your
2476           vendor has implemented them in the intuitive fashion that calling
2477           the regular C library routines gets the shadow versions if you're
2478           running under privilege or if there exists the shadow(3) functions
2479           as found in System V (this includes Solaris and Linux).  Those
2480           systems that implement a proprietary shadow password facility are
2481           unlikely to be supported.
2482
2483           The $members value returned by getgr*() is a space-separated list
2484           of the login names of the members of the group.
2485
2486           For the gethost*() functions, if the "h_errno" variable is
2487           supported in C, it will be returned to you via $? if the function
2488           call fails.  The @addrs value returned by a successful call is a
2489           list of raw addresses returned by the corresponding library call.
2490           In the Internet domain, each address is four bytes long; you can
2491           unpack it by saying something like:
2492
2493               my ($w,$x,$y,$z) = unpack('W4',$addr[0]);
2494
2495           The Socket library makes this slightly easier:
2496
2497               use Socket;
2498               my $iaddr = inet_aton("127.1"); # or whatever address
2499               my $name  = gethostbyaddr($iaddr, AF_INET);
2500
2501               # or going the other way
2502               my $straddr = inet_ntoa($iaddr);
2503
2504           In the opposite way, to resolve a hostname to the IP address you
2505           can write this:
2506
2507               use Socket;
2508               my $packed_ip = gethostbyname("www.perl.org");
2509               my $ip_address;
2510               if (defined $packed_ip) {
2511                   $ip_address = inet_ntoa($packed_ip);
2512               }
2513
2514           Make sure "gethostbyname" is called in SCALAR context and that its
2515           return value is checked for definedness.
2516
2517           The "getprotobynumber" function, even though it only takes one
2518           argument, has the precedence of a list operator, so beware:
2519
2520               getprotobynumber $number eq 'icmp'   # WRONG
2521               getprotobynumber($number eq 'icmp')  # actually means this
2522               getprotobynumber($number) eq 'icmp'  # better this way
2523
2524           If you get tired of remembering which element of the return list
2525           contains which return value, by-name interfaces are provided in
2526           standard modules: "File::stat", "Net::hostent", "Net::netent",
2527           "Net::protoent", "Net::servent", "Time::gmtime", "Time::localtime",
2528           and "User::grent".  These override the normal built-ins, supplying
2529           versions that return objects with the appropriate names for each
2530           field.  For example:
2531
2532              use File::stat;
2533              use User::pwent;
2534              my $is_his = (stat($filename)->uid == pwent($whoever)->uid);
2535
2536           Even though it looks as though they're the same method calls (uid),
2537           they aren't, because a "File::stat" object is different from a
2538           "User::pwent" object.
2539
2540           Portability issues: "getpwnam" in perlport to "endservent" in
2541           perlport.
2542
2543       getsockname SOCKET
2544           Returns the packed sockaddr address of this end of the SOCKET
2545           connection, in case you don't know the address because you have
2546           several different IPs that the connection might have come in on.
2547
2548               use Socket;
2549               my $mysockaddr = getsockname($sock);
2550               my ($port, $myaddr) = sockaddr_in($mysockaddr);
2551               printf "Connect to %s [%s]\n",
2552                  scalar gethostbyaddr($myaddr, AF_INET),
2553                  inet_ntoa($myaddr);
2554
2555       getsockopt SOCKET,LEVEL,OPTNAME
2556           Queries the option named OPTNAME associated with SOCKET at a given
2557           LEVEL.  Options may exist at multiple protocol levels depending on
2558           the socket type, but at least the uppermost socket level SOL_SOCKET
2559           (defined in the "Socket" module) will exist.  To query options at
2560           another level the protocol number of the appropriate protocol
2561           controlling the option should be supplied.  For example, to
2562           indicate that an option is to be interpreted by the TCP protocol,
2563           LEVEL should be set to the protocol number of TCP, which you can
2564           get using "getprotobyname".
2565
2566           The function returns a packed string representing the requested
2567           socket option, or "undef" on error, with the reason for the error
2568           placed in $!.  Just what is in the packed string depends on LEVEL
2569           and OPTNAME; consult getsockopt(2) for details.  A common case is
2570           that the option is an integer, in which case the result is a packed
2571           integer, which you can decode using "unpack" with the "i" (or "I")
2572           format.
2573
2574           Here's an example to test whether Nagle's algorithm is enabled on a
2575           socket:
2576
2577               use Socket qw(:all);
2578
2579               defined(my $tcp = getprotobyname("tcp"))
2580                   or die "Could not determine the protocol number for tcp";
2581               # my $tcp = IPPROTO_TCP; # Alternative
2582               my $packed = getsockopt($socket, $tcp, TCP_NODELAY)
2583                   or die "getsockopt TCP_NODELAY: $!";
2584               my $nodelay = unpack("I", $packed);
2585               print "Nagle's algorithm is turned ",
2586                      $nodelay ? "off\n" : "on\n";
2587
2588           Portability issues: "getsockopt" in perlport.
2589
2590       glob EXPR
2591       glob
2592           In list context, returns a (possibly empty) list of filename
2593           expansions on the value of EXPR such as the standard Unix shell
2594           /bin/csh would do.  In scalar context, glob iterates through such
2595           filename expansions, returning undef when the list is exhausted.
2596           This is the internal function implementing the "<*.c>" operator,
2597           but you can use it directly.  If EXPR is omitted, $_ is used.  The
2598           "<*.c>" operator is discussed in more detail in "I/O Operators" in
2599           perlop.
2600
2601           Note that "glob" splits its arguments on whitespace and treats each
2602           segment as separate pattern.  As such, "glob("*.c *.h")" matches
2603           all files with a .c or .h extension.  The expression "glob(".* *")"
2604           matches all files in the current working directory.  If you want to
2605           glob filenames that might contain whitespace, you'll have to use
2606           extra quotes around the spacey filename to protect it.  For
2607           example, to glob filenames that have an "e" followed by a space
2608           followed by an "f", use one of:
2609
2610               my @spacies = <"*e f*">;
2611               my @spacies = glob '"*e f*"';
2612               my @spacies = glob q("*e f*");
2613
2614           If you had to get a variable through, you could do this:
2615
2616               my @spacies = glob "'*${var}e f*'";
2617               my @spacies = glob qq("*${var}e f*");
2618
2619           If non-empty braces are the only wildcard characters used in the
2620           "glob", no filenames are matched, but potentially many strings are
2621           returned.  For example, this produces nine strings, one for each
2622           pairing of fruits and colors:
2623
2624               my @many = glob "{apple,tomato,cherry}={green,yellow,red}";
2625
2626           This operator is implemented using the standard "File::Glob"
2627           extension.  See File::Glob for details, including "bsd_glob", which
2628           does not treat whitespace as a pattern separator.
2629
2630           Portability issues: "glob" in perlport.
2631
2632       gmtime EXPR
2633       gmtime
2634           Works just like "localtime" but the returned values are localized
2635           for the standard Greenwich time zone.
2636
2637           Note: When called in list context, $isdst, the last value returned
2638           by gmtime, is always 0.  There is no Daylight Saving Time in GMT.
2639
2640           Portability issues: "gmtime" in perlport.
2641
2642       goto LABEL
2643       goto EXPR
2644       goto &NAME
2645           The "goto LABEL" form finds the statement labeled with LABEL and
2646           resumes execution there.  It can't be used to get out of a block or
2647           subroutine given to "sort".  It can be used to go almost anywhere
2648           else within the dynamic scope, including out of subroutines, but
2649           it's usually better to use some other construct such as "last" or
2650           "die".  The author of Perl has never felt the need to use this form
2651           of "goto" (in Perl, that is; C is another matter).  (The difference
2652           is that C does not offer named loops combined with loop control.
2653           Perl does, and this replaces most structured uses of "goto" in
2654           other languages.)
2655
2656           The "goto EXPR" form expects to evaluate "EXPR" to a code reference
2657           or a label name.  If it evaluates to a code reference, it will be
2658           handled like "goto &NAME", below.  This is especially useful for
2659           implementing tail recursion via "goto __SUB__".
2660
2661           If the expression evaluates to a label name, its scope will be
2662           resolved dynamically.  This allows for computed "goto"s per
2663           FORTRAN, but isn't necessarily recommended if you're optimizing for
2664           maintainability:
2665
2666               goto ("FOO", "BAR", "GLARCH")[$i];
2667
2668           As shown in this example, "goto EXPR" is exempt from the "looks
2669           like a function" rule.  A pair of parentheses following it does not
2670           (necessarily) delimit its argument.  "goto("NE")."XT"" is
2671           equivalent to "goto NEXT".  Also, unlike most named operators, this
2672           has the same precedence as assignment.
2673
2674           Use of "goto LABEL" or "goto EXPR" to jump into a construct is
2675           deprecated and will issue a warning.  Even then, it may not be used
2676           to go into any construct that requires initialization, such as a
2677           subroutine or a "foreach" loop.  It also can't be used to go into a
2678           construct that is optimized away.
2679
2680           The "goto &NAME" form is quite different from the other forms of
2681           "goto".  In fact, it isn't a goto in the normal sense at all, and
2682           doesn't have the stigma associated with other gotos.  Instead, it
2683           exits the current subroutine (losing any changes set by "local")
2684           and immediately calls in its place the named subroutine using the
2685           current value of @_.  This is used by "AUTOLOAD" subroutines that
2686           wish to load another subroutine and then pretend that the other
2687           subroutine had been called in the first place (except that any
2688           modifications to @_ in the current subroutine are propagated to the
2689           other subroutine.) After the "goto", not even "caller" will be able
2690           to tell that this routine was called first.
2691
2692           NAME needn't be the name of a subroutine; it can be a scalar
2693           variable containing a code reference or a block that evaluates to a
2694           code reference.
2695
2696       grep BLOCK LIST
2697       grep EXPR,LIST
2698           This is similar in spirit to, but not the same as, grep(1) and its
2699           relatives.  In particular, it is not limited to using regular
2700           expressions.
2701
2702           Evaluates the BLOCK or EXPR for each element of LIST (locally
2703           setting $_ to each element) and returns the list value consisting
2704           of those elements for which the expression evaluated to true.  In
2705           scalar context, returns the number of times the expression was
2706           true.
2707
2708               my @foo = grep(!/^#/, @bar);    # weed out comments
2709
2710           or equivalently,
2711
2712               my @foo = grep {!/^#/} @bar;    # weed out comments
2713
2714           Note that $_ is an alias to the list value, so it can be used to
2715           modify the elements of the LIST.  While this is useful and
2716           supported, it can cause bizarre results if the elements of LIST are
2717           not variables.  Similarly, grep returns aliases into the original
2718           list, much as a for loop's index variable aliases the list
2719           elements.  That is, modifying an element of a list returned by grep
2720           (for example, in a "foreach", "map" or another "grep") actually
2721           modifies the element in the original list.  This is usually
2722           something to be avoided when writing clear code.
2723
2724           See also "map" for a list composed of the results of the BLOCK or
2725           EXPR.
2726
2727       hex EXPR
2728       hex Interprets EXPR as a hex string and returns the corresponding
2729           numeric value.  If EXPR is omitted, uses $_.
2730
2731               print hex '0xAf'; # prints '175'
2732               print hex 'aF';   # same
2733               $valid_input =~ /\A(?:0?[xX])?(?:_?[0-9a-fA-F])*\z/
2734
2735           A hex string consists of hex digits and an optional "0x" or "x"
2736           prefix.  Each hex digit may be preceded by a single underscore,
2737           which will be ignored.  Any other character triggers a warning and
2738           causes the rest of the string to be ignored (even leading
2739           whitespace, unlike "oct").  Only integers can be represented, and
2740           integer overflow triggers a warning.
2741
2742           To convert strings that might start with any of 0, "0x", or "0b",
2743           see "oct".  To present something as hex, look into "printf",
2744           "sprintf", and "unpack".
2745
2746       import LIST
2747           There is no builtin "import" function.  It is just an ordinary
2748           method (subroutine) defined (or inherited) by modules that wish to
2749           export names to another module.  The "use" function calls the
2750           "import" method for the package used.  See also "use", perlmod, and
2751           Exporter.
2752
2753       index STR,SUBSTR,POSITION
2754       index STR,SUBSTR
2755           The index function searches for one string within another, but
2756           without the wildcard-like behavior of a full regular-expression
2757           pattern match.  It returns the position of the first occurrence of
2758           SUBSTR in STR at or after POSITION.  If POSITION is omitted, starts
2759           searching from the beginning of the string.  POSITION before the
2760           beginning of the string or after its end is treated as if it were
2761           the beginning or the end, respectively.  POSITION and the return
2762           value are based at zero.  If the substring is not found, "index"
2763           returns -1.
2764
2765       int EXPR
2766       int Returns the integer portion of EXPR.  If EXPR is omitted, uses $_.
2767           You should not use this function for rounding: one because it
2768           truncates towards 0, and two because machine representations of
2769           floating-point numbers can sometimes produce counterintuitive
2770           results.  For example, "int(-6.725/0.025)" produces -268 rather
2771           than the correct -269; that's because it's really more like
2772           -268.99999999999994315658 instead.  Usually, the "sprintf",
2773           "printf", or the "POSIX::floor" and "POSIX::ceil" functions will
2774           serve you better than will "int".
2775
2776       ioctl FILEHANDLE,FUNCTION,SCALAR
2777           Implements the ioctl(2) function.  You'll probably first have to
2778           say
2779
2780               require "sys/ioctl.ph";  # probably in
2781                                        # $Config{archlib}/sys/ioctl.ph
2782
2783           to get the correct function definitions.  If sys/ioctl.ph doesn't
2784           exist or doesn't have the correct definitions you'll have to roll
2785           your own, based on your C header files such as <sys/ioctl.h>.
2786           (There is a Perl script called h2ph that comes with the Perl kit
2787           that may help you in this, but it's nontrivial.)  SCALAR will be
2788           read and/or written depending on the FUNCTION; a C pointer to the
2789           string value of SCALAR will be passed as the third argument of the
2790           actual "ioctl" call.  (If SCALAR has no string value but does have
2791           a numeric value, that value will be passed rather than a pointer to
2792           the string value.  To guarantee this to be true, add a 0 to the
2793           scalar before using it.)  The "pack" and "unpack" functions may be
2794           needed to manipulate the values of structures used by "ioctl".
2795
2796           The return value of "ioctl" (and "fcntl") is as follows:
2797
2798               if OS returns:      then Perl returns:
2799                   -1               undefined value
2800                    0              string "0 but true"
2801               anything else           that number
2802
2803           Thus Perl returns true on success and false on failure, yet you can
2804           still easily determine the actual value returned by the operating
2805           system:
2806
2807               my $retval = ioctl(...) || -1;
2808               printf "System returned %d\n", $retval;
2809
2810           The special string "0 but true" is exempt from "Argument "..."
2811           isn't numeric" warnings on improper numeric conversions.
2812
2813           Portability issues: "ioctl" in perlport.
2814
2815       join EXPR,LIST
2816           Joins the separate strings of LIST into a single string with fields
2817           separated by the value of EXPR, and returns that new string.
2818           Example:
2819
2820              my $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
2821
2822           Beware that unlike "split", "join" doesn't take a pattern as its
2823           first argument.  Compare "split".
2824
2825       keys HASH
2826       keys ARRAY
2827           Called in list context, returns a list consisting of all the keys
2828           of the named hash, or in Perl 5.12 or later only, the indices of an
2829           array.  Perl releases prior to 5.12 will produce a syntax error if
2830           you try to use an array argument.  In scalar context, returns the
2831           number of keys or indices.
2832
2833           Hash entries are returned in an apparently random order.  The
2834           actual random order is specific to a given hash; the exact same
2835           series of operations on two hashes may result in a different order
2836           for each hash.  Any insertion into the hash may change the order,
2837           as will any deletion, with the exception that the most recent key
2838           returned by "each" or "keys" may be deleted without changing the
2839           order.  So long as a given hash is unmodified you may rely on
2840           "keys", "values" and "each" to repeatedly return the same order as
2841           each other.  See "Algorithmic Complexity Attacks" in perlsec for
2842           details on why hash order is randomized.  Aside from the guarantees
2843           provided here the exact details of Perl's hash algorithm and the
2844           hash traversal order are subject to change in any release of Perl.
2845           Tied hashes may behave differently to Perl's hashes with respect to
2846           changes in order on insertion and deletion of items.
2847
2848           As a side effect, calling "keys" resets the internal iterator of
2849           the HASH or ARRAY (see "each").  In particular, calling "keys" in
2850           void context resets the iterator with no other overhead.
2851
2852           Here is yet another way to print your environment:
2853
2854               my @keys = keys %ENV;
2855               my @values = values %ENV;
2856               while (@keys) {
2857                   print pop(@keys), '=', pop(@values), "\n";
2858               }
2859
2860           or how about sorted by key:
2861
2862               foreach my $key (sort(keys %ENV)) {
2863                   print $key, '=', $ENV{$key}, "\n";
2864               }
2865
2866           The returned values are copies of the original keys in the hash, so
2867           modifying them will not affect the original hash.  Compare
2868           "values".
2869
2870           To sort a hash by value, you'll need to use a "sort" function.
2871           Here's a descending numeric sort of a hash by its values:
2872
2873               foreach my $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
2874                   printf "%4d %s\n", $hash{$key}, $key;
2875               }
2876
2877           Used as an lvalue, "keys" allows you to increase the number of hash
2878           buckets allocated for the given hash.  This can gain you a measure
2879           of efficiency if you know the hash is going to get big.  (This is
2880           similar to pre-extending an array by assigning a larger number to
2881           $#array.)  If you say
2882
2883               keys %hash = 200;
2884
2885           then %hash will have at least 200 buckets allocated for it--256 of
2886           them, in fact, since it rounds up to the next power of two.  These
2887           buckets will be retained even if you do "%hash = ()", use "undef
2888           %hash" if you want to free the storage while %hash is still in
2889           scope.  You can't shrink the number of buckets allocated for the
2890           hash using "keys" in this way (but you needn't worry about doing
2891           this by accident, as trying has no effect).  "keys @array" in an
2892           lvalue context is a syntax error.
2893
2894           Starting with Perl 5.14, an experimental feature allowed "keys" to
2895           take a scalar expression. This experiment has been deemed
2896           unsuccessful, and was removed as of Perl 5.24.
2897
2898           To avoid confusing would-be users of your code who are running
2899           earlier versions of Perl with mysterious syntax errors, put this
2900           sort of thing at the top of your file to signal that your code will
2901           work only on Perls of a recent vintage:
2902
2903               use 5.012;  # so keys/values/each work on arrays
2904
2905           See also "each", "values", and "sort".
2906
2907       kill SIGNAL, LIST
2908       kill SIGNAL
2909           Sends a signal to a list of processes.  Returns the number of
2910           arguments that were successfully used to signal (which is not
2911           necessarily the same as the number of processes actually killed,
2912           e.g. where a process group is killed).
2913
2914               my $cnt = kill 'HUP', $child1, $child2;
2915               kill 'KILL', @goners;
2916
2917           SIGNAL may be either a signal name (a string) or a signal number.
2918           A signal name may start with a "SIG" prefix, thus "FOO" and
2919           "SIGFOO" refer to the same signal.  The string form of SIGNAL is
2920           recommended for portability because the same signal may have
2921           different numbers in different operating systems.
2922
2923           A list of signal names supported by the current platform can be
2924           found in $Config{sig_name}, which is provided by the "Config"
2925           module.  See Config for more details.
2926
2927           A negative signal name is the same as a negative signal number,
2928           killing process groups instead of processes.  For example, "kill
2929           '-KILL', $pgrp" and "kill -9, $pgrp" will send "SIGKILL" to the
2930           entire process group specified.  That means you usually want to use
2931           positive not negative signals.
2932
2933           If SIGNAL is either the number 0 or the string "ZERO" (or
2934           "SIGZERO"), no signal is sent to the process, but "kill" checks
2935           whether it's possible to send a signal to it (that means, to be
2936           brief, that the process is owned by the same user, or we are the
2937           super-user).  This is useful to check that a child process is still
2938           alive (even if only as a zombie) and hasn't changed its UID.  See
2939           perlport for notes on the portability of this construct.
2940
2941           The behavior of kill when a PROCESS number is zero or negative
2942           depends on the operating system.  For example, on POSIX-conforming
2943           systems, zero will signal the current process group, -1 will signal
2944           all processes, and any other negative PROCESS number will act as a
2945           negative signal number and kill the entire process group specified.
2946
2947           If both the SIGNAL and the PROCESS are negative, the results are
2948           undefined.  A warning may be produced in a future version.
2949
2950           See "Signals" in perlipc for more details.
2951
2952           On some platforms such as Windows where the fork(2) system call is
2953           not available, Perl can be built to emulate "fork" at the
2954           interpreter level.  This emulation has limitations related to kill
2955           that have to be considered, for code running on Windows and in code
2956           intended to be portable.
2957
2958           See perlfork for more details.
2959
2960           If there is no LIST of processes, no signal is sent, and the return
2961           value is 0.  This form is sometimes used, however, because it
2962           causes tainting checks to be run.  But see "Laundering and
2963           Detecting Tainted Data" in perlsec.
2964
2965           Portability issues: "kill" in perlport.
2966
2967       last LABEL
2968       last EXPR
2969       last
2970           The "last" command is like the "break" statement in C (as used in
2971           loops); it immediately exits the loop in question.  If the LABEL is
2972           omitted, the command refers to the innermost enclosing loop.  The
2973           "last EXPR" form, available starting in Perl 5.18.0, allows a label
2974           name to be computed at run time, and is otherwise identical to
2975           "last LABEL".  The "continue" block, if any, is not executed:
2976
2977               LINE: while (<STDIN>) {
2978                   last LINE if /^$/;  # exit when done with header
2979                   #...
2980               }
2981
2982           "last" cannot be used to exit a block that returns a value such as
2983           "eval {}", "sub {}", or "do {}", and should not be used to exit a
2984           "grep" or "map" operation.
2985
2986           Note that a block by itself is semantically identical to a loop
2987           that executes once.  Thus "last" can be used to effect an early
2988           exit out of such a block.
2989
2990           See also "continue" for an illustration of how "last", "next", and
2991           "redo" work.
2992
2993           Unlike most named operators, this has the same precedence as
2994           assignment.  It is also exempt from the looks-like-a-function rule,
2995           so "last ("foo")."bar"" will cause "bar" to be part of the argument
2996           to "last".
2997
2998       lc EXPR
2999       lc  Returns a lowercased version of EXPR.  This is the internal
3000           function implementing the "\L" escape in double-quoted strings.
3001
3002           If EXPR is omitted, uses $_.
3003
3004           What gets returned depends on several factors:
3005
3006           If "use bytes" is in effect:
3007               The results follow ASCII rules.  Only the characters "A-Z"
3008               change, to "a-z" respectively.
3009
3010           Otherwise, if "use locale" for "LC_CTYPE" is in effect:
3011               Respects current "LC_CTYPE" locale for code points < 256; and
3012               uses Unicode rules for the remaining code points (this last can
3013               only happen if the UTF8 flag is also set).  See perllocale.
3014
3015               Starting in v5.20, Perl uses full Unicode rules if the locale
3016               is UTF-8.  Otherwise, there is a deficiency in this scheme,
3017               which is that case changes that cross the 255/256 boundary are
3018               not well-defined.  For example, the lower case of LATIN CAPITAL
3019               LETTER SHARP S (U+1E9E) in Unicode rules is U+00DF (on ASCII
3020               platforms).   But under "use locale" (prior to v5.20 or not a
3021               UTF-8 locale), the lower case of U+1E9E is itself, because 0xDF
3022               may not be LATIN SMALL LETTER SHARP S in the current locale,
3023               and Perl has no way of knowing if that character even exists in
3024               the locale, much less what code point it is.  Perl returns a
3025               result that is above 255 (almost always the input character
3026               unchanged), for all instances (and there aren't many) where the
3027               255/256 boundary would otherwise be crossed; and starting in
3028               v5.22, it raises a locale warning.
3029
3030           Otherwise, If EXPR has the UTF8 flag set:
3031               Unicode rules are used for the case change.
3032
3033           Otherwise, if "use feature 'unicode_strings'" or "use locale
3034           ':not_characters'" is in effect:
3035               Unicode rules are used for the case change.
3036
3037           Otherwise:
3038               ASCII rules are used for the case change.  The lowercase of any
3039               character outside the ASCII range is the character itself.
3040
3041       lcfirst EXPR
3042       lcfirst
3043           Returns the value of EXPR with the first character lowercased.
3044           This is the internal function implementing the "\l" escape in
3045           double-quoted strings.
3046
3047           If EXPR is omitted, uses $_.
3048
3049           This function behaves the same way under various pragmas, such as
3050           in a locale, as "lc" does.
3051
3052       length EXPR
3053       length
3054           Returns the length in characters of the value of EXPR.  If EXPR is
3055           omitted, returns the length of $_.  If EXPR is undefined, returns
3056           "undef".
3057
3058           This function cannot be used on an entire array or hash to find out
3059           how many elements these have.  For that, use "scalar @array" and
3060           "scalar keys %hash", respectively.
3061
3062           Like all Perl character operations, "length" normally deals in
3063           logical characters, not physical bytes.  For how many bytes a
3064           string encoded as UTF-8 would take up, use
3065           "length(Encode::encode('UTF-8', EXPR))" (you'll have to "use
3066           Encode" first).  See Encode and perlunicode.
3067
3068       __LINE__
3069           A special token that compiles to the current line number.
3070
3071       link OLDFILE,NEWFILE
3072           Creates a new filename linked to the old filename.  Returns true
3073           for success, false otherwise.
3074
3075           Portability issues: "link" in perlport.
3076
3077       listen SOCKET,QUEUESIZE
3078           Does the same thing that the listen(2) system call does.  Returns
3079           true if it succeeded, false otherwise.  See the example in
3080           "Sockets: Client/Server Communication" in perlipc.
3081
3082       local EXPR
3083           You really probably want to be using "my" instead, because "local"
3084           isn't what most people think of as "local".  See "Private Variables
3085           via my()" in perlsub for details.
3086
3087           A local modifies the listed variables to be local to the enclosing
3088           block, file, or eval.  If more than one value is listed, the list
3089           must be placed in parentheses.  See "Temporary Values via local()"
3090           in perlsub for details, including issues with tied arrays and
3091           hashes.
3092
3093           The "delete local EXPR" construct can also be used to localize the
3094           deletion of array/hash elements to the current block.  See
3095           "Localized deletion of elements of composite types" in perlsub.
3096
3097       localtime EXPR
3098       localtime
3099           Converts a time as returned by the time function to a 9-element
3100           list with the time analyzed for the local time zone.  Typically
3101           used as follows:
3102
3103               #     0    1    2     3     4    5     6     7     8
3104               my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
3105                                                           localtime(time);
3106
3107           All list elements are numeric and come straight out of the C
3108           `struct tm'.  $sec, $min, and $hour are the seconds, minutes, and
3109           hours of the specified time.
3110
3111           $mday is the day of the month and $mon the month in the range
3112           0..11, with 0 indicating January and 11 indicating December.  This
3113           makes it easy to get a month name from a list:
3114
3115               my @abbr = qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec);
3116               print "$abbr[$mon] $mday";
3117               # $mon=9, $mday=18 gives "Oct 18"
3118
3119           $year contains the number of years since 1900.  To get a 4-digit
3120           year write:
3121
3122               $year += 1900;
3123
3124           To get the last two digits of the year (e.g., "01" in 2001) do:
3125
3126               $year = sprintf("%02d", $year % 100);
3127
3128           $wday is the day of the week, with 0 indicating Sunday and 3
3129           indicating Wednesday.  $yday is the day of the year, in the range
3130           0..364 (or 0..365 in leap years.)
3131
3132           $isdst is true if the specified time occurs during Daylight Saving
3133           Time, false otherwise.
3134
3135           If EXPR is omitted, "localtime" uses the current time (as returned
3136           by "time").
3137
3138           In scalar context, "localtime" returns the ctime(3) value:
3139
3140               my $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"
3141
3142           The format of this scalar value is not locale-dependent but built
3143           into Perl.  For GMT instead of local time use the "gmtime" builtin.
3144           See also the "Time::Local" module (for converting seconds, minutes,
3145           hours, and such back to the integer value returned by "time"), and
3146           the POSIX module's "strftime" and "mktime" functions.
3147
3148           To get somewhat similar but locale-dependent date strings, set up
3149           your locale environment variables appropriately (please see
3150           perllocale) and try for example:
3151
3152               use POSIX qw(strftime);
3153               my $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
3154               # or for GMT formatted appropriately for your locale:
3155               my $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
3156
3157           Note that %a and %b, the short forms of the day of the week and the
3158           month of the year, may not necessarily be three characters wide.
3159
3160           The Time::gmtime and Time::localtime modules provide a convenient,
3161           by-name access mechanism to the "gmtime" and "localtime" functions,
3162           respectively.
3163
3164           For a comprehensive date and time representation look at the
3165           DateTime module on CPAN.
3166
3167           Portability issues: "localtime" in perlport.
3168
3169       lock THING
3170           This function places an advisory lock on a shared variable or
3171           referenced object contained in THING until the lock goes out of
3172           scope.
3173
3174           The value returned is the scalar itself, if the argument is a
3175           scalar, or a reference, if the argument is a hash, array or
3176           subroutine.
3177
3178           "lock" is a "weak keyword"; this means that if you've defined a
3179           function by this name (before any calls to it), that function will
3180           be called instead.  If you are not under "use threads::shared" this
3181           does nothing.  See threads::shared.
3182
3183       log EXPR
3184       log Returns the natural logarithm (base e) of EXPR.  If EXPR is
3185           omitted, returns the log of $_.  To get the log of another base,
3186           use basic algebra: The base-N log of a number is equal to the
3187           natural log of that number divided by the natural log of N.  For
3188           example:
3189
3190               sub log10 {
3191                   my $n = shift;
3192                   return log($n)/log(10);
3193               }
3194
3195           See also "exp" for the inverse operation.
3196
3197       lstat FILEHANDLE
3198       lstat EXPR
3199       lstat DIRHANDLE
3200       lstat
3201           Does the same thing as the "stat" function (including setting the
3202           special "_" filehandle) but stats a symbolic link instead of the
3203           file the symbolic link points to.  If symbolic links are
3204           unimplemented on your system, a normal "stat" is done.  For much
3205           more detailed information, please see the documentation for "stat".
3206
3207           If EXPR is omitted, stats $_.
3208
3209           Portability issues: "lstat" in perlport.
3210
3211       m// The match operator.  See "Regexp Quote-Like Operators" in perlop.
3212
3213       map BLOCK LIST
3214       map EXPR,LIST
3215           Evaluates the BLOCK or EXPR for each element of LIST (locally
3216           setting $_ to each element) and returns the list value composed of
3217           the results of each such evaluation.  In scalar context, returns
3218           the total number of elements so generated.  Evaluates BLOCK or EXPR
3219           in list context, so each element of LIST may produce zero, one, or
3220           more elements in the returned value.
3221
3222               my @chars = map(chr, @numbers);
3223
3224           translates a list of numbers to the corresponding characters.
3225
3226               my @squares = map { $_ * $_ } @numbers;
3227
3228           translates a list of numbers to their squared values.
3229
3230               my @squares = map { $_ > 5 ? ($_ * $_) : () } @numbers;
3231
3232           shows that number of returned elements can differ from the number
3233           of input elements.  To omit an element, return an empty list ().
3234           This could also be achieved by writing
3235
3236               my @squares = map { $_ * $_ } grep { $_ > 5 } @numbers;
3237
3238           which makes the intention more clear.
3239
3240           Map always returns a list, which can be assigned to a hash such
3241           that the elements become key/value pairs.  See perldata for more
3242           details.
3243
3244               my %hash = map { get_a_key_for($_) => $_ } @array;
3245
3246           is just a funny way to write
3247
3248               my %hash;
3249               foreach (@array) {
3250                   $hash{get_a_key_for($_)} = $_;
3251               }
3252
3253           Note that $_ is an alias to the list value, so it can be used to
3254           modify the elements of the LIST.  While this is useful and
3255           supported, it can cause bizarre results if the elements of LIST are
3256           not variables.  Using a regular "foreach" loop for this purpose
3257           would be clearer in most cases.  See also "grep" for a list
3258           composed of those items of the original list for which the BLOCK or
3259           EXPR evaluates to true.
3260
3261           "{" starts both hash references and blocks, so "map { ..." could be
3262           either the start of map BLOCK LIST or map EXPR, LIST.  Because Perl
3263           doesn't look ahead for the closing "}" it has to take a guess at
3264           which it's dealing with based on what it finds just after the "{".
3265           Usually it gets it right, but if it doesn't it won't realize
3266           something is wrong until it gets to the "}" and encounters the
3267           missing (or unexpected) comma.  The syntax error will be reported
3268           close to the "}", but you'll need to change something near the "{"
3269           such as using a unary "+" or semicolon to give Perl some help:
3270
3271            my %hash = map {  "\L$_" => 1  } @array # perl guesses EXPR. wrong
3272            my %hash = map { +"\L$_" => 1  } @array # perl guesses BLOCK. right
3273            my %hash = map {; "\L$_" => 1  } @array # this also works
3274            my %hash = map { ("\L$_" => 1) } @array # as does this
3275            my %hash = map {  lc($_) => 1  } @array # and this.
3276            my %hash = map +( lc($_) => 1 ), @array # this is EXPR and works!
3277
3278            my %hash = map  ( lc($_), 1 ),   @array # evaluates to (1, @array)
3279
3280           or to force an anon hash constructor use "+{":
3281
3282               my @hashes = map +{ lc($_) => 1 }, @array # EXPR, so needs
3283                                                         # comma at end
3284
3285           to get a list of anonymous hashes each with only one entry apiece.
3286
3287       mkdir FILENAME,MASK
3288       mkdir FILENAME
3289       mkdir
3290           Creates the directory specified by FILENAME, with permissions
3291           specified by MASK (as modified by "umask").  If it succeeds it
3292           returns true; otherwise it returns false and sets $! (errno).  MASK
3293           defaults to 0777 if omitted, and FILENAME defaults to $_ if
3294           omitted.
3295
3296           In general, it is better to create directories with a permissive
3297           MASK and let the user modify that with their "umask" than it is to
3298           supply a restrictive MASK and give the user no way to be more
3299           permissive.  The exceptions to this rule are when the file or
3300           directory should be kept private (mail files, for instance).  The
3301           documentation for "umask" discusses the choice of MASK in more
3302           detail.
3303
3304           Note that according to the POSIX 1003.1-1996 the FILENAME may have
3305           any number of trailing slashes.  Some operating and filesystems do
3306           not get this right, so Perl automatically removes all trailing
3307           slashes to keep everyone happy.
3308
3309           To recursively create a directory structure, look at the
3310           "make_path" function of the File::Path module.
3311
3312       msgctl ID,CMD,ARG
3313           Calls the System V IPC function msgctl(2).  You'll probably have to
3314           say
3315
3316               use IPC::SysV;
3317
3318           first to get the correct constant definitions.  If CMD is
3319           "IPC_STAT", then ARG must be a variable that will hold the returned
3320           "msqid_ds" structure.  Returns like "ioctl": the undefined value
3321           for error, "0 but true" for zero, or the actual return value
3322           otherwise.  See also "SysV IPC" in perlipc and the documentation
3323           for "IPC::SysV" and "IPC::Semaphore".
3324
3325           Portability issues: "msgctl" in perlport.
3326
3327       msgget KEY,FLAGS
3328           Calls the System V IPC function msgget(2).  Returns the message
3329           queue id, or "undef" on error.  See also "SysV IPC" in perlipc and
3330           the documentation for "IPC::SysV" and "IPC::Msg".
3331
3332           Portability issues: "msgget" in perlport.
3333
3334       msgrcv ID,VAR,SIZE,TYPE,FLAGS
3335           Calls the System V IPC function msgrcv to receive a message from
3336           message queue ID into variable VAR with a maximum message size of
3337           SIZE.  Note that when a message is received, the message type as a
3338           native long integer will be the first thing in VAR, followed by the
3339           actual message.  This packing may be opened with "unpack("l! a*")".
3340           Taints the variable.  Returns true if successful, false on error.
3341           See also "SysV IPC" in perlipc and the documentation for
3342           "IPC::SysV" and "IPC::Msg".
3343
3344           Portability issues: "msgrcv" in perlport.
3345
3346       msgsnd ID,MSG,FLAGS
3347           Calls the System V IPC function msgsnd to send the message MSG to
3348           the message queue ID.  MSG must begin with the native long integer
3349           message type, be followed by the length of the actual message, and
3350           then finally the message itself.  This kind of packing can be
3351           achieved with "pack("l! a*", $type, $message)".  Returns true if
3352           successful, false on error.  See also "SysV IPC" in perlipc and the
3353           documentation for "IPC::SysV" and "IPC::Msg".
3354
3355           Portability issues: "msgsnd" in perlport.
3356
3357       my VARLIST
3358       my TYPE VARLIST
3359       my VARLIST : ATTRS
3360       my TYPE VARLIST : ATTRS
3361           A "my" declares the listed variables to be local (lexically) to the
3362           enclosing block, file, or "eval".  If more than one variable is
3363           listed, the list must be placed in parentheses.
3364
3365           The exact semantics and interface of TYPE and ATTRS are still
3366           evolving.  TYPE may be a bareword, a constant declared with "use
3367           constant", or "__PACKAGE__".  It is currently bound to the use of
3368           the fields pragma, and attributes are handled using the attributes
3369           pragma, or starting from Perl 5.8.0 also via the
3370           Attribute::Handlers module.  See "Private Variables via my()" in
3371           perlsub for details.
3372
3373           Note that with a parenthesised list, "undef" can be used as a dummy
3374           placeholder, for example to skip assignment of initial values:
3375
3376               my ( undef, $min, $hour ) = localtime;
3377
3378       next LABEL
3379       next EXPR
3380       next
3381           The "next" command is like the "continue" statement in C; it starts
3382           the next iteration of the loop:
3383
3384               LINE: while (<STDIN>) {
3385                   next LINE if /^#/;  # discard comments
3386                   #...
3387               }
3388
3389           Note that if there were a "continue" block on the above, it would
3390           get executed even on discarded lines.  If LABEL is omitted, the
3391           command refers to the innermost enclosing loop.  The "next EXPR"
3392           form, available as of Perl 5.18.0, allows a label name to be
3393           computed at run time, being otherwise identical to "next LABEL".
3394
3395           "next" cannot be used to exit a block which returns a value such as
3396           "eval {}", "sub {}", or "do {}", and should not be used to exit a
3397           "grep" or "map" operation.
3398
3399           Note that a block by itself is semantically identical to a loop
3400           that executes once.  Thus "next" will exit such a block early.
3401
3402           See also "continue" for an illustration of how "last", "next", and
3403           "redo" work.
3404
3405           Unlike most named operators, this has the same precedence as
3406           assignment.  It is also exempt from the looks-like-a-function rule,
3407           so "next ("foo")."bar"" will cause "bar" to be part of the argument
3408           to "next".
3409
3410       no MODULE VERSION LIST
3411       no MODULE VERSION
3412       no MODULE LIST
3413       no MODULE
3414       no VERSION
3415           See the "use" function, of which "no" is the opposite.
3416
3417       oct EXPR
3418       oct Interprets EXPR as an octal string and returns the corresponding
3419           value.  (If EXPR happens to start off with "0x", interprets it as a
3420           hex string.  If EXPR starts off with "0b", it is interpreted as a
3421           binary string.  Leading whitespace is ignored in all three cases.)
3422           The following will handle decimal, binary, octal, and hex in
3423           standard Perl notation:
3424
3425               $val = oct($val) if $val =~ /^0/;
3426
3427           If EXPR is omitted, uses $_.   To go the other way (produce a
3428           number in octal), use "sprintf" or "printf":
3429
3430               my $dec_perms = (stat("filename"))[2] & 07777;
3431               my $oct_perm_str = sprintf "%o", $perms;
3432
3433           The "oct" function is commonly used when a string such as 644 needs
3434           to be converted into a file mode, for example.  Although Perl
3435           automatically converts strings into numbers as needed, this
3436           automatic conversion assumes base 10.
3437
3438           Leading white space is ignored without warning, as too are any
3439           trailing non-digits, such as a decimal point ("oct" only handles
3440           non-negative integers, not negative integers or floating point).
3441
3442       open FILEHANDLE,EXPR
3443       open FILEHANDLE,MODE,EXPR
3444       open FILEHANDLE,MODE,EXPR,LIST
3445       open FILEHANDLE,MODE,REFERENCE
3446       open FILEHANDLE
3447           Opens the file whose filename is given by EXPR, and associates it
3448           with FILEHANDLE.
3449
3450           Simple examples to open a file for reading:
3451
3452               open(my $fh, "<", "input.txt")
3453                   or die "Can't open < input.txt: $!";
3454
3455           and for writing:
3456
3457               open(my $fh, ">", "output.txt")
3458                   or die "Can't open > output.txt: $!";
3459
3460           (The following is a comprehensive reference to "open": for a
3461           gentler introduction you may consider perlopentut.)
3462
3463           If FILEHANDLE is an undefined scalar variable (or array or hash
3464           element), a new filehandle is autovivified, meaning that the
3465           variable is assigned a reference to a newly allocated anonymous
3466           filehandle.  Otherwise if FILEHANDLE is an expression, its value is
3467           the real filehandle.  (This is considered a symbolic reference, so
3468           "use strict "refs"" should not be in effect.)
3469
3470           If three (or more) arguments are specified, the open mode
3471           (including optional encoding) in the second argument are distinct
3472           from the filename in the third.  If MODE is "<" or nothing, the
3473           file is opened for input.  If MODE is ">", the file is opened for
3474           output, with existing files first being truncated ("clobbered") and
3475           nonexisting files newly created.  If MODE is ">>", the file is
3476           opened for appending, again being created if necessary.
3477
3478           You can put a "+" in front of the ">" or "<" to indicate that you
3479           want both read and write access to the file; thus "+<" is almost
3480           always preferred for read/write updates--the "+>" mode would
3481           clobber the file first.  You can't usually use either read-write
3482           mode for updating textfiles, since they have variable-length
3483           records.  See the -i switch in perlrun for a better approach.  The
3484           file is created with permissions of 0666 modified by the process's
3485           "umask" value.
3486
3487           These various prefixes correspond to the fopen(3) modes of "r",
3488           "r+", "w", "w+", "a", and "a+".
3489
3490           In the one- and two-argument forms of the call, the mode and
3491           filename should be concatenated (in that order), preferably
3492           separated by white space.  You can--but shouldn't--omit the mode in
3493           these forms when that mode is "<".  It is safe to use the two-
3494           argument form of "open" if the filename argument is a known
3495           literal.
3496
3497           For three or more arguments if MODE is "|-", the filename is
3498           interpreted as a command to which output is to be piped, and if
3499           MODE is "-|", the filename is interpreted as a command that pipes
3500           output to us.  In the two-argument (and one-argument) form, one
3501           should replace dash ("-") with the command.  See "Using open() for
3502           IPC" in perlipc for more examples of this.  (You are not allowed to
3503           "open" to a command that pipes both in and out, but see IPC::Open2,
3504           IPC::Open3, and "Bidirectional Communication with Another Process"
3505           in perlipc for alternatives.)
3506
3507           In the form of pipe opens taking three or more arguments, if LIST
3508           is specified (extra arguments after the command name) then LIST
3509           becomes arguments to the command invoked if the platform supports
3510           it.  The meaning of "open" with more than three arguments for non-
3511           pipe modes is not yet defined, but experimental "layers" may give
3512           extra LIST arguments meaning.
3513
3514           In the two-argument (and one-argument) form, opening "<-" or "-"
3515           opens STDIN and opening ">-" opens STDOUT.
3516
3517           You may (and usually should) use the three-argument form of open to
3518           specify I/O layers (sometimes referred to as "disciplines") to
3519           apply to the handle that affect how the input and output are
3520           processed (see open and PerlIO for more details).  For example:
3521
3522             open(my $fh, "<:encoding(UTF-8)", $filename)
3523               || die "Can't open UTF-8 encoded $filename: $!";
3524
3525           opens the UTF8-encoded file containing Unicode characters; see
3526           perluniintro.  Note that if layers are specified in the three-
3527           argument form, then default layers stored in ${^OPEN} (see perlvar;
3528           usually set by the open pragma or the switch "-CioD") are ignored.
3529           Those layers will also be ignored if you specify a colon with no
3530           name following it.  In that case the default layer for the
3531           operating system (:raw on Unix, :crlf on Windows) is used.
3532
3533           Open returns nonzero on success, the undefined value otherwise.  If
3534           the "open" involved a pipe, the return value happens to be the pid
3535           of the subprocess.
3536
3537           On some systems (in general, DOS- and Windows-based systems)
3538           "binmode" is necessary when you're not working with a text file.
3539           For the sake of portability it is a good idea always to use it when
3540           appropriate, and never to use it when it isn't appropriate.  Also,
3541           people can set their I/O to be by default UTF8-encoded Unicode, not
3542           bytes.
3543
3544           When opening a file, it's seldom a good idea to continue if the
3545           request failed, so "open" is frequently used with "die".  Even if
3546           "die" won't do what you want (say, in a CGI script, where you want
3547           to format a suitable error message (but there are modules that can
3548           help with that problem)) always check the return value from opening
3549           a file.
3550
3551           The filehandle will be closed when its reference count reaches
3552           zero.  If it is a lexically scoped variable declared with "my",
3553           that usually means the end of the enclosing scope.  However, this
3554           automatic close does not check for errors, so it is better to
3555           explicitly close filehandles, especially those used for writing:
3556
3557               close($handle)
3558                  || warn "close failed: $!";
3559
3560           An older style is to use a bareword as the filehandle, as
3561
3562               open(FH, "<", "input.txt")
3563                  or die "Can't open < input.txt: $!";
3564
3565           Then you can use "FH" as the filehandle, in "close FH" and "<FH>"
3566           and so on.  Note that it's a global variable, so this form is not
3567           recommended in new code.
3568
3569           As a shortcut a one-argument call takes the filename from the
3570           global scalar variable of the same name as the filehandle:
3571
3572               $ARTICLE = 100;
3573               open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";
3574
3575           Here $ARTICLE must be a global (package) scalar variable - not one
3576           declared with "my" or "state".
3577
3578           As a special case the three-argument form with a read/write mode
3579           and the third argument being "undef":
3580
3581               open(my $tmp, "+>", undef) or die ...
3582
3583           opens a filehandle to a newly created empty anonymous temporary
3584           file.  (This happens under any mode, which makes "+>" the only
3585           useful and sensible mode to use.)  You will need to "seek" to do
3586           the reading.
3587
3588           Perl is built using PerlIO by default.  Unless you've changed this
3589           (such as building Perl with "Configure -Uuseperlio"), you can open
3590           filehandles directly to Perl scalars via:
3591
3592               open(my $fh, ">", \$variable) || ..
3593
3594           To (re)open "STDOUT" or "STDERR" as an in-memory file, close it
3595           first:
3596
3597               close STDOUT;
3598               open(STDOUT, ">", \$variable)
3599                   or die "Can't open STDOUT: $!";
3600
3601           See perliol for detailed info on PerlIO.
3602
3603           General examples:
3604
3605            open(my $log, ">>", "/usr/spool/news/twitlog");
3606            # if the open fails, output is discarded
3607
3608            open(my $dbase, "+<", "dbase.mine")      # open for update
3609                or die "Can't open 'dbase.mine' for update: $!";
3610
3611            open(my $dbase, "+<dbase.mine")          # ditto
3612                or die "Can't open 'dbase.mine' for update: $!";
3613
3614            open(my $article_fh, "-|", "caesar <$article")  # decrypt
3615                                                            # article
3616                or die "Can't start caesar: $!";
3617
3618            open(my $article_fh, "caesar <$article |")      # ditto
3619                or die "Can't start caesar: $!";
3620
3621            open(my $out_fh, "|-", "sort >Tmp$$")    # $$ is our process id
3622                or die "Can't start sort: $!";
3623
3624            # in-memory files
3625            open(my $memory, ">", \$var)
3626                or die "Can't open memory file: $!";
3627            print $memory "foo!\n";              # output will appear in $var
3628
3629           You may also, in the Bourne shell tradition, specify an EXPR
3630           beginning with ">&", in which case the rest of the string is
3631           interpreted as the name of a filehandle (or file descriptor, if
3632           numeric) to be duped (as in dup(2)) and opened.  You may use "&"
3633           after ">", ">>", "<", "+>", "+>>", and "+<".  The mode you specify
3634           should match the mode of the original filehandle.  (Duping a
3635           filehandle does not take into account any existing contents of IO
3636           buffers.)  If you use the three-argument form, then you can pass
3637           either a number, the name of a filehandle, or the normal "reference
3638           to a glob".
3639
3640           Here is a script that saves, redirects, and restores "STDOUT" and
3641           "STDERR" using various methods:
3642
3643               #!/usr/bin/perl
3644               open(my $oldout, ">&STDOUT")     or die "Can't dup STDOUT: $!";
3645               open(OLDERR,     ">&", \*STDERR) or die "Can't dup STDERR: $!";
3646
3647               open(STDOUT, '>', "foo.out") or die "Can't redirect STDOUT: $!";
3648               open(STDERR, ">&STDOUT")     or die "Can't dup STDOUT: $!";
3649
3650               select STDERR; $| = 1;  # make unbuffered
3651               select STDOUT; $| = 1;  # make unbuffered
3652
3653               print STDOUT "stdout 1\n";  # this works for
3654               print STDERR "stderr 1\n";  # subprocesses too
3655
3656               open(STDOUT, ">&", $oldout) or die "Can't dup \$oldout: $!";
3657               open(STDERR, ">&OLDERR")    or die "Can't dup OLDERR: $!";
3658
3659               print STDOUT "stdout 2\n";
3660               print STDERR "stderr 2\n";
3661
3662           If you specify '<&=X', where "X" is a file descriptor number or a
3663           filehandle, then Perl will do an equivalent of C's fdopen(3) of
3664           that file descriptor (and not call dup(2)); this is more
3665           parsimonious of file descriptors.  For example:
3666
3667               # open for input, reusing the fileno of $fd
3668               open(my $fh, "<&=", $fd)
3669
3670           or
3671
3672               open(my $fh, "<&=$fd")
3673
3674           or
3675
3676               # open for append, using the fileno of $oldfh
3677               open(my $fh, ">>&=", $oldfh)
3678
3679           Being parsimonious on filehandles is also useful (besides being
3680           parsimonious) for example when something is dependent on file
3681           descriptors, like for example locking using "flock".  If you do
3682           just "open(my $A, ">>&", $B)", the filehandle $A will not have the
3683           same file descriptor as $B, and therefore "flock($A)" will not
3684           "flock($B)" nor vice versa.  But with "open(my $A, ">>&=", $B)",
3685           the filehandles will share the same underlying system file
3686           descriptor.
3687
3688           Note that under Perls older than 5.8.0, Perl uses the standard C
3689           library's' fdopen(3) to implement the "=" functionality.  On many
3690           Unix systems, fdopen(3) fails when file descriptors exceed a
3691           certain value, typically 255.  For Perls 5.8.0 and later, PerlIO is
3692           (most often) the default.
3693
3694           You can see whether your Perl was built with PerlIO by running
3695           "perl -V:useperlio".  If it says 'define', you have PerlIO;
3696           otherwise you don't.
3697
3698           If you open a pipe on the command "-" (that is, specify either "|-"
3699           or "-|" with the one- or two-argument forms of "open"), an implicit
3700           "fork" is done, so "open" returns twice: in the parent process it
3701           returns the pid of the child process, and in the child process it
3702           returns (a defined) 0.  Use "defined($pid)" or "//" to determine
3703           whether the open was successful.
3704
3705           For example, use either
3706
3707              my $child_pid = open(my $from_kid, "-|") // die "Can't fork: $!";
3708
3709           or
3710
3711              my $child_pid = open(my $to_kid,   "|-") // die "Can't fork: $!";
3712
3713           followed by
3714
3715               if ($child_pid) {
3716                   # am the parent:
3717                   # either write $to_kid or else read $from_kid
3718                   ...
3719                  waitpid $child_pid, 0;
3720               } else {
3721                   # am the child; use STDIN/STDOUT normally
3722                   ...
3723                   exit;
3724               }
3725
3726           The filehandle behaves normally for the parent, but I/O to that
3727           filehandle is piped from/to the STDOUT/STDIN of the child process.
3728           In the child process, the filehandle isn't opened--I/O happens
3729           from/to the new STDOUT/STDIN.  Typically this is used like the
3730           normal piped open when you want to exercise more control over just
3731           how the pipe command gets executed, such as when running setuid and
3732           you don't want to have to scan shell commands for metacharacters.
3733
3734           The following blocks are more or less equivalent:
3735
3736               open(my $fh, "|tr '[a-z]' '[A-Z]'");
3737               open(my $fh, "|-", "tr '[a-z]' '[A-Z]'");
3738               open(my $fh, "|-") || exec 'tr', '[a-z]', '[A-Z]';
3739               open(my $fh, "|-", "tr", '[a-z]', '[A-Z]');
3740
3741               open(my $fh, "cat -n '$file'|");
3742               open(my $fh, "-|", "cat -n '$file'");
3743               open(my $fh, "-|") || exec "cat", "-n", $file;
3744               open(my $fh, "-|", "cat", "-n", $file);
3745
3746           The last two examples in each block show the pipe as "list form",
3747           which is not yet supported on all platforms.  A good rule of thumb
3748           is that if your platform has a real "fork" (in other words, if your
3749           platform is Unix, including Linux and MacOS X), you can use the
3750           list form.  You would want to use the list form of the pipe so you
3751           can pass literal arguments to the command without risk of the shell
3752           interpreting any shell metacharacters in them.  However, this also
3753           bars you from opening pipes to commands that intentionally contain
3754           shell metacharacters, such as:
3755
3756               open(my $fh, "|cat -n | expand -4 | lpr")
3757                   || die "Can't open pipeline to lpr: $!";
3758
3759           See "Safe Pipe Opens" in perlipc for more examples of this.
3760
3761           Perl will attempt to flush all files opened for output before any
3762           operation that may do a fork, but this may not be supported on some
3763           platforms (see perlport).  To be safe, you may need to set $|
3764           ($AUTOFLUSH in English) or call the "autoflush" method of
3765           "IO::Handle" on any open handles.
3766
3767           On systems that support a close-on-exec flag on files, the flag
3768           will be set for the newly opened file descriptor as determined by
3769           the value of $^F.  See "$^F" in perlvar.
3770
3771           Closing any piped filehandle causes the parent process to wait for
3772           the child to finish, then returns the status value in $? and
3773           "${^CHILD_ERROR_NATIVE}".
3774
3775           The filename passed to the one- and two-argument forms of "open"
3776           will have leading and trailing whitespace deleted and normal
3777           redirection characters honored.  This property, known as "magic
3778           open", can often be used to good effect.  A user could specify a
3779           filename of "rsh cat file |", or you could change certain filenames
3780           as needed:
3781
3782               $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
3783               open(my $fh, $filename) or die "Can't open $filename: $!";
3784
3785           Use the three-argument form to open a file with arbitrary weird
3786           characters in it,
3787
3788               open(my $fh, "<", $file)
3789                   || die "Can't open $file: $!";
3790
3791           otherwise it's necessary to protect any leading and trailing
3792           whitespace:
3793
3794               $file =~ s#^(\s)#./$1#;
3795               open(my $fh, "< $file\0")
3796                   || die "Can't open $file: $!";
3797
3798           (this may not work on some bizarre filesystems).  One should
3799           conscientiously choose between the magic and three-argument form of
3800           "open":
3801
3802               open(my $in, $ARGV[0]) || die "Can't open $ARGV[0]: $!";
3803
3804           will allow the user to specify an argument of the form "rsh cat
3805           file |", but will not work on a filename that happens to have a
3806           trailing space, while
3807
3808               open(my $in, "<", $ARGV[0])
3809                   || die "Can't open $ARGV[0]: $!";
3810
3811           will have exactly the opposite restrictions. (However, some shells
3812           support the syntax "perl your_program.pl <( rsh cat file )", which
3813           produces a filename that can be opened normally.)
3814
3815           If you want a "real" C open(2), then you should use the "sysopen"
3816           function, which involves no such magic (but uses different
3817           filemodes than Perl "open", which corresponds to C fopen(3)).  This
3818           is another way to protect your filenames from interpretation.  For
3819           example:
3820
3821               use IO::Handle;
3822               sysopen(my $fh, $path, O_RDWR|O_CREAT|O_EXCL)
3823                   or die "Can't open $path: $!";
3824               $fh->autoflush(1);
3825               print $fh "stuff $$\n";
3826               seek($fh, 0, 0);
3827               print "File contains: ", readline($fh);
3828
3829           See "seek" for some details about mixing reading and writing.
3830
3831           Portability issues: "open" in perlport.
3832
3833       opendir DIRHANDLE,EXPR
3834           Opens a directory named EXPR for processing by "readdir",
3835           "telldir", "seekdir", "rewinddir", and "closedir".  Returns true if
3836           successful.  DIRHANDLE may be an expression whose value can be used
3837           as an indirect dirhandle, usually the real dirhandle name.  If
3838           DIRHANDLE is an undefined scalar variable (or array or hash
3839           element), the variable is assigned a reference to a new anonymous
3840           dirhandle; that is, it's autovivified.  DIRHANDLEs have their own
3841           namespace separate from FILEHANDLEs.
3842
3843           See the example at "readdir".
3844
3845       ord EXPR
3846       ord Returns the numeric value of the first character of EXPR.  If EXPR
3847           is an empty string, returns 0.  If EXPR is omitted, uses $_.  (Note
3848           character, not byte.)
3849
3850           For the reverse, see "chr".  See perlunicode for more about
3851           Unicode.
3852
3853       our VARLIST
3854       our TYPE VARLIST
3855       our VARLIST : ATTRS
3856       our TYPE VARLIST : ATTRS
3857           "our" makes a lexical alias to a package (i.e. global) variable of
3858           the same name in the current package for use within the current
3859           lexical scope.
3860
3861           "our" has the same scoping rules as "my" or "state", meaning that
3862           it is only valid within a lexical scope.  Unlike "my" and "state",
3863           which both declare new (lexical) variables, "our" only creates an
3864           alias to an existing variable: a package variable of the same name.
3865
3866           This means that when "use strict 'vars'" is in effect, "our" lets
3867           you use a package variable without qualifying it with the package
3868           name, but only within the lexical scope of the "our" declaration.
3869           This applies immediately--even within the same statement.
3870
3871               package Foo;
3872               use strict;
3873
3874               $Foo::foo = 23;
3875
3876               {
3877                   our $foo;   # alias to $Foo::foo
3878                   print $foo; # prints 23
3879               }
3880
3881               print $Foo::foo; # prints 23
3882
3883               print $foo; # ERROR: requires explicit package name
3884
3885           This works even if the package variable has not been used before,
3886           as package variables spring into existence when first used.
3887
3888               package Foo;
3889               use strict;
3890
3891               our $foo = 23;   # just like $Foo::foo = 23
3892
3893               print $Foo::foo; # prints 23
3894
3895           Because the variable becomes legal immediately under "use strict
3896           'vars'", so long as there is no variable with that name is already
3897           in scope, you can then reference the package variable again even
3898           within the same statement.
3899
3900               package Foo;
3901               use strict;
3902
3903               my  $foo = $foo; # error, undeclared $foo on right-hand side
3904               our $foo = $foo; # no errors
3905
3906           If more than one variable is listed, the list must be placed in
3907           parentheses.
3908
3909               our($bar, $baz);
3910
3911           An "our" declaration declares an alias for a package variable that
3912           will be visible across its entire lexical scope, even across
3913           package boundaries.  The package in which the variable is entered
3914           is determined at the point of the declaration, not at the point of
3915           use.  This means the following behavior holds:
3916
3917               package Foo;
3918               our $bar;      # declares $Foo::bar for rest of lexical scope
3919               $bar = 20;
3920
3921               package Bar;
3922               print $bar;    # prints 20, as it refers to $Foo::bar
3923
3924           Multiple "our" declarations with the same name in the same lexical
3925           scope are allowed if they are in different packages.  If they
3926           happen to be in the same package, Perl will emit warnings if you
3927           have asked for them, just like multiple "my" declarations.  Unlike
3928           a second "my" declaration, which will bind the name to a fresh
3929           variable, a second "our" declaration in the same package, in the
3930           same scope, is merely redundant.
3931
3932               use warnings;
3933               package Foo;
3934               our $bar;      # declares $Foo::bar for rest of lexical scope
3935               $bar = 20;
3936
3937               package Bar;
3938               our $bar = 30; # declares $Bar::bar for rest of lexical scope
3939               print $bar;    # prints 30
3940
3941               our $bar;      # emits warning but has no other effect
3942               print $bar;    # still prints 30
3943
3944           An "our" declaration may also have a list of attributes associated
3945           with it.
3946
3947           The exact semantics and interface of TYPE and ATTRS are still
3948           evolving.  TYPE is currently bound to the use of the fields pragma,
3949           and attributes are handled using the attributes pragma, or,
3950           starting from Perl 5.8.0, also via the Attribute::Handlers module.
3951           See "Private Variables via my()" in perlsub for details.
3952
3953           Note that with a parenthesised list, "undef" can be used as a dummy
3954           placeholder, for example to skip assignment of initial values:
3955
3956               our ( undef, $min, $hour ) = localtime;
3957
3958           "our" differs from "use vars", which allows use of an unqualified
3959           name only within the affected package, but across scopes.
3960
3961       pack TEMPLATE,LIST
3962           Takes a LIST of values and converts it into a string using the
3963           rules given by the TEMPLATE.  The resulting string is the
3964           concatenation of the converted values.  Typically, each converted
3965           value looks like its machine-level representation.  For example, on
3966           32-bit machines an integer may be represented by a sequence of 4
3967           bytes, which  will in Perl be presented as a string that's 4
3968           characters long.
3969
3970           See perlpacktut for an introduction to this function.
3971
3972           The TEMPLATE is a sequence of characters that give the order and
3973           type of values, as follows:
3974
3975               a  A string with arbitrary binary data, will be null padded.
3976               A  A text (ASCII) string, will be space padded.
3977               Z  A null-terminated (ASCIZ) string, will be null padded.
3978
3979               b  A bit string (ascending bit order inside each byte,
3980                  like vec()).
3981               B  A bit string (descending bit order inside each byte).
3982               h  A hex string (low nybble first).
3983               H  A hex string (high nybble first).
3984
3985               c  A signed char (8-bit) value.
3986               C  An unsigned char (octet) value.
3987               W  An unsigned char value (can be greater than 255).
3988
3989               s  A signed short (16-bit) value.
3990               S  An unsigned short value.
3991
3992               l  A signed long (32-bit) value.
3993               L  An unsigned long value.
3994
3995               q  A signed quad (64-bit) value.
3996               Q  An unsigned quad value.
3997                    (Quads are available only if your system supports 64-bit
3998                     integer values _and_ if Perl has been compiled to support
3999                     those.  Raises an exception otherwise.)
4000
4001               i  A signed integer value.
4002               I  A unsigned integer value.
4003                    (This 'integer' is _at_least_ 32 bits wide.  Its exact
4004                     size depends on what a local C compiler calls 'int'.)
4005
4006               n  An unsigned short (16-bit) in "network" (big-endian) order.
4007               N  An unsigned long (32-bit) in "network" (big-endian) order.
4008               v  An unsigned short (16-bit) in "VAX" (little-endian) order.
4009               V  An unsigned long (32-bit) in "VAX" (little-endian) order.
4010
4011               j  A Perl internal signed integer value (IV).
4012               J  A Perl internal unsigned integer value (UV).
4013
4014               f  A single-precision float in native format.
4015               d  A double-precision float in native format.
4016
4017               F  A Perl internal floating-point value (NV) in native format
4018               D  A float of long-double precision in native format.
4019                    (Long doubles are available only if your system supports
4020                     long double values _and_ if Perl has been compiled to
4021                     support those.  Raises an exception otherwise.
4022                     Note that there are different long double formats.)
4023
4024               p  A pointer to a null-terminated string.
4025               P  A pointer to a structure (fixed-length string).
4026
4027               u  A uuencoded string.
4028               U  A Unicode character number.  Encodes to a character in char-
4029                  acter mode and UTF-8 (or UTF-EBCDIC in EBCDIC platforms) in
4030                  byte mode.
4031
4032               w  A BER compressed integer (not an ASN.1 BER, see perlpacktut
4033                  for details).  Its bytes represent an unsigned integer in
4034                  base 128, most significant digit first, with as few digits
4035                  as possible.  Bit eight (the high bit) is set on each byte
4036                  except the last.
4037
4038               x  A null byte (a.k.a ASCII NUL, "\000", chr(0))
4039               X  Back up a byte.
4040               @  Null-fill or truncate to absolute position, counted from the
4041                  start of the innermost ()-group.
4042               .  Null-fill or truncate to absolute position specified by
4043                  the value.
4044               (  Start of a ()-group.
4045
4046           One or more modifiers below may optionally follow certain letters
4047           in the TEMPLATE (the second column lists letters for which the
4048           modifier is valid):
4049
4050               !   sSlLiI     Forces native (short, long, int) sizes instead
4051                              of fixed (16-/32-bit) sizes.
4052
4053               !   xX         Make x and X act as alignment commands.
4054
4055               !   nNvV       Treat integers as signed instead of unsigned.
4056
4057               !   @.         Specify position as byte offset in the internal
4058                              representation of the packed string.  Efficient
4059                              but dangerous.
4060
4061               >   sSiIlLqQ   Force big-endian byte-order on the type.
4062                   jJfFdDpP   (The "big end" touches the construct.)
4063
4064               <   sSiIlLqQ   Force little-endian byte-order on the type.
4065                   jJfFdDpP   (The "little end" touches the construct.)
4066
4067           The ">" and "<" modifiers can also be used on "()" groups to force
4068           a particular byte-order on all components in that group, including
4069           all its subgroups.
4070
4071           The following rules apply:
4072
4073           ·   Each letter may optionally be followed by a number indicating
4074               the repeat count.  A numeric repeat count may optionally be
4075               enclosed in brackets, as in "pack("C[80]", @arr)".  The repeat
4076               count gobbles that many values from the LIST when used with all
4077               format types other than "a", "A", "Z", "b", "B", "h", "H", "@",
4078               ".", "x", "X", and "P", where it means something else,
4079               described below.  Supplying a "*" for the repeat count instead
4080               of a number means to use however many items are left, except
4081               for:
4082
4083               ·   "@", "x", and "X", where it is equivalent to 0.
4084
4085               ·   <.>, where it means relative to the start of the string.
4086
4087               ·   "u", where it is equivalent to 1 (or 45, which here is
4088                   equivalent).
4089
4090               One can replace a numeric repeat count with a template letter
4091               enclosed in brackets to use the packed byte length of the
4092               bracketed template for the repeat count.
4093
4094               For example, the template "x[L]" skips as many bytes as in a
4095               packed long, and the template "$t X[$t] $t" unpacks twice
4096               whatever $t (when variable-expanded) unpacks.  If the template
4097               in brackets contains alignment commands (such as "x![d]"), its
4098               packed length is calculated as if the start of the template had
4099               the maximal possible alignment.
4100
4101               When used with "Z", a "*" as the repeat count is guaranteed to
4102               add a trailing null byte, so the resulting string is always one
4103               byte longer than the byte length of the item itself.
4104
4105               When used with "@", the repeat count represents an offset from
4106               the start of the innermost "()" group.
4107
4108               When used with ".", the repeat count determines the starting
4109               position to calculate the value offset as follows:
4110
4111               ·   If the repeat count is 0, it's relative to the current
4112                   position.
4113
4114               ·   If the repeat count is "*", the offset is relative to the
4115                   start of the packed string.
4116
4117               ·   And if it's an integer n, the offset is relative to the
4118                   start of the nth innermost "( )" group, or to the start of
4119                   the string if n is bigger then the group level.
4120
4121               The repeat count for "u" is interpreted as the maximal number
4122               of bytes to encode per line of output, with 0, 1 and 2 replaced
4123               by 45.  The repeat count should not be more than 65.
4124
4125           ·   The "a", "A", and "Z" types gobble just one value, but pack it
4126               as a string of length count, padding with nulls or spaces as
4127               needed.  When unpacking, "A" strips trailing whitespace and
4128               nulls, "Z" strips everything after the first null, and "a"
4129               returns data with no stripping at all.
4130
4131               If the value to pack is too long, the result is truncated.  If
4132               it's too long and an explicit count is provided, "Z" packs only
4133               "$count-1" bytes, followed by a null byte.  Thus "Z" always
4134               packs a trailing null, except when the count is 0.
4135
4136           ·   Likewise, the "b" and "B" formats pack a string that's that
4137               many bits long.  Each such format generates 1 bit of the
4138               result.  These are typically followed by a repeat count like
4139               "B8" or "B64".
4140
4141               Each result bit is based on the least-significant bit of the
4142               corresponding input character, i.e., on "ord($char)%2".  In
4143               particular, characters "0" and "1" generate bits 0 and 1, as do
4144               characters "\000" and "\001".
4145
4146               Starting from the beginning of the input string, each 8-tuple
4147               of characters is converted to 1 character of output.  With
4148               format "b", the first character of the 8-tuple determines the
4149               least-significant bit of a character; with format "B", it
4150               determines the most-significant bit of a character.
4151
4152               If the length of the input string is not evenly divisible by 8,
4153               the remainder is packed as if the input string were padded by
4154               null characters at the end.  Similarly during unpacking,
4155               "extra" bits are ignored.
4156
4157               If the input string is longer than needed, remaining characters
4158               are ignored.
4159
4160               A "*" for the repeat count uses all characters of the input
4161               field.  On unpacking, bits are converted to a string of 0s and
4162               1s.
4163
4164           ·   The "h" and "H" formats pack a string that many nybbles (4-bit
4165               groups, representable as hexadecimal digits, "0".."9" "a".."f")
4166               long.
4167
4168               For each such format, "pack" generates 4 bits of result.  With
4169               non-alphabetical characters, the result is based on the 4
4170               least-significant bits of the input character, i.e., on
4171               "ord($char)%16".  In particular, characters "0" and "1"
4172               generate nybbles 0 and 1, as do bytes "\000" and "\001".  For
4173               characters "a".."f" and "A".."F", the result is compatible with
4174               the usual hexadecimal digits, so that "a" and "A" both generate
4175               the nybble "0xA==10".  Use only these specific hex characters
4176               with this format.
4177
4178               Starting from the beginning of the template to "pack", each
4179               pair of characters is converted to 1 character of output.  With
4180               format "h", the first character of the pair determines the
4181               least-significant nybble of the output character; with format
4182               "H", it determines the most-significant nybble.
4183
4184               If the length of the input string is not even, it behaves as if
4185               padded by a null character at the end.  Similarly, "extra"
4186               nybbles are ignored during unpacking.
4187
4188               If the input string is longer than needed, extra characters are
4189               ignored.
4190
4191               A "*" for the repeat count uses all characters of the input
4192               field.  For "unpack", nybbles are converted to a string of
4193               hexadecimal digits.
4194
4195           ·   The "p" format packs a pointer to a null-terminated string.
4196               You are responsible for ensuring that the string is not a
4197               temporary value, as that could potentially get deallocated
4198               before you got around to using the packed result.  The "P"
4199               format packs a pointer to a structure of the size indicated by
4200               the length.  A null pointer is created if the corresponding
4201               value for "p" or "P" is "undef"; similarly with "unpack", where
4202               a null pointer unpacks into "undef".
4203
4204               If your system has a strange pointer size--meaning a pointer is
4205               neither as big as an int nor as big as a long--it may not be
4206               possible to pack or unpack pointers in big- or little-endian
4207               byte order.  Attempting to do so raises an exception.
4208
4209           ·   The "/" template character allows packing and unpacking of a
4210               sequence of items where the packed structure contains a packed
4211               item count followed by the packed items themselves.  This is
4212               useful when the structure you're unpacking has encoded the
4213               sizes or repeat counts for some of its fields within the
4214               structure itself as separate fields.
4215
4216               For "pack", you write length-item"/"sequence-item, and the
4217               length-item describes how the length value is packed.  Formats
4218               likely to be of most use are integer-packing ones like "n" for
4219               Java strings, "w" for ASN.1 or SNMP, and "N" for Sun XDR.
4220
4221               For "pack", sequence-item may have a repeat count, in which
4222               case the minimum of that and the number of available items is
4223               used as the argument for length-item.  If it has no repeat
4224               count or uses a '*', the number of available items is used.
4225
4226               For "unpack", an internal stack of integer arguments unpacked
4227               so far is used.  You write "/"sequence-item and the repeat
4228               count is obtained by popping off the last element from the
4229               stack.  The sequence-item must not have a repeat count.
4230
4231               If sequence-item refers to a string type ("A", "a", or "Z"),
4232               the length-item is the string length, not the number of
4233               strings.  With an explicit repeat count for pack, the packed
4234               string is adjusted to that length.  For example:
4235
4236                This code:                             gives this result:
4237
4238                unpack("W/a", "\004Gurusamy")          ("Guru")
4239                unpack("a3/A A*", "007 Bond  J ")      (" Bond", "J")
4240                unpack("a3 x2 /A A*", "007: Bond, J.") ("Bond, J", ".")
4241
4242                pack("n/a* w/a","hello,","world")     "\000\006hello,\005world"
4243                pack("a/W2", ord("a") .. ord("z"))    "2ab"
4244
4245               The length-item is not returned explicitly from "unpack".
4246
4247               Supplying a count to the length-item format letter is only
4248               useful with "A", "a", or "Z".  Packing with a length-item of
4249               "a" or "Z" may introduce "\000" characters, which Perl does not
4250               regard as legal in numeric strings.
4251
4252           ·   The integer types "s", "S", "l", and "L" may be followed by a
4253               "!" modifier to specify native shorts or longs.  As shown in
4254               the example above, a bare "l" means exactly 32 bits, although
4255               the native "long" as seen by the local C compiler may be
4256               larger.  This is mainly an issue on 64-bit platforms.  You can
4257               see whether using "!" makes any difference this way:
4258
4259                   printf "format s is %d, s! is %d\n",
4260                       length pack("s"), length pack("s!");
4261
4262                   printf "format l is %d, l! is %d\n",
4263                       length pack("l"), length pack("l!");
4264
4265               "i!" and "I!" are also allowed, but only for completeness'
4266               sake: they are identical to "i" and "I".
4267
4268               The actual sizes (in bytes) of native shorts, ints, longs, and
4269               long longs on the platform where Perl was built are also
4270               available from the command line:
4271
4272                   $ perl -V:{short,int,long{,long}}size
4273                   shortsize='2';
4274                   intsize='4';
4275                   longsize='4';
4276                   longlongsize='8';
4277
4278               or programmatically via the "Config" module:
4279
4280                      use Config;
4281                      print $Config{shortsize},    "\n";
4282                      print $Config{intsize},      "\n";
4283                      print $Config{longsize},     "\n";
4284                      print $Config{longlongsize}, "\n";
4285
4286               $Config{longlongsize} is undefined on systems without long long
4287               support.
4288
4289           ·   The integer formats "s", "S", "i", "I", "l", "L", "j", and "J"
4290               are inherently non-portable between processors and operating
4291               systems because they obey native byteorder and endianness.  For
4292               example, a 4-byte integer 0x12345678 (305419896 decimal) would
4293               be ordered natively (arranged in and handled by the CPU
4294               registers) into bytes as
4295
4296                   0x12 0x34 0x56 0x78  # big-endian
4297                   0x78 0x56 0x34 0x12  # little-endian
4298
4299               Basically, Intel and VAX CPUs are little-endian, while
4300               everybody else, including Motorola m68k/88k, PPC, Sparc, HP PA,
4301               Power, and Cray, are big-endian.  Alpha and MIPS can be either:
4302               Digital/Compaq uses (well, used) them in little-endian mode,
4303               but SGI/Cray uses them in big-endian mode.
4304
4305               The names big-endian and little-endian are comic references to
4306               the egg-eating habits of the little-endian Lilliputians and the
4307               big-endian Blefuscudians from the classic Jonathan Swift
4308               satire, Gulliver's Travels.  This entered computer lingo via
4309               the paper "On Holy Wars and a Plea for Peace" by Danny Cohen,
4310               USC/ISI IEN 137, April 1, 1980.
4311
4312               Some systems may have even weirder byte orders such as
4313
4314                  0x56 0x78 0x12 0x34
4315                  0x34 0x12 0x78 0x56
4316
4317               These are called mid-endian, middle-endian, mixed-endian, or
4318               just weird.
4319
4320               You can determine your system endianness with this incantation:
4321
4322                  printf("%#02x ", $_) for unpack("W*", pack L=>0x12345678);
4323
4324               The byteorder on the platform where Perl was built is also
4325               available via Config:
4326
4327                   use Config;
4328                   print "$Config{byteorder}\n";
4329
4330               or from the command line:
4331
4332                   $ perl -V:byteorder
4333
4334               Byteorders "1234" and "12345678" are little-endian; "4321" and
4335               "87654321" are big-endian.  Systems with multiarchitecture
4336               binaries will have "ffff", signifying that static information
4337               doesn't work, one must use runtime probing.
4338
4339               For portably packed integers, either use the formats "n", "N",
4340               "v", and "V" or else use the ">" and "<" modifiers described
4341               immediately below.  See also perlport.
4342
4343           ·   Also floating point numbers have endianness.  Usually (but not
4344               always) this agrees with the integer endianness.  Even though
4345               most platforms these days use the IEEE 754 binary format, there
4346               are differences, especially if the long doubles are involved.
4347               You can see the "Config" variables "doublekind" and
4348               "longdblkind" (also "doublesize", "longdblsize"): the "kind"
4349               values are enums, unlike "byteorder".
4350
4351               Portability-wise the best option is probably to keep to the
4352               IEEE 754 64-bit doubles, and of agreed-upon endianness.
4353               Another possibility is the "%a") format of "printf".
4354
4355           ·   Starting with Perl 5.10.0, integer and floating-point formats,
4356               along with the "p" and "P" formats and "()" groups, may all be
4357               followed by the ">" or "<" endianness modifiers to respectively
4358               enforce big- or little-endian byte-order.  These modifiers are
4359               especially useful given how "n", "N", "v", and "V" don't cover
4360               signed integers, 64-bit integers, or floating-point values.
4361
4362               Here are some concerns to keep in mind when using an endianness
4363               modifier:
4364
4365               ·   Exchanging signed integers between different platforms
4366                   works only when all platforms store them in the same
4367                   format.  Most platforms store signed integers in two's-
4368                   complement notation, so usually this is not an issue.
4369
4370               ·   The ">" or "<" modifiers can only be used on floating-point
4371                   formats on big- or little-endian machines.  Otherwise,
4372                   attempting to use them raises an exception.
4373
4374               ·   Forcing big- or little-endian byte-order on floating-point
4375                   values for data exchange can work only if all platforms use
4376                   the same binary representation such as IEEE floating-point.
4377                   Even if all platforms are using IEEE, there may still be
4378                   subtle differences.  Being able to use ">" or "<" on
4379                   floating-point values can be useful, but also dangerous if
4380                   you don't know exactly what you're doing.  It is not a
4381                   general way to portably store floating-point values.
4382
4383               ·   When using ">" or "<" on a "()" group, this affects all
4384                   types inside the group that accept byte-order modifiers,
4385                   including all subgroups.  It is silently ignored for all
4386                   other types.  You are not allowed to override the byte-
4387                   order within a group that already has a byte-order modifier
4388                   suffix.
4389
4390           ·   Real numbers (floats and doubles) are in native machine format
4391               only.  Due to the multiplicity of floating-point formats and
4392               the lack of a standard "network" representation for them, no
4393               facility for interchange has been made.  This means that packed
4394               floating-point data written on one machine may not be readable
4395               on another, even if both use IEEE floating-point arithmetic
4396               (because the endianness of the memory representation is not
4397               part of the IEEE spec).  See also perlport.
4398
4399               If you know exactly what you're doing, you can use the ">" or
4400               "<" modifiers to force big- or little-endian byte-order on
4401               floating-point values.
4402
4403               Because Perl uses doubles (or long doubles, if configured)
4404               internally for all numeric calculation, converting from double
4405               into float and thence to double again loses precision, so
4406               "unpack("f", pack("f", $foo)") will not in general equal $foo.
4407
4408           ·   Pack and unpack can operate in two modes: character mode ("C0"
4409               mode) where the packed string is processed per character, and
4410               UTF-8 byte mode ("U0" mode) where the packed string is
4411               processed in its UTF-8-encoded Unicode form on a byte-by-byte
4412               basis.  Character mode is the default unless the format string
4413               starts with "U".  You can always switch mode mid-format with an
4414               explicit "C0" or "U0" in the format.  This mode remains in
4415               effect until the next mode change, or until the end of the "()"
4416               group it (directly) applies to.
4417
4418               Using "C0" to get Unicode characters while using "U0" to get
4419               non-Unicode bytes is not necessarily obvious.   Probably only
4420               the first of these is what you want:
4421
4422                   $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
4423                     perl -CS -ne 'printf "%v04X\n", $_ for unpack("C0A*", $_)'
4424                   03B1.03C9
4425                   $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
4426                     perl -CS -ne 'printf "%v02X\n", $_ for unpack("U0A*", $_)'
4427                   CE.B1.CF.89
4428                   $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
4429                     perl -C0 -ne 'printf "%v02X\n", $_ for unpack("C0A*", $_)'
4430                   CE.B1.CF.89
4431                   $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
4432                     perl -C0 -ne 'printf "%v02X\n", $_ for unpack("U0A*", $_)'
4433                   C3.8E.C2.B1.C3.8F.C2.89
4434
4435               Those examples also illustrate that you should not try to use
4436               "pack"/"unpack" as a substitute for the Encode module.
4437
4438           ·   You must yourself do any alignment or padding by inserting, for
4439               example, enough "x"es while packing.  There is no way for
4440               "pack" and "unpack" to know where characters are going to or
4441               coming from, so they handle their output and input as flat
4442               sequences of characters.
4443
4444           ·   A "()" group is a sub-TEMPLATE enclosed in parentheses.  A
4445               group may take a repeat count either as postfix, or for
4446               "unpack", also via the "/" template character.  Within each
4447               repetition of a group, positioning with "@" starts over at 0.
4448               Therefore, the result of
4449
4450                   pack("@1A((@2A)@3A)", qw[X Y Z])
4451
4452               is the string "\0X\0\0YZ".
4453
4454           ·   "x" and "X" accept the "!" modifier to act as alignment
4455               commands: they jump forward or back to the closest position
4456               aligned at a multiple of "count" characters.  For example, to
4457               "pack" or "unpack" a C structure like
4458
4459                   struct {
4460                       char   c;    /* one signed, 8-bit character */
4461                       double d;
4462                       char   cc[2];
4463                   }
4464
4465               one may need to use the template "c x![d] d c[2]".  This
4466               assumes that doubles must be aligned to the size of double.
4467
4468               For alignment commands, a "count" of 0 is equivalent to a
4469               "count" of 1; both are no-ops.
4470
4471           ·   "n", "N", "v" and "V" accept the "!" modifier to represent
4472               signed 16-/32-bit integers in big-/little-endian order.  This
4473               is portable only when all platforms sharing packed data use the
4474               same binary representation for signed integers; for example,
4475               when all platforms use two's-complement representation.
4476
4477           ·   Comments can be embedded in a TEMPLATE using "#" through the
4478               end of line.  White space can separate pack codes from each
4479               other, but modifiers and repeat counts must follow immediately.
4480               Breaking complex templates into individual line-by-line
4481               components, suitably annotated, can do as much to improve
4482               legibility and maintainability of pack/unpack formats as "/x"
4483               can for complicated pattern matches.
4484
4485           ·   If TEMPLATE requires more arguments than "pack" is given,
4486               "pack" assumes additional "" arguments.  If TEMPLATE requires
4487               fewer arguments than given, extra arguments are ignored.
4488
4489           ·   Attempting to pack the special floating point values "Inf" and
4490               "NaN" (infinity, also in negative, and not-a-number) into
4491               packed integer values (like "L") is a fatal error.  The reason
4492               for this is that there simply isn't any sensible mapping for
4493               these special values into integers.
4494
4495           Examples:
4496
4497               $foo = pack("WWWW",65,66,67,68);
4498               # foo eq "ABCD"
4499               $foo = pack("W4",65,66,67,68);
4500               # same thing
4501               $foo = pack("W4",0x24b6,0x24b7,0x24b8,0x24b9);
4502               # same thing with Unicode circled letters.
4503               $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9);
4504               # same thing with Unicode circled letters.  You don't get the
4505               # UTF-8 bytes because the U at the start of the format caused
4506               # a switch to U0-mode, so the UTF-8 bytes get joined into
4507               # characters
4508               $foo = pack("C0U4",0x24b6,0x24b7,0x24b8,0x24b9);
4509               # foo eq "\xe2\x92\xb6\xe2\x92\xb7\xe2\x92\xb8\xe2\x92\xb9"
4510               # This is the UTF-8 encoding of the string in the
4511               # previous example
4512
4513               $foo = pack("ccxxcc",65,66,67,68);
4514               # foo eq "AB\0\0CD"
4515
4516               # NOTE: The examples above featuring "W" and "c" are true
4517               # only on ASCII and ASCII-derived systems such as ISO Latin 1
4518               # and UTF-8.  On EBCDIC systems, the first example would be
4519               #      $foo = pack("WWWW",193,194,195,196);
4520
4521               $foo = pack("s2",1,2);
4522               # "\001\000\002\000" on little-endian
4523               # "\000\001\000\002" on big-endian
4524
4525               $foo = pack("a4","abcd","x","y","z");
4526               # "abcd"
4527
4528               $foo = pack("aaaa","abcd","x","y","z");
4529               # "axyz"
4530
4531               $foo = pack("a14","abcdefg");
4532               # "abcdefg\0\0\0\0\0\0\0"
4533
4534               $foo = pack("i9pl", gmtime);
4535               # a real struct tm (on my system anyway)
4536
4537               $utmp_template = "Z8 Z8 Z16 L";
4538               $utmp = pack($utmp_template, @utmp1);
4539               # a struct utmp (BSDish)
4540
4541               @utmp2 = unpack($utmp_template, $utmp);
4542               # "@utmp1" eq "@utmp2"
4543
4544               sub bintodec {
4545                   unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
4546               }
4547
4548               $foo = pack('sx2l', 12, 34);
4549               # short 12, two zero bytes padding, long 34
4550               $bar = pack('s@4l', 12, 34);
4551               # short 12, zero fill to position 4, long 34
4552               # $foo eq $bar
4553               $baz = pack('s.l', 12, 4, 34);
4554               # short 12, zero fill to position 4, long 34
4555
4556               $foo = pack('nN', 42, 4711);
4557               # pack big-endian 16- and 32-bit unsigned integers
4558               $foo = pack('S>L>', 42, 4711);
4559               # exactly the same
4560               $foo = pack('s<l<', -42, 4711);
4561               # pack little-endian 16- and 32-bit signed integers
4562               $foo = pack('(sl)<', -42, 4711);
4563               # exactly the same
4564
4565           The same template may generally also be used in "unpack".
4566
4567       package NAMESPACE
4568       package NAMESPACE VERSION
4569       package NAMESPACE BLOCK
4570       package NAMESPACE VERSION BLOCK
4571           Declares the BLOCK or the rest of the compilation unit as being in
4572           the given namespace.  The scope of the package declaration is
4573           either the supplied code BLOCK or, in the absence of a BLOCK, from
4574           the declaration itself through the end of current scope (the
4575           enclosing block, file, or "eval").  That is, the forms without a
4576           BLOCK are operative through the end of the current scope, just like
4577           the "my", "state", and "our" operators.  All unqualified dynamic
4578           identifiers in this scope will be in the given namespace, except
4579           where overridden by another "package" declaration or when they're
4580           one of the special identifiers that qualify into "main::", like
4581           "STDOUT", "ARGV", "ENV", and the punctuation variables.
4582
4583           A package statement affects dynamic variables only, including those
4584           you've used "local" on, but not lexically-scoped variables, which
4585           are created with "my", "state", or "our".  Typically it would be
4586           the first declaration in a file included by "require" or "use".
4587           You can switch into a package in more than one place, since this
4588           only determines which default symbol table the compiler uses for
4589           the rest of that block.  You can refer to identifiers in other
4590           packages than the current one by prefixing the identifier with the
4591           package name and a double colon, as in $SomePack::var or
4592           "ThatPack::INPUT_HANDLE".  If package name is omitted, the "main"
4593           package as assumed.  That is, $::sail is equivalent to $main::sail
4594           (as well as to "$main'sail", still seen in ancient code, mostly
4595           from Perl 4).
4596
4597           If VERSION is provided, "package" sets the $VERSION variable in the
4598           given namespace to a version object with the VERSION provided.
4599           VERSION must be a "strict" style version number as defined by the
4600           version module: a positive decimal number (integer or decimal-
4601           fraction) without exponentiation or else a dotted-decimal v-string
4602           with a leading 'v' character and at least three components.  You
4603           should set $VERSION only once per package.
4604
4605           See "Packages" in perlmod for more information about packages,
4606           modules, and classes.  See perlsub for other scoping issues.
4607
4608       __PACKAGE__
4609           A special token that returns the name of the package in which it
4610           occurs.
4611
4612       pipe READHANDLE,WRITEHANDLE
4613           Opens a pair of connected pipes like the corresponding system call.
4614           Note that if you set up a loop of piped processes, deadlock can
4615           occur unless you are very careful.  In addition, note that Perl's
4616           pipes use IO buffering, so you may need to set $| to flush your
4617           WRITEHANDLE after each command, depending on the application.
4618
4619           Returns true on success.
4620
4621           See IPC::Open2, IPC::Open3, and "Bidirectional Communication with
4622           Another Process" in perlipc for examples of such things.
4623
4624           On systems that support a close-on-exec flag on files, that flag is
4625           set on all newly opened file descriptors whose "fileno"s are higher
4626           than the current value of $^F (by default 2 for "STDERR").  See
4627           "$^F" in perlvar.
4628
4629       pop ARRAY
4630       pop Pops and returns the last value of the array, shortening the array
4631           by one element.
4632
4633           Returns the undefined value if the array is empty, although this
4634           may also happen at other times.  If ARRAY is omitted, pops the
4635           @ARGV array in the main program, but the @_ array in subroutines,
4636           just like "shift".
4637
4638           Starting with Perl 5.14, an experimental feature allowed "pop" to
4639           take a scalar expression. This experiment has been deemed
4640           unsuccessful, and was removed as of Perl 5.24.
4641
4642       pos SCALAR
4643       pos Returns the offset of where the last "m//g" search left off for the
4644           variable in question ($_ is used when the variable is not
4645           specified).  This offset is in characters unless the (no-longer-
4646           recommended) "use bytes" pragma is in effect, in which case the
4647           offset is in bytes.  Note that 0 is a valid match offset.  "undef"
4648           indicates that the search position is reset (usually due to match
4649           failure, but can also be because no match has yet been run on the
4650           scalar).
4651
4652           "pos" directly accesses the location used by the regexp engine to
4653           store the offset, so assigning to "pos" will change that offset,
4654           and so will also influence the "\G" zero-width assertion in regular
4655           expressions.  Both of these effects take place for the next match,
4656           so you can't affect the position with "pos" during the current
4657           match, such as in "(?{pos() = 5})" or "s//pos() = 5/e".
4658
4659           Setting "pos" also resets the matched with zero-length flag,
4660           described under "Repeated Patterns Matching a Zero-length
4661           Substring" in perlre.
4662
4663           Because a failed "m//gc" match doesn't reset the offset, the return
4664           from "pos" won't change either in this case.  See perlre and
4665           perlop.
4666
4667       print FILEHANDLE LIST
4668       print FILEHANDLE
4669       print LIST
4670       print
4671           Prints a string or a list of strings.  Returns true if successful.
4672           FILEHANDLE may be a scalar variable containing the name of or a
4673           reference to the filehandle, thus introducing one level of
4674           indirection.  (NOTE: If FILEHANDLE is a variable and the next token
4675           is a term, it may be misinterpreted as an operator unless you
4676           interpose a "+" or put parentheses around the arguments.)  If
4677           FILEHANDLE is omitted, prints to the last selected (see "select")
4678           output handle.  If LIST is omitted, prints $_ to the currently
4679           selected output handle.  To use FILEHANDLE alone to print the
4680           content of $_ to it, you must use a bareword filehandle like "FH",
4681           not an indirect one like $fh.  To set the default output handle to
4682           something other than STDOUT, use the select operation.
4683
4684           The current value of $, (if any) is printed between each LIST item.
4685           The current value of "$\" (if any) is printed after the entire LIST
4686           has been printed.  Because print takes a LIST, anything in the LIST
4687           is evaluated in list context, including any subroutines whose
4688           return lists you pass to "print".  Be careful not to follow the
4689           print keyword with a left parenthesis unless you want the
4690           corresponding right parenthesis to terminate the arguments to the
4691           print; put parentheses around all arguments (or interpose a "+",
4692           but that doesn't look as good).
4693
4694           If you're storing handles in an array or hash, or in general
4695           whenever you're using any expression more complex than a bareword
4696           handle or a plain, unsubscripted scalar variable to retrieve it,
4697           you will have to use a block returning the filehandle value
4698           instead, in which case the LIST may not be omitted:
4699
4700               print { $files[$i] } "stuff\n";
4701               print { $OK ? *STDOUT : *STDERR } "stuff\n";
4702
4703           Printing to a closed pipe or socket will generate a SIGPIPE signal.
4704           See perlipc for more on signal handling.
4705
4706       printf FILEHANDLE FORMAT, LIST
4707       printf FILEHANDLE
4708       printf FORMAT, LIST
4709       printf
4710           Equivalent to "print FILEHANDLE sprintf(FORMAT, LIST)", except that
4711           "$\" (the output record separator) is not appended.  The FORMAT and
4712           the LIST are actually parsed as a single list.  The first argument
4713           of the list will be interpreted as the "printf" format.  This means
4714           that "printf(@_)" will use $_[0] as the format.  See sprintf for an
4715           explanation of the format argument.  If "use locale" (including
4716           "use locale ':not_characters'") is in effect and "POSIX::setlocale"
4717           has been called, the character used for the decimal separator in
4718           formatted floating-point numbers is affected by the "LC_NUMERIC"
4719           locale setting.  See perllocale and POSIX.
4720
4721           For historical reasons, if you omit the list, $_ is used as the
4722           format; to use FILEHANDLE without a list, you must use a bareword
4723           filehandle like "FH", not an indirect one like $fh.  However, this
4724           will rarely do what you want; if $_ contains formatting codes, they
4725           will be replaced with the empty string and a warning will be
4726           emitted if warnings are enabled.  Just use "print" if you want to
4727           print the contents of $_.
4728
4729           Don't fall into the trap of using a "printf" when a simple "print"
4730           would do.  The "print" is more efficient and less error prone.
4731
4732       prototype FUNCTION
4733       prototype
4734           Returns the prototype of a function as a string (or "undef" if the
4735           function has no prototype).  FUNCTION is a reference to, or the
4736           name of, the function whose prototype you want to retrieve.  If
4737           FUNCTION is omitted, $_ is used.
4738
4739           If FUNCTION is a string starting with "CORE::", the rest is taken
4740           as a name for a Perl builtin.  If the builtin's arguments cannot be
4741           adequately expressed by a prototype (such as "system"), "prototype"
4742           returns "undef", because the builtin does not really behave like a
4743           Perl function.  Otherwise, the string describing the equivalent
4744           prototype is returned.
4745
4746       push ARRAY,LIST
4747           Treats ARRAY as a stack by appending the values of LIST to the end
4748           of ARRAY.  The length of ARRAY increases by the length of LIST.
4749           Has the same effect as
4750
4751               for my $value (LIST) {
4752                   $ARRAY[++$#ARRAY] = $value;
4753               }
4754
4755           but is more efficient.  Returns the number of elements in the array
4756           following the completed "push".
4757
4758           Starting with Perl 5.14, an experimental feature allowed "push" to
4759           take a scalar expression. This experiment has been deemed
4760           unsuccessful, and was removed as of Perl 5.24.
4761
4762       q/STRING/
4763       qq/STRING/
4764       qw/STRING/
4765       qx/STRING/
4766           Generalized quotes.  See "Quote-Like Operators" in perlop.
4767
4768       qr/STRING/
4769           Regexp-like quote.  See "Regexp Quote-Like Operators" in perlop.
4770
4771       quotemeta EXPR
4772       quotemeta
4773           Returns the value of EXPR with all the ASCII non-"word" characters
4774           backslashed.  (That is, all ASCII characters not matching
4775           "/[A-Za-z_0-9]/" will be preceded by a backslash in the returned
4776           string, regardless of any locale settings.)  This is the internal
4777           function implementing the "\Q" escape in double-quoted strings.
4778           (See below for the behavior on non-ASCII code points.)
4779
4780           If EXPR is omitted, uses $_.
4781
4782           quotemeta (and "\Q" ... "\E") are useful when interpolating strings
4783           into regular expressions, because by default an interpolated
4784           variable will be considered a mini-regular expression.  For
4785           example:
4786
4787               my $sentence = 'The quick brown fox jumped over the lazy dog';
4788               my $substring = 'quick.*?fox';
4789               $sentence =~ s{$substring}{big bad wolf};
4790
4791           Will cause $sentence to become 'The big bad wolf jumped over...'.
4792
4793           On the other hand:
4794
4795               my $sentence = 'The quick brown fox jumped over the lazy dog';
4796               my $substring = 'quick.*?fox';
4797               $sentence =~ s{\Q$substring\E}{big bad wolf};
4798
4799           Or:
4800
4801               my $sentence = 'The quick brown fox jumped over the lazy dog';
4802               my $substring = 'quick.*?fox';
4803               my $quoted_substring = quotemeta($substring);
4804               $sentence =~ s{$quoted_substring}{big bad wolf};
4805
4806           Will both leave the sentence as is.  Normally, when accepting
4807           literal string input from the user, "quotemeta" or "\Q" must be
4808           used.
4809
4810           In Perl v5.14, all non-ASCII characters are quoted in
4811           non-UTF-8-encoded strings, but not quoted in UTF-8 strings.
4812
4813           Starting in Perl v5.16, Perl adopted a Unicode-defined strategy for
4814           quoting non-ASCII characters; the quoting of ASCII characters is
4815           unchanged.
4816
4817           Also unchanged is the quoting of non-UTF-8 strings when outside the
4818           scope of a "use feature 'unicode_strings'", which is to quote all
4819           characters in the upper Latin1 range.  This provides complete
4820           backwards compatibility for old programs which do not use Unicode.
4821           (Note that "unicode_strings" is automatically enabled within the
4822           scope of a "use v5.12" or greater.)
4823
4824           Within the scope of "use locale", all non-ASCII Latin1 code points
4825           are quoted whether the string is encoded as UTF-8 or not.  As
4826           mentioned above, locale does not affect the quoting of ASCII-range
4827           characters.  This protects against those locales where characters
4828           such as "|" are considered to be word characters.
4829
4830           Otherwise, Perl quotes non-ASCII characters using an adaptation
4831           from Unicode (see <http://www.unicode.org/reports/tr31/>).  The
4832           only code points that are quoted are those that have any of the
4833           Unicode properties:  Pattern_Syntax, Pattern_White_Space,
4834           White_Space, Default_Ignorable_Code_Point, or
4835           General_Category=Control.
4836
4837           Of these properties, the two important ones are Pattern_Syntax and
4838           Pattern_White_Space.  They have been set up by Unicode for exactly
4839           this purpose of deciding which characters in a regular expression
4840           pattern should be quoted.  No character that can be in an
4841           identifier has these properties.
4842
4843           Perl promises, that if we ever add regular expression pattern
4844           metacharacters to the dozen already defined ("\ | ( ) [ { ^ $ * + ?
4845           ."), that we will only use ones that have the Pattern_Syntax
4846           property.  Perl also promises, that if we ever add characters that
4847           are considered to be white space in regular expressions (currently
4848           mostly affected by "/x"), they will all have the
4849           Pattern_White_Space property.
4850
4851           Unicode promises that the set of code points that have these two
4852           properties will never change, so something that is not quoted in
4853           v5.16 will never need to be quoted in any future Perl release.
4854           (Not all the code points that match Pattern_Syntax have actually
4855           had characters assigned to them; so there is room to grow, but they
4856           are quoted whether assigned or not.  Perl, of course, would never
4857           use an unassigned code point as an actual metacharacter.)
4858
4859           Quoting characters that have the other 3 properties is done to
4860           enhance the readability of the regular expression and not because
4861           they actually need to be quoted for regular expression purposes
4862           (characters with the White_Space property are likely to be
4863           indistinguishable on the page or screen from those with the
4864           Pattern_White_Space property; and the other two properties contain
4865           non-printing characters).
4866
4867       rand EXPR
4868       rand
4869           Returns a random fractional number greater than or equal to 0 and
4870           less than the value of EXPR.  (EXPR should be positive.)  If EXPR
4871           is omitted, the value 1 is used.  Currently EXPR with the value 0
4872           is also special-cased as 1 (this was undocumented before Perl 5.8.0
4873           and is subject to change in future versions of Perl).
4874           Automatically calls "srand" unless "srand" has already been called.
4875           See also "srand".
4876
4877           Apply "int" to the value returned by "rand" if you want random
4878           integers instead of random fractional numbers.  For example,
4879
4880               int(rand(10))
4881
4882           returns a random integer between 0 and 9, inclusive.
4883
4884           (Note: If your rand function consistently returns numbers that are
4885           too large or too small, then your version of Perl was probably
4886           compiled with the wrong number of RANDBITS.)
4887
4888           "rand" is not cryptographically secure.  You should not rely on it
4889           in security-sensitive situations.  As of this writing, a number of
4890           third-party CPAN modules offer random number generators intended by
4891           their authors to be cryptographically secure, including:
4892           Data::Entropy, Crypt::Random, Math::Random::Secure, and
4893           Math::TrulyRandom.
4894
4895       read FILEHANDLE,SCALAR,LENGTH,OFFSET
4896       read FILEHANDLE,SCALAR,LENGTH
4897           Attempts to read LENGTH characters of data into variable SCALAR
4898           from the specified FILEHANDLE.  Returns the number of characters
4899           actually read, 0 at end of file, or undef if there was an error (in
4900           the latter case $! is also set).  SCALAR will be grown or shrunk so
4901           that the last character actually read is the last character of the
4902           scalar after the read.
4903
4904           An OFFSET may be specified to place the read data at some place in
4905           the string other than the beginning.  A negative OFFSET specifies
4906           placement at that many characters counting backwards from the end
4907           of the string.  A positive OFFSET greater than the length of SCALAR
4908           results in the string being padded to the required size with "\0"
4909           bytes before the result of the read is appended.
4910
4911           The call is implemented in terms of either Perl's or your system's
4912           native fread(3) library function.  To get a true read(2) system
4913           call, see sysread.
4914
4915           Note the characters: depending on the status of the filehandle,
4916           either (8-bit) bytes or characters are read.  By default, all
4917           filehandles operate on bytes, but for example if the filehandle has
4918           been opened with the ":utf8" I/O layer (see "open", and the open
4919           pragma), the I/O will operate on UTF8-encoded Unicode characters,
4920           not bytes.  Similarly for the ":encoding" layer: in that case
4921           pretty much any characters can be read.
4922
4923       readdir DIRHANDLE
4924           Returns the next directory entry for a directory opened by
4925           "opendir".  If used in list context, returns all the rest of the
4926           entries in the directory.  If there are no more entries, returns
4927           the undefined value in scalar context and the empty list in list
4928           context.
4929
4930           If you're planning to filetest the return values out of a
4931           "readdir", you'd better prepend the directory in question.
4932           Otherwise, because we didn't "chdir" there, it would have been
4933           testing the wrong file.
4934
4935               opendir(my $dh, $some_dir) || die "Can't opendir $some_dir: $!";
4936               my @dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh);
4937               closedir $dh;
4938
4939           As of Perl 5.12 you can use a bare "readdir" in a "while" loop,
4940           which will set $_ on every iteration.
4941
4942               opendir(my $dh, $some_dir) || die "Can't open $some_dir: $!";
4943               while (readdir $dh) {
4944                   print "$some_dir/$_\n";
4945               }
4946               closedir $dh;
4947
4948           To avoid confusing would-be users of your code who are running
4949           earlier versions of Perl with mysterious failures, put this sort of
4950           thing at the top of your file to signal that your code will work
4951           only on Perls of a recent vintage:
4952
4953               use 5.012; # so readdir assigns to $_ in a lone while test
4954
4955       readline EXPR
4956       readline
4957           Reads from the filehandle whose typeglob is contained in EXPR (or
4958           from *ARGV if EXPR is not provided).  In scalar context, each call
4959           reads and returns the next line until end-of-file is reached,
4960           whereupon the subsequent call returns "undef".  In list context,
4961           reads until end-of-file is reached and returns a list of lines.
4962           Note that the notion of "line" used here is whatever you may have
4963           defined with $/ (or $INPUT_RECORD_SEPARATOR in English).  See "$/"
4964           in perlvar.
4965
4966           When $/ is set to "undef", when "readline" is in scalar context
4967           (i.e., file slurp mode), and when an empty file is read, it returns
4968           '' the first time, followed by "undef" subsequently.
4969
4970           This is the internal function implementing the "<EXPR>" operator,
4971           but you can use it directly.  The "<EXPR>" operator is discussed in
4972           more detail in "I/O Operators" in perlop.
4973
4974               my $line = <STDIN>;
4975               my $line = readline(STDIN);    # same thing
4976
4977           If "readline" encounters an operating system error, $! will be set
4978           with the corresponding error message.  It can be helpful to check
4979           $! when you are reading from filehandles you don't trust, such as a
4980           tty or a socket.  The following example uses the operator form of
4981           "readline" and dies if the result is not defined.
4982
4983               while ( ! eof($fh) ) {
4984                   defined( $_ = readline $fh ) or die "readline failed: $!";
4985                   ...
4986               }
4987
4988           Note that you have can't handle "readline" errors that way with the
4989           "ARGV" filehandle.  In that case, you have to open each element of
4990           @ARGV yourself since "eof" handles "ARGV" differently.
4991
4992               foreach my $arg (@ARGV) {
4993                   open(my $fh, $arg) or warn "Can't open $arg: $!";
4994
4995                   while ( ! eof($fh) ) {
4996                       defined( $_ = readline $fh )
4997                           or die "readline failed for $arg: $!";
4998                       ...
4999                   }
5000               }
5001
5002       readlink EXPR
5003       readlink
5004           Returns the value of a symbolic link, if symbolic links are
5005           implemented.  If not, raises an exception.  If there is a system
5006           error, returns the undefined value and sets $! (errno).  If EXPR is
5007           omitted, uses $_.
5008
5009           Portability issues: "readlink" in perlport.
5010
5011       readpipe EXPR
5012       readpipe
5013           EXPR is executed as a system command.  The collected standard
5014           output of the command is returned.  In scalar context, it comes
5015           back as a single (potentially multi-line) string.  In list context,
5016           returns a list of lines (however you've defined lines with $/ (or
5017           $INPUT_RECORD_SEPARATOR in English)).  This is the internal
5018           function implementing the "qx/EXPR/" operator, but you can use it
5019           directly.  The "qx/EXPR/" operator is discussed in more detail in
5020           "I/O Operators" in perlop.  If EXPR is omitted, uses $_.
5021
5022       recv SOCKET,SCALAR,LENGTH,FLAGS
5023           Receives a message on a socket.  Attempts to receive LENGTH
5024           characters of data into variable SCALAR from the specified SOCKET
5025           filehandle.  SCALAR will be grown or shrunk to the length actually
5026           read.  Takes the same flags as the system call of the same name.
5027           Returns the address of the sender if SOCKET's protocol supports
5028           this; returns an empty string otherwise.  If there's an error,
5029           returns the undefined value.  This call is actually implemented in
5030           terms of the recvfrom(2) system call.  See "UDP: Message Passing"
5031           in perlipc for examples.
5032
5033           Note the characters: depending on the status of the socket, either
5034           (8-bit) bytes or characters are received.  By default all sockets
5035           operate on bytes, but for example if the socket has been changed
5036           using "binmode" to operate with the ":encoding(UTF-8)" I/O layer
5037           (see the open pragma), the I/O will operate on UTF8-encoded Unicode
5038           characters, not bytes.  Similarly for the ":encoding" layer: in
5039           that case pretty much any characters can be read.
5040
5041       redo LABEL
5042       redo EXPR
5043       redo
5044           The "redo" command restarts the loop block without evaluating the
5045           conditional again.  The "continue" block, if any, is not executed.
5046           If the LABEL is omitted, the command refers to the innermost
5047           enclosing loop.  The "redo EXPR" form, available starting in Perl
5048           5.18.0, allows a label name to be computed at run time, and is
5049           otherwise identical to "redo LABEL".  Programs that want to lie to
5050           themselves about what was just input normally use this command:
5051
5052               # a simpleminded Pascal comment stripper
5053               # (warning: assumes no { or } in strings)
5054               LINE: while (<STDIN>) {
5055                   while (s|({.*}.*){.*}|$1 |) {}
5056                   s|{.*}| |;
5057                   if (s|{.*| |) {
5058                       my $front = $_;
5059                       while (<STDIN>) {
5060                           if (/}/) {  # end of comment?
5061                               s|^|$front\{|;
5062                               redo LINE;
5063                           }
5064                       }
5065                   }
5066                   print;
5067               }
5068
5069           "redo" cannot be used to retry a block that returns a value such as
5070           "eval {}", "sub {}", or "do {}", and should not be used to exit a
5071           "grep" or "map" operation.
5072
5073           Note that a block by itself is semantically identical to a loop
5074           that executes once.  Thus "redo" inside such a block will
5075           effectively turn it into a looping construct.
5076
5077           See also "continue" for an illustration of how "last", "next", and
5078           "redo" work.
5079
5080           Unlike most named operators, this has the same precedence as
5081           assignment.  It is also exempt from the looks-like-a-function rule,
5082           so "redo ("foo")."bar"" will cause "bar" to be part of the argument
5083           to "redo".
5084
5085       ref EXPR
5086       ref Returns a non-empty string if EXPR is a reference, the empty string
5087           otherwise.  If EXPR is not specified, $_ will be used.  The value
5088           returned depends on the type of thing the reference is a reference
5089           to.
5090
5091           Builtin types include:
5092
5093               SCALAR
5094               ARRAY
5095               HASH
5096               CODE
5097               REF
5098               GLOB
5099               LVALUE
5100               FORMAT
5101               IO
5102               VSTRING
5103               Regexp
5104
5105           You can think of "ref" as a "typeof" operator.
5106
5107               if (ref($r) eq "HASH") {
5108                   print "r is a reference to a hash.\n";
5109               }
5110               unless (ref($r)) {
5111                   print "r is not a reference at all.\n";
5112               }
5113
5114           The return value "LVALUE" indicates a reference to an lvalue that
5115           is not a variable.  You get this from taking the reference of
5116           function calls like "pos" or "substr".  "VSTRING" is returned if
5117           the reference points to a version string.
5118
5119           The result "Regexp" indicates that the argument is a regular
5120           expression resulting from "qr//".
5121
5122           If the referenced object has been blessed into a package, then that
5123           package name is returned instead.  But don't use that, as it's now
5124           considered "bad practice".  For one reason, an object could be
5125           using a class called "Regexp" or "IO", or even "HASH".  Also, "ref"
5126           doesn't take into account subclasses, like "isa" does.
5127
5128           Instead, use "blessed" (in the Scalar::Util module) for boolean
5129           checks, "isa" for specific class checks and "reftype" (also from
5130           Scalar::Util) for type checks.  (See perlobj for details and a
5131           "blessed"/"isa" example.)
5132
5133           See also perlref.
5134
5135       rename OLDNAME,NEWNAME
5136           Changes the name of a file; an existing file NEWNAME will be
5137           clobbered.  Returns true for success, false otherwise.
5138
5139           Behavior of this function varies wildly depending on your system
5140           implementation.  For example, it will usually not work across file
5141           system boundaries, even though the system mv command sometimes
5142           compensates for this.  Other restrictions include whether it works
5143           on directories, open files, or pre-existing files.  Check perlport
5144           and either the rename(2) manpage or equivalent system documentation
5145           for details.
5146
5147           For a platform independent "move" function look at the File::Copy
5148           module.
5149
5150           Portability issues: "rename" in perlport.
5151
5152       require VERSION
5153       require EXPR
5154       require
5155           Demands a version of Perl specified by VERSION, or demands some
5156           semantics specified by EXPR or by $_ if EXPR is not supplied.
5157
5158           VERSION may be either a numeric argument such as 5.006, which will
5159           be compared to $], or a literal of the form v5.6.1, which will be
5160           compared to $^V (or $PERL_VERSION in English).  An exception is
5161           raised if VERSION is greater than the version of the current Perl
5162           interpreter.  Compare with "use", which can do a similar check at
5163           compile time.
5164
5165           Specifying VERSION as a literal of the form v5.6.1 should generally
5166           be avoided, because it leads to misleading error messages under
5167           earlier versions of Perl that do not support this syntax.  The
5168           equivalent numeric version should be used instead.
5169
5170               require v5.6.1;     # run time version check
5171               require 5.6.1;      # ditto
5172               require 5.006_001;  # ditto; preferred for backwards
5173                                     compatibility
5174
5175           Otherwise, "require" demands that a library file be included if it
5176           hasn't already been included.  The file is included via the do-FILE
5177           mechanism, which is essentially just a variety of "eval" with the
5178           caveat that lexical variables in the invoking script will be
5179           invisible to the included code.  If it were implemented in pure
5180           Perl, it would have semantics similar to the following:
5181
5182               use Carp 'croak';
5183               use version;
5184
5185               sub require {
5186                   my ($filename) = @_;
5187                   if ( my $version = eval { version->parse($filename) } ) {
5188                       if ( $version > $^V ) {
5189                          my $vn = $version->normal;
5190                          croak "Perl $vn required--this is only $^V, stopped";
5191                       }
5192                       return 1;
5193                   }
5194
5195                   if (exists $INC{$filename}) {
5196                       return 1 if $INC{$filename};
5197                       croak "Compilation failed in require";
5198                   }
5199
5200                   foreach $prefix (@INC) {
5201                       if (ref($prefix)) {
5202                           #... do other stuff - see text below ....
5203                       }
5204                       # (see text below about possible appending of .pmc
5205                       # suffix to $filename)
5206                       my $realfilename = "$prefix/$filename";
5207                       next if ! -e $realfilename || -d _ || -b _;
5208                       $INC{$filename} = $realfilename;
5209                       my $result = do($realfilename);
5210                                    # but run in caller's namespace
5211
5212                       if (!defined $result) {
5213                           $INC{$filename} = undef;
5214                           croak $@ ? "$@Compilation failed in require"
5215                                    : "Can't locate $filename: $!\n";
5216                       }
5217                       if (!$result) {
5218                           delete $INC{$filename};
5219                           croak "$filename did not return true value";
5220                       }
5221                       $! = 0;
5222                       return $result;
5223                   }
5224                   croak "Can't locate $filename in \@INC ...";
5225               }
5226
5227           Note that the file will not be included twice under the same
5228           specified name.
5229
5230           The file must return true as the last statement to indicate
5231           successful execution of any initialization code, so it's customary
5232           to end such a file with "1;" unless you're sure it'll return true
5233           otherwise.  But it's better just to put the "1;", in case you add
5234           more statements.
5235
5236           If EXPR is a bareword, "require" assumes a .pm extension and
5237           replaces "::" with "/" in the filename for you, to make it easy to
5238           load standard modules.  This form of loading of modules does not
5239           risk altering your namespace.
5240
5241           In other words, if you try this:
5242
5243                   require Foo::Bar;     # a splendid bareword
5244
5245           The require function will actually look for the Foo/Bar.pm file in
5246           the directories specified in the @INC array.
5247
5248           But if you try this:
5249
5250                   my $class = 'Foo::Bar';
5251                   require $class;       # $class is not a bareword
5252               #or
5253                   require "Foo::Bar";   # not a bareword because of the ""
5254
5255           The require function will look for the Foo::Bar file in the @INC
5256           array and will complain about not finding Foo::Bar there.  In this
5257           case you can do:
5258
5259                   eval "require $class";
5260
5261           Now that you understand how "require" looks for files with a
5262           bareword argument, there is a little extra functionality going on
5263           behind the scenes.  Before "require" looks for a .pm extension, it
5264           will first look for a similar filename with a .pmc extension.  If
5265           this file is found, it will be loaded in place of any file ending
5266           in a .pm extension.
5267
5268           You can also insert hooks into the import facility by putting Perl
5269           code directly into the @INC array.  There are three forms of hooks:
5270           subroutine references, array references, and blessed objects.
5271
5272           Subroutine references are the simplest case.  When the inclusion
5273           system walks through @INC and encounters a subroutine, this
5274           subroutine gets called with two parameters, the first a reference
5275           to itself, and the second the name of the file to be included
5276           (e.g., Foo/Bar.pm).  The subroutine should return either nothing or
5277           else a list of up to four values in the following order:
5278
5279           1.  A reference to a scalar, containing any initial source code to
5280               prepend to the file or generator output.
5281
5282           2.  A filehandle, from which the file will be read.
5283
5284           3.  A reference to a subroutine.  If there is no filehandle
5285               (previous item), then this subroutine is expected to generate
5286               one line of source code per call, writing the line into $_ and
5287               returning 1, then finally at end of file returning 0.  If there
5288               is a filehandle, then the subroutine will be called to act as a
5289               simple source filter, with the line as read in $_.  Again,
5290               return 1 for each valid line, and 0 after all lines have been
5291               returned.
5292
5293           4.  Optional state for the subroutine.  The state is passed in as
5294               $_[1].  A reference to the subroutine itself is passed in as
5295               $_[0].
5296
5297           If an empty list, "undef", or nothing that matches the first 3
5298           values above is returned, then "require" looks at the remaining
5299           elements of @INC.  Note that this filehandle must be a real
5300           filehandle (strictly a typeglob or reference to a typeglob, whether
5301           blessed or unblessed); tied filehandles will be ignored and
5302           processing will stop there.
5303
5304           If the hook is an array reference, its first element must be a
5305           subroutine reference.  This subroutine is called as above, but the
5306           first parameter is the array reference.  This lets you indirectly
5307           pass arguments to the subroutine.
5308
5309           In other words, you can write:
5310
5311               push @INC, \&my_sub;
5312               sub my_sub {
5313                   my ($coderef, $filename) = @_;  # $coderef is \&my_sub
5314                   ...
5315               }
5316
5317           or:
5318
5319               push @INC, [ \&my_sub, $x, $y, ... ];
5320               sub my_sub {
5321                   my ($arrayref, $filename) = @_;
5322                   # Retrieve $x, $y, ...
5323                   my (undef, @parameters) = @$arrayref;
5324                   ...
5325               }
5326
5327           If the hook is an object, it must provide an "INC" method that will
5328           be called as above, the first parameter being the object itself.
5329           (Note that you must fully qualify the sub's name, as unqualified
5330           "INC" is always forced into package "main".)  Here is a typical
5331           code layout:
5332
5333               # In Foo.pm
5334               package Foo;
5335               sub new { ... }
5336               sub Foo::INC {
5337                   my ($self, $filename) = @_;
5338                   ...
5339               }
5340
5341               # In the main program
5342               push @INC, Foo->new(...);
5343
5344           These hooks are also permitted to set the %INC entry corresponding
5345           to the files they have loaded.  See "%INC" in perlvar.
5346
5347           For a yet-more-powerful import facility, see "use" and perlmod.
5348
5349       reset EXPR
5350       reset
5351           Generally used in a "continue" block at the end of a loop to clear
5352           variables and reset "m?pattern?" searches so that they work again.
5353           The expression is interpreted as a list of single characters
5354           (hyphens allowed for ranges).  All variables and arrays beginning
5355           with one of those letters are reset to their pristine state.  If
5356           the expression is omitted, one-match searches ("m?pattern?") are
5357           reset to match again.  Only resets variables or searches in the
5358           current package.  Always returns 1.  Examples:
5359
5360               reset 'X';      # reset all X variables
5361               reset 'a-z';    # reset lower case variables
5362               reset;          # just reset m?one-time? searches
5363
5364           Resetting "A-Z" is not recommended because you'll wipe out your
5365           @ARGV and @INC arrays and your %ENV hash.  Resets only package
5366           variables; lexical variables are unaffected, but they clean
5367           themselves up on scope exit anyway, so you'll probably want to use
5368           them instead.  See "my".
5369
5370       return EXPR
5371       return
5372           Returns from a subroutine, "eval", "do FILE", "sort" block or regex
5373           eval block (but not a "grep" or "map" block) with the value given
5374           in EXPR.  Evaluation of EXPR may be in list, scalar, or void
5375           context, depending on how the return value will be used, and the
5376           context may vary from one execution to the next (see "wantarray").
5377           If no EXPR is given, returns an empty list in list context, the
5378           undefined value in scalar context, and (of course) nothing at all
5379           in void context.
5380
5381           (In the absence of an explicit "return", a subroutine, "eval", or
5382           "do FILE" automatically returns the value of the last expression
5383           evaluated.)
5384
5385           Unlike most named operators, this is also exempt from the looks-
5386           like-a-function rule, so "return ("foo")."bar"" will cause "bar" to
5387           be part of the argument to "return".
5388
5389       reverse LIST
5390           In list context, returns a list value consisting of the elements of
5391           LIST in the opposite order.  In scalar context, concatenates the
5392           elements of LIST and returns a string value with all characters in
5393           the opposite order.
5394
5395               print join(", ", reverse "world", "Hello"); # Hello, world
5396
5397               print scalar reverse "dlrow ,", "olleH";    # Hello, world
5398
5399           Used without arguments in scalar context, "reverse" reverses $_.
5400
5401               $_ = "dlrow ,olleH";
5402               print reverse;                         # No output, list context
5403               print scalar reverse;                  # Hello, world
5404
5405           Note that reversing an array to itself (as in "@a = reverse @a")
5406           will preserve non-existent elements whenever possible; i.e., for
5407           non-magical arrays or for tied arrays with "EXISTS" and "DELETE"
5408           methods.
5409
5410           This operator is also handy for inverting a hash, although there
5411           are some caveats.  If a value is duplicated in the original hash,
5412           only one of those can be represented as a key in the inverted hash.
5413           Also, this has to unwind one hash and build a whole new one, which
5414           may take some time on a large hash, such as from a DBM file.
5415
5416               my %by_name = reverse %by_address;  # Invert the hash
5417
5418       rewinddir DIRHANDLE
5419           Sets the current position to the beginning of the directory for the
5420           "readdir" routine on DIRHANDLE.
5421
5422           Portability issues: "rewinddir" in perlport.
5423
5424       rindex STR,SUBSTR,POSITION
5425       rindex STR,SUBSTR
5426           Works just like "index" except that it returns the position of the
5427           last occurrence of SUBSTR in STR.  If POSITION is specified,
5428           returns the last occurrence beginning at or before that position.
5429
5430       rmdir FILENAME
5431       rmdir
5432           Deletes the directory specified by FILENAME if that directory is
5433           empty.  If it succeeds it returns true; otherwise it returns false
5434           and sets $! (errno).  If FILENAME is omitted, uses $_.
5435
5436           To remove a directory tree recursively ("rm -rf" on Unix) look at
5437           the "rmtree" function of the File::Path module.
5438
5439       s///
5440           The substitution operator.  See "Regexp Quote-Like Operators" in
5441           perlop.
5442
5443       say FILEHANDLE LIST
5444       say FILEHANDLE
5445       say LIST
5446       say Just like "print", but implicitly appends a newline.  "say LIST" is
5447           simply an abbreviation for "{ local $\ = "\n"; print LIST }".  To
5448           use FILEHANDLE without a LIST to print the contents of $_ to it,
5449           you must use a bareword filehandle like "FH", not an indirect one
5450           like $fh.
5451
5452           "say" is available only if the "say" feature is enabled or if it is
5453           prefixed with "CORE::".  The "say" feature is enabled automatically
5454           with a "use v5.10" (or higher) declaration in the current scope.
5455
5456       scalar EXPR
5457           Forces EXPR to be interpreted in scalar context and returns the
5458           value of EXPR.
5459
5460               my @counts = ( scalar @a, scalar @b, scalar @c );
5461
5462           There is no equivalent operator to force an expression to be
5463           interpolated in list context because in practice, this is never
5464           needed.  If you really wanted to do so, however, you could use the
5465           construction "@{[ (some expression) ]}", but usually a simple
5466           "(some expression)" suffices.
5467
5468           Because "scalar" is a unary operator, if you accidentally use a
5469           parenthesized list for the EXPR, this behaves as a scalar comma
5470           expression, evaluating all but the last element in void context and
5471           returning the final element evaluated in scalar context.  This is
5472           seldom what you want.
5473
5474           The following single statement:
5475
5476               print uc(scalar(foo(), $bar)), $baz;
5477
5478           is the moral equivalent of these two:
5479
5480               foo();
5481               print(uc($bar), $baz);
5482
5483           See perlop for more details on unary operators and the comma
5484           operator, and perldata for details on evaluating a hash in scalar
5485           contex.
5486
5487       seek FILEHANDLE,POSITION,WHENCE
5488           Sets FILEHANDLE's position, just like the fseek(3) call of C
5489           "stdio".  FILEHANDLE may be an expression whose value gives the
5490           name of the filehandle.  The values for WHENCE are 0 to set the new
5491           position in bytes to POSITION; 1 to set it to the current position
5492           plus POSITION; and 2 to set it to EOF plus POSITION, typically
5493           negative.  For WHENCE you may use the constants "SEEK_SET",
5494           "SEEK_CUR", and "SEEK_END" (start of the file, current position,
5495           end of the file) from the Fcntl module.  Returns 1 on success,
5496           false otherwise.
5497
5498           Note the emphasis on bytes: even if the filehandle has been set to
5499           operate on characters (for example using the ":encoding(UTF-8)" I/O
5500           layer), the "seek", "tell", and "sysseek" family of functions use
5501           byte offsets, not character offsets, because seeking to a character
5502           offset would be very slow in a UTF-8 file.
5503
5504           If you want to position the file for "sysread" or "syswrite", don't
5505           use "seek", because buffering makes its effect on the file's read-
5506           write position unpredictable and non-portable.  Use "sysseek"
5507           instead.
5508
5509           Due to the rules and rigors of ANSI C, on some systems you have to
5510           do a seek whenever you switch between reading and writing.  Amongst
5511           other things, this may have the effect of calling stdio's
5512           clearerr(3).  A WHENCE of 1 ("SEEK_CUR") is useful for not moving
5513           the file position:
5514
5515               seek($fh, 0, 1);
5516
5517           This is also useful for applications emulating "tail -f".  Once you
5518           hit EOF on your read and then sleep for a while, you (probably)
5519           have to stick in a dummy "seek" to reset things.  The "seek"
5520           doesn't change the position, but it does clear the end-of-file
5521           condition on the handle, so that the next "readline FILE" makes
5522           Perl try again to read something.  (We hope.)
5523
5524           If that doesn't work (some I/O implementations are particularly
5525           cantankerous), you might need something like this:
5526
5527               for (;;) {
5528                   for ($curpos = tell($fh); $_ = readline($fh);
5529                        $curpos = tell($fh)) {
5530                       # search for some stuff and put it into files
5531                   }
5532                   sleep($for_a_while);
5533                   seek($fh, $curpos, 0);
5534               }
5535
5536       seekdir DIRHANDLE,POS
5537           Sets the current position for the "readdir" routine on DIRHANDLE.
5538           POS must be a value returned by "telldir".  "seekdir" also has the
5539           same caveats about possible directory compaction as the
5540           corresponding system library routine.
5541
5542       select FILEHANDLE
5543       select
5544           Returns the currently selected filehandle.  If FILEHANDLE is
5545           supplied, sets the new current default filehandle for output.  This
5546           has two effects: first, a "write" or a "print" without a filehandle
5547           default to this FILEHANDLE.  Second, references to variables
5548           related to output will refer to this output channel.
5549
5550           For example, to set the top-of-form format for more than one output
5551           channel, you might do the following:
5552
5553               select(REPORT1);
5554               $^ = 'report1_top';
5555               select(REPORT2);
5556               $^ = 'report2_top';
5557
5558           FILEHANDLE may be an expression whose value gives the name of the
5559           actual filehandle.  Thus:
5560
5561               my $oldfh = select(STDERR); $| = 1; select($oldfh);
5562
5563           Some programmers may prefer to think of filehandles as objects with
5564           methods, preferring to write the last example as:
5565
5566               STDERR->autoflush(1);
5567
5568           (Prior to Perl version 5.14, you have to "use IO::Handle;"
5569           explicitly first.)
5570
5571           Portability issues: "select" in perlport.
5572
5573       select RBITS,WBITS,EBITS,TIMEOUT
5574           This calls the select(2) syscall with the bit masks specified,
5575           which can be constructed using "fileno" and "vec", along these
5576           lines:
5577
5578               my $rin = my $win = my $ein = '';
5579               vec($rin, fileno(STDIN),  1) = 1;
5580               vec($win, fileno(STDOUT), 1) = 1;
5581               $ein = $rin | $win;
5582
5583           If you want to select on many filehandles, you may wish to write a
5584           subroutine like this:
5585
5586               sub fhbits {
5587                   my @fhlist = @_;
5588                   my $bits = "";
5589                   for my $fh (@fhlist) {
5590                       vec($bits, fileno($fh), 1) = 1;
5591                   }
5592                   return $bits;
5593               }
5594               my $rin = fhbits(\*STDIN, $tty, $mysock);
5595
5596           The usual idiom is:
5597
5598            my ($nfound, $timeleft) =
5599              select(my $rout = $rin, my $wout = $win, my $eout = $ein,
5600                                                                     $timeout);
5601
5602           or to block until something becomes ready just do this
5603
5604            my $nfound =
5605              select(my $rout = $rin, my $wout = $win, my $eout = $ein, undef);
5606
5607           Most systems do not bother to return anything useful in $timeleft,
5608           so calling "select" in scalar context just returns $nfound.
5609
5610           Any of the bit masks can also be "undef".  The timeout, if
5611           specified, is in seconds, which may be fractional.  Note: not all
5612           implementations are capable of returning the $timeleft.  If not,
5613           they always return $timeleft equal to the supplied $timeout.
5614
5615           You can effect a sleep of 250 milliseconds this way:
5616
5617               select(undef, undef, undef, 0.25);
5618
5619           Note that whether "select" gets restarted after signals (say,
5620           SIGALRM) is implementation-dependent.  See also perlport for notes
5621           on the portability of "select".
5622
5623           On error, "select" behaves just like select(2): it returns "-1" and
5624           sets $!.
5625
5626           On some Unixes, select(2) may report a socket file descriptor as
5627           "ready for reading" even when no data is available, and thus any
5628           subsequent "read" would block.  This can be avoided if you always
5629           use "O_NONBLOCK" on the socket.  See select(2) and fcntl(2) for
5630           further details.
5631
5632           The standard "IO::Select" module provides a user-friendlier
5633           interface to "select", mostly because it does all the bit-mask work
5634           for you.
5635
5636           WARNING: One should not attempt to mix buffered I/O (like "read" or
5637           "readline") with "select", except as permitted by POSIX, and even
5638           then only on POSIX systems.  You have to use "sysread" instead.
5639
5640           Portability issues: "select" in perlport.
5641
5642       semctl ID,SEMNUM,CMD,ARG
5643           Calls the System V IPC function semctl(2).  You'll probably have to
5644           say
5645
5646               use IPC::SysV;
5647
5648           first to get the correct constant definitions.  If CMD is IPC_STAT
5649           or GETALL, then ARG must be a variable that will hold the returned
5650           semid_ds structure or semaphore value array.  Returns like "ioctl":
5651           the undefined value for error, ""0 but true"" for zero, or the
5652           actual return value otherwise.  The ARG must consist of a vector of
5653           native short integers, which may be created with
5654           "pack("s!",(0)x$nsem)".  See also "SysV IPC" in perlipc and the
5655           documentation for "IPC::SysV" and "IPC::Semaphore".
5656
5657           Portability issues: "semctl" in perlport.
5658
5659       semget KEY,NSEMS,FLAGS
5660           Calls the System V IPC function semget(2).  Returns the semaphore
5661           id, or the undefined value on error.  See also "SysV IPC" in
5662           perlipc and the documentation for "IPC::SysV" and "IPC::Semaphore".
5663
5664           Portability issues: "semget" in perlport.
5665
5666       semop KEY,OPSTRING
5667           Calls the System V IPC function semop(2) for semaphore operations
5668           such as signalling and waiting.  OPSTRING must be a packed array of
5669           semop structures.  Each semop structure can be generated with
5670           "pack("s!3", $semnum, $semop, $semflag)".  The length of OPSTRING
5671           implies the number of semaphore operations.  Returns true if
5672           successful, false on error.  As an example, the following code
5673           waits on semaphore $semnum of semaphore id $semid:
5674
5675               my $semop = pack("s!3", $semnum, -1, 0);
5676               die "Semaphore trouble: $!\n" unless semop($semid, $semop);
5677
5678           To signal the semaphore, replace "-1" with 1.  See also "SysV IPC"
5679           in perlipc and the documentation for "IPC::SysV" and
5680           "IPC::Semaphore".
5681
5682           Portability issues: "semop" in perlport.
5683
5684       send SOCKET,MSG,FLAGS,TO
5685       send SOCKET,MSG,FLAGS
5686           Sends a message on a socket.  Attempts to send the scalar MSG to
5687           the SOCKET filehandle.  Takes the same flags as the system call of
5688           the same name.  On unconnected sockets, you must specify a
5689           destination to send to, in which case it does a sendto(2) syscall.
5690           Returns the number of characters sent, or the undefined value on
5691           error.  The sendmsg(2) syscall is currently unimplemented.  See
5692           "UDP: Message Passing" in perlipc for examples.
5693
5694           Note the characters: depending on the status of the socket, either
5695           (8-bit) bytes or characters are sent.  By default all sockets
5696           operate on bytes, but for example if the socket has been changed
5697           using "binmode" to operate with the ":encoding(UTF-8)" I/O layer
5698           (see "open", or the open pragma), the I/O will operate on UTF-8
5699           encoded Unicode characters, not bytes.  Similarly for the
5700           ":encoding" layer: in that case pretty much any characters can be
5701           sent.
5702
5703       setpgrp PID,PGRP
5704           Sets the current process group for the specified PID, 0 for the
5705           current process.  Raises an exception when used on a machine that
5706           doesn't implement POSIX setpgid(2) or BSD setpgrp(2).  If the
5707           arguments are omitted, it defaults to "0,0".  Note that the BSD 4.2
5708           version of "setpgrp" does not accept any arguments, so only
5709           "setpgrp(0,0)" is portable.  See also "POSIX::setsid()".
5710
5711           Portability issues: "setpgrp" in perlport.
5712
5713       setpriority WHICH,WHO,PRIORITY
5714           Sets the current priority for a process, a process group, or a
5715           user.  (See setpriority(2).)  Raises an exception when used on a
5716           machine that doesn't implement setpriority(2).
5717
5718           Portability issues: "setpriority" in perlport.
5719
5720       setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
5721           Sets the socket option requested.  Returns "undef" on error.  Use
5722           integer constants provided by the "Socket" module for LEVEL and
5723           OPNAME.  Values for LEVEL can also be obtained from getprotobyname.
5724           OPTVAL might either be a packed string or an integer.  An integer
5725           OPTVAL is shorthand for pack("i", OPTVAL).
5726
5727           An example disabling Nagle's algorithm on a socket:
5728
5729               use Socket qw(IPPROTO_TCP TCP_NODELAY);
5730               setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
5731
5732           Portability issues: "setsockopt" in perlport.
5733
5734       shift ARRAY
5735       shift
5736           Shifts the first value of the array off and returns it, shortening
5737           the array by 1 and moving everything down.  If there are no
5738           elements in the array, returns the undefined value.  If ARRAY is
5739           omitted, shifts the @_ array within the lexical scope of
5740           subroutines and formats, and the @ARGV array outside a subroutine
5741           and also within the lexical scopes established by the "eval
5742           STRING", "BEGIN {}", "INIT {}", "CHECK {}", "UNITCHECK {}", and
5743           "END {}" constructs.
5744
5745           Starting with Perl 5.14, an experimental feature allowed "shift" to
5746           take a scalar expression. This experiment has been deemed
5747           unsuccessful, and was removed as of Perl 5.24.
5748
5749           See also "unshift", "push", and "pop".  "shift" and "unshift" do
5750           the same thing to the left end of an array that "pop" and "push" do
5751           to the right end.
5752
5753       shmctl ID,CMD,ARG
5754           Calls the System V IPC function shmctl.  You'll probably have to
5755           say
5756
5757               use IPC::SysV;
5758
5759           first to get the correct constant definitions.  If CMD is
5760           "IPC_STAT", then ARG must be a variable that will hold the returned
5761           "shmid_ds" structure.  Returns like ioctl: "undef" for error; "0
5762           but true" for zero; and the actual return value otherwise.  See
5763           also "SysV IPC" in perlipc and the documentation for "IPC::SysV".
5764
5765           Portability issues: "shmctl" in perlport.
5766
5767       shmget KEY,SIZE,FLAGS
5768           Calls the System V IPC function shmget.  Returns the shared memory
5769           segment id, or "undef" on error.  See also "SysV IPC" in perlipc
5770           and the documentation for "IPC::SysV".
5771
5772           Portability issues: "shmget" in perlport.
5773
5774       shmread ID,VAR,POS,SIZE
5775       shmwrite ID,STRING,POS,SIZE
5776           Reads or writes the System V shared memory segment ID starting at
5777           position POS for size SIZE by attaching to it, copying in/out, and
5778           detaching from it.  When reading, VAR must be a variable that will
5779           hold the data read.  When writing, if STRING is too long, only SIZE
5780           bytes are used; if STRING is too short, nulls are written to fill
5781           out SIZE bytes.  Return true if successful, false on error.
5782           "shmread" taints the variable.  See also "SysV IPC" in perlipc and
5783           the documentation for "IPC::SysV" and the "IPC::Shareable" module
5784           from CPAN.
5785
5786           Portability issues: "shmread" in perlport and "shmwrite" in
5787           perlport.
5788
5789       shutdown SOCKET,HOW
5790           Shuts down a socket connection in the manner indicated by HOW,
5791           which has the same interpretation as in the syscall of the same
5792           name.
5793
5794               shutdown($socket, 0);    # I/we have stopped reading data
5795               shutdown($socket, 1);    # I/we have stopped writing data
5796               shutdown($socket, 2);    # I/we have stopped using this socket
5797
5798           This is useful with sockets when you want to tell the other side
5799           you're done writing but not done reading, or vice versa.  It's also
5800           a more insistent form of close because it also disables the file
5801           descriptor in any forked copies in other processes.
5802
5803           Returns 1 for success; on error, returns "undef" if the first
5804           argument is not a valid filehandle, or returns 0 and sets $! for
5805           any other failure.
5806
5807       sin EXPR
5808       sin Returns the sine of EXPR (expressed in radians).  If EXPR is
5809           omitted, returns sine of $_.
5810
5811           For the inverse sine operation, you may use the "Math::Trig::asin"
5812           function, or use this relation:
5813
5814               sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
5815
5816       sleep EXPR
5817       sleep
5818           Causes the script to sleep for (integer) EXPR seconds, or forever
5819           if no argument is given.  Returns the integer number of seconds
5820           actually slept.
5821
5822           May be interrupted if the process receives a signal such as
5823           "SIGALRM".
5824
5825               eval {
5826                   local $SIG{ALRM} = sub { die "Alarm!\n" };
5827                   sleep;
5828               };
5829               die $@ unless $@ eq "Alarm!\n";
5830
5831           You probably cannot mix "alarm" and "sleep" calls, because "sleep"
5832           is often implemented using "alarm".
5833
5834           On some older systems, it may sleep up to a full second less than
5835           what you requested, depending on how it counts seconds.  Most
5836           modern systems always sleep the full amount.  They may appear to
5837           sleep longer than that, however, because your process might not be
5838           scheduled right away in a busy multitasking system.
5839
5840           For delays of finer granularity than one second, the Time::HiRes
5841           module (from CPAN, and starting from Perl 5.8 part of the standard
5842           distribution) provides "usleep".  You may also use Perl's four-
5843           argument version of "select" leaving the first three arguments
5844           undefined, or you might be able to use the "syscall" interface to
5845           access setitimer(2) if your system supports it.  See perlfaq8 for
5846           details.
5847
5848           See also the POSIX module's "pause" function.
5849
5850       socket SOCKET,DOMAIN,TYPE,PROTOCOL
5851           Opens a socket of the specified kind and attaches it to filehandle
5852           SOCKET.  DOMAIN, TYPE, and PROTOCOL are specified the same as for
5853           the syscall of the same name.  You should "use Socket" first to get
5854           the proper definitions imported.  See the examples in "Sockets:
5855           Client/Server Communication" in perlipc.
5856
5857           On systems that support a close-on-exec flag on files, the flag
5858           will be set for the newly opened file descriptor, as determined by
5859           the value of $^F.  See "$^F" in perlvar.
5860
5861       socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
5862           Creates an unnamed pair of sockets in the specified domain, of the
5863           specified type.  DOMAIN, TYPE, and PROTOCOL are specified the same
5864           as for the syscall of the same name.  If unimplemented, raises an
5865           exception.  Returns true if successful.
5866
5867           On systems that support a close-on-exec flag on files, the flag
5868           will be set for the newly opened file descriptors, as determined by
5869           the value of $^F.  See "$^F" in perlvar.
5870
5871           Some systems define "pipe" in terms of "socketpair", in which a
5872           call to "pipe($rdr, $wtr)" is essentially:
5873
5874               use Socket;
5875               socketpair(my $rdr, my $wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC);
5876               shutdown($rdr, 1);        # no more writing for reader
5877               shutdown($wtr, 0);        # no more reading for writer
5878
5879           See perlipc for an example of socketpair use.  Perl 5.8 and later
5880           will emulate socketpair using IP sockets to localhost if your
5881           system implements sockets but not socketpair.
5882
5883           Portability issues: "socketpair" in perlport.
5884
5885       sort SUBNAME LIST
5886       sort BLOCK LIST
5887       sort LIST
5888           In list context, this sorts the LIST and returns the sorted list
5889           value.  In scalar context, the behaviour of "sort" is undefined.
5890
5891           If SUBNAME or BLOCK is omitted, "sort"s in standard string
5892           comparison order.  If SUBNAME is specified, it gives the name of a
5893           subroutine that returns an integer less than, equal to, or greater
5894           than 0, depending on how the elements of the list are to be
5895           ordered.  (The "<=>" and "cmp" operators are extremely useful in
5896           such routines.)  SUBNAME may be a scalar variable name
5897           (unsubscripted), in which case the value provides the name of (or a
5898           reference to) the actual subroutine to use.  In place of a SUBNAME,
5899           you can provide a BLOCK as an anonymous, in-line sort subroutine.
5900
5901           If the subroutine's prototype is "($$)", the elements to be
5902           compared are passed by reference in @_, as for a normal subroutine.
5903           This is slower than unprototyped subroutines, where the elements to
5904           be compared are passed into the subroutine as the package global
5905           variables $a and $b (see example below).
5906
5907           If the subroutine is an XSUB, the elements to be compared are
5908           pushed on to the stack, the way arguments are usually passed to
5909           XSUBs.  $a and $b are not set.
5910
5911           The values to be compared are always passed by reference and should
5912           not be modified.
5913
5914           You also cannot exit out of the sort block or subroutine using any
5915           of the loop control operators described in perlsyn or with "goto".
5916
5917           When "use locale" (but not "use locale ':not_characters'") is in
5918           effect, "sort LIST" sorts LIST according to the current collation
5919           locale.  See perllocale.
5920
5921           "sort" returns aliases into the original list, much as a for loop's
5922           index variable aliases the list elements.  That is, modifying an
5923           element of a list returned by "sort" (for example, in a "foreach",
5924           "map" or "grep") actually modifies the element in the original
5925           list.  This is usually something to be avoided when writing clear
5926           code.
5927
5928           Perl 5.6 and earlier used a quicksort algorithm to implement sort.
5929           That algorithm was not stable and could go quadratic.  (A stable
5930           sort preserves the input order of elements that compare equal.
5931           Although quicksort's run time is O(NlogN) when averaged over all
5932           arrays of length N, the time can be O(N**2), quadratic behavior,
5933           for some inputs.)  In 5.7, the quicksort implementation was
5934           replaced with a stable mergesort algorithm whose worst-case
5935           behavior is O(NlogN).  But benchmarks indicated that for some
5936           inputs, on some platforms, the original quicksort was faster.  5.8
5937           has a sort pragma for limited control of the sort.  Its rather
5938           blunt control of the underlying algorithm may not persist into
5939           future Perls, but the ability to characterize the input or output
5940           in implementation independent ways quite probably will.
5941
5942           Examples:
5943
5944               # sort lexically
5945               my @articles = sort @files;
5946
5947               # same thing, but with explicit sort routine
5948               my @articles = sort {$a cmp $b} @files;
5949
5950               # now case-insensitively
5951               my @articles = sort {fc($a) cmp fc($b)} @files;
5952
5953               # same thing in reversed order
5954               my @articles = sort {$b cmp $a} @files;
5955
5956               # sort numerically ascending
5957               my @articles = sort {$a <=> $b} @files;
5958
5959               # sort numerically descending
5960               my @articles = sort {$b <=> $a} @files;
5961
5962               # this sorts the %age hash by value instead of key
5963               # using an in-line function
5964               my @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
5965
5966               # sort using explicit subroutine name
5967               sub byage {
5968                   $age{$a} <=> $age{$b};  # presuming numeric
5969               }
5970               my @sortedclass = sort byage @class;
5971
5972               sub backwards { $b cmp $a }
5973               my @harry  = qw(dog cat x Cain Abel);
5974               my @george = qw(gone chased yz Punished Axed);
5975               print sort @harry;
5976                   # prints AbelCaincatdogx
5977               print sort backwards @harry;
5978                   # prints xdogcatCainAbel
5979               print sort @george, 'to', @harry;
5980                   # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
5981
5982               # inefficiently sort by descending numeric compare using
5983               # the first integer after the first = sign, or the
5984               # whole record case-insensitively otherwise
5985
5986               my @new = sort {
5987                   ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
5988                                       ||
5989                               fc($a)  cmp  fc($b)
5990               } @old;
5991
5992               # same thing, but much more efficiently;
5993               # we'll build auxiliary indices instead
5994               # for speed
5995               my (@nums, @caps);
5996               for (@old) {
5997                   push @nums, ( /=(\d+)/ ? $1 : undef );
5998                   push @caps, fc($_);
5999               }
6000
6001               my @new = @old[ sort {
6002                                      $nums[$b] <=> $nums[$a]
6003                                               ||
6004                                      $caps[$a] cmp $caps[$b]
6005                                    } 0..$#old
6006                             ];
6007
6008               # same thing, but without any temps
6009               my @new = map { $_->[0] }
6010                      sort { $b->[1] <=> $a->[1]
6011                                      ||
6012                             $a->[2] cmp $b->[2]
6013                      } map { [$_, /=(\d+)/, fc($_)] } @old;
6014
6015               # using a prototype allows you to use any comparison subroutine
6016               # as a sort subroutine (including other package's subroutines)
6017               package Other;
6018               sub backwards ($$) { $_[1] cmp $_[0]; }  # $a and $b are
6019                                                        # not set here
6020               package main;
6021               my @new = sort Other::backwards @old;
6022
6023               # guarantee stability, regardless of algorithm
6024               use sort 'stable';
6025               my @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
6026
6027               # force use of mergesort (not portable outside Perl 5.8)
6028               use sort '_mergesort';  # note discouraging _
6029               my @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
6030
6031           Warning: syntactical care is required when sorting the list
6032           returned from a function.  If you want to sort the list returned by
6033           the function call "find_records(@key)", you can use:
6034
6035               my @contact = sort { $a cmp $b } find_records @key;
6036               my @contact = sort +find_records(@key);
6037               my @contact = sort &find_records(@key);
6038               my @contact = sort(find_records(@key));
6039
6040           If instead you want to sort the array @key with the comparison
6041           routine "find_records()" then you can use:
6042
6043               my @contact = sort { find_records() } @key;
6044               my @contact = sort find_records(@key);
6045               my @contact = sort(find_records @key);
6046               my @contact = sort(find_records (@key));
6047
6048           $a and $b are set as package globals in the package the sort() is
6049           called from.  That means $main::a and $main::b (or $::a and $::b)
6050           in the "main" package, $FooPack::a and $FooPack::b in the "FooPack"
6051           package, etc.  If the sort block is in scope of a "my" or "state"
6052           declaration of $a and/or $b, you must spell out the full name of
6053           the variables in the sort block :
6054
6055              package main;
6056              my $a = "C"; # DANGER, Will Robinson, DANGER !!!
6057
6058              print sort { $a cmp $b }               qw(A C E G B D F H);
6059                                                     # WRONG
6060              sub badlexi { $a cmp $b }
6061              print sort badlexi                     qw(A C E G B D F H);
6062                                                     # WRONG
6063              # the above prints BACFEDGH or some other incorrect ordering
6064
6065              print sort { $::a cmp $::b }           qw(A C E G B D F H);
6066                                                     # OK
6067              print sort { our $a cmp our $b }       qw(A C E G B D F H);
6068                                                     # also OK
6069              print sort { our ($a, $b); $a cmp $b } qw(A C E G B D F H);
6070                                                     # also OK
6071              sub lexi { our $a cmp our $b }
6072              print sort lexi                        qw(A C E G B D F H);
6073                                                     # also OK
6074              # the above print ABCDEFGH
6075
6076           With proper care you may mix package and my (or state) $a and/or
6077           $b:
6078
6079              my $a = {
6080                 tiny   => -2,
6081                 small  => -1,
6082                 normal => 0,
6083                 big    => 1,
6084                 huge   => 2
6085              };
6086
6087              say sort { $a->{our $a} <=> $a->{our $b} }
6088                  qw{ huge normal tiny small big};
6089
6090              # prints tinysmallnormalbighuge
6091
6092           $a and $b are implicitely local to the sort() execution and regain
6093           their former values upon completing the sort.
6094
6095           Sort subroutines written using $a and $b are bound to their calling
6096           package. It is possible, but of limited interest, to define them in
6097           a different package, since the subroutine must still refer to the
6098           calling package's $a and $b :
6099
6100              package Foo;
6101              sub lexi { $Bar::a cmp $Bar::b }
6102              package Bar;
6103              ... sort Foo::lexi ...
6104
6105           Use the prototyped versions (see above) for a more generic
6106           alternative.
6107
6108           The comparison function is required to behave.  If it returns
6109           inconsistent results (sometimes saying $x[1] is less than $x[2] and
6110           sometimes saying the opposite, for example) the results are not
6111           well-defined.
6112
6113           Because "<=>" returns "undef" when either operand is "NaN" (not-a-
6114           number), be careful when sorting with a comparison function like
6115           "$a <=> $b" any lists that might contain a "NaN".  The following
6116           example takes advantage that "NaN != NaN" to eliminate any "NaN"s
6117           from the input list.
6118
6119               my @result = sort { $a <=> $b } grep { $_ == $_ } @input;
6120
6121       splice ARRAY,OFFSET,LENGTH,LIST
6122       splice ARRAY,OFFSET,LENGTH
6123       splice ARRAY,OFFSET
6124       splice ARRAY
6125           Removes the elements designated by OFFSET and LENGTH from an array,
6126           and replaces them with the elements of LIST, if any.  In list
6127           context, returns the elements removed from the array.  In scalar
6128           context, returns the last element removed, or "undef" if no
6129           elements are removed.  The array grows or shrinks as necessary.  If
6130           OFFSET is negative then it starts that far from the end of the
6131           array.  If LENGTH is omitted, removes everything from OFFSET
6132           onward.  If LENGTH is negative, removes the elements from OFFSET
6133           onward except for -LENGTH elements at the end of the array.  If
6134           both OFFSET and LENGTH are omitted, removes everything.  If OFFSET
6135           is past the end of the array and a LENGTH was provided, Perl issues
6136           a warning, and splices at the end of the array.
6137
6138           The following equivalences hold (assuming "$#a >= $i" )
6139
6140               push(@a,$x,$y)      splice(@a,@a,0,$x,$y)
6141               pop(@a)             splice(@a,-1)
6142               shift(@a)           splice(@a,0,1)
6143               unshift(@a,$x,$y)   splice(@a,0,0,$x,$y)
6144               $a[$i] = $y         splice(@a,$i,1,$y)
6145
6146           "splice" can be used, for example, to implement n-ary queue
6147           processing:
6148
6149               sub nary_print {
6150                 my $n = shift;
6151                 while (my @next_n = splice @_, 0, $n) {
6152                   say join q{ -- }, @next_n;
6153                 }
6154               }
6155
6156               nary_print(3, qw(a b c d e f g h));
6157               # prints:
6158               #   a -- b -- c
6159               #   d -- e -- f
6160               #   g -- h
6161
6162           Starting with Perl 5.14, an experimental feature allowed "splice"
6163           to take a scalar expression. This experiment has been deemed
6164           unsuccessful, and was removed as of Perl 5.24.
6165
6166       split /PATTERN/,EXPR,LIMIT
6167       split /PATTERN/,EXPR
6168       split /PATTERN/
6169       split
6170           Splits the string EXPR into a list of strings and returns the list
6171           in list context, or the size of the list in scalar context.  (Prior
6172           to Perl 5.11, it also overwrote @_ with the list in void and scalar
6173           context. If you target old perls, beware.)
6174
6175           If only PATTERN is given, EXPR defaults to $_.
6176
6177           Anything in EXPR that matches PATTERN is taken to be a separator
6178           that separates the EXPR into substrings (called "fields") that do
6179           not include the separator.  Note that a separator may be longer
6180           than one character or even have no characters at all (the empty
6181           string, which is a zero-width match).
6182
6183           The PATTERN need not be constant; an expression may be used to
6184           specify a pattern that varies at runtime.
6185
6186           If PATTERN matches the empty string, the EXPR is split at the match
6187           position (between characters).  As an example, the following:
6188
6189               print join(':', split(/b/, 'abc')), "\n";
6190
6191           uses the "b" in 'abc' as a separator to produce the output "a:c".
6192           However, this:
6193
6194               print join(':', split(//, 'abc')), "\n";
6195
6196           uses empty string matches as separators to produce the output
6197           "a:b:c"; thus, the empty string may be used to split EXPR into a
6198           list of its component characters.
6199
6200           As a special case for "split", the empty pattern given in match
6201           operator syntax ("//") specifically matches the empty string, which
6202           is contrary to its usual interpretation as the last successful
6203           match.
6204
6205           If PATTERN is "/^/", then it is treated as if it used the multiline
6206           modifier ("/^/m"), since it isn't much use otherwise.
6207
6208           "/m" and any of the other pattern modifiers valid for "qr"
6209           (summarized in "qr/STRING/msixpodualn" in perlop) may be specified
6210           explicitly.
6211
6212           As another special case, "split" emulates the default behavior of
6213           the command line tool awk when the PATTERN is either omitted or a
6214           string composed of a single space character (such as ' ' or "\x20",
6215           but not e.g. "/ /").  In this case, any leading whitespace in EXPR
6216           is removed before splitting occurs, and the PATTERN is instead
6217           treated as if it were "/\s+/"; in particular, this means that any
6218           contiguous whitespace (not just a single space character) is used
6219           as a separator.  However, this special treatment can be avoided by
6220           specifying the pattern "/ /" instead of the string " ", thereby
6221           allowing only a single space character to be a separator.  In
6222           earlier Perls this special case was restricted to the use of a
6223           plain " " as the pattern argument to split; in Perl 5.18.0 and
6224           later this special case is triggered by any expression which
6225           evaluates to the simple string " ".
6226
6227           As of Perl 5.28, this special-cased whitespace splitting works as
6228           expected in the scope of "use feature 'unicode_strings". In
6229           previous versions, and outside the scope of that feature, it
6230           exhibits "The "Unicode Bug"" in perlunicode: characters that are
6231           whitespace according to Unicode rules but not according to ASCII
6232           rules can be treated as part of fields rather than as field
6233           separators, depending on the string's internal encoding.
6234
6235           If omitted, PATTERN defaults to a single space, " ", triggering the
6236           previously described awk emulation.
6237
6238           If LIMIT is specified and positive, it represents the maximum
6239           number of fields into which the EXPR may be split; in other words,
6240           LIMIT is one greater than the maximum number of times EXPR may be
6241           split.  Thus, the LIMIT value 1 means that EXPR may be split a
6242           maximum of zero times, producing a maximum of one field (namely,
6243           the entire value of EXPR).  For instance:
6244
6245               print join(':', split(//, 'abc', 1)), "\n";
6246
6247           produces the output "abc", and this:
6248
6249               print join(':', split(//, 'abc', 2)), "\n";
6250
6251           produces the output "a:bc", and each of these:
6252
6253               print join(':', split(//, 'abc', 3)), "\n";
6254               print join(':', split(//, 'abc', 4)), "\n";
6255
6256           produces the output "a:b:c".
6257
6258           If LIMIT is negative, it is treated as if it were instead
6259           arbitrarily large; as many fields as possible are produced.
6260
6261           If LIMIT is omitted (or, equivalently, zero), then it is usually
6262           treated as if it were instead negative but with the exception that
6263           trailing empty fields are stripped (empty leading fields are always
6264           preserved); if all fields are empty, then all fields are considered
6265           to be trailing (and are thus stripped in this case).  Thus, the
6266           following:
6267
6268               print join(':', split(/,/, 'a,b,c,,,')), "\n";
6269
6270           produces the output "a:b:c", but the following:
6271
6272               print join(':', split(/,/, 'a,b,c,,,', -1)), "\n";
6273
6274           produces the output "a:b:c:::".
6275
6276           In time-critical applications, it is worthwhile to avoid splitting
6277           into more fields than necessary.  Thus, when assigning to a list,
6278           if LIMIT is omitted (or zero), then LIMIT is treated as though it
6279           were one larger than the number of variables in the list; for the
6280           following, LIMIT is implicitly 3:
6281
6282               my ($login, $passwd) = split(/:/);
6283
6284           Note that splitting an EXPR that evaluates to the empty string
6285           always produces zero fields, regardless of the LIMIT specified.
6286
6287           An empty leading field is produced when there is a positive-width
6288           match at the beginning of EXPR.  For instance:
6289
6290               print join(':', split(/ /, ' abc')), "\n";
6291
6292           produces the output ":abc".  However, a zero-width match at the
6293           beginning of EXPR never produces an empty field, so that:
6294
6295               print join(':', split(//, ' abc'));
6296
6297           produces the output " :a:b:c" (rather than ": :a:b:c").
6298
6299           An empty trailing field, on the other hand, is produced when there
6300           is a match at the end of EXPR, regardless of the length of the
6301           match (of course, unless a non-zero LIMIT is given explicitly, such
6302           fields are removed, as in the last example).  Thus:
6303
6304               print join(':', split(//, ' abc', -1)), "\n";
6305
6306           produces the output " :a:b:c:".
6307
6308           If the PATTERN contains capturing groups, then for each separator,
6309           an additional field is produced for each substring captured by a
6310           group (in the order in which the groups are specified, as per
6311           backreferences); if any group does not match, then it captures the
6312           "undef" value instead of a substring.  Also, note that any such
6313           additional field is produced whenever there is a separator (that
6314           is, whenever a split occurs), and such an additional field does not
6315           count towards the LIMIT.  Consider the following expressions
6316           evaluated in list context (each returned list is provided in the
6317           associated comment):
6318
6319               split(/-|,/, "1-10,20", 3)
6320               # ('1', '10', '20')
6321
6322               split(/(-|,)/, "1-10,20", 3)
6323               # ('1', '-', '10', ',', '20')
6324
6325               split(/-|(,)/, "1-10,20", 3)
6326               # ('1', undef, '10', ',', '20')
6327
6328               split(/(-)|,/, "1-10,20", 3)
6329               # ('1', '-', '10', undef, '20')
6330
6331               split(/(-)|(,)/, "1-10,20", 3)
6332               # ('1', '-', undef, '10', undef, ',', '20')
6333
6334       sprintf FORMAT, LIST
6335           Returns a string formatted by the usual "printf" conventions of the
6336           C library function "sprintf".  See below for more details and see
6337           sprintf(3) or printf(3) on your system for an explanation of the
6338           general principles.
6339
6340           For example:
6341
6342                   # Format number with up to 8 leading zeroes
6343                   my $result = sprintf("%08d", $number);
6344
6345                   # Round number to 3 digits after decimal point
6346                   my $rounded = sprintf("%.3f", $number);
6347
6348           Perl does its own "sprintf" formatting: it emulates the C function
6349           sprintf(3), but doesn't use it except for floating-point numbers,
6350           and even then only standard modifiers are allowed.  Non-standard
6351           extensions in your local sprintf(3) are therefore unavailable from
6352           Perl.
6353
6354           Unlike "printf", "sprintf" does not do what you probably mean when
6355           you pass it an array as your first argument.  The array is given
6356           scalar context, and instead of using the 0th element of the array
6357           as the format, Perl will use the count of elements in the array as
6358           the format, which is almost never useful.
6359
6360           Perl's "sprintf" permits the following universally-known
6361           conversions:
6362
6363              %%    a percent sign
6364              %c    a character with the given number
6365              %s    a string
6366              %d    a signed integer, in decimal
6367              %u    an unsigned integer, in decimal
6368              %o    an unsigned integer, in octal
6369              %x    an unsigned integer, in hexadecimal
6370              %e    a floating-point number, in scientific notation
6371              %f    a floating-point number, in fixed decimal notation
6372              %g    a floating-point number, in %e or %f notation
6373
6374           In addition, Perl permits the following widely-supported
6375           conversions:
6376
6377              %X    like %x, but using upper-case letters
6378              %E    like %e, but using an upper-case "E"
6379              %G    like %g, but with an upper-case "E" (if applicable)
6380              %b    an unsigned integer, in binary
6381              %B    like %b, but using an upper-case "B" with the # flag
6382              %p    a pointer (outputs the Perl value's address in hexadecimal)
6383              %n    special: *stores* the number of characters output so far
6384                    into the next argument in the parameter list
6385              %a    hexadecimal floating point
6386              %A    like %a, but using upper-case letters
6387
6388           Finally, for backward (and we do mean "backward") compatibility,
6389           Perl permits these unnecessary but widely-supported conversions:
6390
6391              %i    a synonym for %d
6392              %D    a synonym for %ld
6393              %U    a synonym for %lu
6394              %O    a synonym for %lo
6395              %F    a synonym for %f
6396
6397           Note that the number of exponent digits in the scientific notation
6398           produced by %e, %E, %g and %G for numbers with the modulus of the
6399           exponent less than 100 is system-dependent: it may be three or less
6400           (zero-padded as necessary).  In other words, 1.23 times ten to the
6401           99th may be either "1.23e99" or "1.23e099".  Similarly for %a and
6402           %A: the exponent or the hexadecimal digits may float: especially
6403           the "long doubles" Perl configuration option may cause surprises.
6404
6405           Between the "%" and the format letter, you may specify several
6406           additional attributes controlling the interpretation of the format.
6407           In order, these are:
6408
6409           format parameter index
6410               An explicit format parameter index, such as "2$".  By default
6411               sprintf will format the next unused argument in the list, but
6412               this allows you to take the arguments out of order:
6413
6414                 printf '%2$d %1$d', 12, 34;      # prints "34 12"
6415                 printf '%3$d %d %1$d', 1, 2, 3;  # prints "3 1 1"
6416
6417           flags
6418               one or more of:
6419
6420                  space   prefix non-negative number with a space
6421                  +       prefix non-negative number with a plus sign
6422                  -       left-justify within the field
6423                  0       use zeros, not spaces, to right-justify
6424                  #       ensure the leading "0" for any octal,
6425                          prefix non-zero hexadecimal with "0x" or "0X",
6426                          prefix non-zero binary with "0b" or "0B"
6427
6428               For example:
6429
6430                 printf '<% d>',  12;   # prints "< 12>"
6431                 printf '<% d>',   0;   # prints "< 0>"
6432                 printf '<% d>', -12;   # prints "<-12>"
6433                 printf '<%+d>',  12;   # prints "<+12>"
6434                 printf '<%+d>',   0;   # prints "<+0>"
6435                 printf '<%+d>', -12;   # prints "<-12>"
6436                 printf '<%6s>',  12;   # prints "<    12>"
6437                 printf '<%-6s>', 12;   # prints "<12    >"
6438                 printf '<%06s>', 12;   # prints "<000012>"
6439                 printf '<%#o>',  12;   # prints "<014>"
6440                 printf '<%#x>',  12;   # prints "<0xc>"
6441                 printf '<%#X>',  12;   # prints "<0XC>"
6442                 printf '<%#b>',  12;   # prints "<0b1100>"
6443                 printf '<%#B>',  12;   # prints "<0B1100>"
6444
6445               When a space and a plus sign are given as the flags at once,
6446               the space is ignored.
6447
6448                 printf '<%+ d>', 12;   # prints "<+12>"
6449                 printf '<% +d>', 12;   # prints "<+12>"
6450
6451               When the # flag and a precision are given in the %o conversion,
6452               the precision is incremented if it's necessary for the leading
6453               "0".
6454
6455                 printf '<%#.5o>', 012;      # prints "<00012>"
6456                 printf '<%#.5o>', 012345;   # prints "<012345>"
6457                 printf '<%#.0o>', 0;        # prints "<0>"
6458
6459           vector flag
6460               This flag tells Perl to interpret the supplied string as a
6461               vector of integers, one for each character in the string.  Perl
6462               applies the format to each integer in turn, then joins the
6463               resulting strings with a separator (a dot "." by default).
6464               This can be useful for displaying ordinal values of characters
6465               in arbitrary strings:
6466
6467                 printf "%vd", "AB\x{100}";           # prints "65.66.256"
6468                 printf "version is v%vd\n", $^V;     # Perl's version
6469
6470               Put an asterisk "*" before the "v" to override the string to
6471               use to separate the numbers:
6472
6473                 printf "address is %*vX\n", ":", $addr;   # IPv6 address
6474                 printf "bits are %0*v8b\n", " ", $bits;   # random bitstring
6475
6476               You can also explicitly specify the argument number to use for
6477               the join string using something like "*2$v"; for example:
6478
6479                 printf '%*4$vX %*4$vX %*4$vX',       # 3 IPv6 addresses
6480                         @addr[1..3], ":";
6481
6482           (minimum) width
6483               Arguments are usually formatted to be only as wide as required
6484               to display the given value.  You can override the width by
6485               putting a number here, or get the width from the next argument
6486               (with "*") or from a specified argument (e.g., with "*2$"):
6487
6488                printf "<%s>", "a";       # prints "<a>"
6489                printf "<%6s>", "a";      # prints "<     a>"
6490                printf "<%*s>", 6, "a";   # prints "<     a>"
6491                printf '<%*2$s>', "a", 6; # prints "<     a>"
6492                printf "<%2s>", "long";   # prints "<long>" (does not truncate)
6493
6494               If a field width obtained through "*" is negative, it has the
6495               same effect as the "-" flag: left-justification.
6496
6497           precision, or maximum width
6498               You can specify a precision (for numeric conversions) or a
6499               maximum width (for string conversions) by specifying a "."
6500               followed by a number.  For floating-point formats except "g"
6501               and "G", this specifies how many places right of the decimal
6502               point to show (the default being 6).  For example:
6503
6504                 # these examples are subject to system-specific variation
6505                 printf '<%f>', 1;    # prints "<1.000000>"
6506                 printf '<%.1f>', 1;  # prints "<1.0>"
6507                 printf '<%.0f>', 1;  # prints "<1>"
6508                 printf '<%e>', 10;   # prints "<1.000000e+01>"
6509                 printf '<%.1e>', 10; # prints "<1.0e+01>"
6510
6511               For "g" and "G", this specifies the maximum number of
6512               significant digits to show; for example:
6513
6514                 # These examples are subject to system-specific variation.
6515                 printf '<%g>', 1;        # prints "<1>"
6516                 printf '<%.10g>', 1;     # prints "<1>"
6517                 printf '<%g>', 100;      # prints "<100>"
6518                 printf '<%.1g>', 100;    # prints "<1e+02>"
6519                 printf '<%.2g>', 100.01; # prints "<1e+02>"
6520                 printf '<%.5g>', 100.01; # prints "<100.01>"
6521                 printf '<%.4g>', 100.01; # prints "<100>"
6522                 printf '<%.1g>', 0.0111; # prints "<0.01>"
6523                 printf '<%.2g>', 0.0111; # prints "<0.011>"
6524                 printf '<%.3g>', 0.0111; # prints "<0.0111>"
6525
6526               For integer conversions, specifying a precision implies that
6527               the output of the number itself should be zero-padded to this
6528               width, where the 0 flag is ignored:
6529
6530                 printf '<%.6d>', 1;      # prints "<000001>"
6531                 printf '<%+.6d>', 1;     # prints "<+000001>"
6532                 printf '<%-10.6d>', 1;   # prints "<000001    >"
6533                 printf '<%10.6d>', 1;    # prints "<    000001>"
6534                 printf '<%010.6d>', 1;   # prints "<    000001>"
6535                 printf '<%+10.6d>', 1;   # prints "<   +000001>"
6536
6537                 printf '<%.6x>', 1;      # prints "<000001>"
6538                 printf '<%#.6x>', 1;     # prints "<0x000001>"
6539                 printf '<%-10.6x>', 1;   # prints "<000001    >"
6540                 printf '<%10.6x>', 1;    # prints "<    000001>"
6541                 printf '<%010.6x>', 1;   # prints "<    000001>"
6542                 printf '<%#10.6x>', 1;   # prints "<  0x000001>"
6543
6544               For string conversions, specifying a precision truncates the
6545               string to fit the specified width:
6546
6547                 printf '<%.5s>', "truncated";   # prints "<trunc>"
6548                 printf '<%10.5s>', "truncated"; # prints "<     trunc>"
6549
6550               You can also get the precision from the next argument using
6551               ".*", or from a specified argument (e.g., with ".*2$"):
6552
6553                 printf '<%.6x>', 1;       # prints "<000001>"
6554                 printf '<%.*x>', 6, 1;    # prints "<000001>"
6555
6556                 printf '<%.*2$x>', 1, 6;  # prints "<000001>"
6557
6558                 printf '<%6.*2$x>', 1, 4; # prints "<  0001>"
6559
6560               If a precision obtained through "*" is negative, it counts as
6561               having no precision at all.
6562
6563                 printf '<%.*s>',  7, "string";   # prints "<string>"
6564                 printf '<%.*s>',  3, "string";   # prints "<str>"
6565                 printf '<%.*s>',  0, "string";   # prints "<>"
6566                 printf '<%.*s>', -1, "string";   # prints "<string>"
6567
6568                 printf '<%.*d>',  1, 0;   # prints "<0>"
6569                 printf '<%.*d>',  0, 0;   # prints "<>"
6570                 printf '<%.*d>', -1, 0;   # prints "<0>"
6571
6572           size
6573               For numeric conversions, you can specify the size to interpret
6574               the number as using "l", "h", "V", "q", "L", or "ll".  For
6575               integer conversions ("d u o x X b i D U O"), numbers are
6576               usually assumed to be whatever the default integer size is on
6577               your platform (usually 32 or 64 bits), but you can override
6578               this to use instead one of the standard C types, as supported
6579               by the compiler used to build Perl:
6580
6581                  hh          interpret integer as C type "char" or "unsigned
6582                              char" on Perl 5.14 or later
6583                  h           interpret integer as C type "short" or
6584                              "unsigned short"
6585                  j           interpret integer as C type "intmax_t" on Perl
6586                              5.14 or later, and only with a C99 compiler
6587                              (unportable)
6588                  l           interpret integer as C type "long" or
6589                              "unsigned long"
6590                  q, L, or ll interpret integer as C type "long long",
6591                              "unsigned long long", or "quad" (typically
6592                              64-bit integers)
6593                  t           interpret integer as C type "ptrdiff_t" on Perl
6594                              5.14 or later
6595                  z           interpret integer as C type "size_t" on Perl 5.14
6596                              or later
6597
6598               As of 5.14, none of these raises an exception if they are not
6599               supported on your platform.  However, if warnings are enabled,
6600               a warning of the "printf" warning class is issued on an
6601               unsupported conversion flag.  Should you instead prefer an
6602               exception, do this:
6603
6604                   use warnings FATAL => "printf";
6605
6606               If you would like to know about a version dependency before you
6607               start running the program, put something like this at its top:
6608
6609                   use 5.014;  # for hh/j/t/z/ printf modifiers
6610
6611               You can find out whether your Perl supports quads via Config:
6612
6613                   use Config;
6614                   if ($Config{use64bitint} eq "define"
6615                       || $Config{longsize} >= 8) {
6616                       print "Nice quads!\n";
6617                   }
6618
6619               For floating-point conversions ("e f g E F G"), numbers are
6620               usually assumed to be the default floating-point size on your
6621               platform (double or long double), but you can force "long
6622               double" with "q", "L", or "ll" if your platform supports them.
6623               You can find out whether your Perl supports long doubles via
6624               Config:
6625
6626                   use Config;
6627                   print "long doubles\n" if $Config{d_longdbl} eq "define";
6628
6629               You can find out whether Perl considers "long double" to be the
6630               default floating-point size to use on your platform via Config:
6631
6632                   use Config;
6633                   if ($Config{uselongdouble} eq "define") {
6634                       print "long doubles by default\n";
6635                   }
6636
6637               It can also be that long doubles and doubles are the same
6638               thing:
6639
6640                       use Config;
6641                       ($Config{doublesize} == $Config{longdblsize}) &&
6642                               print "doubles are long doubles\n";
6643
6644               The size specifier "V" has no effect for Perl code, but is
6645               supported for compatibility with XS code.  It means "use the
6646               standard size for a Perl integer or floating-point number",
6647               which is the default.
6648
6649           order of arguments
6650               Normally, "sprintf" takes the next unused argument as the value
6651               to format for each format specification.  If the format
6652               specification uses "*" to require additional arguments, these
6653               are consumed from the argument list in the order they appear in
6654               the format specification before the value to format.  Where an
6655               argument is specified by an explicit index, this does not
6656               affect the normal order for the arguments, even when the
6657               explicitly specified index would have been the next argument.
6658
6659               So:
6660
6661                   printf "<%*.*s>", $a, $b, $c;
6662
6663               uses $a for the width, $b for the precision, and $c as the
6664               value to format; while:
6665
6666                 printf '<%*1$.*s>', $a, $b;
6667
6668               would use $a for the width and precision, and $b as the value
6669               to format.
6670
6671               Here are some more examples; be aware that when using an
6672               explicit index, the "$" may need escaping:
6673
6674                printf "%2\$d %d\n",      12, 34;     # will print "34 12\n"
6675                printf "%2\$d %d %d\n",   12, 34;     # will print "34 12 34\n"
6676                printf "%3\$d %d %d\n",   12, 34, 56; # will print "56 12 34\n"
6677                printf "%2\$*3\$d %d\n",  12, 34,  3; # will print " 34 12\n"
6678                printf "%*1\$.*f\n",       4,  5, 10; # will print "5.0000\n"
6679
6680           If "use locale" (including "use locale ':not_characters'") is in
6681           effect and "POSIX::setlocale" has been called, the character used
6682           for the decimal separator in formatted floating-point numbers is
6683           affected by the "LC_NUMERIC" locale.  See perllocale and POSIX.
6684
6685       sqrt EXPR
6686       sqrt
6687           Return the positive square root of EXPR.  If EXPR is omitted, uses
6688           $_.  Works only for non-negative operands unless you've loaded the
6689           "Math::Complex" module.
6690
6691               use Math::Complex;
6692               print sqrt(-4);    # prints 2i
6693
6694       srand EXPR
6695       srand
6696           Sets and returns the random number seed for the "rand" operator.
6697
6698           The point of the function is to "seed" the "rand" function so that
6699           "rand" can produce a different sequence each time you run your
6700           program.  When called with a parameter, "srand" uses that for the
6701           seed; otherwise it (semi-)randomly chooses a seed.  In either case,
6702           starting with Perl 5.14, it returns the seed.  To signal that your
6703           code will work only on Perls of a recent vintage:
6704
6705               use 5.014;  # so srand returns the seed
6706
6707           If "srand" is not called explicitly, it is called implicitly
6708           without a parameter at the first use of the "rand" operator.
6709           However, there are a few situations where programs are likely to
6710           want to call "srand".  One is for generating predictable results,
6711           generally for testing or debugging.  There, you use "srand($seed)",
6712           with the same $seed each time.  Another case is that you may want
6713           to call "srand" after a "fork" to avoid child processes sharing the
6714           same seed value as the parent (and consequently each other).
6715
6716           Do not call "srand()" (i.e., without an argument) more than once
6717           per process.  The internal state of the random number generator
6718           should contain more entropy than can be provided by any seed, so
6719           calling "srand" again actually loses randomness.
6720
6721           Most implementations of "srand" take an integer and will silently
6722           truncate decimal numbers.  This means "srand(42)" will usually
6723           produce the same results as "srand(42.1)".  To be safe, always pass
6724           "srand" an integer.
6725
6726           A typical use of the returned seed is for a test program which has
6727           too many combinations to test comprehensively in the time available
6728           to it each run.  It can test a random subset each time, and should
6729           there be a failure, log the seed used for that run so that it can
6730           later be used to reproduce the same results.
6731
6732           "rand" is not cryptographically secure.  You should not rely on it
6733           in security-sensitive situations.  As of this writing, a number of
6734           third-party CPAN modules offer random number generators intended by
6735           their authors to be cryptographically secure, including:
6736           Data::Entropy, Crypt::Random, Math::Random::Secure, and
6737           Math::TrulyRandom.
6738
6739       stat FILEHANDLE
6740       stat EXPR
6741       stat DIRHANDLE
6742       stat
6743           Returns a 13-element list giving the status info for a file, either
6744           the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR.  If
6745           EXPR is omitted, it stats $_ (not "_"!).  Returns the empty list if
6746           "stat" fails.  Typically used as follows:
6747
6748               my ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
6749                   $atime,$mtime,$ctime,$blksize,$blocks)
6750                      = stat($filename);
6751
6752           Not all fields are supported on all filesystem types.  Here are the
6753           meanings of the fields:
6754
6755             0 dev      device number of filesystem
6756             1 ino      inode number
6757             2 mode     file mode  (type and permissions)
6758             3 nlink    number of (hard) links to the file
6759             4 uid      numeric user ID of file's owner
6760             5 gid      numeric group ID of file's owner
6761             6 rdev     the device identifier (special files only)
6762             7 size     total size of file, in bytes
6763             8 atime    last access time in seconds since the epoch
6764             9 mtime    last modify time in seconds since the epoch
6765            10 ctime    inode change time in seconds since the epoch (*)
6766            11 blksize  preferred I/O size in bytes for interacting with the
6767                        file (may vary from file to file)
6768            12 blocks   actual number of system-specific blocks allocated
6769                        on disk (often, but not always, 512 bytes each)
6770
6771           (The epoch was at 00:00 January 1, 1970 GMT.)
6772
6773           (*) Not all fields are supported on all filesystem types.  Notably,
6774           the ctime field is non-portable.  In particular, you cannot expect
6775           it to be a "creation time"; see "Files and Filesystems" in perlport
6776           for details.
6777
6778           If "stat" is passed the special filehandle consisting of an
6779           underline, no stat is done, but the current contents of the stat
6780           structure from the last "stat", "lstat", or filetest are returned.
6781           Example:
6782
6783               if (-x $file && (($d) = stat(_)) && $d < 0) {
6784                   print "$file is executable NFS file\n";
6785               }
6786
6787           (This works on machines only for which the device number is
6788           negative under NFS.)
6789
6790           Because the mode contains both the file type and its permissions,
6791           you should mask off the file type portion and (s)printf using a
6792           "%o" if you want to see the real permissions.
6793
6794               my $mode = (stat($filename))[2];
6795               printf "Permissions are %04o\n", $mode & 07777;
6796
6797           In scalar context, "stat" returns a boolean value indicating
6798           success or failure, and, if successful, sets the information
6799           associated with the special filehandle "_".
6800
6801           The File::stat module provides a convenient, by-name access
6802           mechanism:
6803
6804               use File::stat;
6805               my $sb = stat($filename);
6806               printf "File is %s, size is %s, perm %04o, mtime %s\n",
6807                      $filename, $sb->size, $sb->mode & 07777,
6808                      scalar localtime $sb->mtime;
6809
6810           You can import symbolic mode constants ("S_IF*") and functions
6811           ("S_IS*") from the Fcntl module:
6812
6813               use Fcntl ':mode';
6814
6815               my $mode = (stat($filename))[2];
6816
6817               my $user_rwx      = ($mode & S_IRWXU) >> 6;
6818               my $group_read    = ($mode & S_IRGRP) >> 3;
6819               my $other_execute =  $mode & S_IXOTH;
6820
6821               printf "Permissions are %04o\n", S_IMODE($mode), "\n";
6822
6823               my $is_setuid     =  $mode & S_ISUID;
6824               my $is_directory  =  S_ISDIR($mode);
6825
6826           You could write the last two using the "-u" and "-d" operators.
6827           Commonly available "S_IF*" constants are:
6828
6829               # Permissions: read, write, execute, for user, group, others.
6830
6831               S_IRWXU S_IRUSR S_IWUSR S_IXUSR
6832               S_IRWXG S_IRGRP S_IWGRP S_IXGRP
6833               S_IRWXO S_IROTH S_IWOTH S_IXOTH
6834
6835               # Setuid/Setgid/Stickiness/SaveText.
6836               # Note that the exact meaning of these is system-dependent.
6837
6838               S_ISUID S_ISGID S_ISVTX S_ISTXT
6839
6840               # File types.  Not all are necessarily available on
6841               # your system.
6842
6843               S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR
6844               S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
6845
6846               # The following are compatibility aliases for S_IRUSR,
6847               # S_IWUSR, and S_IXUSR.
6848
6849               S_IREAD S_IWRITE S_IEXEC
6850
6851           and the "S_IF*" functions are
6852
6853               S_IMODE($mode)    the part of $mode containing the permission
6854                                 bits and the setuid/setgid/sticky bits
6855
6856               S_IFMT($mode)     the part of $mode containing the file type
6857                                 which can be bit-anded with (for example)
6858                                 S_IFREG or with the following functions
6859
6860               # The operators -f, -d, -l, -b, -c, -p, and -S.
6861
6862               S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
6863               S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
6864
6865               # No direct -X operator counterpart, but for the first one
6866               # the -g operator is often equivalent.  The ENFMT stands for
6867               # record flocking enforcement, a platform-dependent feature.
6868
6869               S_ISENFMT($mode) S_ISWHT($mode)
6870
6871           See your native chmod(2) and stat(2) documentation for more details
6872           about the "S_*" constants.  To get status info for a symbolic link
6873           instead of the target file behind the link, use the "lstat"
6874           function.
6875
6876           Portability issues: "stat" in perlport.
6877
6878       state VARLIST
6879       state TYPE VARLIST
6880       state VARLIST : ATTRS
6881       state TYPE VARLIST : ATTRS
6882           "state" declares a lexically scoped variable, just like "my".
6883           However, those variables will never be reinitialized, contrary to
6884           lexical variables that are reinitialized each time their enclosing
6885           block is entered.  See "Persistent Private Variables" in perlsub
6886           for details.
6887
6888           If more than one variable is listed, the list must be placed in
6889           parentheses.  With a parenthesised list, "undef" can be used as a
6890           dummy placeholder.  However, since initialization of state
6891           variables in list context is currently not possible this would
6892           serve no purpose.
6893
6894           "state" is available only if the "state" feature is enabled or if
6895           it is prefixed with "CORE::".  The "state" feature is enabled
6896           automatically with a "use v5.10" (or higher) declaration in the
6897           current scope.
6898
6899       study SCALAR
6900       study
6901           At this time, "study" does nothing. This may change in the future.
6902
6903           Prior to Perl version 5.16, it would create an inverted index of
6904           all characters that occurred in the given SCALAR (or $_ if
6905           unspecified). When matching a pattern, the rarest character from
6906           the pattern would be looked up in this index. Rarity was based on
6907           some static frequency tables constructed from some C programs and
6908           English text.
6909
6910       sub NAME BLOCK
6911       sub NAME (PROTO) BLOCK
6912       sub NAME : ATTRS BLOCK
6913       sub NAME (PROTO) : ATTRS BLOCK
6914           This is subroutine definition, not a real function per se.  Without
6915           a BLOCK it's just a forward declaration.  Without a NAME, it's an
6916           anonymous function declaration, so does return a value: the CODE
6917           ref of the closure just created.
6918
6919           See perlsub and perlref for details about subroutines and
6920           references; see attributes and Attribute::Handlers for more
6921           information about attributes.
6922
6923       __SUB__
6924           A special token that returns a reference to the current subroutine,
6925           or "undef" outside of a subroutine.
6926
6927           The behaviour of "__SUB__" within a regex code block (such as
6928           "/(?{...})/") is subject to change.
6929
6930           This token is only available under "use v5.16" or the "current_sub"
6931           feature.  See feature.
6932
6933       substr EXPR,OFFSET,LENGTH,REPLACEMENT
6934       substr EXPR,OFFSET,LENGTH
6935       substr EXPR,OFFSET
6936           Extracts a substring out of EXPR and returns it.  First character
6937           is at offset zero.  If OFFSET is negative, starts that far back
6938           from the end of the string.  If LENGTH is omitted, returns
6939           everything through the end of the string.  If LENGTH is negative,
6940           leaves that many characters off the end of the string.
6941
6942               my $s = "The black cat climbed the green tree";
6943               my $color  = substr $s, 4, 5;      # black
6944               my $middle = substr $s, 4, -11;    # black cat climbed the
6945               my $end    = substr $s, 14;        # climbed the green tree
6946               my $tail   = substr $s, -4;        # tree
6947               my $z      = substr $s, -4, 2;     # tr
6948
6949           You can use the "substr" function as an lvalue, in which case EXPR
6950           must itself be an lvalue.  If you assign something shorter than
6951           LENGTH, the string will shrink, and if you assign something longer
6952           than LENGTH, the string will grow to accommodate it.  To keep the
6953           string the same length, you may need to pad or chop your value
6954           using "sprintf".
6955
6956           If OFFSET and LENGTH specify a substring that is partly outside the
6957           string, only the part within the string is returned.  If the
6958           substring is beyond either end of the string, "substr" returns the
6959           undefined value and produces a warning.  When used as an lvalue,
6960           specifying a substring that is entirely outside the string raises
6961           an exception.  Here's an example showing the behavior for boundary
6962           cases:
6963
6964               my $name = 'fred';
6965               substr($name, 4) = 'dy';         # $name is now 'freddy'
6966               my $null = substr $name, 6, 2;   # returns "" (no warning)
6967               my $oops = substr $name, 7;      # returns undef, with warning
6968               substr($name, 7) = 'gap';        # raises an exception
6969
6970           An alternative to using "substr" as an lvalue is to specify the
6971           replacement string as the 4th argument.  This allows you to replace
6972           parts of the EXPR and return what was there before in one
6973           operation, just as you can with "splice".
6974
6975               my $s = "The black cat climbed the green tree";
6976               my $z = substr $s, 14, 7, "jumped from";    # climbed
6977               # $s is now "The black cat jumped from the green tree"
6978
6979           Note that the lvalue returned by the three-argument version of
6980           "substr" acts as a 'magic bullet'; each time it is assigned to, it
6981           remembers which part of the original string is being modified; for
6982           example:
6983
6984               my $x = '1234';
6985               for (substr($x,1,2)) {
6986                   $_ = 'a';   print $x,"\n";    # prints 1a4
6987                   $_ = 'xyz'; print $x,"\n";    # prints 1xyz4
6988                   $x = '56789';
6989                   $_ = 'pq';  print $x,"\n";    # prints 5pq9
6990               }
6991
6992           With negative offsets, it remembers its position from the end of
6993           the string when the target string is modified:
6994
6995               my $x = '1234';
6996               for (substr($x, -3, 2)) {
6997                   $_ = 'a';   print $x,"\n";    # prints 1a4, as above
6998                   $x = 'abcdefg';
6999                   print $_,"\n";                # prints f
7000               }
7001
7002           Prior to Perl version 5.10, the result of using an lvalue multiple
7003           times was unspecified.  Prior to 5.16, the result with negative
7004           offsets was unspecified.
7005
7006       symlink OLDFILE,NEWFILE
7007           Creates a new filename symbolically linked to the old filename.
7008           Returns 1 for success, 0 otherwise.  On systems that don't support
7009           symbolic links, raises an exception.  To check for that, use eval:
7010
7011               my $symlink_exists = eval { symlink("",""); 1 };
7012
7013           Portability issues: "symlink" in perlport.
7014
7015       syscall NUMBER, LIST
7016           Calls the system call specified as the first element of the list,
7017           passing the remaining elements as arguments to the system call.  If
7018           unimplemented, raises an exception.  The arguments are interpreted
7019           as follows: if a given argument is numeric, the argument is passed
7020           as an int.  If not, the pointer to the string value is passed.  You
7021           are responsible to make sure a string is pre-extended long enough
7022           to receive any result that might be written into a string.  You
7023           can't use a string literal (or other read-only string) as an
7024           argument to "syscall" because Perl has to assume that any string
7025           pointer might be written through.  If your integer arguments are
7026           not literals and have never been interpreted in a numeric context,
7027           you may need to add 0 to them to force them to look like numbers.
7028           This emulates the "syswrite" function (or vice versa):
7029
7030               require 'syscall.ph';        # may need to run h2ph
7031               my $s = "hi there\n";
7032               syscall(SYS_write(), fileno(STDOUT), $s, length $s);
7033
7034           Note that Perl supports passing of up to only 14 arguments to your
7035           syscall, which in practice should (usually) suffice.
7036
7037           Syscall returns whatever value returned by the system call it
7038           calls.  If the system call fails, "syscall" returns "-1" and sets
7039           $! (errno).  Note that some system calls can legitimately return
7040           "-1".  The proper way to handle such calls is to assign "$! = 0"
7041           before the call, then check the value of $! if "syscall" returns
7042           "-1".
7043
7044           There's a problem with "syscall(SYS_pipe())": it returns the file
7045           number of the read end of the pipe it creates, but there is no way
7046           to retrieve the file number of the other end.  You can avoid this
7047           problem by using "pipe" instead.
7048
7049           Portability issues: "syscall" in perlport.
7050
7051       sysopen FILEHANDLE,FILENAME,MODE
7052       sysopen FILEHANDLE,FILENAME,MODE,PERMS
7053           Opens the file whose filename is given by FILENAME, and associates
7054           it with FILEHANDLE.  If FILEHANDLE is an expression, its value is
7055           used as the real filehandle wanted; an undefined scalar will be
7056           suitably autovivified.  This function calls the underlying
7057           operating system's open(2) function with the parameters FILENAME,
7058           MODE, and PERMS.
7059
7060           Returns true on success and "undef" otherwise.
7061
7062           The possible values and flag bits of the MODE parameter are system-
7063           dependent; they are available via the standard module "Fcntl".  See
7064           the documentation of your operating system's open(2) syscall to see
7065           which values and flag bits are available.  You may combine several
7066           flags using the "|"-operator.
7067
7068           Some of the most common values are "O_RDONLY" for opening the file
7069           in read-only mode, "O_WRONLY" for opening the file in write-only
7070           mode, and "O_RDWR" for opening the file in read-write mode.
7071
7072           For historical reasons, some values work on almost every system
7073           supported by Perl: 0 means read-only, 1 means write-only, and 2
7074           means read/write.  We know that these values do not work under
7075           OS/390 and on the Macintosh; you probably don't want to use them in
7076           new code.
7077
7078           If the file named by FILENAME does not exist and the "open" call
7079           creates it (typically because MODE includes the "O_CREAT" flag),
7080           then the value of PERMS specifies the permissions of the newly
7081           created file.  If you omit the PERMS argument to "sysopen", Perl
7082           uses the octal value 0666.  These permission values need to be in
7083           octal, and are modified by your process's current "umask".
7084
7085           In many systems the "O_EXCL" flag is available for opening files in
7086           exclusive mode.  This is not locking: exclusiveness means here that
7087           if the file already exists, "sysopen" fails.  "O_EXCL" may not work
7088           on network filesystems, and has no effect unless the "O_CREAT" flag
7089           is set as well.  Setting "O_CREAT|O_EXCL" prevents the file from
7090           being opened if it is a symbolic link.  It does not protect against
7091           symbolic links in the file's path.
7092
7093           Sometimes you may want to truncate an already-existing file.  This
7094           can be done using the "O_TRUNC" flag.  The behavior of "O_TRUNC"
7095           with "O_RDONLY" is undefined.
7096
7097           You should seldom if ever use 0644 as argument to "sysopen",
7098           because that takes away the user's option to have a more permissive
7099           umask.  Better to omit it.  See "umask" for more on this.
7100
7101           Note that under Perls older than 5.8.0, "sysopen" depends on the
7102           fdopen(3) C library function.  On many Unix systems, fdopen(3) is
7103           known to fail when file descriptors exceed a certain value,
7104           typically 255.  If you need more file descriptors than that,
7105           consider using the "POSIX::open" function.  For Perls 5.8.0 and
7106           later, PerlIO is (most often) the default.
7107
7108           See perlopentut for a kinder, gentler explanation of opening files.
7109
7110           Portability issues: "sysopen" in perlport.
7111
7112       sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
7113       sysread FILEHANDLE,SCALAR,LENGTH
7114           Attempts to read LENGTH bytes of data into variable SCALAR from the
7115           specified FILEHANDLE, using read(2).  It bypasses buffered IO, so
7116           mixing this with other kinds of reads, "print", "write", "seek",
7117           "tell", or "eof" can cause confusion because the perlio or stdio
7118           layers usually buffer data.  Returns the number of bytes actually
7119           read, 0 at end of file, or undef if there was an error (in the
7120           latter case $! is also set).  SCALAR will be grown or shrunk so
7121           that the last byte actually read is the last byte of the scalar
7122           after the read.
7123
7124           An OFFSET may be specified to place the read data at some place in
7125           the string other than the beginning.  A negative OFFSET specifies
7126           placement at that many characters counting backwards from the end
7127           of the string.  A positive OFFSET greater than the length of SCALAR
7128           results in the string being padded to the required size with "\0"
7129           bytes before the result of the read is appended.
7130
7131           There is no syseof() function, which is ok, since "eof" doesn't
7132           work well on device files (like ttys) anyway.  Use "sysread" and
7133           check for a return value for 0 to decide whether you're done.
7134
7135           Note that if the filehandle has been marked as ":utf8", Unicode
7136           characters are read instead of bytes (the LENGTH, OFFSET, and the
7137           return value of "sysread" are in Unicode characters).  The
7138           ":encoding(...)" layer implicitly introduces the ":utf8" layer.
7139           See "binmode", "open", and the open pragma.
7140
7141       sysseek FILEHANDLE,POSITION,WHENCE
7142           Sets FILEHANDLE's system position in bytes using lseek(2).
7143           FILEHANDLE may be an expression whose value gives the name of the
7144           filehandle.  The values for WHENCE are 0 to set the new position to
7145           POSITION; 1 to set the it to the current position plus POSITION;
7146           and 2 to set it to EOF plus POSITION, typically negative.
7147
7148           Note the emphasis on bytes: even if the filehandle has been set to
7149           operate on characters (for example using the ":encoding(UTF-8)" I/O
7150           layer), the "seek", "tell", and "sysseek" family of functions use
7151           byte offsets, not character offsets, because seeking to a character
7152           offset would be very slow in a UTF-8 file.
7153
7154           "sysseek" bypasses normal buffered IO, so mixing it with reads
7155           other than "sysread" (for example "readline" or "read"), "print",
7156           "write", "seek", "tell", or "eof" may cause confusion.
7157
7158           For WHENCE, you may also use the constants "SEEK_SET", "SEEK_CUR",
7159           and "SEEK_END" (start of the file, current position, end of the
7160           file) from the Fcntl module.  Use of the constants is also more
7161           portable than relying on 0, 1, and 2.  For example to define a
7162           "systell" function:
7163
7164               use Fcntl 'SEEK_CUR';
7165               sub systell { sysseek($_[0], 0, SEEK_CUR) }
7166
7167           Returns the new position, or the undefined value on failure.  A
7168           position of zero is returned as the string "0 but true"; thus
7169           "sysseek" returns true on success and false on failure, yet you can
7170           still easily determine the new position.
7171
7172       system LIST
7173       system PROGRAM LIST
7174           Does exactly the same thing as "exec", except that a fork is done
7175           first and the parent process waits for the child process to exit.
7176           Note that argument processing varies depending on the number of
7177           arguments.  If there is more than one argument in LIST, or if LIST
7178           is an array with more than one value, starts the program given by
7179           the first element of the list with arguments given by the rest of
7180           the list.  If there is only one scalar argument, the argument is
7181           checked for shell metacharacters, and if there are any, the entire
7182           argument is passed to the system's command shell for parsing (this
7183           is "/bin/sh -c" on Unix platforms, but varies on other platforms).
7184           If there are no shell metacharacters in the argument, it is split
7185           into words and passed directly to "execvp", which is more
7186           efficient.  On Windows, only the "system PROGRAM LIST" syntax will
7187           reliably avoid using the shell; "system LIST", even with more than
7188           one element, will fall back to the shell if the first spawn fails.
7189
7190           Perl will attempt to flush all files opened for output before any
7191           operation that may do a fork, but this may not be supported on some
7192           platforms (see perlport).  To be safe, you may need to set $|
7193           ($AUTOFLUSH in English) or call the "autoflush" method of
7194           "IO::Handle" on any open handles.
7195
7196           The return value is the exit status of the program as returned by
7197           the "wait" call.  To get the actual exit value, shift right by
7198           eight (see below).  See also "exec".  This is not what you want to
7199           use to capture the output from a command; for that you should use
7200           merely backticks or "qx//", as described in "`STRING`" in perlop.
7201           Return value of -1 indicates a failure to start the program or an
7202           error of the wait(2) system call (inspect $! for the reason).
7203
7204           If you'd like to make "system" (and many other bits of Perl) die on
7205           error, have a look at the autodie pragma.
7206
7207           Like "exec", "system" allows you to lie to a program about its name
7208           if you use the "system PROGRAM LIST" syntax.  Again, see "exec".
7209
7210           Since "SIGINT" and "SIGQUIT" are ignored during the execution of
7211           "system", if you expect your program to terminate on receipt of
7212           these signals you will need to arrange to do so yourself based on
7213           the return value.
7214
7215               my @args = ("command", "arg1", "arg2");
7216               system(@args) == 0
7217                   or die "system @args failed: $?";
7218
7219           If you'd like to manually inspect "system"'s failure, you can check
7220           all possible failure modes by inspecting $? like this:
7221
7222               if ($? == -1) {
7223                   print "failed to execute: $!\n";
7224               }
7225               elsif ($? & 127) {
7226                   printf "child died with signal %d, %s coredump\n",
7227                       ($? & 127),  ($? & 128) ? 'with' : 'without';
7228               }
7229               else {
7230                   printf "child exited with value %d\n", $? >> 8;
7231               }
7232
7233           Alternatively, you may inspect the value of
7234           "${^CHILD_ERROR_NATIVE}" with the "W*()" calls from the POSIX
7235           module.
7236
7237           When "system"'s arguments are executed indirectly by the shell,
7238           results and return codes are subject to its quirks.  See "`STRING`"
7239           in perlop and "exec" for details.
7240
7241           Since "system" does a "fork" and "wait" it may affect a "SIGCHLD"
7242           handler.  See perlipc for details.
7243
7244           Portability issues: "system" in perlport.
7245
7246       syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
7247       syswrite FILEHANDLE,SCALAR,LENGTH
7248       syswrite FILEHANDLE,SCALAR
7249           Attempts to write LENGTH bytes of data from variable SCALAR to the
7250           specified FILEHANDLE, using write(2).  If LENGTH is not specified,
7251           writes whole SCALAR.  It bypasses buffered IO, so mixing this with
7252           reads (other than "sysread)"), "print", "write", "seek", "tell", or
7253           "eof" may cause confusion because the perlio and stdio layers
7254           usually buffer data.  Returns the number of bytes actually written,
7255           or "undef" if there was an error (in this case the errno variable
7256           $! is also set).  If the LENGTH is greater than the data available
7257           in the SCALAR after the OFFSET, only as much data as is available
7258           will be written.
7259
7260           An OFFSET may be specified to write the data from some part of the
7261           string other than the beginning.  A negative OFFSET specifies
7262           writing that many characters counting backwards from the end of the
7263           string.  If SCALAR is of length zero, you can only use an OFFSET of
7264           0.
7265
7266           WARNING: If the filehandle is marked ":utf8", Unicode characters
7267           encoded in UTF-8 are written instead of bytes, and the LENGTH,
7268           OFFSET, and return value of "syswrite" are in (UTF8-encoded
7269           Unicode) characters.  The ":encoding(...)" layer implicitly
7270           introduces the ":utf8" layer.  Alternately, if the handle is not
7271           marked with an encoding but you attempt to write characters with
7272           code points over 255, raises an exception.  See "binmode", "open",
7273           and the open pragma.
7274
7275       tell FILEHANDLE
7276       tell
7277           Returns the current position in bytes for FILEHANDLE, or -1 on
7278           error.  FILEHANDLE may be an expression whose value gives the name
7279           of the actual filehandle.  If FILEHANDLE is omitted, assumes the
7280           file last read.
7281
7282           Note the emphasis on bytes: even if the filehandle has been set to
7283           operate on characters (for example using the ":encoding(UTF-8)" I/O
7284           layer), the "seek", "tell", and "sysseek" family of functions use
7285           byte offsets, not character offsets, because seeking to a character
7286           offset would be very slow in a UTF-8 file.
7287
7288           The return value of "tell" for the standard streams like the STDIN
7289           depends on the operating system: it may return -1 or something
7290           else.  "tell" on pipes, fifos, and sockets usually returns -1.
7291
7292           There is no "systell" function.  Use "sysseek($fh, 0, 1)" for that.
7293
7294           Do not use "tell" (or other buffered I/O operations) on a
7295           filehandle that has been manipulated by "sysread", "syswrite", or
7296           "sysseek".  Those functions ignore the buffering, while "tell" does
7297           not.
7298
7299       telldir DIRHANDLE
7300           Returns the current position of the "readdir" routines on
7301           DIRHANDLE.  Value may be given to "seekdir" to access a particular
7302           location in a directory.  "telldir" has the same caveats about
7303           possible directory compaction as the corresponding system library
7304           routine.
7305
7306       tie VARIABLE,CLASSNAME,LIST
7307           This function binds a variable to a package class that will provide
7308           the implementation for the variable.  VARIABLE is the name of the
7309           variable to be enchanted.  CLASSNAME is the name of a class
7310           implementing objects of correct type.  Any additional arguments are
7311           passed to the appropriate constructor method of the class (meaning
7312           "TIESCALAR", "TIEHANDLE", "TIEARRAY", or "TIEHASH").  Typically
7313           these are arguments such as might be passed to the dbm_open(3)
7314           function of C.  The object returned by the constructor is also
7315           returned by the "tie" function, which would be useful if you want
7316           to access other methods in CLASSNAME.
7317
7318           Note that functions such as "keys" and "values" may return huge
7319           lists when used on large objects, like DBM files.  You may prefer
7320           to use the "each" function to iterate over such.  Example:
7321
7322               # print out history file offsets
7323               use NDBM_File;
7324               tie(my %HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
7325               while (my ($key,$val) = each %HIST) {
7326                   print $key, ' = ', unpack('L', $val), "\n";
7327               }
7328
7329           A class implementing a hash should have the following methods:
7330
7331               TIEHASH classname, LIST
7332               FETCH this, key
7333               STORE this, key, value
7334               DELETE this, key
7335               CLEAR this
7336               EXISTS this, key
7337               FIRSTKEY this
7338               NEXTKEY this, lastkey
7339               SCALAR this
7340               DESTROY this
7341               UNTIE this
7342
7343           A class implementing an ordinary array should have the following
7344           methods:
7345
7346               TIEARRAY classname, LIST
7347               FETCH this, key
7348               STORE this, key, value
7349               FETCHSIZE this
7350               STORESIZE this, count
7351               CLEAR this
7352               PUSH this, LIST
7353               POP this
7354               SHIFT this
7355               UNSHIFT this, LIST
7356               SPLICE this, offset, length, LIST
7357               EXTEND this, count
7358               DELETE this, key
7359               EXISTS this, key
7360               DESTROY this
7361               UNTIE this
7362
7363           A class implementing a filehandle should have the following
7364           methods:
7365
7366               TIEHANDLE classname, LIST
7367               READ this, scalar, length, offset
7368               READLINE this
7369               GETC this
7370               WRITE this, scalar, length, offset
7371               PRINT this, LIST
7372               PRINTF this, format, LIST
7373               BINMODE this
7374               EOF this
7375               FILENO this
7376               SEEK this, position, whence
7377               TELL this
7378               OPEN this, mode, LIST
7379               CLOSE this
7380               DESTROY this
7381               UNTIE this
7382
7383           A class implementing a scalar should have the following methods:
7384
7385               TIESCALAR classname, LIST
7386               FETCH this,
7387               STORE this, value
7388               DESTROY this
7389               UNTIE this
7390
7391           Not all methods indicated above need be implemented.  See perltie,
7392           Tie::Hash, Tie::Array, Tie::Scalar, and Tie::Handle.
7393
7394           Unlike "dbmopen", the "tie" function will not "use" or "require" a
7395           module for you; you need to do that explicitly yourself.  See
7396           DB_File or the Config module for interesting "tie" implementations.
7397
7398           For further details see perltie, "tied".
7399
7400       tied VARIABLE
7401           Returns a reference to the object underlying VARIABLE (the same
7402           value that was originally returned by the "tie" call that bound the
7403           variable to a package.)  Returns the undefined value if VARIABLE
7404           isn't tied to a package.
7405
7406       time
7407           Returns the number of non-leap seconds since whatever time the
7408           system considers to be the epoch, suitable for feeding to "gmtime"
7409           and "localtime".  On most systems the epoch is 00:00:00 UTC,
7410           January 1, 1970; a prominent exception being Mac OS Classic which
7411           uses 00:00:00, January 1, 1904 in the current local time zone for
7412           its epoch.
7413
7414           For measuring time in better granularity than one second, use the
7415           Time::HiRes module from Perl 5.8 onwards (or from CPAN before
7416           then), or, if you have gettimeofday(2), you may be able to use the
7417           "syscall" interface of Perl.  See perlfaq8 for details.
7418
7419           For date and time processing look at the many related modules on
7420           CPAN.  For a comprehensive date and time representation look at the
7421           DateTime module.
7422
7423       times
7424           Returns a four-element list giving the user and system times in
7425           seconds for this process and any exited children of this process.
7426
7427               my ($user,$system,$cuser,$csystem) = times;
7428
7429           In scalar context, "times" returns $user.
7430
7431           Children's times are only included for terminated children.
7432
7433           Portability issues: "times" in perlport.
7434
7435       tr///
7436           The transliteration operator.  Same as "y///".  See "Quote-Like
7437           Operators" in perlop.
7438
7439       truncate FILEHANDLE,LENGTH
7440       truncate EXPR,LENGTH
7441           Truncates the file opened on FILEHANDLE, or named by EXPR, to the
7442           specified length.  Raises an exception if truncate isn't
7443           implemented on your system.  Returns true if successful, "undef" on
7444           error.
7445
7446           The behavior is undefined if LENGTH is greater than the length of
7447           the file.
7448
7449           The position in the file of FILEHANDLE is left unchanged.  You may
7450           want to call seek before writing to the file.
7451
7452           Portability issues: "truncate" in perlport.
7453
7454       uc EXPR
7455       uc  Returns an uppercased version of EXPR.  This is the internal
7456           function implementing the "\U" escape in double-quoted strings.  It
7457           does not attempt to do titlecase mapping on initial letters.  See
7458           "ucfirst" for that.
7459
7460           If EXPR is omitted, uses $_.
7461
7462           This function behaves the same way under various pragmas, such as
7463           in a locale, as "lc" does.
7464
7465       ucfirst EXPR
7466       ucfirst
7467           Returns the value of EXPR with the first character in uppercase
7468           (titlecase in Unicode).  This is the internal function implementing
7469           the "\u" escape in double-quoted strings.
7470
7471           If EXPR is omitted, uses $_.
7472
7473           This function behaves the same way under various pragmas, such as
7474           in a locale, as "lc" does.
7475
7476       umask EXPR
7477       umask
7478           Sets the umask for the process to EXPR and returns the previous
7479           value.  If EXPR is omitted, merely returns the current umask.
7480
7481           The Unix permission "rwxr-x---" is represented as three sets of
7482           three bits, or three octal digits: 0750 (the leading 0 indicates
7483           octal and isn't one of the digits).  The "umask" value is such a
7484           number representing disabled permissions bits.  The permission (or
7485           "mode") values you pass "mkdir" or "sysopen" are modified by your
7486           umask, so even if you tell "sysopen" to create a file with
7487           permissions 0777, if your umask is 0022, then the file will
7488           actually be created with permissions 0755.  If your "umask" were
7489           0027 (group can't write; others can't read, write, or execute),
7490           then passing "sysopen" 0666 would create a file with mode 0640
7491           (because "0666 &~ 027" is 0640).
7492
7493           Here's some advice: supply a creation mode of 0666 for regular
7494           files (in "sysopen") and one of 0777 for directories (in "mkdir")
7495           and executable files.  This gives users the freedom of choice: if
7496           they want protected files, they might choose process umasks of 022,
7497           027, or even the particularly antisocial mask of 077.  Programs
7498           should rarely if ever make policy decisions better left to the
7499           user.  The exception to this is when writing files that should be
7500           kept private: mail files, web browser cookies, .rhosts files, and
7501           so on.
7502
7503           If umask(2) is not implemented on your system and you are trying to
7504           restrict access for yourself (i.e., "(EXPR & 0700) > 0"), raises an
7505           exception.  If umask(2) is not implemented and you are not trying
7506           to restrict access for yourself, returns "undef".
7507
7508           Remember that a umask is a number, usually given in octal; it is
7509           not a string of octal digits.  See also "oct", if all you have is a
7510           string.
7511
7512           Portability issues: "umask" in perlport.
7513
7514       undef EXPR
7515       undef
7516           Undefines the value of EXPR, which must be an lvalue.  Use only on
7517           a scalar value, an array (using "@"), a hash (using "%"), a
7518           subroutine (using "&"), or a typeglob (using "*").  Saying "undef
7519           $hash{$key}" will probably not do what you expect on most
7520           predefined variables or DBM list values, so don't do that; see
7521           "delete".  Always returns the undefined value.  You can omit the
7522           EXPR, in which case nothing is undefined, but you still get an
7523           undefined value that you could, for instance, return from a
7524           subroutine, assign to a variable, or pass as a parameter.
7525           Examples:
7526
7527               undef $foo;
7528               undef $bar{'blurfl'};      # Compare to: delete $bar{'blurfl'};
7529               undef @ary;
7530               undef %hash;
7531               undef &mysub;
7532               undef *xyz;       # destroys $xyz, @xyz, %xyz, &xyz, etc.
7533               return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
7534               select undef, undef, undef, 0.25;
7535               my ($x, $y, undef, $z) = foo();    # Ignore third value returned
7536
7537           Note that this is a unary operator, not a list operator.
7538
7539       unlink LIST
7540       unlink
7541           Deletes a list of files.  On success, it returns the number of
7542           files it successfully deleted.  On failure, it returns false and
7543           sets $! (errno):
7544
7545               my $unlinked = unlink 'a', 'b', 'c';
7546               unlink @goners;
7547               unlink glob "*.bak";
7548
7549           On error, "unlink" will not tell you which files it could not
7550           remove.  If you want to know which files you could not remove, try
7551           them one at a time:
7552
7553                foreach my $file ( @goners ) {
7554                    unlink $file or warn "Could not unlink $file: $!";
7555                }
7556
7557           Note: "unlink" will not attempt to delete directories unless you
7558           are superuser and the -U flag is supplied to Perl.  Even if these
7559           conditions are met, be warned that unlinking a directory can
7560           inflict damage on your filesystem.  Finally, using "unlink" on
7561           directories is not supported on many operating systems.  Use
7562           "rmdir" instead.
7563
7564           If LIST is omitted, "unlink" uses $_.
7565
7566       unpack TEMPLATE,EXPR
7567       unpack TEMPLATE
7568           "unpack" does the reverse of "pack": it takes a string and expands
7569           it out into a list of values.  (In scalar context, it returns
7570           merely the first value produced.)
7571
7572           If EXPR is omitted, unpacks the $_ string.  See perlpacktut for an
7573           introduction to this function.
7574
7575           The string is broken into chunks described by the TEMPLATE.  Each
7576           chunk is converted separately to a value.  Typically, either the
7577           string is a result of "pack", or the characters of the string
7578           represent a C structure of some kind.
7579
7580           The TEMPLATE has the same format as in the "pack" function.  Here's
7581           a subroutine that does substring:
7582
7583               sub substr {
7584                   my ($what, $where, $howmuch) = @_;
7585                   unpack("x$where a$howmuch", $what);
7586               }
7587
7588           and then there's
7589
7590               sub ordinal { unpack("W",$_[0]); } # same as ord()
7591
7592           In addition to fields allowed in "pack", you may prefix a field
7593           with a %<number> to indicate that you want a <number>-bit checksum
7594           of the items instead of the items themselves.  Default is a 16-bit
7595           checksum.  The checksum is calculated by summing numeric values of
7596           expanded values (for string fields the sum of "ord($char)" is
7597           taken; for bit fields the sum of zeroes and ones).
7598
7599           For example, the following computes the same number as the System V
7600           sum program:
7601
7602               my $checksum = do {
7603                   local $/;  # slurp!
7604                   unpack("%32W*", readline) % 65535;
7605               };
7606
7607           The following efficiently counts the number of set bits in a bit
7608           vector:
7609
7610               my $setbits = unpack("%32b*", $selectmask);
7611
7612           The "p" and "P" formats should be used with care.  Since Perl has
7613           no way of checking whether the value passed to "unpack" corresponds
7614           to a valid memory location, passing a pointer value that's not
7615           known to be valid is likely to have disastrous consequences.
7616
7617           If there are more pack codes or if the repeat count of a field or a
7618           group is larger than what the remainder of the input string allows,
7619           the result is not well defined: the repeat count may be decreased,
7620           or "unpack" may produce empty strings or zeros, or it may raise an
7621           exception.  If the input string is longer than one described by the
7622           TEMPLATE, the remainder of that input string is ignored.
7623
7624           See "pack" for more examples and notes.
7625
7626       unshift ARRAY,LIST
7627           Does the opposite of a "shift".  Or the opposite of a "push",
7628           depending on how you look at it.  Prepends list to the front of the
7629           array and returns the new number of elements in the array.
7630
7631               unshift(@ARGV, '-e') unless $ARGV[0] =~ /^-/;
7632
7633           Note the LIST is prepended whole, not one element at a time, so the
7634           prepended elements stay in the same order.  Use "reverse" to do the
7635           reverse.
7636
7637           Starting with Perl 5.14, an experimental feature allowed "unshift"
7638           to take a scalar expression. This experiment has been deemed
7639           unsuccessful, and was removed as of Perl 5.24.
7640
7641       untie VARIABLE
7642           Breaks the binding between a variable and a package.  (See tie.)
7643           Has no effect if the variable is not tied.
7644
7645       use Module VERSION LIST
7646       use Module VERSION
7647       use Module LIST
7648       use Module
7649       use VERSION
7650           Imports some semantics into the current package from the named
7651           module, generally by aliasing certain subroutine or variable names
7652           into your package.  It is exactly equivalent to
7653
7654               BEGIN { require Module; Module->import( LIST ); }
7655
7656           except that Module must be a bareword.  The importation can be made
7657           conditional by using the if module.
7658
7659           In the peculiar "use VERSION" form, VERSION may be either a
7660           positive decimal fraction such as 5.006, which will be compared to
7661           $], or a v-string of the form v5.6.1, which will be compared to $^V
7662           (aka $PERL_VERSION).  An exception is raised if VERSION is greater
7663           than the version of the current Perl interpreter; Perl will not
7664           attempt to parse the rest of the file.  Compare with "require",
7665           which can do a similar check at run time.  Symmetrically, "no
7666           VERSION" allows you to specify that you want a version of Perl
7667           older than the specified one.
7668
7669           Specifying VERSION as a literal of the form v5.6.1 should generally
7670           be avoided, because it leads to misleading error messages under
7671           earlier versions of Perl (that is, prior to 5.6.0) that do not
7672           support this syntax.  The equivalent numeric version should be used
7673           instead.
7674
7675               use v5.6.1;     # compile time version check
7676               use 5.6.1;      # ditto
7677               use 5.006_001;  # ditto; preferred for backwards compatibility
7678
7679           This is often useful if you need to check the current Perl version
7680           before "use"ing library modules that won't work with older versions
7681           of Perl.  (We try not to do this more than we have to.)
7682
7683           "use VERSION" also lexically enables all features available in the
7684           requested version as defined by the feature pragma, disabling any
7685           features not in the requested version's feature bundle.  See
7686           feature.  Similarly, if the specified Perl version is greater than
7687           or equal to 5.12.0, strictures are enabled lexically as with "use
7688           strict".  Any explicit use of "use strict" or "no strict" overrides
7689           "use VERSION", even if it comes before it.  Later use of "use
7690           VERSION" will override all behavior of a previous "use VERSION",
7691           possibly removing the "strict" and "feature" added by "use
7692           VERSION".  "use VERSION" does not load the feature.pm or strict.pm
7693           files.
7694
7695           The "BEGIN" forces the "require" and "import" to happen at compile
7696           time.  The "require" makes sure the module is loaded into memory if
7697           it hasn't been yet.  The "import" is not a builtin; it's just an
7698           ordinary static method call into the "Module" package to tell the
7699           module to import the list of features back into the current
7700           package.  The module can implement its "import" method any way it
7701           likes, though most modules just choose to derive their "import"
7702           method via inheritance from the "Exporter" class that is defined in
7703           the "Exporter" module.  See Exporter.  If no "import" method can be
7704           found, then the call is skipped, even if there is an AUTOLOAD
7705           method.
7706
7707           If you do not want to call the package's "import" method (for
7708           instance, to stop your namespace from being altered), explicitly
7709           supply the empty list:
7710
7711               use Module ();
7712
7713           That is exactly equivalent to
7714
7715               BEGIN { require Module }
7716
7717           If the VERSION argument is present between Module and LIST, then
7718           the "use" will call the "VERSION" method in class Module with the
7719           given version as an argument:
7720
7721               use Module 12.34;
7722
7723           is equivalent to:
7724
7725               BEGIN { require Module; Module->VERSION(12.34) }
7726
7727           The default "VERSION" method, inherited from the "UNIVERSAL" class,
7728           croaks if the given version is larger than the value of the
7729           variable $Module::VERSION.
7730
7731           Again, there is a distinction between omitting LIST ("import"
7732           called with no arguments) and an explicit empty LIST "()" ("import"
7733           not called).  Note that there is no comma after VERSION!
7734
7735           Because this is a wide-open interface, pragmas (compiler
7736           directives) are also implemented this way.  Some of the currently
7737           implemented pragmas are:
7738
7739               use constant;
7740               use diagnostics;
7741               use integer;
7742               use sigtrap  qw(SEGV BUS);
7743               use strict   qw(subs vars refs);
7744               use subs     qw(afunc blurfl);
7745               use warnings qw(all);
7746               use sort     qw(stable _quicksort _mergesort);
7747
7748           Some of these pseudo-modules import semantics into the current
7749           block scope (like "strict" or "integer", unlike ordinary modules,
7750           which import symbols into the current package (which are effective
7751           through the end of the file).
7752
7753           Because "use" takes effect at compile time, it doesn't respect the
7754           ordinary flow control of the code being compiled.  In particular,
7755           putting a "use" inside the false branch of a conditional doesn't
7756           prevent it from being processed.  If a module or pragma only needs
7757           to be loaded conditionally, this can be done using the if pragma:
7758
7759               use if $] < 5.008, "utf8";
7760               use if WANT_WARNINGS, warnings => qw(all);
7761
7762           There's a corresponding "no" declaration that unimports meanings
7763           imported by "use", i.e., it calls "Module->unimport(LIST)" instead
7764           of "import".  It behaves just as "import" does with VERSION, an
7765           omitted or empty LIST, or no unimport method being found.
7766
7767               no integer;
7768               no strict 'refs';
7769               no warnings;
7770
7771           Care should be taken when using the "no VERSION" form of "no".  It
7772           is only meant to be used to assert that the running Perl is of a
7773           earlier version than its argument and not to undo the feature-
7774           enabling side effects of "use VERSION".
7775
7776           See perlmodlib for a list of standard modules and pragmas.  See
7777           perlrun for the "-M" and "-m" command-line options to Perl that
7778           give "use" functionality from the command-line.
7779
7780       utime LIST
7781           Changes the access and modification times on each file of a list of
7782           files.  The first two elements of the list must be the NUMERIC
7783           access and modification times, in that order.  Returns the number
7784           of files successfully changed.  The inode change time of each file
7785           is set to the current time.  For example, this code has the same
7786           effect as the Unix touch(1) command when the files already exist
7787           and belong to the user running the program:
7788
7789               #!/usr/bin/perl
7790               my $atime = my $mtime = time;
7791               utime $atime, $mtime, @ARGV;
7792
7793           Since Perl 5.8.0, if the first two elements of the list are
7794           "undef", the utime(2) syscall from your C library is called with a
7795           null second argument.  On most systems, this will set the file's
7796           access and modification times to the current time (i.e., equivalent
7797           to the example above) and will work even on files you don't own
7798           provided you have write permission:
7799
7800               for my $file (@ARGV) {
7801                   utime(undef, undef, $file)
7802                       || warn "Couldn't touch $file: $!";
7803               }
7804
7805           Under NFS this will use the time of the NFS server, not the time of
7806           the local machine.  If there is a time synchronization problem, the
7807           NFS server and local machine will have different times.  The Unix
7808           touch(1) command will in fact normally use this form instead of the
7809           one shown in the first example.
7810
7811           Passing only one of the first two elements as "undef" is equivalent
7812           to passing a 0 and will not have the effect described when both are
7813           "undef".  This also triggers an uninitialized warning.
7814
7815           On systems that support futimes(2), you may pass filehandles among
7816           the files.  On systems that don't support futimes(2), passing
7817           filehandles raises an exception.  Filehandles must be passed as
7818           globs or glob references to be recognized; barewords are considered
7819           filenames.
7820
7821           Portability issues: "utime" in perlport.
7822
7823       values HASH
7824       values ARRAY
7825           In list context, returns a list consisting of all the values of the
7826           named hash.  In Perl 5.12 or later only, will also return a list of
7827           the values of an array; prior to that release, attempting to use an
7828           array argument will produce a syntax error.  In scalar context,
7829           returns the number of values.
7830
7831           Hash entries are returned in an apparently random order.  The
7832           actual random order is specific to a given hash; the exact same
7833           series of operations on two hashes may result in a different order
7834           for each hash.  Any insertion into the hash may change the order,
7835           as will any deletion, with the exception that the most recent key
7836           returned by "each" or "keys" may be deleted without changing the
7837           order.  So long as a given hash is unmodified you may rely on
7838           "keys", "values" and "each" to repeatedly return the same order as
7839           each other.  See "Algorithmic Complexity Attacks" in perlsec for
7840           details on why hash order is randomized.  Aside from the guarantees
7841           provided here the exact details of Perl's hash algorithm and the
7842           hash traversal order are subject to change in any release of Perl.
7843           Tied hashes may behave differently to Perl's hashes with respect to
7844           changes in order on insertion and deletion of items.
7845
7846           As a side effect, calling "values" resets the HASH or ARRAY's
7847           internal iterator, see "each".  (In particular, calling "values" in
7848           void context resets the iterator with no other overhead.  Apart
7849           from resetting the iterator, "values @array" in list context is the
7850           same as plain @array.  (We recommend that you use void context
7851           "keys @array" for this, but reasoned that taking "values @array"
7852           out would require more documentation than leaving it in.)
7853
7854           Note that the values are not copied, which means modifying them
7855           will modify the contents of the hash:
7856
7857               for (values %hash)      { s/foo/bar/g }  # modifies %hash values
7858               for (@hash{keys %hash}) { s/foo/bar/g }  # same
7859
7860           Starting with Perl 5.14, an experimental feature allowed "values"
7861           to take a scalar expression. This experiment has been deemed
7862           unsuccessful, and was removed as of Perl 5.24.
7863
7864           To avoid confusing would-be users of your code who are running
7865           earlier versions of Perl with mysterious syntax errors, put this
7866           sort of thing at the top of your file to signal that your code will
7867           work only on Perls of a recent vintage:
7868
7869               use 5.012;  # so keys/values/each work on arrays
7870
7871           See also "keys", "each", and "sort".
7872
7873       vec EXPR,OFFSET,BITS
7874           Treats the string in EXPR as a bit vector made up of elements of
7875           width BITS and returns the value of the element specified by OFFSET
7876           as an unsigned integer.  BITS therefore specifies the number of
7877           bits that are reserved for each element in the bit vector.  This
7878           must be a power of two from 1 to 32 (or 64, if your platform
7879           supports that).
7880
7881           If BITS is 8, "elements" coincide with bytes of the input string.
7882
7883           If BITS is 16 or more, bytes of the input string are grouped into
7884           chunks of size BITS/8, and each group is converted to a number as
7885           with "pack"/"unpack" with big-endian formats "n"/"N" (and
7886           analogously for BITS==64).  See "pack" for details.
7887
7888           If bits is 4 or less, the string is broken into bytes, then the
7889           bits of each byte are broken into 8/BITS groups.  Bits of a byte
7890           are numbered in a little-endian-ish way, as in 0x01, 0x02, 0x04,
7891           0x08, 0x10, 0x20, 0x40, 0x80.  For example, breaking the single
7892           input byte "chr(0x36)" into two groups gives a list "(0x6, 0x3)";
7893           breaking it into 4 groups gives "(0x2, 0x1, 0x3, 0x0)".
7894
7895           "vec" may also be assigned to, in which case parentheses are needed
7896           to give the expression the correct precedence as in
7897
7898               vec($image, $max_x * $x + $y, 8) = 3;
7899
7900           If the selected element is outside the string, the value 0 is
7901           returned.  If an element off the end of the string is written to,
7902           Perl will first extend the string with sufficiently many zero
7903           bytes.   It is an error to try to write off the beginning of the
7904           string (i.e., negative OFFSET).
7905
7906           If the string happens to be encoded as UTF-8 internally (and thus
7907           has the UTF8 flag set), "vec" tries to convert it to use a one-
7908           byte-per-character internal representation. However, if the string
7909           contains characters with values of 256 or higher, that conversion
7910           will fail. In that situation, "vec" will operate on the underlying
7911           buffer regardless, in its internal UTF-8 representation.
7912
7913           Strings created with "vec" can also be manipulated with the logical
7914           operators "|", "&", "^", and "~".  These operators will assume a
7915           bit vector operation is desired when both operands are strings.
7916           See "Bitwise String Operators" in perlop.
7917
7918           The following code will build up an ASCII string saying
7919           'PerlPerlPerl'.  The comments show the string after each step.
7920           Note that this code works in the same way on big-endian or little-
7921           endian machines.
7922
7923               my $foo = '';
7924               vec($foo,  0, 32) = 0x5065726C; # 'Perl'
7925
7926               # $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits
7927               print vec($foo, 0, 8);  # prints 80 == 0x50 == ord('P')
7928
7929               vec($foo,  2, 16) = 0x5065; # 'PerlPe'
7930               vec($foo,  3, 16) = 0x726C; # 'PerlPerl'
7931               vec($foo,  8,  8) = 0x50;   # 'PerlPerlP'
7932               vec($foo,  9,  8) = 0x65;   # 'PerlPerlPe'
7933               vec($foo, 20,  4) = 2;      # 'PerlPerlPe'   . "\x02"
7934               vec($foo, 21,  4) = 7;      # 'PerlPerlPer'
7935                                              # 'r' is "\x72"
7936               vec($foo, 45,  2) = 3;      # 'PerlPerlPer'  . "\x0c"
7937               vec($foo, 93,  1) = 1;      # 'PerlPerlPer'  . "\x2c"
7938               vec($foo, 94,  1) = 1;      # 'PerlPerlPerl'
7939                                              # 'l' is "\x6c"
7940
7941           To transform a bit vector into a string or list of 0's and 1's, use
7942           these:
7943
7944               my $bits = unpack("b*", $vector);
7945               my @bits = split(//, unpack("b*", $vector));
7946
7947           If you know the exact length in bits, it can be used in place of
7948           the "*".
7949
7950           Here is an example to illustrate how the bits actually fall in
7951           place:
7952
7953             #!/usr/bin/perl -wl
7954
7955             print <<'EOT';
7956                                               0         1         2         3
7957                                unpack("V",$_) 01234567890123456789012345678901
7958             ------------------------------------------------------------------
7959             EOT
7960
7961             for $w (0..3) {
7962                 $width = 2**$w;
7963                 for ($shift=0; $shift < $width; ++$shift) {
7964                     for ($off=0; $off < 32/$width; ++$off) {
7965                         $str = pack("B*", "0"x32);
7966                         $bits = (1<<$shift);
7967                         vec($str, $off, $width) = $bits;
7968                         $res = unpack("b*",$str);
7969                         $val = unpack("V", $str);
7970                         write;
7971                     }
7972                 }
7973             }
7974
7975             format STDOUT =
7976             vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
7977             $off, $width, $bits, $val, $res
7978             .
7979             __END__
7980
7981           Regardless of the machine architecture on which it runs, the
7982           example above should print the following table:
7983
7984                                               0         1         2         3
7985                                unpack("V",$_) 01234567890123456789012345678901
7986             ------------------------------------------------------------------
7987             vec($_, 0, 1) = 1   ==          1 10000000000000000000000000000000
7988             vec($_, 1, 1) = 1   ==          2 01000000000000000000000000000000
7989             vec($_, 2, 1) = 1   ==          4 00100000000000000000000000000000
7990             vec($_, 3, 1) = 1   ==          8 00010000000000000000000000000000
7991             vec($_, 4, 1) = 1   ==         16 00001000000000000000000000000000
7992             vec($_, 5, 1) = 1   ==         32 00000100000000000000000000000000
7993             vec($_, 6, 1) = 1   ==         64 00000010000000000000000000000000
7994             vec($_, 7, 1) = 1   ==        128 00000001000000000000000000000000
7995             vec($_, 8, 1) = 1   ==        256 00000000100000000000000000000000
7996             vec($_, 9, 1) = 1   ==        512 00000000010000000000000000000000
7997             vec($_,10, 1) = 1   ==       1024 00000000001000000000000000000000
7998             vec($_,11, 1) = 1   ==       2048 00000000000100000000000000000000
7999             vec($_,12, 1) = 1   ==       4096 00000000000010000000000000000000
8000             vec($_,13, 1) = 1   ==       8192 00000000000001000000000000000000
8001             vec($_,14, 1) = 1   ==      16384 00000000000000100000000000000000
8002             vec($_,15, 1) = 1   ==      32768 00000000000000010000000000000000
8003             vec($_,16, 1) = 1   ==      65536 00000000000000001000000000000000
8004             vec($_,17, 1) = 1   ==     131072 00000000000000000100000000000000
8005             vec($_,18, 1) = 1   ==     262144 00000000000000000010000000000000
8006             vec($_,19, 1) = 1   ==     524288 00000000000000000001000000000000
8007             vec($_,20, 1) = 1   ==    1048576 00000000000000000000100000000000
8008             vec($_,21, 1) = 1   ==    2097152 00000000000000000000010000000000
8009             vec($_,22, 1) = 1   ==    4194304 00000000000000000000001000000000
8010             vec($_,23, 1) = 1   ==    8388608 00000000000000000000000100000000
8011             vec($_,24, 1) = 1   ==   16777216 00000000000000000000000010000000
8012             vec($_,25, 1) = 1   ==   33554432 00000000000000000000000001000000
8013             vec($_,26, 1) = 1   ==   67108864 00000000000000000000000000100000
8014             vec($_,27, 1) = 1   ==  134217728 00000000000000000000000000010000
8015             vec($_,28, 1) = 1   ==  268435456 00000000000000000000000000001000
8016             vec($_,29, 1) = 1   ==  536870912 00000000000000000000000000000100
8017             vec($_,30, 1) = 1   == 1073741824 00000000000000000000000000000010
8018             vec($_,31, 1) = 1   == 2147483648 00000000000000000000000000000001
8019             vec($_, 0, 2) = 1   ==          1 10000000000000000000000000000000
8020             vec($_, 1, 2) = 1   ==          4 00100000000000000000000000000000
8021             vec($_, 2, 2) = 1   ==         16 00001000000000000000000000000000
8022             vec($_, 3, 2) = 1   ==         64 00000010000000000000000000000000
8023             vec($_, 4, 2) = 1   ==        256 00000000100000000000000000000000
8024             vec($_, 5, 2) = 1   ==       1024 00000000001000000000000000000000
8025             vec($_, 6, 2) = 1   ==       4096 00000000000010000000000000000000
8026             vec($_, 7, 2) = 1   ==      16384 00000000000000100000000000000000
8027             vec($_, 8, 2) = 1   ==      65536 00000000000000001000000000000000
8028             vec($_, 9, 2) = 1   ==     262144 00000000000000000010000000000000
8029             vec($_,10, 2) = 1   ==    1048576 00000000000000000000100000000000
8030             vec($_,11, 2) = 1   ==    4194304 00000000000000000000001000000000
8031             vec($_,12, 2) = 1   ==   16777216 00000000000000000000000010000000
8032             vec($_,13, 2) = 1   ==   67108864 00000000000000000000000000100000
8033             vec($_,14, 2) = 1   ==  268435456 00000000000000000000000000001000
8034             vec($_,15, 2) = 1   == 1073741824 00000000000000000000000000000010
8035             vec($_, 0, 2) = 2   ==          2 01000000000000000000000000000000
8036             vec($_, 1, 2) = 2   ==          8 00010000000000000000000000000000
8037             vec($_, 2, 2) = 2   ==         32 00000100000000000000000000000000
8038             vec($_, 3, 2) = 2   ==        128 00000001000000000000000000000000
8039             vec($_, 4, 2) = 2   ==        512 00000000010000000000000000000000
8040             vec($_, 5, 2) = 2   ==       2048 00000000000100000000000000000000
8041             vec($_, 6, 2) = 2   ==       8192 00000000000001000000000000000000
8042             vec($_, 7, 2) = 2   ==      32768 00000000000000010000000000000000
8043             vec($_, 8, 2) = 2   ==     131072 00000000000000000100000000000000
8044             vec($_, 9, 2) = 2   ==     524288 00000000000000000001000000000000
8045             vec($_,10, 2) = 2   ==    2097152 00000000000000000000010000000000
8046             vec($_,11, 2) = 2   ==    8388608 00000000000000000000000100000000
8047             vec($_,12, 2) = 2   ==   33554432 00000000000000000000000001000000
8048             vec($_,13, 2) = 2   ==  134217728 00000000000000000000000000010000
8049             vec($_,14, 2) = 2   ==  536870912 00000000000000000000000000000100
8050             vec($_,15, 2) = 2   == 2147483648 00000000000000000000000000000001
8051             vec($_, 0, 4) = 1   ==          1 10000000000000000000000000000000
8052             vec($_, 1, 4) = 1   ==         16 00001000000000000000000000000000
8053             vec($_, 2, 4) = 1   ==        256 00000000100000000000000000000000
8054             vec($_, 3, 4) = 1   ==       4096 00000000000010000000000000000000
8055             vec($_, 4, 4) = 1   ==      65536 00000000000000001000000000000000
8056             vec($_, 5, 4) = 1   ==    1048576 00000000000000000000100000000000
8057             vec($_, 6, 4) = 1   ==   16777216 00000000000000000000000010000000
8058             vec($_, 7, 4) = 1   ==  268435456 00000000000000000000000000001000
8059             vec($_, 0, 4) = 2   ==          2 01000000000000000000000000000000
8060             vec($_, 1, 4) = 2   ==         32 00000100000000000000000000000000
8061             vec($_, 2, 4) = 2   ==        512 00000000010000000000000000000000
8062             vec($_, 3, 4) = 2   ==       8192 00000000000001000000000000000000
8063             vec($_, 4, 4) = 2   ==     131072 00000000000000000100000000000000
8064             vec($_, 5, 4) = 2   ==    2097152 00000000000000000000010000000000
8065             vec($_, 6, 4) = 2   ==   33554432 00000000000000000000000001000000
8066             vec($_, 7, 4) = 2   ==  536870912 00000000000000000000000000000100
8067             vec($_, 0, 4) = 4   ==          4 00100000000000000000000000000000
8068             vec($_, 1, 4) = 4   ==         64 00000010000000000000000000000000
8069             vec($_, 2, 4) = 4   ==       1024 00000000001000000000000000000000
8070             vec($_, 3, 4) = 4   ==      16384 00000000000000100000000000000000
8071             vec($_, 4, 4) = 4   ==     262144 00000000000000000010000000000000
8072             vec($_, 5, 4) = 4   ==    4194304 00000000000000000000001000000000
8073             vec($_, 6, 4) = 4   ==   67108864 00000000000000000000000000100000
8074             vec($_, 7, 4) = 4   == 1073741824 00000000000000000000000000000010
8075             vec($_, 0, 4) = 8   ==          8 00010000000000000000000000000000
8076             vec($_, 1, 4) = 8   ==        128 00000001000000000000000000000000
8077             vec($_, 2, 4) = 8   ==       2048 00000000000100000000000000000000
8078             vec($_, 3, 4) = 8   ==      32768 00000000000000010000000000000000
8079             vec($_, 4, 4) = 8   ==     524288 00000000000000000001000000000000
8080             vec($_, 5, 4) = 8   ==    8388608 00000000000000000000000100000000
8081             vec($_, 6, 4) = 8   ==  134217728 00000000000000000000000000010000
8082             vec($_, 7, 4) = 8   == 2147483648 00000000000000000000000000000001
8083             vec($_, 0, 8) = 1   ==          1 10000000000000000000000000000000
8084             vec($_, 1, 8) = 1   ==        256 00000000100000000000000000000000
8085             vec($_, 2, 8) = 1   ==      65536 00000000000000001000000000000000
8086             vec($_, 3, 8) = 1   ==   16777216 00000000000000000000000010000000
8087             vec($_, 0, 8) = 2   ==          2 01000000000000000000000000000000
8088             vec($_, 1, 8) = 2   ==        512 00000000010000000000000000000000
8089             vec($_, 2, 8) = 2   ==     131072 00000000000000000100000000000000
8090             vec($_, 3, 8) = 2   ==   33554432 00000000000000000000000001000000
8091             vec($_, 0, 8) = 4   ==          4 00100000000000000000000000000000
8092             vec($_, 1, 8) = 4   ==       1024 00000000001000000000000000000000
8093             vec($_, 2, 8) = 4   ==     262144 00000000000000000010000000000000
8094             vec($_, 3, 8) = 4   ==   67108864 00000000000000000000000000100000
8095             vec($_, 0, 8) = 8   ==          8 00010000000000000000000000000000
8096             vec($_, 1, 8) = 8   ==       2048 00000000000100000000000000000000
8097             vec($_, 2, 8) = 8   ==     524288 00000000000000000001000000000000
8098             vec($_, 3, 8) = 8   ==  134217728 00000000000000000000000000010000
8099             vec($_, 0, 8) = 16  ==         16 00001000000000000000000000000000
8100             vec($_, 1, 8) = 16  ==       4096 00000000000010000000000000000000
8101             vec($_, 2, 8) = 16  ==    1048576 00000000000000000000100000000000
8102             vec($_, 3, 8) = 16  ==  268435456 00000000000000000000000000001000
8103             vec($_, 0, 8) = 32  ==         32 00000100000000000000000000000000
8104             vec($_, 1, 8) = 32  ==       8192 00000000000001000000000000000000
8105             vec($_, 2, 8) = 32  ==    2097152 00000000000000000000010000000000
8106             vec($_, 3, 8) = 32  ==  536870912 00000000000000000000000000000100
8107             vec($_, 0, 8) = 64  ==         64 00000010000000000000000000000000
8108             vec($_, 1, 8) = 64  ==      16384 00000000000000100000000000000000
8109             vec($_, 2, 8) = 64  ==    4194304 00000000000000000000001000000000
8110             vec($_, 3, 8) = 64  == 1073741824 00000000000000000000000000000010
8111             vec($_, 0, 8) = 128 ==        128 00000001000000000000000000000000
8112             vec($_, 1, 8) = 128 ==      32768 00000000000000010000000000000000
8113             vec($_, 2, 8) = 128 ==    8388608 00000000000000000000000100000000
8114             vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
8115
8116       wait
8117           Behaves like wait(2) on your system: it waits for a child process
8118           to terminate and returns the pid of the deceased process, or "-1"
8119           if there are no child processes.  The status is returned in $? and
8120           "${^CHILD_ERROR_NATIVE}".  Note that a return value of "-1" could
8121           mean that child processes are being automatically reaped, as
8122           described in perlipc.
8123
8124           If you use "wait" in your handler for $SIG{CHLD}, it may
8125           accidentally wait for the child created by "qx" or "system".  See
8126           perlipc for details.
8127
8128           Portability issues: "wait" in perlport.
8129
8130       waitpid PID,FLAGS
8131           Waits for a particular child process to terminate and returns the
8132           pid of the deceased process, or "-1" if there is no such child
8133           process.  A non-blocking wait (with WNOHANG in FLAGS) can return 0
8134           if there are child processes matching PID but none have terminated
8135           yet.  The status is returned in $? and "${^CHILD_ERROR_NATIVE}".
8136
8137           A PID of 0 indicates to wait for any child process whose process
8138           group ID is equal to that of the current process.  A PID of less
8139           than "-1" indicates to wait for any child process whose process
8140           group ID is equal to -PID.  A PID of "-1" indicates to wait for any
8141           child process.
8142
8143           If you say
8144
8145               use POSIX ":sys_wait_h";
8146
8147               my $kid;
8148               do {
8149                   $kid = waitpid(-1, WNOHANG);
8150               } while $kid > 0;
8151
8152           or
8153
8154               1 while waitpid(-1, WNOHANG) > 0;
8155
8156           then you can do a non-blocking wait for all pending zombie
8157           processes (see "WAIT" in POSIX).  Non-blocking wait is available on
8158           machines supporting either the waitpid(2) or wait4(2) syscalls.
8159           However, waiting for a particular pid with FLAGS of 0 is
8160           implemented everywhere.  (Perl emulates the system call by
8161           remembering the status values of processes that have exited but
8162           have not been harvested by the Perl script yet.)
8163
8164           Note that on some systems, a return value of "-1" could mean that
8165           child processes are being automatically reaped.  See perlipc for
8166           details, and for other examples.
8167
8168           Portability issues: "waitpid" in perlport.
8169
8170       wantarray
8171           Returns true if the context of the currently executing subroutine
8172           or "eval" is looking for a list value.  Returns false if the
8173           context is looking for a scalar.  Returns the undefined value if
8174           the context is looking for no value (void context).
8175
8176               return unless defined wantarray; # don't bother doing more
8177               my @a = complex_calculation();
8178               return wantarray ? @a : "@a";
8179
8180           "wantarray"'s result is unspecified in the top level of a file, in
8181           a "BEGIN", "UNITCHECK", "CHECK", "INIT" or "END" block, or in a
8182           "DESTROY" method.
8183
8184           This function should have been named wantlist() instead.
8185
8186       warn LIST
8187           Prints the value of LIST to STDERR.  If the last element of LIST
8188           does not end in a newline, it appends the same file/line number
8189           text as "die" does.
8190
8191           If the output is empty and $@ already contains a value (typically
8192           from a previous eval) that value is used after appending
8193           "\t...caught" to $@.  This is useful for staying almost, but not
8194           entirely similar to "die".
8195
8196           If $@ is empty, then the string "Warning: Something's wrong" is
8197           used.
8198
8199           No message is printed if there is a $SIG{__WARN__} handler
8200           installed.  It is the handler's responsibility to deal with the
8201           message as it sees fit (like, for instance, converting it into a
8202           "die").  Most handlers must therefore arrange to actually display
8203           the warnings that they are not prepared to deal with, by calling
8204           "warn" again in the handler.  Note that this is quite safe and will
8205           not produce an endless loop, since "__WARN__" hooks are not called
8206           from inside one.
8207
8208           You will find this behavior is slightly different from that of
8209           $SIG{__DIE__} handlers (which don't suppress the error text, but
8210           can instead call "die" again to change it).
8211
8212           Using a "__WARN__" handler provides a powerful way to silence all
8213           warnings (even the so-called mandatory ones).  An example:
8214
8215               # wipe out *all* compile-time warnings
8216               BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
8217               my $foo = 10;
8218               my $foo = 20;          # no warning about duplicate my $foo,
8219                                      # but hey, you asked for it!
8220               # no compile-time or run-time warnings before here
8221               $DOWARN = 1;
8222
8223               # run-time warnings enabled after here
8224               warn "\$foo is alive and $foo!";     # does show up
8225
8226           See perlvar for details on setting %SIG entries and for more
8227           examples.  See the Carp module for other kinds of warnings using
8228           its "carp"