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