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