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 Note that the only types of call frames that are visible are
665 subroutine calls and "eval". Other forms of context, such as
666 "while" or "foreach" loops or "try" blocks are not considered
667 interesting to "caller", as they do not alter the behaviour of the
668 "return" expression.
669 Furthermore, when called from within the DB package in list
671 context, and with an argument, caller returns more detailed
672 information: it sets the list variable @DB::args to be the
673 arguments with which the subroutine was invoked.
674 Be aware that the optimizer might have optimized call frames away
676 before "caller" had a chance to get the information. That means
677 that caller(N) might not return information about the call frame
678 you expect it to, for "N > 1". In particular, @DB::args might have
679 information from the previous time "caller" was called.
680 Be aware that setting @DB::args is best effort, intended for
682 debugging or generating backtraces, and should not be relied upon.
683 In particular, as @_ contains aliases to the caller's arguments,
684 Perl does not take a copy of @_, so @DB::args will contain
685 modifications the subroutine makes to @_ or its contents, not the
686 original values at call time. @DB::args, like @_, does not hold
687 explicit references to its elements, so under certain cases its
688 elements may have become freed and reallocated for other variables
689 or temporary values. Finally, a side effect of the current
690 implementation is that the effects of "shift @_" can normally be
691 undone (but not "pop @_" or other splicing, and not if a reference
692 to @_ has been taken, and subject to the caveat about reallocated
693 elements), so @DB::args is actually a hybrid of the current state
694 and initial state of @_. Buyer beware.
695 chdir EXPR
697 chdir FILEHANDLE
698 chdir DIRHANDLE
699 chdir
700 Changes the working directory to EXPR, if possible. If EXPR is
701 omitted, changes to the directory specified by $ENV{HOME}, if set;
702 if not, changes to the directory specified by $ENV{LOGDIR}. (Under
703 VMS, the variable $ENV{'SYS$LOGIN'} is also checked, and used if it
704 is set.) If neither is set, "chdir" does nothing and fails. It
705 returns true on success, false otherwise. See the example under
706 "die".
707 On systems that support fchdir(2), you may pass a filehandle or
709 directory handle as the argument. On systems that don't support
710 fchdir(2), passing handles raises an exception.
711 chmod LIST
713 Changes the permissions of a list of files. The first element of
714 the list must be the numeric mode, which should probably be an
715 octal number, and which definitely should not be a string of octal
716 digits: 0644 is okay, but "0644" is not. Returns the number of
717 files successfully changed. See also "oct" if all you have is a
718 string.
719 my $cnt = chmod 0755, "foo", "bar";
721 chmod 0755, @executables;
722 my $mode = "0644"; chmod $mode, "foo"; # !!! sets mode to
723 # --w----r-T
724 my $mode = "0644"; chmod oct($mode), "foo"; # this is better
725 my $mode = 0644; chmod $mode, "foo"; # this is best
726 On systems that support fchmod(2), you may pass filehandles among
728 the files. On systems that don't support fchmod(2), passing
729 filehandles raises an exception. Filehandles must be passed as
730 globs or glob references to be recognized; barewords are considered
731 filenames.
732 open(my $fh, "<", "foo");
734 my $perm = (stat $fh)[2] & 07777;
735 chmod($perm | 0600, $fh);
736 You can also import the symbolic "S_I*" constants from the "Fcntl"
738 module:
739 use Fcntl qw( :mode );
741 chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
742 # Identical to the chmod 0755 of the example above.
743 Portability issues: "chmod" in perlport.
745 chomp VARIABLE
747 chomp( LIST )
748 chomp
749 This safer version of "chop" removes any trailing string that
750 corresponds to the current value of $/ (also known as
751 $INPUT_RECORD_SEPARATOR in the "English" module). It returns the
752 total number of characters removed from all its arguments. It's
753 often used to remove the newline from the end of an input record
754 when you're worried that the final record may be missing its
755 newline. When in paragraph mode ("$/ = ''"), it removes all
756 trailing newlines from the string. When in slurp mode ("$/ =
757 undef") or fixed-length record mode ($/ is a reference to an
758 integer or the like; see perlvar), "chomp" won't remove anything.
759 If VARIABLE is omitted, it chomps $_. Example:
760 while (<>) {
762 chomp; # avoid \n on last field
763 my @array = split(/:/);
764 # ...
765 }
766 If VARIABLE is a hash, it chomps the hash's values, but not its
768 keys, resetting the "each" iterator in the process.
769 You can actually chomp anything that's an lvalue, including an
771 assignment:
772 chomp(my $cwd = `pwd`);
774 chomp(my $answer = <STDIN>);
775 If you chomp a list, each element is chomped, and the total number
777 of characters removed is returned.
778 Note that parentheses are necessary when you're chomping anything
780 that is not a simple variable. This is because "chomp $cwd =
781 `pwd`;" is interpreted as "(chomp $cwd) = `pwd`;", rather than as
782 "chomp( $cwd = `pwd` )" which you might expect. Similarly, "chomp
783 $a, $b" is interpreted as "chomp($a), $b" rather than as "chomp($a,
784 $b)".
785 chop VARIABLE
787 chop( LIST )
788 chop
789 Chops off the last character of a string and returns the character
790 chopped. It is much more efficient than "s/.$//s" because it
791 neither scans nor copies the string. If VARIABLE is omitted, chops
792 $_. If VARIABLE is a hash, it chops the hash's values, but not its
793 keys, resetting the "each" iterator in the process.
794 You can actually chop anything that's an lvalue, including an
796 assignment.
797 If you chop a list, each element is chopped. Only the value of the
799 last "chop" is returned.
800 Note that "chop" returns the last character. To return all but the
802 last character, use "substr($string, 0, -1)".
803 See also "chomp".
805 chown LIST
807 Changes the owner (and group) of a list of files. The first two
808 elements of the list must be the numeric uid and gid, in that
809 order. A value of -1 in either position is interpreted by most
810 systems to leave that value unchanged. Returns the number of files
811 successfully changed.
812 my $cnt = chown $uid, $gid, 'foo', 'bar';
814 chown $uid, $gid, @filenames;
815 On systems that support fchown(2), you may pass filehandles among
817 the files. On systems that don't support fchown(2), passing
818 filehandles raises an exception. Filehandles must be passed as
819 globs or glob references to be recognized; barewords are considered
820 filenames.
821 Here's an example that looks up nonnumeric uids in the passwd file:
823 print "User: ";
825 chomp(my $user = <STDIN>);
826 print "Files: ";
827 chomp(my $pattern = <STDIN>);
828 my ($login,$pass,$uid,$gid) = getpwnam($user)
830 or die "$user not in passwd file";
831 my @ary = glob($pattern); # expand filenames
833 chown $uid, $gid, @ary;
834 On most systems, you are not allowed to change the ownership of the
836 file unless you're the superuser, although you should be able to
837 change the group to any of your secondary groups. On insecure
838 systems, these restrictions may be relaxed, but this is not a
839 portable assumption. On POSIX systems, you can detect this
840 condition this way:
841 use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
843 my $can_chown_giveaway = ! sysconf(_PC_CHOWN_RESTRICTED);
844 Portability issues: "chown" in perlport.
846 chr NUMBER
848 chr Returns the character represented by that NUMBER in the character
849 set. For example, "chr(65)" is "A" in either ASCII or Unicode, and
850 chr(0x263a) is a Unicode smiley face.
851 Negative values give the Unicode replacement character
853 (chr(0xfffd)), except under the bytes pragma, where the low eight
854 bits of the value (truncated to an integer) are used.
855 If NUMBER is omitted, uses $_.
857 For the reverse, use "ord".
859 Note that characters from 128 to 255 (inclusive) are by default
861 internally not encoded as UTF-8 for backward compatibility reasons.
862 See perlunicode for more about Unicode.
864 chroot FILENAME
866 chroot
867 This function works like the system call by the same name: it makes
868 the named directory the new root directory for all further
869 pathnames that begin with a "/" by your process and all its
870 children. (It doesn't change your current working directory, which
871 is unaffected.) For security reasons, this call is restricted to
872 the superuser. If FILENAME is omitted, does a "chroot" to $_.
873 NOTE: It is mandatory for security to "chdir("/")" ("chdir" to the
875 root directory) immediately after a "chroot", otherwise the current
876 working directory may be outside of the new root.
877 Portability issues: "chroot" in perlport.
879 close FILEHANDLE
881 close
882 Closes the file or pipe associated with the filehandle, flushes the
883 IO buffers, and closes the system file descriptor. Returns true if
884 those operations succeed and if no error was reported by any PerlIO
885 layer. Closes the currently selected filehandle if the argument is
886 omitted.
887 You don't have to close FILEHANDLE if you are immediately going to
889 do another "open" on it, because "open" closes it for you. (See
890 "open".) However, an explicit "close" on an input file resets the
891 line counter ($.), while the implicit close done by "open" does
892 not.
893 If the filehandle came from a piped open, "close" returns false if
895 one of the other syscalls involved fails or if its program exits
896 with non-zero status. If the only problem was that the program
897 exited non-zero, $! will be set to 0. Closing a pipe also waits
898 for the process executing on the pipe to exit--in case you wish to
899 look at the output of the pipe afterwards--and implicitly puts the
900 exit status value of that command into $? and
901 "${^CHILD_ERROR_NATIVE}".
902 If there are multiple threads running, "close" on a filehandle from
904 a piped open returns true without waiting for the child process to
905 terminate, if the filehandle is still open in another thread.
906 Closing the read end of a pipe before the process writing to it at
908 the other end is done writing results in the writer receiving a
909 SIGPIPE. If the other end can't handle that, be sure to read all
910 the data before closing the pipe.
911 Example:
913 open(OUTPUT, '|sort >foo') # pipe to sort
915 or die "Can't start sort: $!";
916 #... # print stuff to output
917 close OUTPUT # wait for sort to finish
918 or warn $! ? "Error closing sort pipe: $!"
919 : "Exit status $? from sort";
920 open(INPUT, 'foo') # get sort's results
921 or die "Can't open 'foo' for input: $!";
922 FILEHANDLE may be an expression whose value can be used as an
924 indirect filehandle, usually the real filehandle name or an
925 autovivified handle.
926 closedir DIRHANDLE
928 Closes a directory opened by "opendir" and returns the success of
929 that system call.
930 connect SOCKET,NAME
932 Attempts to connect to a remote socket, just like connect(2).
933 Returns true if it succeeded, false otherwise. NAME should be a
934 packed address of the appropriate type for the socket. See the
935 examples in "Sockets: Client/Server Communication" in perlipc.
936 continue BLOCK
938 continue
939 When followed by a BLOCK, "continue" is actually a flow control
940 statement rather than a function. If there is a "continue" BLOCK
941 attached to a BLOCK (typically in a "while" or "foreach"), it is
942 always executed just before the conditional is about to be
943 evaluated again, just like the third part of a "for" loop in C.
944 Thus it can be used to increment a loop variable, even when the
945 loop has been continued via the "next" statement (which is similar
946 to the C "continue" statement).
947 "last", "next", or "redo" may appear within a "continue" block;
949 "last" and "redo" behave as if they had been executed within the
950 main block. So will "next", but since it will execute a "continue"
951 block, it may be more entertaining.
952 while (EXPR) {
954 ### redo always comes here
955 do_something;
956 } continue {
957 ### next always comes here
958 do_something_else;
959 # then back the top to re-check EXPR
960 }
961 ### last always comes here
962 Omitting the "continue" section is equivalent to using an empty
964 one, logically enough, so "next" goes directly back to check the
965 condition at the top of the loop.
966 When there is no BLOCK, "continue" is a function that falls through
968 the current "when" or "default" block instead of iterating a
969 dynamically enclosing "foreach" or exiting a lexically enclosing
970 "given". In Perl 5.14 and earlier, this form of "continue" was
971 only available when the "switch" feature was enabled. See feature
972 and "Switch Statements" in perlsyn for more information.
973 cos EXPR
975 cos Returns the cosine of EXPR (expressed in radians). If EXPR is
976 omitted, takes the cosine of $_.
977 For the inverse cosine operation, you may use the
979 "Math::Trig::acos" function, or use this relation:
980 sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
982 crypt PLAINTEXT,SALT
984 Creates a digest string exactly like the crypt(3) function in the C
985 library (assuming that you actually have a version there that has
986 not been extirpated as a potential munition).
987 "crypt" is a one-way hash function. The PLAINTEXT and SALT are
989 turned into a short string, called a digest, which is returned.
990 The same PLAINTEXT and SALT will always return the same string, but
991 there is no (known) way to get the original PLAINTEXT from the
992 hash. Small changes in the PLAINTEXT or SALT will result in large
993 changes in the digest.
994 There is no decrypt function. This function isn't all that useful
996 for cryptography (for that, look for Crypt modules on your nearby
997 CPAN mirror) and the name "crypt" is a bit of a misnomer. Instead
998 it is primarily used to check if two pieces of text are the same
999 without having to transmit or store the text itself. An example is
1000 checking if a correct password is given. The digest of the
1001 password is stored, not the password itself. The user types in a
1002 password that is "crypt"'d with the same salt as the stored digest.
1003 If the two digests match, the password is correct.
1004 When verifying an existing digest string you should use the digest
1006 as the salt (like "crypt($plain, $digest) eq $digest"). The SALT
1007 used to create the digest is visible as part of the digest. This
1008 ensures "crypt" will hash the new string with the same salt as the
1009 digest. This allows your code to work with the standard "crypt"
1010 and with more exotic implementations. In other words, assume
1011 nothing about the returned string itself nor about how many bytes
1012 of SALT may matter.
1013 Traditionally the result is a string of 13 bytes: two first bytes
1015 of the salt, followed by 11 bytes from the set "[./0-9A-Za-z]", and
1016 only the first eight bytes of PLAINTEXT mattered. But alternative
1017 hashing schemes (like MD5), higher level security schemes (like
1018 C2), and implementations on non-Unix platforms may produce
1019 different strings.
1020 When choosing a new salt create a random two character string whose
1022 characters come from the set "[./0-9A-Za-z]" (like "join '', ('.',
1023 '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]"). This set of
1024 characters is just a recommendation; the characters allowed in the
1025 salt depend solely on your system's crypt library, and Perl can't
1026 restrict what salts "crypt" accepts.
1027 Here's an example that makes sure that whoever runs this program
1029 knows their password:
1030 my $pwd = (getpwuid($<))[1];
1032 system "stty -echo";
1034 print "Password: ";
1035 chomp(my $word = <STDIN>);
1036 print "\n";
1037 system "stty echo";
1038 if (crypt($word, $pwd) ne $pwd) {
1040 die "Sorry...\n";
1041 } else {
1042 print "ok\n";
1043 }
1044 Of course, typing in your own password to whoever asks you for it
1046 is unwise.
1047 The "crypt" function is unsuitable for hashing large quantities of
1049 data, not least of all because you can't get the information back.
1050 Look at the Digest module for more robust algorithms.
1051 If using "crypt" on a Unicode string (which potentially has
1053 characters with codepoints above 255), Perl tries to make sense of
1054 the situation by trying to downgrade (a copy of) the string back to
1055 an eight-bit byte string before calling "crypt" (on that copy). If
1056 that works, good. If not, "crypt" dies with "Wide character in
1057 crypt".
1058 Portability issues: "crypt" in perlport.
1060 dbmclose HASH
1062 [This function has been largely superseded by the "untie"
1063 function.]
1064 Breaks the binding between a DBM file and a hash.
1066 Portability issues: "dbmclose" in perlport.
1068 dbmopen HASH,DBNAME,MASK
1070 [This function has been largely superseded by the "tie" function.]
1071 This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file
1073 to a hash. HASH is the name of the hash. (Unlike normal "open",
1074 the first argument is not a filehandle, even though it looks like
1075 one). DBNAME is the name of the database (without the .dir or .pag
1076 extension if any). If the database does not exist, it is created
1077 with protection specified by MASK (as modified by the "umask"). To
1078 prevent creation of the database if it doesn't exist, you may
1079 specify a MODE of 0, and the function will return a false value if
1080 it can't find an existing database. If your system supports only
1081 the older DBM functions, you may make only one "dbmopen" call in
1082 your program. In older versions of Perl, if your system had
1083 neither DBM nor ndbm, calling "dbmopen" produced a fatal error; it
1084 now falls back to sdbm(3).
1085 If you don't have write access to the DBM file, you can only read
1087 hash variables, not set them. If you want to test whether you can
1088 write, either use file tests or try setting a dummy hash entry
1089 inside an "eval" to trap the error.
1090 Note that functions such as "keys" and "values" may return huge
1092 lists when used on large DBM files. You may prefer to use the
1093 "each" function to iterate over large DBM files. Example:
1094 # print out history file offsets
1096 dbmopen(%HIST,'/usr/lib/news/history',0666);
1097 while (($key,$val) = each %HIST) {
1098 print $key, ' = ', unpack('L',$val), "\n";
1099 }
1100 dbmclose(%HIST);
1101 See also AnyDBM_File for a more general description of the pros and
1103 cons of the various dbm approaches, as well as DB_File for a
1104 particularly rich implementation.
1105 You can control which DBM library you use by loading that library
1107 before you call "dbmopen":
1108 use DB_File;
1110 dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
1111 or die "Can't open netscape history file: $!";
1112 Portability issues: "dbmopen" in perlport.
1114 defined EXPR
1116 defined
1117 Returns a Boolean value telling whether EXPR has a value other than
1118 the undefined value "undef". If EXPR is not present, $_ is
1119 checked.
1120 Many operations return "undef" to indicate failure, end of file,
1122 system error, uninitialized variable, and other exceptional
1123 conditions. This function allows you to distinguish "undef" from
1124 other values. (A simple Boolean test will not distinguish among
1125 "undef", zero, the empty string, and "0", which are all equally
1126 false.) Note that since "undef" is a valid scalar, its presence
1127 doesn't necessarily indicate an exceptional condition: "pop"
1128 returns "undef" when its argument is an empty array, or when the
1129 element to return happens to be "undef".
1130 You may also use "defined(&func)" to check whether subroutine
1132 "func" has ever been defined. The return value is unaffected by
1133 any forward declarations of "func". A subroutine that is not
1134 defined may still be callable: its package may have an "AUTOLOAD"
1135 method that makes it spring into existence the first time that it
1136 is called; see perlsub.
1137 Use of "defined" on aggregates (hashes and arrays) is no longer
1139 supported. It used to report whether memory for that aggregate had
1140 ever been allocated. You should instead use a simple test for
1141 size:
1142 if (@an_array) { print "has array elements\n" }
1144 if (%a_hash) { print "has hash members\n" }
1145 When used on a hash element, it tells you whether the value is
1147 defined, not whether the key exists in the hash. Use "exists" for
1148 the latter purpose.
1149 Examples:
1151 print if defined $switch{D};
1153 print "$val\n" while defined($val = pop(@ary));
1154 die "Can't readlink $sym: $!"
1155 unless defined($value = readlink $sym);
1156 sub foo { defined &$bar ? $bar->(@_) : die "No bar"; }
1157 $debugging = 0 unless defined $debugging;
1158 Note: Many folks tend to overuse "defined" and are then surprised
1160 to discover that the number 0 and "" (the zero-length string) are,
1161 in fact, defined values. For example, if you say
1162 "ab" =~ /a(.*)b/;
1164 The pattern match succeeds and $1 is defined, although it matched
1166 "nothing". It didn't really fail to match anything. Rather, it
1167 matched something that happened to be zero characters long. This
1168 is all very above-board and honest. When a function returns an
1169 undefined value, it's an admission that it couldn't give you an
1170 honest answer. So you should use "defined" only when questioning
1171 the integrity of what you're trying to do. At other times, a
1172 simple comparison to 0 or "" is what you want.
1173 See also "undef", "exists", "ref".
1175 delete EXPR
1177 Given an expression that specifies an element or slice of a hash,
1178 "delete" deletes the specified elements from that hash so that
1179 "exists" on that element no longer returns true. Setting a hash
1180 element to the undefined value does not remove its key, but
1181 deleting it does; see "exists".
1182 In list context, usually returns the value or values deleted, or
1184 the last such element in scalar context. The return list's length
1185 corresponds to that of the argument list: deleting non-existent
1186 elements returns the undefined value in their corresponding
1187 positions. When a key/value hash slice is passed to "delete", the
1188 return value is a list of key/value pairs (two elements for each
1189 item deleted from the hash).
1190 "delete" may also be used on arrays and array slices, but its
1192 behavior is less straightforward. Although "exists" will return
1193 false for deleted entries, deleting array elements never changes
1194 indices of existing values; use "shift" or "splice" for that.
1195 However, if any deleted elements fall at the end of an array, the
1196 array's size shrinks to the position of the highest element that
1197 still tests true for "exists", or to 0 if none do. In other words,
1198 an array won't have trailing nonexistent elements after a delete.
1199 WARNING: Calling "delete" on array values is strongly discouraged.
1201 The notion of deleting or checking the existence of Perl array
1202 elements is not conceptually coherent, and can lead to surprising
1203 behavior.
1204 Deleting from %ENV modifies the environment. Deleting from a hash
1206 tied to a DBM file deletes the entry from the DBM file. Deleting
1207 from a "tied" hash or array may not necessarily return anything; it
1208 depends on the implementation of the "tied" package's DELETE
1209 method, which may do whatever it pleases.
1210 The "delete local EXPR" construct localizes the deletion to the
1212 current block at run time. Until the block exits, elements locally
1213 deleted temporarily no longer exist. See "Localized deletion of
1214 elements of composite types" in perlsub.
1215 my %hash = (foo => 11, bar => 22, baz => 33);
1217 my $scalar = delete $hash{foo}; # $scalar is 11
1218 $scalar = delete @hash{qw(foo bar)}; # $scalar is 22
1219 my @array = delete @hash{qw(foo baz)}; # @array is (undef,33)
1220 The following (inefficiently) deletes all the values of %HASH and
1222 @ARRAY:
1223 foreach my $key (keys %HASH) {
1225 delete $HASH{$key};
1226 }
1227 foreach my $index (0 .. $#ARRAY) {
1229 delete $ARRAY[$index];
1230 }
1231 And so do these:
1233 delete @HASH{keys %HASH};
1235 delete @ARRAY[0 .. $#ARRAY];
1237 But both are slower than assigning the empty list or undefining
1239 %HASH or @ARRAY, which is the customary way to empty out an
1240 aggregate:
1241 %HASH = (); # completely empty %HASH
1243 undef %HASH; # forget %HASH ever existed
1244 @ARRAY = (); # completely empty @ARRAY
1246 undef @ARRAY; # forget @ARRAY ever existed
1247 The EXPR can be arbitrarily complicated provided its final
1249 operation is an element or slice of an aggregate:
1250 delete $ref->[$x][$y]{$key};
1252 delete $ref->[$x][$y]->@{$key1, $key2, @morekeys};
1253 delete $ref->[$x][$y][$index];
1255 delete $ref->[$x][$y]->@[$index1, $index2, @moreindices];
1256 die LIST
1258 "die" raises an exception. Inside an "eval" the exception is
1259 stuffed into $@ and the "eval" is terminated with the undefined
1260 value. If the exception is outside of all enclosing "eval"s, then
1261 the uncaught exception is printed to "STDERR" and perl exits with
1262 an exit code indicating failure. If you need to exit the process
1263 with a specific exit code, see "exit".
1264 Equivalent examples:
1266 die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
1268 chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
1269 Most of the time, "die" is called with a string to use as the
1271 exception. You may either give a single non-reference operand to
1272 serve as the exception, or a list of two or more items, which will
1273 be stringified and concatenated to make the exception.
1274 If the string exception does not end in a newline, the current
1276 script line number and input line number (if any) and a newline are
1277 appended to it. Note that the "input line number" (also known as
1278 "chunk") is subject to whatever notion of "line" happens to be
1279 currently in effect, and is also available as the special variable
1280 $.. See "$/" in perlvar and "$." in perlvar.
1281 Hint: sometimes appending ", stopped" to your message will cause it
1283 to make better sense when the string "at foo line 123" is appended.
1284 Suppose you are running script "canasta".
1285 die "/etc/games is no good";
1287 die "/etc/games is no good, stopped";
1288 produce, respectively
1290 /etc/games is no good at canasta line 123.
1292 /etc/games is no good, stopped at canasta line 123.
1293 If LIST was empty or made an empty string, and $@ already contains
1295 an exception value (typically from a previous "eval"), then that
1296 value is reused after appending "\t...propagated". This is useful
1297 for propagating exceptions:
1298 eval { ... };
1300 die unless $@ =~ /Expected exception/;
1301 If LIST was empty or made an empty string, and $@ contains an
1303 object reference that has a "PROPAGATE" method, that method will be
1304 called with additional file and line number parameters. The return
1305 value replaces the value in $@; i.e., as if "$@ = eval {
1306 $@->PROPAGATE(__FILE__, __LINE__) };" were called.
1307 If LIST was empty or made an empty string, and $@ is also empty,
1309 then the string "Died" is used.
1310 You can also call "die" with a reference argument, and if this is
1312 trapped within an "eval", $@ contains that reference. This permits
1313 more elaborate exception handling using objects that maintain
1314 arbitrary state about the exception. Such a scheme is sometimes
1315 preferable to matching particular string values of $@ with regular
1316 expressions.
1317 Because Perl stringifies uncaught exception messages before
1319 display, you'll probably want to overload stringification
1320 operations on exception objects. See overload for details about
1321 that. The stringified message should be non-empty, and should end
1322 in a newline, in order to fit in with the treatment of string
1323 exceptions. Also, because an exception object reference cannot be
1324 stringified without destroying it, Perl doesn't attempt to append
1325 location or other information to a reference exception. If you
1326 want location information with a complex exception object, you'll
1327 have to arrange to put the location information into the object
1328 yourself.
1329 Because $@ is a global variable, be careful that analyzing an
1331 exception caught by "eval" doesn't replace the reference in the
1332 global variable. It's easiest to make a local copy of the
1333 reference before any manipulations. Here's an example:
1334 use Scalar::Util "blessed";
1336 eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
1338 if (my $ev_err = $@) {
1339 if (blessed($ev_err)
1340 && $ev_err->isa("Some::Module::Exception")) {
1341 # handle Some::Module::Exception
1342 }
1343 else {
1344 # handle all other possible exceptions
1345 }
1346 }
1347 If an uncaught exception results in interpreter exit, the exit code
1349 is determined from the values of $! and $? with this pseudocode:
1350 exit $! if $!; # errno
1352 exit $? >> 8 if $? >> 8; # child exit status
1353 exit 255; # last resort
1354 As with "exit", $? is set prior to unwinding the call stack; any
1356 "DESTROY" or "END" handlers can then alter this value, and thus
1357 Perl's exit code.
1358 The intent is to squeeze as much possible information about the
1360 likely cause into the limited space of the system exit code.
1361 However, as $! is the value of C's "errno", which can be set by any
1362 system call, this means that the value of the exit code used by
1363 "die" can be non-predictable, so should not be relied upon, other
1364 than to be non-zero.
1365 You can arrange for a callback to be run just before the "die" does
1367 its deed, by setting the $SIG{__DIE__} hook. The associated
1368 handler is called with the exception as an argument, and can change
1369 the exception, if it sees fit, by calling "die" again. See "%SIG"
1370 in perlvar for details on setting %SIG entries, and "eval" for some
1371 examples. Although this feature was to be run only right before
1372 your program was to exit, this is not currently so: the
1373 $SIG{__DIE__} hook is currently called even inside "eval"ed
1374 blocks/strings! If one wants the hook to do nothing in such
1375 situations, put
1376 die @_ if $^S;
1378 as the first line of the handler (see "$^S" in perlvar). Because
1380 this promotes strange action at a distance, this counterintuitive
1381 behavior may be fixed in a future release.
1382 See also "exit", "warn", and the Carp module.
1384 do BLOCK
1386 Not really a function. Returns the value of the last command in
1387 the sequence of commands indicated by BLOCK. When modified by the
1388 "while" or "until" loop modifier, executes the BLOCK once before
1389 testing the loop condition. (On other statements the loop
1390 modifiers test the conditional first.)
1391 "do BLOCK" does not count as a loop, so the loop control statements
1393 "next", "last", or "redo" cannot be used to leave or restart the
1394 block. See perlsyn for alternative strategies.
1395 do EXPR
1397 Uses the value of EXPR as a filename and executes the contents of
1398 the file as a Perl script:
1399 # load the exact specified file (./ and ../ special-cased)
1401 do '/foo/stat.pl';
1402 do './stat.pl';
1403 do '../foo/stat.pl';
1404 # search for the named file within @INC
1406 do 'stat.pl';
1407 do 'foo/stat.pl';
1408 "do './stat.pl'" is largely like
1410 eval `cat stat.pl`;
1412 except that it's more concise, runs no external processes, and
1414 keeps track of the current filename for error messages. It also
1415 differs in that code evaluated with "do FILE" cannot see lexicals
1416 in the enclosing scope; "eval STRING" does. It's the same,
1417 however, in that it does reparse the file every time you call it,
1418 so you probably don't want to do this inside a loop.
1419 Using "do" with a relative path (except for ./ and ../), like
1421 do 'foo/stat.pl';
1423 will search the @INC directories, and update %INC if the file is
1425 found. See "@INC" in perlvar and "%INC" in perlvar for these
1426 variables. In particular, note that whilst historically @INC
1427 contained '.' (the current directory) making these two cases
1428 equivalent, that is no longer necessarily the case, as '.' is not
1429 included in @INC by default in perl versions 5.26.0 onwards.
1430 Instead, perl will now warn:
1431 do "stat.pl" failed, '.' is no longer in @INC;
1433 did you mean do "./stat.pl"?
1434 If "do" can read the file but cannot compile it, it returns "undef"
1436 and sets an error message in $@. If "do" cannot read the file, it
1437 returns undef and sets $! to the error. Always check $@ first, as
1438 compilation could fail in a way that also sets $!. If the file is
1439 successfully compiled, "do" returns the value of the last
1440 expression evaluated.
1441 Inclusion of library modules is better done with the "use" and
1443 "require" operators, which also do automatic error checking and
1444 raise an exception if there's a problem.
1445 You might like to use "do" to read in a program configuration file.
1447 Manual error checking can be done this way:
1448 # Read in config files: system first, then user.
1450 # Beware of using relative pathnames here.
1451 for $file ("/share/prog/defaults.rc",
1452 "$ENV{HOME}/.someprogrc")
1453 {
1454 unless ($return = do $file) {
1455 warn "couldn't parse $file: $@" if $@;
1456 warn "couldn't do $file: $!" unless defined $return;
1457 warn "couldn't run $file" unless $return;
1458 }
1459 }
1460 dump LABEL
1462 dump EXPR
1463 dump
1464 This function causes an immediate core dump. See also the -u
1465 command-line switch in perlrun, which does the same thing.
1466 Primarily this is so that you can use the undump program (not
1467 supplied) to turn your core dump into an executable binary after
1468 having initialized all your variables at the beginning of the
1469 program. When the new binary is executed it will begin by
1470 executing a "goto LABEL" (with all the restrictions that "goto"
1471 suffers). Think of it as a goto with an intervening core dump and
1472 reincarnation. If "LABEL" is omitted, restarts the program from
1473 the top. The "dump EXPR" form, available starting in Perl 5.18.0,
1474 allows a name to be computed at run time, being otherwise identical
1475 to "dump LABEL".
1476 WARNING: Any files opened at the time of the dump will not be open
1478 any more when the program is reincarnated, with possible resulting
1479 confusion by Perl.
1480 This function is now largely obsolete, mostly because it's very
1482 hard to convert a core file into an executable. As of Perl 5.30,
1483 it must be invoked as "CORE::dump()".
1484 Unlike most named operators, this has the same precedence as
1486 assignment. It is also exempt from the looks-like-a-function rule,
1487 so "dump ("foo")."bar"" will cause "bar" to be part of the argument
1488 to "dump".
1489 Portability issues: "dump" in perlport.
1491 each HASH
1493 each ARRAY
1494 When called on a hash in list context, returns a 2-element list
1495 consisting of the key and value for the next element of a hash. In
1496 Perl 5.12 and later only, it will also return the index and value
1497 for the next element of an array so that you can iterate over it;
1498 older Perls consider this a syntax error. When called in scalar
1499 context, returns only the key (not the value) in a hash, or the
1500 index in an array.
1501 Hash entries are returned in an apparently random order. The
1503 actual random order is specific to a given hash; the exact same
1504 series of operations on two hashes may result in a different order
1505 for each hash. Any insertion into the hash may change the order,
1506 as will any deletion, with the exception that the most recent key
1507 returned by "each" or "keys" may be deleted without changing the
1508 order. So long as a given hash is unmodified you may rely on
1509 "keys", "values" and "each" to repeatedly return the same order as
1510 each other. See "Algorithmic Complexity Attacks" in perlsec for
1511 details on why hash order is randomized. Aside from the guarantees
1512 provided here the exact details of Perl's hash algorithm and the
1513 hash traversal order are subject to change in any release of Perl.
1514 After "each" has returned all entries from the hash or array, the
1516 next call to "each" returns the empty list in list context and
1517 "undef" in scalar context; the next call following that one
1518 restarts iteration. Each hash or array has its own internal
1519 iterator, accessed by "each", "keys", and "values". The iterator
1520 is implicitly reset when "each" has reached the end as just
1521 described; it can be explicitly reset by calling "keys" or "values"
1522 on the hash or array, or by referencing the hash (but not array) in
1523 list context. If you add or delete a hash's elements while
1524 iterating over it, the effect on the iterator is unspecified; for
1525 example, entries may be skipped or duplicated--so don't do that.
1526 Exception: It is always safe to delete the item most recently
1527 returned by "each", so the following code works properly:
1528 while (my ($key, $value) = each %hash) {
1530 print $key, "\n";
1531 delete $hash{$key}; # This is safe
1532 }
1533 Tied hashes may have a different ordering behaviour to perl's hash
1535 implementation.
1536 The iterator used by "each" is attached to the hash or array, and
1538 is shared between all iteration operations applied to the same hash
1539 or array. Thus all uses of "each" on a single hash or array
1540 advance the same iterator location. All uses of "each" are also
1541 subject to having the iterator reset by any use of "keys" or
1542 "values" on the same hash or array, or by the hash (but not array)
1543 being referenced in list context. This makes "each"-based loops
1544 quite fragile: it is easy to arrive at such a loop with the
1545 iterator already part way through the object, or to accidentally
1546 clobber the iterator state during execution of the loop body. It's
1547 easy enough to explicitly reset the iterator before starting a
1548 loop, but there is no way to insulate the iterator state used by a
1549 loop from the iterator state used by anything else that might
1550 execute during the loop body. To avoid these problems, use a
1551 "foreach" loop rather than "while"-"each".
1552 This prints out your environment like the printenv(1) program, but
1554 in a different order:
1555 while (my ($key,$value) = each %ENV) {
1557 print "$key=$value\n";
1558 }
1559 Starting with Perl 5.14, an experimental feature allowed "each" to
1561 take a scalar expression. This experiment has been deemed
1562 unsuccessful, and was removed as of Perl 5.24.
1563 As of Perl 5.18 you can use a bare "each" in a "while" loop, which
1565 will set $_ on every iteration. If either an "each" expression or
1566 an explicit assignment of an "each" expression to a scalar is used
1567 as a "while"/"for" condition, then the condition actually tests for
1568 definedness of the expression's value, not for its regular truth
1569 value.
1570 while (each %ENV) {
1572 print "$_=$ENV{$_}\n";
1573 }
1574 To avoid confusing would-be users of your code who are running
1576 earlier versions of Perl with mysterious syntax errors, put this
1577 sort of thing at the top of your file to signal that your code will
1578 work only on Perls of a recent vintage:
1579 use 5.012; # so keys/values/each work on arrays
1581 use 5.018; # so each assigns to $_ in a lone while test
1582 See also "keys", "values", and "sort".
1584 eof FILEHANDLE
1586 eof ()
1587 eof Returns 1 if the next read on FILEHANDLE will return end of file or
1588 if FILEHANDLE is not open. FILEHANDLE may be an expression whose
1589 value gives the real filehandle. (Note that this function actually
1590 reads a character and then "ungetc"s it, so isn't useful in an
1591 interactive context.) Do not read from a terminal file (or call
1592 "eof(FILEHANDLE)" on it) after end-of-file is reached. File types
1593 such as terminals may lose the end-of-file condition if you do.
1594 An "eof" without an argument uses the last file read. Using
1596 "eof()" with empty parentheses is different. It refers to the
1597 pseudo file formed from the files listed on the command line and
1598 accessed via the "<>" operator. Since "<>" isn't explicitly
1599 opened, as a normal filehandle is, an "eof()" before "<>" has been
1600 used will cause @ARGV to be examined to determine if input is
1601 available. Similarly, an "eof()" after "<>" has returned end-of-
1602 file will assume you are processing another @ARGV list, and if you
1603 haven't set @ARGV, will read input from "STDIN"; see "I/O
1604 Operators" in perlop.
1605 In a "while (<>)" loop, "eof" or "eof(ARGV)" can be used to detect
1607 the end of each file, whereas "eof()" will detect the end of the
1608 very last file only. Examples:
1609 # reset line numbering on each input file
1611 while (<>) {
1612 next if /^\s*#/; # skip comments
1613 print "$.\t$_";
1614 } continue {
1615 close ARGV if eof; # Not eof()!
1616 }
1617 # insert dashes just before last line of last file
1619 while (<>) {
1620 if (eof()) { # check for end of last file
1621 print "--------------\n";
1622 }
1623 print;
1624 last if eof(); # needed if we're reading from a terminal
1625 }
1626 Practical hint: you almost never need to use "eof" in Perl, because
1628 the input operators typically return "undef" when they run out of
1629 data or encounter an error.
1630 eval EXPR
1632 eval BLOCK
1633 eval
1634 "eval" in all its forms is used to execute a little Perl program,
1635 trapping any errors encountered so they don't crash the calling
1636 program.
1637 Plain "eval" with no argument is just "eval EXPR", where the
1639 expression is understood to be contained in $_. Thus there are
1640 only two real "eval" forms; the one with an EXPR is often called
1641 "string eval". In a string eval, the value of the expression
1642 (which is itself determined within scalar context) is first parsed,
1643 and if there were no errors, executed as a block within the lexical
1644 context of the current Perl program. This form is typically used
1645 to delay parsing and subsequent execution of the text of EXPR until
1646 run time. Note that the value is parsed every time the "eval"
1647 executes.
1648 The other form is called "block eval". It is less general than
1650 string eval, but the code within the BLOCK is parsed only once (at
1651 the same time the code surrounding the "eval" itself was parsed)
1652 and executed within the context of the current Perl program. This
1653 form is typically used to trap exceptions more efficiently than the
1654 first, while also providing the benefit of checking the code within
1655 BLOCK at compile time. BLOCK is parsed and compiled just once.
1656 Since errors are trapped, it often is used to check if a given
1657 feature is available.
1658 In both forms, the value returned is the value of the last
1660 expression evaluated inside the mini-program; a return statement
1661 may also be used, just as with subroutines. The expression
1662 providing the return value is evaluated in void, scalar, or list
1663 context, depending on the context of the "eval" itself. See
1664 "wantarray" for more on how the evaluation context can be
1665 determined.
1666 If there is a syntax error or runtime error, or a "die" statement
1668 is executed, "eval" returns "undef" in scalar context, or an empty
1669 list in list context, and $@ is set to the error message. (Prior
1670 to 5.16, a bug caused "undef" to be returned in list context for
1671 syntax errors, but not for runtime errors.) If there was no error,
1672 $@ is set to the empty string. A control flow operator like "last"
1673 or "goto" can bypass the setting of $@. Beware that using "eval"
1674 neither silences Perl from printing warnings to STDERR, nor does it
1675 stuff the text of warning messages into $@. To do either of those,
1676 you have to use the $SIG{__WARN__} facility, or turn off warnings
1677 inside the BLOCK or EXPR using "no warnings 'all'". See "warn",
1678 perlvar, and warnings.
1679 Note that, because "eval" traps otherwise-fatal errors, it is
1681 useful for determining whether a particular feature (such as
1682 "socket" or "symlink") is implemented. It is also Perl's
1683 exception-trapping mechanism, where the "die" operator is used to
1684 raise exceptions.
1685 Before Perl 5.14, the assignment to $@ occurred before restoration
1687 of localized variables, which means that for your code to run on
1688 older versions, a temporary is required if you want to mask some,
1689 but not all errors:
1690 # alter $@ on nefarious repugnancy only
1692 {
1693 my $e;
1694 {
1695 local $@; # protect existing $@
1696 eval { test_repugnancy() };
1697 # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only
1698 $@ =~ /nefarious/ and $e = $@;
1699 }
1700 die $e if defined $e
1701 }
1702 There are some different considerations for each form:
1704 String eval
1706 Since the return value of EXPR is executed as a block within
1707 the lexical context of the current Perl program, any outer
1708 lexical variables are visible to it, and any package variable
1709 settings or subroutine and format definitions remain
1710 afterwards.
1711 Under the "unicode_eval" feature
1713 If this feature is enabled (which is the default under a
1714 "use 5.16" or higher declaration), EXPR is considered to be
1715 in the same encoding as the surrounding program. Thus if
1716 "use utf8" is in effect, the string will be treated as
1717 being UTF-8 encoded. Otherwise, the string is considered
1718 to be a sequence of independent bytes. Bytes that
1719 correspond to ASCII-range code points will have their
1720 normal meanings for operators in the string. The treatment
1721 of the other bytes depends on if the "'unicode_strings""
1722 feature is in effect.
1723 In a plain "eval" without an EXPR argument, being in
1725 "use utf8" or not is irrelevant; the UTF-8ness of $_ itself
1726 determines the behavior.
1727 Any "use utf8" or "no utf8" declarations within the string
1729 have no effect, and source filters are forbidden.
1730 ("unicode_strings", however, can appear within the string.)
1731 See also the "evalbytes" operator, which works properly
1732 with source filters.
1733 Variables defined outside the "eval" and used inside it
1735 retain their original UTF-8ness. Everything inside the
1736 string follows the normal rules for a Perl program with the
1737 given state of "use utf8".
1738 Outside the "unicode_eval" feature
1740 In this case, the behavior is problematic and is not so
1741 easily described. Here are two bugs that cannot easily be
1742 fixed without breaking existing programs:
1743 • It can lose track of whether something should be
1745 encoded as UTF-8 or not.
1746 • Source filters activated within "eval" leak out into
1748 whichever file scope is currently being compiled. To
1749 give an example with the CPAN module Semi::Semicolons:
1750 BEGIN { eval "use Semi::Semicolons; # not filtered" }
1752 # filtered here!
1753 "evalbytes" fixes that to work the way one would
1755 expect:
1756 use feature "evalbytes";
1758 BEGIN { evalbytes "use Semi::Semicolons; # filtered" }
1759 # not filtered
1760 Problems can arise if the string expands a scalar containing a
1762 floating point number. That scalar can expand to letters, such
1763 as "NaN" or "Infinity"; or, within the scope of a "use locale",
1764 the decimal point character may be something other than a dot
1765 (such as a comma). None of these are likely to parse as you
1766 are likely expecting.
1767 You should be especially careful to remember what's being
1769 looked at when:
1770 eval $x; # CASE 1
1772 eval "$x"; # CASE 2
1773 eval '$x'; # CASE 3
1775 eval { $x }; # CASE 4
1776 eval "\$$x++"; # CASE 5
1778 $$x++; # CASE 6
1779 Cases 1 and 2 above behave identically: they run the code
1781 contained in the variable $x. (Although case 2 has misleading
1782 double quotes making the reader wonder what else might be
1783 happening (nothing is).) Cases 3 and 4 likewise behave in the
1784 same way: they run the code '$x', which does nothing but return
1785 the value of $x. (Case 4 is preferred for purely visual
1786 reasons, but it also has the advantage of compiling at compile-
1787 time instead of at run-time.) Case 5 is a place where normally
1788 you would like to use double quotes, except that in this
1789 particular situation, you can just use symbolic references
1790 instead, as in case 6.
1791 An "eval ''" executed within a subroutine defined in the "DB"
1793 package doesn't see the usual surrounding lexical scope, but
1794 rather the scope of the first non-DB piece of code that called
1795 it. You don't normally need to worry about this unless you are
1796 writing a Perl debugger.
1797 The final semicolon, if any, may be omitted from the value of
1799 EXPR.
1800 Block eval
1802 If the code to be executed doesn't vary, you may use the eval-
1803 BLOCK form to trap run-time errors without incurring the
1804 penalty of recompiling each time. The error, if any, is still
1805 returned in $@. Examples:
1806 # make divide-by-zero nonfatal
1808 eval { $answer = $a / $b; }; warn $@ if $@;
1809 # same thing, but less efficient
1811 eval '$answer = $a / $b'; warn $@ if $@;
1812 # a compile-time error
1814 eval { $answer = }; # WRONG
1815 # a run-time error
1817 eval '$answer ='; # sets $@
1818 If you want to trap errors when loading an XS module, some
1820 problems with the binary interface (such as Perl version skew)
1821 may be fatal even with "eval" unless $ENV{PERL_DL_NONLAZY} is
1822 set. See perlrun.
1823 Using the "eval {}" form as an exception trap in libraries does
1825 have some issues. Due to the current arguably broken state of
1826 "__DIE__" hooks, you may wish not to trigger any "__DIE__"
1827 hooks that user code may have installed. You can use the
1828 "local $SIG{__DIE__}" construct for this purpose, as this
1829 example shows:
1830 # a private exception trap for divide-by-zero
1832 eval { local $SIG{'__DIE__'}; $answer = $a / $b; };
1833 warn $@ if $@;
1834 This is especially significant, given that "__DIE__" hooks can
1836 call "die" again, which has the effect of changing their error
1837 messages:
1838 # __DIE__ hooks may modify error messages
1840 {
1841 local $SIG{'__DIE__'} =
1842 sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
1843 eval { die "foo lives here" };
1844 print $@ if $@; # prints "bar lives here"
1845 }
1846 Because this promotes action at a distance, this
1848 counterintuitive behavior may be fixed in a future release.
1849 "eval BLOCK" does not count as a loop, so the loop control
1851 statements "next", "last", or "redo" cannot be used to leave or
1852 restart the block.
1853 The final semicolon, if any, may be omitted from within the
1855 BLOCK.
1856 evalbytes EXPR
1858 evalbytes
1859 This function is similar to a string eval, except it always parses
1860 its argument (or $_ if EXPR is omitted) as a string of independent
1861 bytes.
1862 If called when "use utf8" is in effect, the string will be assumed
1864 to be encoded in UTF-8, and "evalbytes" will make a temporary copy
1865 to work from, downgraded to non-UTF-8. If this is not possible
1866 (because one or more characters in it require UTF-8), the
1867 "evalbytes" will fail with the error stored in $@.
1868 Bytes that correspond to ASCII-range code points will have their
1870 normal meanings for operators in the string. The treatment of the
1871 other bytes depends on if the "'unicode_strings"" feature is in
1872 effect.
1873 Of course, variables that are UTF-8 and are referred to in the
1875 string retain that:
1876 my $a = "\x{100}";
1878 evalbytes 'print ord $a, "\n"';
1879 prints
1881 256
1883 and $@ is empty.
1885 Source filters activated within the evaluated code apply to the
1887 code itself.
1888 "evalbytes" is available starting in Perl v5.16. To access it, you
1890 must say "CORE::evalbytes", but you can omit the "CORE::" if the
1891 "evalbytes" feature is enabled. This is enabled automatically with
1892 a "use v5.16" (or higher) declaration in the current scope.
1893 exec LIST
1895 exec PROGRAM LIST
1896 The "exec" function executes a system command and never returns;
1897 use "system" instead of "exec" if you want it to return. It fails
1898 and returns false only if the command does not exist and it is
1899 executed directly instead of via your system's command shell (see
1900 below).
1901 Since it's a common mistake to use "exec" instead of "system", Perl
1903 warns you if "exec" is called in void context and if there is a
1904 following statement that isn't "die", "warn", or "exit" (if
1905 warnings are enabled--but you always do that, right?). If you
1906 really want to follow an "exec" with some other statement, you can
1907 use one of these styles to avoid the warning:
1908 exec ('foo') or print STDERR "couldn't exec foo: $!";
1910 { exec ('foo') }; print STDERR "couldn't exec foo: $!";
1911 If there is more than one argument in LIST, this calls execvp(3)
1913 with the arguments in LIST. If there is only one element in LIST,
1914 the argument is checked for shell metacharacters, and if there are
1915 any, the entire argument is passed to the system's command shell
1916 for parsing (this is "/bin/sh -c" on Unix platforms, but varies on
1917 other platforms). If there are no shell metacharacters in the
1918 argument, it is split into words and passed directly to "execvp",
1919 which is more efficient. Examples:
1920 exec '/bin/echo', 'Your arguments are: ', @ARGV;
1922 exec "sort $outfile | uniq";
1923 If you don't really want to execute the first argument, but want to
1925 lie to the program you are executing about its own name, you can
1926 specify the program you actually want to run as an "indirect
1927 object" (without a comma) in front of the LIST, as in "exec PROGRAM
1928 LIST". (This always forces interpretation of the LIST as a
1929 multivalued list, even if there is only a single scalar in the
1930 list.) Example:
1931 my $shell = '/bin/csh';
1933 exec $shell '-sh'; # pretend it's a login shell
1934 or, more directly,
1936 exec {'/bin/csh'} '-sh'; # pretend it's a login shell
1938 When the arguments get executed via the system shell, results are
1940 subject to its quirks and capabilities. See "`STRING`" in perlop
1941 for details.
1942 Using an indirect object with "exec" or "system" is also more
1944 secure. This usage (which also works fine with "system") forces
1945 interpretation of the arguments as a multivalued list, even if the
1946 list had just one argument. That way you're safe from the shell
1947 expanding wildcards or splitting up words with whitespace in them.
1948 my @args = ( "echo surprise" );
1950 exec @args; # subject to shell escapes
1952 # if @args == 1
1953 exec { $args[0] } @args; # safe even with one-arg list
1954 The first version, the one without the indirect object, ran the
1956 echo program, passing it "surprise" an argument. The second
1957 version didn't; it tried to run a program named "echo surprise",
1958 didn't find it, and set $? to a non-zero value indicating failure.
1959 On Windows, only the "exec PROGRAM LIST" indirect object syntax
1961 will reliably avoid using the shell; "exec LIST", even with more
1962 than one element, will fall back to the shell if the first spawn
1963 fails.
1964 Perl attempts to flush all files opened for output before the exec,
1966 but this may not be supported on some platforms (see perlport). To
1967 be safe, you may need to set $| ($AUTOFLUSH in English) or call the
1968 "autoflush" method of "IO::Handle" on any open handles to avoid
1969 lost output.
1970 Note that "exec" will not call your "END" blocks, nor will it
1972 invoke "DESTROY" methods on your objects.
1973 Portability issues: "exec" in perlport.
1975 exists EXPR
1977 Given an expression that specifies an element of a hash, returns
1978 true if the specified element in the hash has ever been
1979 initialized, even if the corresponding value is undefined.
1980 print "Exists\n" if exists $hash{$key};
1982 print "Defined\n" if defined $hash{$key};
1983 print "True\n" if $hash{$key};
1984 exists may also be called on array elements, but its behavior is
1986 much less obvious and is strongly tied to the use of "delete" on
1987 arrays.
1988 WARNING: Calling "exists" on array values is strongly discouraged.
1990 The notion of deleting or checking the existence of Perl array
1991 elements is not conceptually coherent, and can lead to surprising
1992 behavior.
1993 print "Exists\n" if exists $array[$index];
1995 print "Defined\n" if defined $array[$index];
1996 print "True\n" if $array[$index];
1997 A hash or array element can be true only if it's defined and
1999 defined only if it exists, but the reverse doesn't necessarily hold
2000 true.
2001 Given an expression that specifies the name of a subroutine,
2003 returns true if the specified subroutine has ever been declared,
2004 even if it is undefined. Mentioning a subroutine name for exists
2005 or defined does not count as declaring it. Note that a subroutine
2006 that does not exist may still be callable: its package may have an
2007 "AUTOLOAD" method that makes it spring into existence the first
2008 time that it is called; see perlsub.
2009 print "Exists\n" if exists &subroutine;
2011 print "Defined\n" if defined &subroutine;
2012 Note that the EXPR can be arbitrarily complicated as long as the
2014 final operation is a hash or array key lookup or subroutine name:
2015 if (exists $ref->{A}->{B}->{$key}) { }
2017 if (exists $hash{A}{B}{$key}) { }
2018 if (exists $ref->{A}->{B}->[$ix]) { }
2020 if (exists $hash{A}{B}[$ix]) { }
2021 if (exists &{$ref->{A}{B}{$key}}) { }
2023 Although the most deeply nested array or hash element will not
2025 spring into existence just because its existence was tested, any
2026 intervening ones will. Thus "$ref->{"A"}" and "$ref->{"A"}->{"B"}"
2027 will spring into existence due to the existence test for the $key
2028 element above. This happens anywhere the arrow operator is used,
2029 including even here:
2030 undef $ref;
2032 if (exists $ref->{"Some key"}) { }
2033 print $ref; # prints HASH(0x80d3d5c)
2034 Use of a subroutine call, rather than a subroutine name, as an
2036 argument to "exists" is an error.
2037 exists ⊂ # OK
2039 exists &sub(); # Error
2040 exit EXPR
2042 exit
2043 Evaluates EXPR and exits immediately with that value. Example:
2044 my $ans = <STDIN>;
2046 exit 0 if $ans =~ /^[Xx]/;
2047 See also "die". If EXPR is omitted, exits with 0 status. The only
2049 universally recognized values for EXPR are 0 for success and 1 for
2050 error; other values are subject to interpretation depending on the
2051 environment in which the Perl program is running. For example,
2052 exiting 69 (EX_UNAVAILABLE) from a sendmail incoming-mail filter
2053 will cause the mailer to return the item undelivered, but that's
2054 not true everywhere.
2055 Don't use "exit" to abort a subroutine if there's any chance that
2057 someone might want to trap whatever error happened. Use "die"
2058 instead, which can be trapped by an "eval".
2059 The "exit" function does not always exit immediately. It calls any
2061 defined "END" routines first, but these "END" routines may not
2062 themselves abort the exit. Likewise any object destructors that
2063 need to be called are called before the real exit. "END" routines
2064 and destructors can change the exit status by modifying $?. If
2065 this is a problem, you can call "POSIX::_exit($status)" to avoid
2066 "END" and destructor processing. See perlmod for details.
2067 Portability issues: "exit" in perlport.
2069 exp EXPR
2071 exp Returns e (the natural logarithm base) to the power of EXPR. If
2072 EXPR is omitted, gives "exp($_)".
2073 fc EXPR
2075 fc Returns the casefolded version of EXPR. This is the internal
2076 function implementing the "\F" escape in double-quoted strings.
2077 Casefolding is the process of mapping strings to a form where case
2079 differences are erased; comparing two strings in their casefolded
2080 form is effectively a way of asking if two strings are equal,
2081 regardless of case.
2082 Roughly, if you ever found yourself writing this
2084 lc($this) eq lc($that) # Wrong!
2086 # or
2087 uc($this) eq uc($that) # Also wrong!
2088 # or
2089 $this =~ /^\Q$that\E\z/i # Right!
2090 Now you can write
2092 fc($this) eq fc($that)
2094 And get the correct results.
2096 Perl only implements the full form of casefolding, but you can
2098 access the simple folds using "casefold()" in Unicode::UCD and
2099 "prop_invmap()" in Unicode::UCD. For further information on
2100 casefolding, refer to the Unicode Standard, specifically sections
2101 3.13 "Default Case Operations", 4.2 "Case-Normative", and 5.18
2102 "Case Mappings", available at
2103 <https://www.unicode.org/versions/latest/>, as well as the Case
2104 Charts available at <https://www.unicode.org/charts/case/>.
2105 If EXPR is omitted, uses $_.
2107 This function behaves the same way under various pragmas, such as
2109 within "use feature 'unicode_strings", as "lc" does, with the
2110 single exception of "fc" of LATIN CAPITAL LETTER SHARP S (U+1E9E)
2111 within the scope of "use locale". The foldcase of this character
2112 would normally be "ss", but as explained in the "lc" section, case
2113 changes that cross the 255/256 boundary are problematic under
2114 locales, and are hence prohibited. Therefore, this function under
2115 locale returns instead the string "\x{17F}\x{17F}", which is the
2116 LATIN SMALL LETTER LONG S. Since that character itself folds to
2117 "s", the string of two of them together should be equivalent to a
2118 single U+1E9E when foldcased.
2119 While the Unicode Standard defines two additional forms of
2121 casefolding, one for Turkic languages and one that never maps one
2122 character into multiple characters, these are not provided by the
2123 Perl core. However, the CPAN module "Unicode::Casing" may be used
2124 to provide an implementation.
2125 "fc" is available only if the "fc" feature is enabled or if it is
2127 prefixed with "CORE::". The "fc" feature is enabled automatically
2128 with a "use v5.16" (or higher) declaration in the current scope.
2129 fcntl FILEHANDLE,FUNCTION,SCALAR
2131 Implements the fcntl(2) function. You'll probably have to say
2132 use Fcntl;
2134 first to get the correct constant definitions. Argument processing
2136 and value returned work just like "ioctl" below. For example:
2137 use Fcntl;
2139 my $flags = fcntl($filehandle, F_GETFL, 0)
2140 or die "Can't fcntl F_GETFL: $!";
2141 You don't have to check for "defined" on the return from "fcntl".
2143 Like "ioctl", it maps a 0 return from the system call into "0 but
2144 true" in Perl. This string is true in boolean context and 0 in
2145 numeric context. It is also exempt from the normal "Argument "..."
2146 isn't numeric" warnings on improper numeric conversions.
2147 Note that "fcntl" raises an exception if used on a machine that
2149 doesn't implement fcntl(2). See the Fcntl module or your fcntl(2)
2150 manpage to learn what functions are available on your system.
2151 Here's an example of setting a filehandle named $REMOTE to be non-
2153 blocking at the system level. You'll have to negotiate $| on your
2154 own, though.
2155 use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
2157 my $flags = fcntl($REMOTE, F_GETFL, 0)
2159 or die "Can't get flags for the socket: $!\n";
2160 fcntl($REMOTE, F_SETFL, $flags | O_NONBLOCK)
2162 or die "Can't set flags for the socket: $!\n";
2163 Portability issues: "fcntl" in perlport.
2165 __FILE__
2167 A special token that returns the name of the file in which it
2168 occurs. It can be altered by the mechanism described at "Plain Old
2169 Comments (Not!)" in perlsyn.
2170 fileno FILEHANDLE
2172 fileno DIRHANDLE
2173 Returns the file descriptor for a filehandle or directory handle,
2174 or undefined if the filehandle is not open. If there is no real
2175 file descriptor at the OS level, as can happen with filehandles
2176 connected to memory objects via "open" with a reference for the
2177 third argument, -1 is returned.
2178 This is mainly useful for constructing bitmaps for "select" and
2180 low-level POSIX tty-handling operations. If FILEHANDLE is an
2181 expression, the value is taken as an indirect filehandle, generally
2182 its name.
2183 You can use this to find out whether two handles refer to the same
2185 underlying descriptor:
2186 if (fileno($this) != -1 && fileno($this) == fileno($that)) {
2188 print "\$this and \$that are dups\n";
2189 } elsif (fileno($this) != -1 && fileno($that) != -1) {
2190 print "\$this and \$that have different " .
2191 "underlying file descriptors\n";
2192 } else {
2193 print "At least one of \$this and \$that does " .
2194 "not have a real file descriptor\n";
2195 }
2196 The behavior of "fileno" on a directory handle depends on the
2198 operating system. On a system with dirfd(3) or similar, "fileno"
2199 on a directory handle returns the underlying file descriptor
2200 associated with the handle; on systems with no such support, it
2201 returns the undefined value, and sets $! (errno).
2202 flock FILEHANDLE,OPERATION
2204 Calls flock(2), or an emulation of it, on FILEHANDLE. Returns true
2205 for success, false on failure. Produces a fatal error if used on a
2206 machine that doesn't implement flock(2), fcntl(2) locking, or
2207 lockf(3). "flock" is Perl's portable file-locking interface,
2208 although it locks entire files only, not records.
2209 Two potentially non-obvious but traditional "flock" semantics are
2211 that it waits indefinitely until the lock is granted, and that its
2212 locks are merely advisory. Such discretionary locks are more
2213 flexible, but offer fewer guarantees. This means that programs
2214 that do not also use "flock" may modify files locked with "flock".
2215 See perlport, your port's specific documentation, and your system-
2216 specific local manpages for details. It's best to assume
2217 traditional behavior if you're writing portable programs. (But if
2218 you're not, you should as always feel perfectly free to write for
2219 your own system's idiosyncrasies (sometimes called "features").
2220 Slavish adherence to portability concerns shouldn't get in the way
2221 of your getting your job done.)
2222 OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined
2224 with LOCK_NB. These constants are traditionally valued 1, 2, 8 and
2225 4, but you can use the symbolic names if you import them from the
2226 Fcntl module, either individually, or as a group using the ":flock"
2227 tag. LOCK_SH requests a shared lock, LOCK_EX requests an exclusive
2228 lock, and LOCK_UN releases a previously requested lock. If LOCK_NB
2229 is bitwise-or'ed with LOCK_SH or LOCK_EX, then "flock" returns
2230 immediately rather than blocking waiting for the lock; check the
2231 return status to see if you got it.
2232 To avoid the possibility of miscoordination, Perl now flushes
2234 FILEHANDLE before locking or unlocking it.
2235 Note that the emulation built with lockf(3) doesn't provide shared
2237 locks, and it requires that FILEHANDLE be open with write intent.
2238 These are the semantics that lockf(3) implements. Most if not all
2239 systems implement lockf(3) in terms of fcntl(2) locking, though, so
2240 the differing semantics shouldn't bite too many people.
2241 Note that the fcntl(2) emulation of flock(3) requires that
2243 FILEHANDLE be open with read intent to use LOCK_SH and requires
2244 that it be open with write intent to use LOCK_EX.
2245 Note also that some versions of "flock" cannot lock things over the
2247 network; you would need to use the more system-specific "fcntl" for
2248 that. If you like you can force Perl to ignore your system's
2249 flock(2) function, and so provide its own fcntl(2)-based emulation,
2250 by passing the switch "-Ud_flock" to the Configure program when you
2251 configure and build a new Perl.
2252 Here's a mailbox appender for BSD systems.
2254 # import LOCK_* and SEEK_END constants
2256 use Fcntl qw(:flock SEEK_END);
2257 sub lock {
2259 my ($fh) = @_;
2260 flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n";
2261 # and, in case we're running on a very old UNIX
2262 # variant without the modern O_APPEND semantics...
2263 seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n";
2264 }
2265 sub unlock {
2267 my ($fh) = @_;
2268 flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n";
2269 }
2270 open(my $mbox, ">>", "/usr/spool/mail/$ENV{'USER'}")
2272 or die "Can't open mailbox: $!";
2273 lock($mbox);
2275 print $mbox $msg,"\n\n";
2276 unlock($mbox);
2277 On systems that support a real flock(2), locks are inherited across
2279 "fork" calls, whereas those that must resort to the more capricious
2280 fcntl(2) function lose their locks, making it seriously harder to
2281 write servers.
2282 See also DB_File for other "flock" examples.
2284 Portability issues: "flock" in perlport.
2286 fork
2288 Does a fork(2) system call to create a new process running the same
2289 program at the same point. It returns the child pid to the parent
2290 process, 0 to the child process, or "undef" if the fork is
2291 unsuccessful. File descriptors (and sometimes locks on those
2292 descriptors) are shared, while everything else is copied. On most
2293 systems supporting fork(2), great care has gone into making it
2294 extremely efficient (for example, using copy-on-write technology on
2295 data pages), making it the dominant paradigm for multitasking over
2296 the last few decades.
2297 Perl attempts to flush all files opened for output before forking
2299 the child process, but this may not be supported on some platforms
2300 (see perlport). To be safe, you may need to set $| ($AUTOFLUSH in
2301 English) or call the "autoflush" method of "IO::Handle" on any open
2302 handles to avoid duplicate output.
2303 If you "fork" without ever waiting on your children, you will
2305 accumulate zombies. On some systems, you can avoid this by setting
2306 $SIG{CHLD} to "IGNORE". See also perlipc for more examples of
2307 forking and reaping moribund children.
2308 Note that if your forked child inherits system file descriptors
2310 like STDIN and STDOUT that are actually connected by a pipe or
2311 socket, even if you exit, then the remote server (such as, say, a
2312 CGI script or a backgrounded job launched from a remote shell)
2313 won't think you're done. You should reopen those to /dev/null if
2314 it's any issue.
2315 On some platforms such as Windows, where the fork(2) system call is
2317 not available, Perl can be built to emulate "fork" in the Perl
2318 interpreter. The emulation is designed, at the level of the Perl
2319 program, to be as compatible as possible with the "Unix" fork(2).
2320 However it has limitations that have to be considered in code
2321 intended to be portable. See perlfork for more details.
2322 Portability issues: "fork" in perlport.
2324 format
2326 Declare a picture format for use by the "write" function. For
2327 example:
2328 format Something =
2330 Test: @<<<<<<<< @||||| @>>>>>
2331 $str, $%, '$' . int($num)
2332 .
2333 $str = "widget";
2335 $num = $cost/$quantity;
2336 $~ = 'Something';
2337 write;
2338 See perlform for many details and examples.
2340 formline PICTURE,LIST
2342 This is an internal function used by "format"s, though you may call
2343 it, too. It formats (see perlform) a list of values according to
2344 the contents of PICTURE, placing the output into the format output
2345 accumulator, $^A (or $ACCUMULATOR in English). Eventually, when a
2346 "write" is done, the contents of $^A are written to some
2347 filehandle. You could also read $^A and then set $^A back to "".
2348 Note that a format typically does one "formline" per line of form,
2349 but the "formline" function itself doesn't care how many newlines
2350 are embedded in the PICTURE. This means that the "~" and "~~"
2351 tokens treat the entire PICTURE as a single line. You may
2352 therefore need to use multiple formlines to implement a single
2353 record format, just like the "format" compiler.
2354 Be careful if you put double quotes around the picture, because an
2356 "@" character may be taken to mean the beginning of an array name.
2357 "formline" always returns true. See perlform for other examples.
2358 If you are trying to use this instead of "write" to capture the
2360 output, you may find it easier to open a filehandle to a scalar
2361 ("open my $fh, ">", \$output") and write to that instead.
2362 getc FILEHANDLE
2364 getc
2365 Returns the next character from the input file attached to
2366 FILEHANDLE, or the undefined value at end of file or if there was
2367 an error (in the latter case $! is set). If FILEHANDLE is omitted,
2368 reads from STDIN. This is not particularly efficient. However, it
2369 cannot be used by itself to fetch single characters without waiting
2370 for the user to hit enter. For that, try something more like:
2371 if ($BSD_STYLE) {
2373 system "stty cbreak </dev/tty >/dev/tty 2>&1";
2374 }
2375 else {
2376 system "stty", '-icanon', 'eol', "\001";
2377 }
2378 my $key = getc(STDIN);
2380 if ($BSD_STYLE) {
2382 system "stty -cbreak </dev/tty >/dev/tty 2>&1";
2383 }
2384 else {
2385 system 'stty', 'icanon', 'eol', '^@'; # ASCII NUL
2386 }
2387 print "\n";
2388 Determination of whether $BSD_STYLE should be set is left as an
2390 exercise to the reader.
2391 The "POSIX::getattr" function can do this more portably on systems
2393 purporting POSIX compliance. See also the "Term::ReadKey" module
2394 on CPAN.
2395 getlogin
2397 This implements the C library function of the same name, which on
2398 most systems returns the current login from /etc/utmp, if any. If
2399 it returns the empty string, use "getpwuid".
2400 my $login = getlogin || getpwuid($<) || "Kilroy";
2402 Do not consider "getlogin" for authentication: it is not as secure
2404 as "getpwuid".
2405 Portability issues: "getlogin" in perlport.
2407 getpeername SOCKET
2409 Returns the packed sockaddr address of the other end of the SOCKET
2410 connection.
2411 use Socket;
2413 my $hersockaddr = getpeername($sock);
2414 my ($port, $iaddr) = sockaddr_in($hersockaddr);
2415 my $herhostname = gethostbyaddr($iaddr, AF_INET);
2416 my $herstraddr = inet_ntoa($iaddr);
2417 getpgrp PID
2419 Returns the current process group for the specified PID. Use a PID
2420 of 0 to get the current process group for the current process.
2421 Will raise an exception if used on a machine that doesn't implement
2422 getpgrp(2). If PID is omitted, returns the process group of the
2423 current process. Note that the POSIX version of "getpgrp" does not
2424 accept a PID argument, so only "PID==0" is truly portable.
2425 Portability issues: "getpgrp" in perlport.
2427 getppid
2429 Returns the process id of the parent process.
2430 Note for Linux users: Between v5.8.1 and v5.16.0 Perl would work
2432 around non-POSIX thread semantics the minority of Linux systems
2433 (and Debian GNU/kFreeBSD systems) that used LinuxThreads, this
2434 emulation has since been removed. See the documentation for $$ for
2435 details.
2436 Portability issues: "getppid" in perlport.
2438 getpriority WHICH,WHO
2440 Returns the current priority for a process, a process group, or a
2441 user. (See getpriority(2).) Will raise a fatal exception if used
2442 on a machine that doesn't implement getpriority(2).
2443 "WHICH" can be any of "PRIO_PROCESS", "PRIO_PGRP" or "PRIO_USER"
2445 imported from "RESOURCE CONSTANTS" in POSIX.
2446 Portability issues: "getpriority" in perlport.
2448 getpwnam NAME
2450 getgrnam NAME
2451 gethostbyname NAME
2452 getnetbyname NAME
2453 getprotobyname NAME
2454 getpwuid UID
2455 getgrgid GID
2456 getservbyname NAME,PROTO
2457 gethostbyaddr ADDR,ADDRTYPE
2458 getnetbyaddr ADDR,ADDRTYPE
2459 getprotobynumber NUMBER
2460 getservbyport PORT,PROTO
2461 getpwent
2462 getgrent
2463 gethostent
2464 getnetent
2465 getprotoent
2466 getservent
2467 setpwent
2468 setgrent
2469 sethostent STAYOPEN
2470 setnetent STAYOPEN
2471 setprotoent STAYOPEN
2472 setservent STAYOPEN
2473 endpwent
2474 endgrent
2475 endhostent
2476 endnetent
2477 endprotoent
2478 endservent
2479 These routines are the same as their counterparts in the system C
2480 library. In list context, the return values from the various get
2481 routines are as follows:
2482 # 0 1 2 3 4
2484 my ( $name, $passwd, $gid, $members ) = getgr*
2485 my ( $name, $aliases, $addrtype, $net ) = getnet*
2486 my ( $name, $aliases, $port, $proto ) = getserv*
2487 my ( $name, $aliases, $proto ) = getproto*
2488 my ( $name, $aliases, $addrtype, $length, @addrs ) = gethost*
2489 my ( $name, $passwd, $uid, $gid, $quota,
2490 $comment, $gcos, $dir, $shell, $expire ) = getpw*
2491 # 5 6 7 8 9
2492 (If the entry doesn't exist, the return value is a single
2494 meaningless true value.)
2495 The exact meaning of the $gcos field varies but it usually contains
2497 the real name of the user (as opposed to the login name) and other
2498 information pertaining to the user. Beware, however, that in many
2499 system users are able to change this information and therefore it
2500 cannot be trusted and therefore the $gcos is tainted (see perlsec).
2501 The $passwd and $shell, user's encrypted password and login shell,
2502 are also tainted, for the same reason.
2503 In scalar context, you get the name, unless the function was a
2505 lookup by name, in which case you get the other thing, whatever it
2506 is. (If the entry doesn't exist you get the undefined value.) For
2507 example:
2508 my $uid = getpwnam($name);
2510 my $name = getpwuid($num);
2511 my $name = getpwent();
2512 my $gid = getgrnam($name);
2513 my $name = getgrgid($num);
2514 my $name = getgrent();
2515 # etc.
2516 In getpw*() the fields $quota, $comment, and $expire are special in
2518 that they are unsupported on many systems. If the $quota is
2519 unsupported, it is an empty scalar. If it is supported, it usually
2520 encodes the disk quota. If the $comment field is unsupported, it
2521 is an empty scalar. If it is supported it usually encodes some
2522 administrative comment about the user. In some systems the $quota
2523 field may be $change or $age, fields that have to do with password
2524 aging. In some systems the $comment field may be $class. The
2525 $expire field, if present, encodes the expiration period of the
2526 account or the password. For the availability and the exact
2527 meaning of these fields in your system, please consult getpwnam(3)
2528 and your system's pwd.h file. You can also find out from within
2529 Perl what your $quota and $comment fields mean and whether you have
2530 the $expire field by using the "Config" module and the values
2531 "d_pwquota", "d_pwage", "d_pwchange", "d_pwcomment", and
2532 "d_pwexpire". Shadow password files are supported only if your
2533 vendor has implemented them in the intuitive fashion that calling
2534 the regular C library routines gets the shadow versions if you're
2535 running under privilege or if there exists the shadow(3) functions
2536 as found in System V (this includes Solaris and Linux). Those
2537 systems that implement a proprietary shadow password facility are
2538 unlikely to be supported.
2539 The $members value returned by getgr*() is a space-separated list
2541 of the login names of the members of the group.
2542 For the gethost*() functions, if the "h_errno" variable is
2544 supported in C, it will be returned to you via $? if the function
2545 call fails. The @addrs value returned by a successful call is a
2546 list of raw addresses returned by the corresponding library call.
2547 In the Internet domain, each address is four bytes long; you can
2548 unpack it by saying something like:
2549 my ($w,$x,$y,$z) = unpack('W4',$addr[0]);
2551 The Socket library makes this slightly easier:
2553 use Socket;
2555 my $iaddr = inet_aton("127.1"); # or whatever address
2556 my $name = gethostbyaddr($iaddr, AF_INET);
2557 # or going the other way
2559 my $straddr = inet_ntoa($iaddr);
2560 In the opposite way, to resolve a hostname to the IP address you
2562 can write this:
2563 use Socket;
2565 my $packed_ip = gethostbyname("www.perl.org");
2566 my $ip_address;
2567 if (defined $packed_ip) {
2568 $ip_address = inet_ntoa($packed_ip);
2569 }
2570 Make sure "gethostbyname" is called in SCALAR context and that its
2572 return value is checked for definedness.
2573 The "getprotobynumber" function, even though it only takes one
2575 argument, has the precedence of a list operator, so beware:
2576 getprotobynumber $number eq 'icmp' # WRONG
2578 getprotobynumber($number eq 'icmp') # actually means this
2579 getprotobynumber($number) eq 'icmp' # better this way
2580 If you get tired of remembering which element of the return list
2582 contains which return value, by-name interfaces are provided in
2583 standard modules: "File::stat", "Net::hostent", "Net::netent",
2584 "Net::protoent", "Net::servent", "Time::gmtime", "Time::localtime",
2585 and "User::grent". These override the normal built-ins, supplying
2586 versions that return objects with the appropriate names for each
2587 field. For example:
2588 use File::stat;
2590 use User::pwent;
2591 my $is_his = (stat($filename)->uid == pwent($whoever)->uid);
2592 Even though it looks as though they're the same method calls (uid),
2594 they aren't, because a "File::stat" object is different from a
2595 "User::pwent" object.
2596 Many of these functions are not safe in a multi-threaded
2598 environment where more than one thread can be using them. In
2599 particular, functions like "getpwent()" iterate per-process and not
2600 per-thread, so if two threads are simultaneously iterating, neither
2601 will get all the records.
2602 Some systems have thread-safe versions of some of the functions,
2604 such as "getpwnam_r()" instead of "getpwnam()". There, Perl
2605 automatically and invisibly substitutes the thread-safe version,
2606 without notice. This means that code that safely runs on some
2607 systems can fail on others that lack the thread-safe versions.
2608 Portability issues: "getpwnam" in perlport to "endservent" in
2610 perlport.
2611 getsockname SOCKET
2613 Returns the packed sockaddr address of this end of the SOCKET
2614 connection, in case you don't know the address because you have
2615 several different IPs that the connection might have come in on.
2616 use Socket;
2618 my $mysockaddr = getsockname($sock);
2619 my ($port, $myaddr) = sockaddr_in($mysockaddr);
2620 printf "Connect to %s [%s]\n",
2621 scalar gethostbyaddr($myaddr, AF_INET),
2622 inet_ntoa($myaddr);
2623 getsockopt SOCKET,LEVEL,OPTNAME
2625 Queries the option named OPTNAME associated with SOCKET at a given
2626 LEVEL. Options may exist at multiple protocol levels depending on
2627 the socket type, but at least the uppermost socket level SOL_SOCKET
2628 (defined in the "Socket" module) will exist. To query options at
2629 another level the protocol number of the appropriate protocol
2630 controlling the option should be supplied. For example, to
2631 indicate that an option is to be interpreted by the TCP protocol,
2632 LEVEL should be set to the protocol number of TCP, which you can
2633 get using "getprotobyname".
2634 The function returns a packed string representing the requested
2636 socket option, or "undef" on error, with the reason for the error
2637 placed in $!. Just what is in the packed string depends on LEVEL
2638 and OPTNAME; consult getsockopt(2) for details. A common case is
2639 that the option is an integer, in which case the result is a packed
2640 integer, which you can decode using "unpack" with the "i" (or "I")
2641 format.
2642 Here's an example to test whether Nagle's algorithm is enabled on a
2644 socket:
2645 use Socket qw(:all);
2647 defined(my $tcp = getprotobyname("tcp"))
2649 or die "Could not determine the protocol number for tcp";
2650 # my $tcp = IPPROTO_TCP; # Alternative
2651 my $packed = getsockopt($socket, $tcp, TCP_NODELAY)
2652 or die "getsockopt TCP_NODELAY: $!";
2653 my $nodelay = unpack("I", $packed);
2654 print "Nagle's algorithm is turned ",
2655 $nodelay ? "off\n" : "on\n";
2656 Portability issues: "getsockopt" in perlport.
2658 glob EXPR
2660 glob
2661 In list context, returns a (possibly empty) list of filename
2662 expansions on the value of EXPR such as the standard Unix shell
2663 /bin/csh would do. In scalar context, glob iterates through such
2664 filename expansions, returning undef when the list is exhausted.
2665 This is the internal function implementing the "<*.c>" operator,
2666 but you can use it directly. If EXPR is omitted, $_ is used. The
2667 "<*.c>" operator is discussed in more detail in "I/O Operators" in
2668 perlop.
2669 Note that "glob" splits its arguments on whitespace and treats each
2671 segment as separate pattern. As such, "glob("*.c *.h")" matches
2672 all files with a .c or .h extension. The expression "glob(".* *")"
2673 matches all files in the current working directory. If you want to
2674 glob filenames that might contain whitespace, you'll have to use
2675 extra quotes around the spacey filename to protect it. For
2676 example, to glob filenames that have an "e" followed by a space
2677 followed by an "f", use one of:
2678 my @spacies = <"*e f*">;
2680 my @spacies = glob '"*e f*"';
2681 my @spacies = glob q("*e f*");
2682 If you had to get a variable through, you could do this:
2684 my @spacies = glob "'*${var}e f*'";
2686 my @spacies = glob qq("*${var}e f*");
2687 If non-empty braces are the only wildcard characters used in the
2689 "glob", no filenames are matched, but potentially many strings are
2690 returned. For example, this produces nine strings, one for each
2691 pairing of fruits and colors:
2692 my @many = glob "{apple,tomato,cherry}={green,yellow,red}";
2694 This operator is implemented using the standard "File::Glob"
2696 extension. See File::Glob for details, including "bsd_glob", which
2697 does not treat whitespace as a pattern separator.
2698 If a "glob" expression is used as the condition of a "while" or
2700 "for" loop, then it will be implicitly assigned to $_. If either a
2701 "glob" expression or an explicit assignment of a "glob" expression
2702 to a scalar is used as a "while"/"for" condition, then the
2703 condition actually tests for definedness of the expression's value,
2704 not for its regular truth value.
2705 Portability issues: "glob" in perlport.
2707 gmtime EXPR
2709 gmtime
2710 Works just like "localtime", but the returned values are localized
2711 for the standard Greenwich time zone.
2712 Note: When called in list context, $isdst, the last value returned
2714 by gmtime, is always 0. There is no Daylight Saving Time in GMT.
2715 Portability issues: "gmtime" in perlport.
2717 goto LABEL
2719 goto EXPR
2720 goto &NAME
2721 The "goto LABEL" form finds the statement labeled with LABEL and
2722 resumes execution there. It can't be used to get out of a block or
2723 subroutine given to "sort". It can be used to go almost anywhere
2724 else within the dynamic scope, including out of subroutines, but
2725 it's usually better to use some other construct such as "last" or
2726 "die". The author of Perl has never felt the need to use this form
2727 of "goto" (in Perl, that is; C is another matter). (The difference
2728 is that C does not offer named loops combined with loop control.
2729 Perl does, and this replaces most structured uses of "goto" in
2730 other languages.)
2731 The "goto EXPR" form expects to evaluate "EXPR" to a code reference
2733 or a label name. If it evaluates to a code reference, it will be
2734 handled like "goto &NAME", below. This is especially useful for
2735 implementing tail recursion via "goto __SUB__".
2736 If the expression evaluates to a label name, its scope will be
2738 resolved dynamically. This allows for computed "goto"s per
2739 FORTRAN, but isn't necessarily recommended if you're optimizing for
2740 maintainability:
2741 goto ("FOO", "BAR", "GLARCH")[$i];
2743 As shown in this example, "goto EXPR" is exempt from the "looks
2745 like a function" rule. A pair of parentheses following it does not
2746 (necessarily) delimit its argument. "goto("NE")."XT"" is
2747 equivalent to "goto NEXT". Also, unlike most named operators, this
2748 has the same precedence as assignment.
2749 Use of "goto LABEL" or "goto EXPR" to jump into a construct is
2751 deprecated and will issue a warning. Even then, it may not be used
2752 to go into any construct that requires initialization, such as a
2753 subroutine, a "foreach" loop, or a "given" block. In general, it
2754 may not be used to jump into the parameter of a binary or list
2755 operator, but it may be used to jump into the first parameter of a
2756 binary operator. (The "=" assignment operator's "first" operand is
2757 its right-hand operand.) It also can't be used to go into a
2758 construct that is optimized away.
2759 The "goto &NAME" form is quite different from the other forms of
2761 "goto". In fact, it isn't a goto in the normal sense at all, and
2762 doesn't have the stigma associated with other gotos. Instead, it
2763 exits the current subroutine (losing any changes set by "local")
2764 and immediately calls in its place the named subroutine using the
2765 current value of @_. This is used by "AUTOLOAD" subroutines that
2766 wish to load another subroutine and then pretend that the other
2767 subroutine had been called in the first place (except that any
2768 modifications to @_ in the current subroutine are propagated to the
2769 other subroutine.) After the "goto", not even "caller" will be able
2770 to tell that this routine was called first.
2771 NAME needn't be the name of a subroutine; it can be a scalar
2773 variable containing a code reference or a block that evaluates to a
2774 code reference.
2775 grep BLOCK LIST
2777 grep EXPR,LIST
2778 This is similar in spirit to, but not the same as, grep(1) and its
2779 relatives. In particular, it is not limited to using regular
2780 expressions.
2781 Evaluates the BLOCK or EXPR for each element of LIST (locally
2783 setting $_ to each element) and returns the list value consisting
2784 of those elements for which the expression evaluated to true. In
2785 scalar context, returns the number of times the expression was
2786 true.
2787 my @foo = grep(!/^#/, @bar); # weed out comments
2789 or equivalently,
2791 my @foo = grep {!/^#/} @bar; # weed out comments
2793 Note that $_ is an alias to the list value, so it can be used to
2795 modify the elements of the LIST. While this is useful and
2796 supported, it can cause bizarre results if the elements of LIST are
2797 not variables. Similarly, grep returns aliases into the original
2798 list, much as a for loop's index variable aliases the list
2799 elements. That is, modifying an element of a list returned by grep
2800 (for example, in a "foreach", "map" or another "grep") actually
2801 modifies the element in the original list. This is usually
2802 something to be avoided when writing clear code.
2803 See also "map" for a list composed of the results of the BLOCK or
2805 EXPR.
2806 hex EXPR
2808 hex Interprets EXPR as a hex string and returns the corresponding
2809 numeric value. If EXPR is omitted, uses $_.
2810 print hex '0xAf'; # prints '175'
2812 print hex 'aF'; # same
2813 $valid_input =~ /\A(?:0?[xX])?(?:_?[0-9a-fA-F])*\z/
2814 A hex string consists of hex digits and an optional "0x" or "x"
2816 prefix. Each hex digit may be preceded by a single underscore,
2817 which will be ignored. Any other character triggers a warning and
2818 causes the rest of the string to be ignored (even leading
2819 whitespace, unlike "oct"). Only integers can be represented, and
2820 integer overflow triggers a warning.
2821 To convert strings that might start with any of 0, "0x", or "0b",
2823 see "oct". To present something as hex, look into "printf",
2824 "sprintf", and "unpack".
2825 import LIST
2827 There is no builtin "import" function. It is just an ordinary
2828 method (subroutine) defined (or inherited) by modules that wish to
2829 export names to another module. The "use" function calls the
2830 "import" method for the package used. See also "use", perlmod, and
2831 Exporter.
2832 index STR,SUBSTR,POSITION
2834 index STR,SUBSTR
2835 The index function searches for one string within another, but
2836 without the wildcard-like behavior of a full regular-expression
2837 pattern match. It returns the position of the first occurrence of
2838 SUBSTR in STR at or after POSITION. If POSITION is omitted, starts
2839 searching from the beginning of the string. POSITION before the
2840 beginning of the string or after its end is treated as if it were
2841 the beginning or the end, respectively. POSITION and the return
2842 value are based at zero. If the substring is not found, "index"
2843 returns -1.
2844 Find characters or strings:
2846 index("Perl is great", "P"); # Returns 0
2848 index("Perl is great", "g"); # Returns 8
2849 index("Perl is great", "great"); # Also returns 8
2850 Attempting to find something not there:
2852 index("Perl is great", "Z"); # Returns -1 (not found)
2854 Using an offset to find the second occurrence:
2856 index("Perl is great", "e", 5); # Returns 10
2858 int EXPR
2860 int Returns the integer portion of EXPR. If EXPR is omitted, uses $_.
2861 You should not use this function for rounding: one because it
2862 truncates towards 0, and two because machine representations of
2863 floating-point numbers can sometimes produce counterintuitive
2864 results. For example, "int(-6.725/0.025)" produces -268 rather
2865 than the correct -269; that's because it's really more like
2866 -268.99999999999994315658 instead. Usually, the "sprintf",
2867 "printf", or the "POSIX::floor" and "POSIX::ceil" functions will
2868 serve you better than will "int".
2869 ioctl FILEHANDLE,FUNCTION,SCALAR
2871 Implements the ioctl(2) function. You'll probably first have to
2872 say
2873 require "sys/ioctl.ph"; # probably in
2875 # $Config{archlib}/sys/ioctl.ph
2876 to get the correct function definitions. If sys/ioctl.ph doesn't
2878 exist or doesn't have the correct definitions you'll have to roll
2879 your own, based on your C header files such as <sys/ioctl.h>.
2880 (There is a Perl script called h2ph that comes with the Perl kit
2881 that may help you in this, but it's nontrivial.) SCALAR will be
2882 read and/or written depending on the FUNCTION; a C pointer to the
2883 string value of SCALAR will be passed as the third argument of the
2884 actual "ioctl" call. (If SCALAR has no string value but does have
2885 a numeric value, that value will be passed rather than a pointer to
2886 the string value. To guarantee this to be true, add a 0 to the
2887 scalar before using it.) The "pack" and "unpack" functions may be
2888 needed to manipulate the values of structures used by "ioctl".
2889 The return value of "ioctl" (and "fcntl") is as follows:
2891 if OS returns: then Perl returns:
2893 -1 undefined value
2894 0 string "0 but true"
2895 anything else that number
2896 Thus Perl returns true on success and false on failure, yet you can
2898 still easily determine the actual value returned by the operating
2899 system:
2900 my $retval = ioctl(...) || -1;
2902 printf "System returned %d\n", $retval;
2903 The special string "0 but true" is exempt from "Argument "..."
2905 isn't numeric" warnings on improper numeric conversions.
2906 Portability issues: "ioctl" in perlport.
2908 join EXPR,LIST
2910 Joins the separate strings of LIST into a single string with fields
2911 separated by the value of EXPR, and returns that new string.
2912 Example:
2913 my $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
2915 Beware that unlike "split", "join" doesn't take a pattern as its
2917 first argument. Compare "split".
2918 keys HASH
2920 keys ARRAY
2921 Called in list context, returns a list consisting of all the keys
2922 of the named hash, or in Perl 5.12 or later only, the indices of an
2923 array. Perl releases prior to 5.12 will produce a syntax error if
2924 you try to use an array argument. In scalar context, returns the
2925 number of keys or indices.
2926 Hash entries are returned in an apparently random order. The
2928 actual random order is specific to a given hash; the exact same
2929 series of operations on two hashes may result in a different order
2930 for each hash. Any insertion into the hash may change the order,
2931 as will any deletion, with the exception that the most recent key
2932 returned by "each" or "keys" may be deleted without changing the
2933 order. So long as a given hash is unmodified you may rely on
2934 "keys", "values" and "each" to repeatedly return the same order as
2935 each other. See "Algorithmic Complexity Attacks" in perlsec for
2936 details on why hash order is randomized. Aside from the guarantees
2937 provided here the exact details of Perl's hash algorithm and the
2938 hash traversal order are subject to change in any release of Perl.
2939 Tied hashes may behave differently to Perl's hashes with respect to
2940 changes in order on insertion and deletion of items.
2941 As a side effect, calling "keys" resets the internal iterator of
2943 the HASH or ARRAY (see "each") before yielding the keys. In
2944 particular, calling "keys" in void context resets the iterator with
2945 no other overhead.
2946 Here is yet another way to print your environment:
2948 my @keys = keys %ENV;
2950 my @values = values %ENV;
2951 while (@keys) {
2952 print pop(@keys), '=', pop(@values), "\n";
2953 }
2954 or how about sorted by key:
2956 foreach my $key (sort(keys %ENV)) {
2958 print $key, '=', $ENV{$key}, "\n";
2959 }
2960 The returned values are copies of the original keys in the hash, so
2962 modifying them will not affect the original hash. Compare
2963 "values".
2964 To sort a hash by value, you'll need to use a "sort" function.
2966 Here's a descending numeric sort of a hash by its values:
2967 foreach my $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
2969 printf "%4d %s\n", $hash{$key}, $key;
2970 }
2971 Used as an lvalue, "keys" allows you to increase the number of hash
2973 buckets allocated for the given hash. This can gain you a measure
2974 of efficiency if you know the hash is going to get big. (This is
2975 similar to pre-extending an array by assigning a larger number to
2976 $#array.) If you say
2977 keys %hash = 200;
2979 then %hash will have at least 200 buckets allocated for it--256 of
2981 them, in fact, since it rounds up to the next power of two. These
2982 buckets will be retained even if you do "%hash = ()", use "undef
2983 %hash" if you want to free the storage while %hash is still in
2984 scope. You can't shrink the number of buckets allocated for the
2985 hash using "keys" in this way (but you needn't worry about doing
2986 this by accident, as trying has no effect). "keys @array" in an
2987 lvalue context is a syntax error.
2988 Starting with Perl 5.14, an experimental feature allowed "keys" to
2990 take a scalar expression. This experiment has been deemed
2991 unsuccessful, and was removed as of Perl 5.24.
2992 To avoid confusing would-be users of your code who are running
2994 earlier versions of Perl with mysterious syntax errors, put this
2995 sort of thing at the top of your file to signal that your code will
2996 work only on Perls of a recent vintage:
2997 use 5.012; # so keys/values/each work on arrays
2999 See also "each", "values", and "sort".
3001 kill SIGNAL, LIST
3003 kill SIGNAL
3004 Sends a signal to a list of processes. Returns the number of
3005 arguments that were successfully used to signal (which is not
3006 necessarily the same as the number of processes actually killed,
3007 e.g. where a process group is killed).
3008 my $cnt = kill 'HUP', $child1, $child2;
3010 kill 'KILL', @goners;
3011 SIGNAL may be either a signal name (a string) or a signal number.
3013 A signal name may start with a "SIG" prefix, thus "FOO" and
3014 "SIGFOO" refer to the same signal. The string form of SIGNAL is
3015 recommended for portability because the same signal may have
3016 different numbers in different operating systems.
3017 A list of signal names supported by the current platform can be
3019 found in $Config{sig_name}, which is provided by the "Config"
3020 module. See Config for more details.
3021 A negative signal name is the same as a negative signal number,
3023 killing process groups instead of processes. For example, "kill
3024 '-KILL', $pgrp" and "kill -9, $pgrp" will send "SIGKILL" to the
3025 entire process group specified. That means you usually want to use
3026 positive not negative signals.
3027 If SIGNAL is either the number 0 or the string "ZERO" (or
3029 "SIGZERO"), no signal is sent to the process, but "kill" checks
3030 whether it's possible to send a signal to it (that means, to be
3031 brief, that the process is owned by the same user, or we are the
3032 super-user). This is useful to check that a child process is still
3033 alive (even if only as a zombie) and hasn't changed its UID. See
3034 perlport for notes on the portability of this construct.
3035 The behavior of kill when a PROCESS number is zero or negative
3037 depends on the operating system. For example, on POSIX-conforming
3038 systems, zero will signal the current process group, -1 will signal
3039 all processes, and any other negative PROCESS number will act as a
3040 negative signal number and kill the entire process group specified.
3041 If both the SIGNAL and the PROCESS are negative, the results are
3043 undefined. A warning may be produced in a future version.
3044 See "Signals" in perlipc for more details.
3046 On some platforms such as Windows where the fork(2) system call is
3048 not available, Perl can be built to emulate "fork" at the
3049 interpreter level. This emulation has limitations related to kill
3050 that have to be considered, for code running on Windows and in code
3051 intended to be portable.
3052 See perlfork for more details.
3054 If there is no LIST of processes, no signal is sent, and the return
3056 value is 0. This form is sometimes used, however, because it
3057 causes tainting checks to be run. But see "Laundering and
3058 Detecting Tainted Data" in perlsec.
3059 Portability issues: "kill" in perlport.
3061 last LABEL
3063 last EXPR
3064 last
3065 The "last" command is like the "break" statement in C (as used in
3066 loops); it immediately exits the loop in question. If the LABEL is
3067 omitted, the command refers to the innermost enclosing loop. The
3068 "last EXPR" form, available starting in Perl 5.18.0, allows a label
3069 name to be computed at run time, and is otherwise identical to
3070 "last LABEL". The "continue" block, if any, is not executed:
3071 LINE: while (<STDIN>) {
3073 last LINE if /^$/; # exit when done with header
3074 #...
3075 }
3076 "last" cannot return a value from a block that typically returns a
3078 value, such as "eval {}", "sub {}", or "do {}". It will perform its
3079 flow control behavior, which precludes any return value. It should
3080 not be used to exit a "grep" or "map" operation.
3081 Note that a block by itself is semantically identical to a loop
3083 that executes once. Thus "last" can be used to effect an early
3084 exit out of such a block.
3085 See also "continue" for an illustration of how "last", "next", and
3087 "redo" work.
3088 Unlike most named operators, this has the same precedence as
3090 assignment. It is also exempt from the looks-like-a-function rule,
3091 so "last ("foo")."bar"" will cause "bar" to be part of the argument
3092 to "last".
3093 lc EXPR
3095 lc Returns a lowercased version of EXPR. This is the internal
3096 function implementing the "\L" escape in double-quoted strings.
3097 If EXPR is omitted, uses $_.
3099 What gets returned depends on several factors:
3101 If "use bytes" is in effect:
3103 The results follow ASCII rules. Only the characters "A-Z"
3104 change, to "a-z" respectively.
3105 Otherwise, if "use locale" for "LC_CTYPE" is in effect:
3107 Respects current "LC_CTYPE" locale for code points < 256; and
3108 uses Unicode rules for the remaining code points (this last can
3109 only happen if the UTF8 flag is also set). See perllocale.
3110 Starting in v5.20, Perl uses full Unicode rules if the locale
3112 is UTF-8. Otherwise, there is a deficiency in this scheme,
3113 which is that case changes that cross the 255/256 boundary are
3114 not well-defined. For example, the lower case of LATIN CAPITAL
3115 LETTER SHARP S (U+1E9E) in Unicode rules is U+00DF (on ASCII
3116 platforms). But under "use locale" (prior to v5.20 or not a
3117 UTF-8 locale), the lower case of U+1E9E is itself, because 0xDF
3118 may not be LATIN SMALL LETTER SHARP S in the current locale,
3119 and Perl has no way of knowing if that character even exists in
3120 the locale, much less what code point it is. Perl returns a
3121 result that is above 255 (almost always the input character
3122 unchanged), for all instances (and there aren't many) where the
3123 255/256 boundary would otherwise be crossed; and starting in
3124 v5.22, it raises a locale warning.
3125 Otherwise, If EXPR has the UTF8 flag set:
3127 Unicode rules are used for the case change.
3128 Otherwise, if "use feature 'unicode_strings'" or "use locale
3130 ':not_characters'" is in effect:
3131 Unicode rules are used for the case change.
3132 Otherwise:
3134 ASCII rules are used for the case change. The lowercase of any
3135 character outside the ASCII range is the character itself.
3136 lcfirst EXPR
3138 lcfirst
3139 Returns the value of EXPR with the first character lowercased.
3140 This is the internal function implementing the "\l" escape in
3141 double-quoted strings.
3142 If EXPR is omitted, uses $_.
3144 This function behaves the same way under various pragmas, such as
3146 in a locale, as "lc" does.
3147 length EXPR
3149 length
3150 Returns the length in characters of the value of EXPR. If EXPR is
3151 omitted, returns the length of $_. If EXPR is undefined, returns
3152 "undef".
3153 This function cannot be used on an entire array or hash to find out
3155 how many elements these have. For that, use "scalar @array" and
3156 "scalar keys %hash", respectively.
3157 Like all Perl character operations, "length" normally deals in
3159 logical characters, not physical bytes. For how many bytes a
3160 string encoded as UTF-8 would take up, use
3161 "length(Encode::encode('UTF-8', EXPR))" (you'll have to "use
3162 Encode" first). See Encode and perlunicode.
3163 __LINE__
3165 A special token that compiles to the current line number. It can
3166 be altered by the mechanism described at "Plain Old Comments
3167 (Not!)" in perlsyn.
3168 link OLDFILE,NEWFILE
3170 Creates a new filename linked to the old filename. Returns true
3171 for success, false otherwise.
3172 Portability issues: "link" in perlport.
3174 listen SOCKET,QUEUESIZE
3176 Does the same thing that the listen(2) system call does. Returns
3177 true if it succeeded, false otherwise. See the example in
3178 "Sockets: Client/Server Communication" in perlipc.
3179 local EXPR
3181 You really probably want to be using "my" instead, because "local"
3182 isn't what most people think of as "local". See "Private Variables
3183 via my()" in perlsub for details.
3184 A local modifies the listed variables to be local to the enclosing
3186 block, file, or eval. If more than one value is listed, the list
3187 must be placed in parentheses. See "Temporary Values via local()"
3188 in perlsub for details, including issues with tied arrays and
3189 hashes.
3190 The "delete local EXPR" construct can also be used to localize the
3192 deletion of array/hash elements to the current block. See
3193 "Localized deletion of elements of composite types" in perlsub.
3194 localtime EXPR
3196 localtime
3197 Converts a time as returned by the time function to a 9-element
3198 list with the time analyzed for the local time zone. Typically
3199 used as follows:
3200 # 0 1 2 3 4 5 6 7 8
3202 my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
3203 localtime(time);
3204 All list elements are numeric and come straight out of the C
3206 `struct tm'. $sec, $min, and $hour are the seconds, minutes, and
3207 hours of the specified time.
3208 $mday is the day of the month and $mon the month in the range
3210 0..11, with 0 indicating January and 11 indicating December. This
3211 makes it easy to get a month name from a list:
3212 my @abbr = qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec);
3214 print "$abbr[$mon] $mday";
3215 # $mon=9, $mday=18 gives "Oct 18"
3216 $year contains the number of years since 1900. To get a 4-digit
3218 year write:
3219 $year += 1900;
3221 To get the last two digits of the year (e.g., "01" in 2001) do:
3223 $year = sprintf("%02d", $year % 100);
3225 $wday is the day of the week, with 0 indicating Sunday and 3
3227 indicating Wednesday. $yday is the day of the year, in the range
3228 0..364 (or 0..365 in leap years.)
3229 $isdst is true if the specified time occurs when Daylight Saving
3231 Time is in effect, false otherwise.
3232 If EXPR is omitted, "localtime" uses the current time (as returned
3234 by "time").
3235 In scalar context, "localtime" returns the ctime(3) value:
3237 my $now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
3239 This scalar value is always in English, and is not locale-
3241 dependent. To get similar but locale-dependent date strings, try
3242 for example:
3243 use POSIX qw(strftime);
3245 my $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
3246 # or for GMT formatted appropriately for your locale:
3247 my $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
3248 C$now_string> will be formatted according to the current LC_TIME
3250 locale the program or thread is running in. See perllocale for how
3251 to set up and change that locale. Note that %a and %b, the short
3252 forms of the day of the week and the month of the year, may not
3253 necessarily be three characters wide.
3254 The Time::gmtime and Time::localtime modules provide a convenient,
3256 by-name access mechanism to the "gmtime" and "localtime" functions,
3257 respectively.
3258 For a comprehensive date and time representation look at the
3260 DateTime module on CPAN.
3261 For GMT instead of local time use the "gmtime" builtin.
3263 See also the "Time::Local" module (for converting seconds, minutes,
3265 hours, and such back to the integer value returned by "time"), and
3266 the POSIX module's "mktime" function.
3267 Portability issues: "localtime" in perlport.
3269 lock THING
3271 This function places an advisory lock on a shared variable or
3272 referenced object contained in THING until the lock goes out of
3273 scope.
3274 The value returned is the scalar itself, if the argument is a
3276 scalar, or a reference, if the argument is a hash, array or
3277 subroutine.
3278 "lock" is a "weak keyword"; this means that if you've defined a
3280 function by this name (before any calls to it), that function will
3281 be called instead. If you are not under "use threads::shared" this
3282 does nothing. See threads::shared.
3283 log EXPR
3285 log Returns the natural logarithm (base e) of EXPR. If EXPR is
3286 omitted, returns the log of $_. To get the log of another base,
3287 use basic algebra: The base-N log of a number is equal to the
3288 natural log of that number divided by the natural log of N. For
3289 example:
3290 sub log10 {
3292 my $n = shift;
3293 return log($n)/log(10);
3294 }
3295 See also "exp" for the inverse operation.
3297 lstat FILEHANDLE
3299 lstat EXPR
3300 lstat DIRHANDLE
3301 lstat
3302 Does the same thing as the "stat" function (including setting the
3303 special "_" filehandle) but stats a symbolic link instead of the
3304 file the symbolic link points to. If symbolic links are
3305 unimplemented on your system, a normal "stat" is done. For much
3306 more detailed information, please see the documentation for "stat".
3307 If EXPR is omitted, stats $_.
3309 Portability issues: "lstat" in perlport.
3311 m// The match operator. See "Regexp Quote-Like Operators" in perlop.
3313 map BLOCK LIST
3315 map EXPR,LIST
3316 Evaluates the BLOCK or EXPR for each element of LIST (locally
3317 setting $_ to each element) and composes a list of the results of
3318 each such evaluation. Each element of LIST may produce zero, one,
3319 or more elements in the generated list, so the number of elements
3320 in the generated list may differ from that in LIST. In scalar
3321 context, returns the total number of elements so generated. In
3322 list context, returns the generated list.
3323 my @chars = map(chr, @numbers);
3325 translates a list of numbers to the corresponding characters.
3327 my @squares = map { $_ * $_ } @numbers;
3329 translates a list of numbers to their squared values.
3331 my @squares = map { $_ > 5 ? ($_ * $_) : () } @numbers;
3333 shows that number of returned elements can differ from the number
3335 of input elements. To omit an element, return an empty list ().
3336 This could also be achieved by writing
3337 my @squares = map { $_ * $_ } grep { $_ > 5 } @numbers;
3339 which makes the intention more clear.
3341 Map always returns a list, which can be assigned to a hash such
3343 that the elements become key/value pairs. See perldata for more
3344 details.
3345 my %hash = map { get_a_key_for($_) => $_ } @array;
3347 is just a funny way to write
3349 my %hash;
3351 foreach (@array) {
3352 $hash{get_a_key_for($_)} = $_;
3353 }
3354 Note that $_ is an alias to the list value, so it can be used to
3356 modify the elements of the LIST. While this is useful and
3357 supported, it can cause bizarre results if the elements of LIST are
3358 not variables. Using a regular "foreach" loop for this purpose
3359 would be clearer in most cases. See also "grep" for a list
3360 composed of those items of the original list for which the BLOCK or
3361 EXPR evaluates to true.
3362 "{" starts both hash references and blocks, so "map { ..." could be
3364 either the start of map BLOCK LIST or map EXPR, LIST. Because Perl
3365 doesn't look ahead for the closing "}" it has to take a guess at
3366 which it's dealing with based on what it finds just after the "{".
3367 Usually it gets it right, but if it doesn't it won't realize
3368 something is wrong until it gets to the "}" and encounters the
3369 missing (or unexpected) comma. The syntax error will be reported
3370 close to the "}", but you'll need to change something near the "{"
3371 such as using a unary "+" or semicolon to give Perl some help:
3372 my %hash = map { "\L$_" => 1 } @array # perl guesses EXPR. wrong
3374 my %hash = map { +"\L$_" => 1 } @array # perl guesses BLOCK. right
3375 my %hash = map {; "\L$_" => 1 } @array # this also works
3376 my %hash = map { ("\L$_" => 1) } @array # as does this
3377 my %hash = map { lc($_) => 1 } @array # and this.
3378 my %hash = map +( lc($_) => 1 ), @array # this is EXPR and works!
3379 my %hash = map ( lc($_), 1 ), @array # evaluates to (1, @array)
3381 or to force an anon hash constructor use "+{":
3383 my @hashes = map +{ lc($_) => 1 }, @array # EXPR, so needs
3385 # comma at end
3386 to get a list of anonymous hashes each with only one entry apiece.
3388 mkdir FILENAME,MODE
3390 mkdir FILENAME
3391 mkdir
3392 Creates the directory specified by FILENAME, with permissions
3393 specified by MODE (as modified by "umask"). If it succeeds it
3394 returns true; otherwise it returns false and sets $! (errno). MODE
3395 defaults to 0777 if omitted, and FILENAME defaults to $_ if
3396 omitted.
3397 In general, it is better to create directories with a permissive
3399 MODE and let the user modify that with their "umask" than it is to
3400 supply a restrictive MODE and give the user no way to be more
3401 permissive. The exceptions to this rule are when the file or
3402 directory should be kept private (mail files, for instance). The
3403 documentation for "umask" discusses the choice of MODE in more
3404 detail.
3405 Note that according to the POSIX 1003.1-1996 the FILENAME may have
3407 any number of trailing slashes. Some operating and filesystems do
3408 not get this right, so Perl automatically removes all trailing
3409 slashes to keep everyone happy.
3410 To recursively create a directory structure, look at the
3412 "make_path" function of the File::Path module.
3413 msgctl ID,CMD,ARG
3415 Calls the System V IPC function msgctl(2). You'll probably have to
3416 say
3417 use IPC::SysV;
3419 first to get the correct constant definitions. If CMD is
3421 "IPC_STAT", then ARG must be a variable that will hold the returned
3422 "msqid_ds" structure. Returns like "ioctl": the undefined value
3423 for error, "0 but true" for zero, or the actual return value
3424 otherwise. See also "SysV IPC" in perlipc and the documentation
3425 for "IPC::SysV" and "IPC::Semaphore".
3426 Portability issues: "msgctl" in perlport.
3428 msgget KEY,FLAGS
3430 Calls the System V IPC function msgget(2). Returns the message
3431 queue id, or "undef" on error. See also "SysV IPC" in perlipc and
3432 the documentation for "IPC::SysV" and "IPC::Msg".
3433 Portability issues: "msgget" in perlport.
3435 msgrcv ID,VAR,SIZE,TYPE,FLAGS
3437 Calls the System V IPC function msgrcv to receive a message from
3438 message queue ID into variable VAR with a maximum message size of
3439 SIZE. Note that when a message is received, the message type as a
3440 native long integer will be the first thing in VAR, followed by the
3441 actual message. This packing may be opened with "unpack("l! a*")".
3442 Taints the variable. Returns true if successful, false on error.
3443 See also "SysV IPC" in perlipc and the documentation for
3444 "IPC::SysV" and "IPC::Msg".
3445 Portability issues: "msgrcv" in perlport.
3447 msgsnd ID,MSG,FLAGS
3449 Calls the System V IPC function msgsnd to send the message MSG to
3450 the message queue ID. MSG must begin with the native long integer
3451 message type, followed by the message itself. This kind of packing
3452 can be achieved with "pack("l! a*", $type, $message)". Returns
3453 true if successful, false on error. See also "SysV IPC" in perlipc
3454 and the documentation for "IPC::SysV" and "IPC::Msg".
3455 Portability issues: "msgsnd" in perlport.
3457 my VARLIST
3459 my TYPE VARLIST
3460 my VARLIST : ATTRS
3461 my TYPE VARLIST : ATTRS
3462 A "my" declares the listed variables to be local (lexically) to the
3463 enclosing block, file, or "eval". If more than one variable is
3464 listed, the list must be placed in parentheses.
3465 Note that with a parenthesised list, "undef" can be used as a dummy
3467 placeholder, for example to skip assignment of initial values:
3468 my ( undef, $min, $hour ) = localtime;
3470 Redeclaring a variable in the same scope or statement will "shadow"
3472 the previous declaration, creating a new instance and preventing
3473 access to the previous one. This is usually undesired and, if
3474 warnings are enabled, will result in a warning in the "shadow"
3475 category.
3476 The exact semantics and interface of TYPE and ATTRS are still
3478 evolving. TYPE may be a bareword, a constant declared with "use
3479 constant", or "__PACKAGE__". It is currently bound to the use of
3480 the fields pragma, and attributes are handled using the attributes
3481 pragma, or starting from Perl 5.8.0 also via the
3482 Attribute::Handlers module. See "Private Variables via my()" in
3483 perlsub for details.
3484 next LABEL
3486 next EXPR
3487 next
3488 The "next" command is like the "continue" statement in C; it starts
3489 the next iteration of the loop:
3490 LINE: while (<STDIN>) {
3492 next LINE if /^#/; # discard comments
3493 #...
3494 }
3495 Note that if there were a "continue" block on the above, it would
3497 get executed even on discarded lines. If LABEL is omitted, the
3498 command refers to the innermost enclosing loop. The "next EXPR"
3499 form, available as of Perl 5.18.0, allows a label name to be
3500 computed at run time, being otherwise identical to "next LABEL".
3501 "next" cannot return a value from a block that typically returns a
3503 value, such as "eval {}", "sub {}", or "do {}". It will perform its
3504 flow control behavior, which precludes any return value. It should
3505 not be used to exit a "grep" or "map" operation.
3506 Note that a block by itself is semantically identical to a loop
3508 that executes once. Thus "next" will exit such a block early.
3509 See also "continue" for an illustration of how "last", "next", and
3511 "redo" work.
3512 Unlike most named operators, this has the same precedence as
3514 assignment. It is also exempt from the looks-like-a-function rule,
3515 so "next ("foo")."bar"" will cause "bar" to be part of the argument
3516 to "next".
3517 no MODULE VERSION LIST
3519 no MODULE VERSION
3520 no MODULE LIST
3521 no MODULE
3522 no VERSION
3523 See the "use" function, of which "no" is the opposite.
3524 oct EXPR
3526 oct Interprets EXPR as an octal string and returns the corresponding
3527 value. An octal string consists of octal digits and, as of Perl
3528 5.33.5, an optional "0o" or "o" prefix. Each octal digit may be
3529 preceded by a single underscore, which will be ignored. (If EXPR
3530 happens to start off with "0x" or "x", interprets it as a hex
3531 string. If EXPR starts off with "0b" or "b", it is interpreted as
3532 a binary string. Leading whitespace is ignored in all three
3533 cases.) The following will handle decimal, binary, octal, and hex
3534 in standard Perl notation:
3535 $val = oct($val) if $val =~ /^0/;
3537 If EXPR is omitted, uses $_. To go the other way (produce a
3539 number in octal), use "sprintf" or "printf":
3540 my $dec_perms = (stat("filename"))[2] & 07777;
3542 my $oct_perm_str = sprintf "%o", $perms;
3543 The "oct" function is commonly used when a string such as 644 needs
3545 to be converted into a file mode, for example. Although Perl
3546 automatically converts strings into numbers as needed, this
3547 automatic conversion assumes base 10.
3548 Leading white space is ignored without warning, as too are any
3550 trailing non-digits, such as a decimal point ("oct" only handles
3551 non-negative integers, not negative integers or floating point).
3552 open FILEHANDLE,MODE,EXPR
3554 open FILEHANDLE,MODE,EXPR,LIST
3555 open FILEHANDLE,MODE,REFERENCE
3556 open FILEHANDLE,EXPR
3557 open FILEHANDLE
3558 Associates an internal FILEHANDLE with the external file specified
3559 by EXPR. That filehandle will subsequently allow you to perform I/O
3560 operations on that file, such as reading from it or writing to it.
3561 Instead of a filename, you may specify an external command (plus an
3563 optional argument list) or a scalar reference, in order to open
3564 filehandles on commands or in-memory scalars, respectively.
3565 A thorough reference to "open" follows. For a gentler introduction
3567 to the basics of "open", see also the perlopentut manual page.
3568 Working with files
3570 Most often, "open" gets invoked with three arguments: the
3571 required FILEHANDLE (usually an empty scalar variable),
3572 followed by MODE (usually a literal describing the I/O mode the
3573 filehandle will use), and then the filename that the new
3574 filehandle will refer to.
3575 Simple examples
3577 Reading from a file:
3578 open(my $fh, "<", "input.txt")
3580 or die "Can't open < input.txt: $!";
3581 # Process every line in input.txt
3583 while (my $line = <$fh>) {
3584 #
3585 # ... do something interesting with $line here ...
3586 #
3587 }
3588 or writing to one:
3590 open(my $fh, ">", "output.txt")
3592 or die "Can't open > output.txt: $!";
3593 print $fh "This line gets printed into output.txt.\n";
3595 For a summary of common filehandle operations such as
3597 these, see "Files and I/O" in perlintro.
3598 About filehandles
3600 The first argument to "open", labeled FILEHANDLE in this
3601 reference, is usually a scalar variable. (Exceptions exist,
3602 described in "Other considerations", below.) If the call to
3603 "open" succeeds, then the expression provided as FILEHANDLE
3604 will get assigned an open filehandle. That filehandle
3605 provides an internal reference to the specified external
3606 file, conveniently stored in a Perl variable, and ready for
3607 I/O operations such as reading and writing.
3608 About modes
3610 When calling "open" with three or more arguments, the
3611 second argument -- labeled MODE here -- defines the open
3612 mode. MODE is usually a literal string comprising special
3613 characters that define the intended I/O role of the
3614 filehandle being created: whether it's read-only, or read-
3615 and-write, and so on.
3616 If MODE is "<", the file is opened for input (read-only).
3618 If MODE is ">", the file is opened for output, with
3619 existing files first being truncated ("clobbered") and
3620 nonexisting files newly created. If MODE is ">>", the file
3621 is opened for appending, again being created if necessary.
3622 You can put a "+" in front of the ">" or "<" to indicate
3624 that you want both read and write access to the file; thus
3625 "+<" is almost always preferred for read/write updates--the
3626 "+>" mode would clobber the file first. You can't usually
3627 use either read-write mode for updating textfiles, since
3628 they have variable-length records. See the -i switch in
3629 perlrun for a better approach. The file is created with
3630 permissions of 0666 modified by the process's "umask"
3631 value.
3632 These various prefixes correspond to the fopen(3) modes of
3634 "r", "r+", "w", "w+", "a", and "a+".
3635 More examples of different modes in action:
3637 # Open a file for concatenation
3639 open(my $log, ">>", "/usr/spool/news/twitlog")
3640 or warn "Couldn't open log file; discarding input";
3641 # Open a file for reading and writing
3643 open(my $dbase, "+<", "dbase.mine")
3644 or die "Can't open 'dbase.mine' for update: $!";
3645 Checking the return value
3647 Open returns nonzero on success, the undefined value
3648 otherwise. If the "open" involved a pipe, the return value
3649 happens to be the pid of the subprocess.
3650 When opening a file, it's seldom a good idea to continue if
3652 the request failed, so "open" is frequently used with
3653 "die". Even if you want your code to do something other
3654 than "die" on a failed open, you should still always check
3655 the return value from opening a file.
3656 Specifying I/O layers in MODE
3658 You can use the three-argument form of open to specify I/O
3659 layers (sometimes referred to as "disciplines") to apply to the
3660 new filehandle. These affect how the input and output are
3661 processed (see open and PerlIO for more details). For example:
3662 open(my $fh, "<:encoding(UTF-8)", $filename)
3664 || die "Can't open UTF-8 encoded $filename: $!";
3665 This opens the UTF8-encoded file containing Unicode characters;
3667 see perluniintro. Note that if layers are specified in the
3668 three-argument form, then default layers stored in "${^OPEN}"
3669 (usually set by the open pragma or the switch "-CioD") are
3670 ignored. Those layers will also be ignored if you specify a
3671 colon with no name following it. In that case the default
3672 layer for the operating system (:raw on Unix, :crlf on Windows)
3673 is used.
3674 On some systems (in general, DOS- and Windows-based systems)
3676 "binmode" is necessary when you're not working with a text
3677 file. For the sake of portability it is a good idea always to
3678 use it when appropriate, and never to use it when it isn't
3679 appropriate. Also, people can set their I/O to be by default
3680 UTF8-encoded Unicode, not bytes.
3681 Using "undef" for temporary files
3683 As a special case the three-argument form with a read/write
3684 mode and the third argument being "undef":
3685 open(my $tmp, "+>", undef) or die ...
3687 opens a filehandle to a newly created empty anonymous temporary
3689 file. (This happens under any mode, which makes "+>" the only
3690 useful and sensible mode to use.) You will need to "seek" to
3691 do the reading.
3692 Opening a filehandle into an in-memory scalar
3694 You can open filehandles directly to Perl scalars instead of a
3695 file or other resource external to the program. To do so,
3696 provide a reference to that scalar as the third argument to
3697 "open", like so:
3698 open(my $memory, ">", \$var)
3700 or die "Can't open memory file: $!";
3701 print $memory "foo!\n"; # output will appear in $var
3702 To (re)open "STDOUT" or "STDERR" as an in-memory file, close it
3704 first:
3705 close STDOUT;
3707 open(STDOUT, ">", \$variable)
3708 or die "Can't open STDOUT: $!";
3709 The scalars for in-memory files are treated as octet strings:
3711 unless the file is being opened with truncation the scalar may
3712 not contain any code points over 0xFF.
3713 Opening in-memory files can fail for a variety of reasons. As
3715 with any other "open", check the return value for success.
3716 Technical note: This feature works only when Perl is built with
3718 PerlIO -- the default, except with older (pre-5.16) Perl
3719 installations that were configured to not include it (e.g. via
3720 "Configure -Uuseperlio"). You can see whether your Perl was
3721 built with PerlIO by running "perl -V:useperlio". If it says
3722 'define', you have PerlIO; otherwise you don't.
3723 See perliol for detailed info on PerlIO.
3725 Opening a filehandle into a command
3727 If MODE is "|-", then the filename is interpreted as a command
3728 to which output is to be piped, and if MODE is "-|", the
3729 filename is interpreted as a command that pipes output to us.
3730 In the two-argument (and one-argument) form, one should replace
3731 dash ("-") with the command. See "Using open() for IPC" in
3732 perlipc for more examples of this. (You are not allowed to
3733 "open" to a command that pipes both in and out, but see
3734 IPC::Open2, IPC::Open3, and "Bidirectional Communication with
3735 Another Process" in perlipc for alternatives.)
3736 open(my $article_fh, "-|", "caesar <$article") # decrypt
3738 # article
3739 or die "Can't start caesar: $!";
3740 open(my $article_fh, "caesar <$article |") # ditto
3742 or die "Can't start caesar: $!";
3743 open(my $out_fh, "|-", "sort >Tmp$$") # $$ is our process id
3745 or die "Can't start sort: $!";
3746 In the form of pipe opens taking three or more arguments, if
3748 LIST is specified (extra arguments after the command name) then
3749 LIST becomes arguments to the command invoked if the platform
3750 supports it. The meaning of "open" with more than three
3751 arguments for non-pipe modes is not yet defined, but
3752 experimental "layers" may give extra LIST arguments meaning.
3753 If you open a pipe on the command "-" (that is, specify either
3755 "|-" or "-|" with the one- or two-argument forms of "open"), an
3756 implicit "fork" is done, so "open" returns twice: in the parent
3757 process it returns the pid of the child process, and in the
3758 child process it returns (a defined) 0. Use "defined($pid)" or
3759 "//" to determine whether the open was successful.
3760 For example, use either
3762 my $child_pid = open(my $from_kid, "-|")
3764 // die "Can't fork: $!";
3765 or
3767 my $child_pid = open(my $to_kid, "|-")
3769 // die "Can't fork: $!";
3770 followed by
3772 if ($child_pid) {
3774 # am the parent:
3775 # either write $to_kid or else read $from_kid
3776 ...
3777 waitpid $child_pid, 0;
3778 } else {
3779 # am the child; use STDIN/STDOUT normally
3780 ...
3781 exit;
3782 }
3783 The filehandle behaves normally for the parent, but I/O to that
3785 filehandle is piped from/to the STDOUT/STDIN of the child
3786 process. In the child process, the filehandle isn't
3787 opened--I/O happens from/to the new STDOUT/STDIN. Typically
3788 this is used like the normal piped open when you want to
3789 exercise more control over just how the pipe command gets
3790 executed, such as when running setuid and you don't want to
3791 have to scan shell commands for metacharacters.
3792 The following blocks are more or less equivalent:
3794 open(my $fh, "|tr '[a-z]' '[A-Z]'");
3796 open(my $fh, "|-", "tr '[a-z]' '[A-Z]'");
3797 open(my $fh, "|-") || exec 'tr', '[a-z]', '[A-Z]';
3798 open(my $fh, "|-", "tr", '[a-z]', '[A-Z]');
3799 open(my $fh, "cat -n '$file'|");
3801 open(my $fh, "-|", "cat -n '$file'");
3802 open(my $fh, "-|") || exec "cat", "-n", $file;
3803 open(my $fh, "-|", "cat", "-n", $file);
3804 The last two examples in each block show the pipe as "list
3806 form", which is not yet supported on all platforms. (If your
3807 platform has a real "fork", such as Linux and macOS, you can
3808 use the list form; it also works on Windows with Perl 5.22 or
3809 later.) You would want to use the list form of the pipe so you
3810 can pass literal arguments to the command without risk of the
3811 shell interpreting any shell metacharacters in them. However,
3812 this also bars you from opening pipes to commands that
3813 intentionally contain shell metacharacters, such as:
3814 open(my $fh, "|cat -n | expand -4 | lpr")
3816 || die "Can't open pipeline to lpr: $!";
3817 See "Safe Pipe Opens" in perlipc for more examples of this.
3819 Duping filehandles
3821 You may also, in the Bourne shell tradition, specify an EXPR
3822 beginning with ">&", in which case the rest of the string is
3823 interpreted as the name of a filehandle (or file descriptor, if
3824 numeric) to be duped (as in dup(2)) and opened. You may use
3825 "&" after ">", ">>", "<", "+>", "+>>", and "+<". The mode you
3826 specify should match the mode of the original filehandle.
3827 (Duping a filehandle does not take into account any existing
3828 contents of IO buffers.) If you use the three-argument form,
3829 then you can pass either a number, the name of a filehandle, or
3830 the normal "reference to a glob".
3831 Here is a script that saves, redirects, and restores "STDOUT"
3833 and "STDERR" using various methods:
3834 #!/usr/bin/perl
3836 open(my $oldout, ">&STDOUT")
3837 or die "Can't dup STDOUT: $!";
3838 open(OLDERR, ">&", \*STDERR)
3839 or die "Can't dup STDERR: $!";
3840 open(STDOUT, '>', "foo.out")
3842 or die "Can't redirect STDOUT: $!";
3843 open(STDERR, ">&STDOUT")
3844 or die "Can't dup STDOUT: $!";
3845 select STDERR; $| = 1; # make unbuffered
3847 select STDOUT; $| = 1; # make unbuffered
3848 print STDOUT "stdout 1\n"; # this works for
3850 print STDERR "stderr 1\n"; # subprocesses too
3851 open(STDOUT, ">&", $oldout)
3853 or die "Can't dup \$oldout: $!";
3854 open(STDERR, ">&OLDERR")
3855 or die "Can't dup OLDERR: $!";
3856 print STDOUT "stdout 2\n";
3858 print STDERR "stderr 2\n";
3859 If you specify '<&=X', where "X" is a file descriptor number or
3861 a filehandle, then Perl will do an equivalent of C's fdopen(3)
3862 of that file descriptor (and not call dup(2)); this is more
3863 parsimonious of file descriptors. For example:
3864 # open for input, reusing the fileno of $fd
3866 open(my $fh, "<&=", $fd)
3867 or
3869 open(my $fh, "<&=$fd")
3871 or
3873 # open for append, using the fileno of $oldfh
3875 open(my $fh, ">>&=", $oldfh)
3876 Being parsimonious on filehandles is also useful (besides being
3878 parsimonious) for example when something is dependent on file
3879 descriptors, like for example locking using "flock". If you do
3880 just "open(my $A, ">>&", $B)", the filehandle $A will not have
3881 the same file descriptor as $B, and therefore "flock($A)" will
3882 not "flock($B)" nor vice versa. But with "open(my $A, ">>&=",
3883 $B)", the filehandles will share the same underlying system
3884 file descriptor.
3885 Note that under Perls older than 5.8.0, Perl uses the standard
3887 C library's' fdopen(3) to implement the "=" functionality. On
3888 many Unix systems, fdopen(3) fails when file descriptors exceed
3889 a certain value, typically 255. For Perls 5.8.0 and later,
3890 PerlIO is (most often) the default.
3891 Legacy usage
3893 This section describes ways to call "open" outside of best
3894 practices; you may encounter these uses in older code. Perl
3895 does not consider their use deprecated, exactly, but neither is
3896 it recommended in new code, for the sake of clarity and
3897 readability.
3898 Specifying mode and filename as a single argument
3900 In the one- and two-argument forms of the call, the mode
3901 and filename should be concatenated (in that order),
3902 preferably separated by white space. You can--but
3903 shouldn't--omit the mode in these forms when that mode is
3904 "<". It is safe to use the two-argument form of "open" if
3905 the filename argument is a known literal.
3906 open(my $dbase, "+<dbase.mine") # ditto
3908 or die "Can't open 'dbase.mine' for update: $!";
3909 In the two-argument (and one-argument) form, opening "<-"
3911 or "-" opens STDIN and opening ">-" opens STDOUT.
3912 New code should favor the three-argument form of "open"
3914 over this older form. Declaring the mode and the filename
3915 as two distinct arguments avoids any confusion between the
3916 two.
3917 Calling "open" with one argument via global variables
3919 As a shortcut, a one-argument call takes the filename from
3920 the global scalar variable of the same name as the
3921 filehandle:
3922 $ARTICLE = 100;
3924 open(ARTICLE)
3925 or die "Can't find article $ARTICLE: $!\n";
3926 Here $ARTICLE must be a global (package) scalar variable -
3928 not one declared with "my" or "state".
3929 Assigning a filehandle to a bareword
3931 An older style is to use a bareword as the filehandle, as
3932 open(FH, "<", "input.txt")
3934 or die "Can't open < input.txt: $!";
3935 Then you can use "FH" as the filehandle, in "close FH" and
3937 "<FH>" and so on. Note that it's a global variable, so
3938 this form is not recommended when dealing with filehandles
3939 other than Perl's built-in ones (e.g. STDOUT and STDIN).
3940 Other considerations
3942 Automatic filehandle closure
3943 The filehandle will be closed when its reference count
3944 reaches zero. If it is a lexically scoped variable declared
3945 with "my", that usually means the end of the enclosing
3946 scope. However, this automatic close does not check for
3947 errors, so it is better to explicitly close filehandles,
3948 especially those used for writing:
3949 close($handle)
3951 || warn "close failed: $!";
3952 Automatic pipe flushing
3954 Perl will attempt to flush all files opened for output
3955 before any operation that may do a fork, but this may not
3956 be supported on some platforms (see perlport). To be safe,
3957 you may need to set $| ($AUTOFLUSH in English) or call the
3958 "autoflush" method of "IO::Handle" on any open handles.
3959 On systems that support a close-on-exec flag on files, the
3961 flag will be set for the newly opened file descriptor as
3962 determined by the value of $^F. See "$^F" in perlvar.
3963 Closing any piped filehandle causes the parent process to
3965 wait for the child to finish, then returns the status value
3966 in $? and "${^CHILD_ERROR_NATIVE}".
3967 Direct versus by-reference assignment of filehandles
3969 If FILEHANDLE -- the first argument in a call to "open" --
3970 is an undefined scalar variable (or array or hash element),
3971 a new filehandle is autovivified, meaning that the variable
3972 is assigned a reference to a newly allocated anonymous
3973 filehandle. Otherwise if FILEHANDLE is an expression, its
3974 value is the real filehandle. (This is considered a
3975 symbolic reference, so "use strict "refs"" should not be in
3976 effect.)
3977 Whitespace and special characters in the filename argument
3979 The filename passed to the one- and two-argument forms of
3980 "open" will have leading and trailing whitespace deleted
3981 and normal redirection characters honored. This property,
3982 known as "magic open", can often be used to good effect. A
3983 user could specify a filename of "rsh cat file |", or you
3984 could change certain filenames as needed:
3985 $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
3987 open(my $fh, $filename)
3988 or die "Can't open $filename: $!";
3989 Use the three-argument form to open a file with arbitrary
3991 weird characters in it,
3992 open(my $fh, "<", $file)
3994 || die "Can't open $file: $!";
3995 otherwise it's necessary to protect any leading and
3997 trailing whitespace:
3998 $file =~ s#^(\s)#./$1#;
4000 open(my $fh, "< $file\0")
4001 || die "Can't open $file: $!";
4002 (this may not work on some bizarre filesystems). One
4004 should conscientiously choose between the magic and three-
4005 argument form of "open":
4006 open(my $in, $ARGV[0]) || die "Can't open $ARGV[0]: $!";
4008 will allow the user to specify an argument of the form "rsh
4010 cat file |", but will not work on a filename that happens
4011 to have a trailing space, while
4012 open(my $in, "<", $ARGV[0])
4014 || die "Can't open $ARGV[0]: $!";
4015 will have exactly the opposite restrictions. (However, some
4017 shells support the syntax "perl your_program.pl <( rsh cat
4018 file )", which produces a filename that can be opened
4019 normally.)
4020 Invoking C-style "open"
4022 If you want a "real" C open(2), then you should use the
4023 "sysopen" function, which involves no such magic (but uses
4024 different filemodes than Perl "open", which corresponds to
4025 C fopen(3)). This is another way to protect your filenames
4026 from interpretation. For example:
4027 use IO::Handle;
4029 sysopen(my $fh, $path, O_RDWR|O_CREAT|O_EXCL)
4030 or die "Can't open $path: $!";
4031 $fh->autoflush(1);
4032 print $fh "stuff $$\n";
4033 seek($fh, 0, 0);
4034 print "File contains: ", readline($fh);
4035 See "seek" for some details about mixing reading and
4037 writing.
4038 Portability issues
4040 See "open" in perlport.
4041 opendir DIRHANDLE,EXPR
4043 Opens a directory named EXPR for processing by "readdir",
4044 "telldir", "seekdir", "rewinddir", and "closedir". Returns true if
4045 successful. DIRHANDLE may be an expression whose value can be used
4046 as an indirect dirhandle, usually the real dirhandle name. If
4047 DIRHANDLE is an undefined scalar variable (or array or hash
4048 element), the variable is assigned a reference to a new anonymous
4049 dirhandle; that is, it's autovivified. Dirhandles are the same
4050 objects as filehandles; an I/O object can only be open as one of
4051 these handle types at once.
4052 See the example at "readdir".
4054 ord EXPR
4056 ord Returns the numeric value of the first character of EXPR. If EXPR
4057 is an empty string, returns 0. If EXPR is omitted, uses $_. (Note
4058 character, not byte.)
4059 For the reverse, see "chr". See perlunicode for more about
4061 Unicode.
4062 our VARLIST
4064 our TYPE VARLIST
4065 our VARLIST : ATTRS
4066 our TYPE VARLIST : ATTRS
4067 "our" makes a lexical alias to a package (i.e. global) variable of
4068 the same name in the current package for use within the current
4069 lexical scope.
4070 "our" has the same scoping rules as "my" or "state", meaning that
4072 it is only valid within a lexical scope. Unlike "my" and "state",
4073 which both declare new (lexical) variables, "our" only creates an
4074 alias to an existing variable: a package variable of the same name.
4075 This means that when "use strict 'vars'" is in effect, "our" lets
4077 you use a package variable without qualifying it with the package
4078 name, but only within the lexical scope of the "our" declaration.
4079 This applies immediately--even within the same statement.
4080 package Foo;
4082 use strict;
4083 $Foo::foo = 23;
4085 {
4087 our $foo; # alias to $Foo::foo
4088 print $foo; # prints 23
4089 }
4090 print $Foo::foo; # prints 23
4092 print $foo; # ERROR: requires explicit package name
4094 This works even if the package variable has not been used before,
4096 as package variables spring into existence when first used.
4097 package Foo;
4099 use strict;
4100 our $foo = 23; # just like $Foo::foo = 23
4102 print $Foo::foo; # prints 23
4104 Because the variable becomes legal immediately under "use strict
4106 'vars'", so long as there is no variable with that name is already
4107 in scope, you can then reference the package variable again even
4108 within the same statement.
4109 package Foo;
4111 use strict;
4112 my $foo = $foo; # error, undeclared $foo on right-hand side
4114 our $foo = $foo; # no errors
4115 If more than one variable is listed, the list must be placed in
4117 parentheses.
4118 our($bar, $baz);
4120 An "our" declaration declares an alias for a package variable that
4122 will be visible across its entire lexical scope, even across
4123 package boundaries. The package in which the variable is entered
4124 is determined at the point of the declaration, not at the point of
4125 use. This means the following behavior holds:
4126 package Foo;
4128 our $bar; # declares $Foo::bar for rest of lexical scope
4129 $bar = 20;
4130 package Bar;
4132 print $bar; # prints 20, as it refers to $Foo::bar
4133 Multiple "our" declarations with the same name in the same lexical
4135 scope are allowed if they are in different packages. If they
4136 happen to be in the same package, Perl will emit warnings if you
4137 have asked for them, just like multiple "my" declarations. Unlike
4138 a second "my" declaration, which will bind the name to a fresh
4139 variable, a second "our" declaration in the same package, in the
4140 same scope, is merely redundant.
4141 use warnings;
4143 package Foo;
4144 our $bar; # declares $Foo::bar for rest of lexical scope
4145 $bar = 20;
4146 package Bar;
4148 our $bar = 30; # declares $Bar::bar for rest of lexical scope
4149 print $bar; # prints 30
4150 our $bar; # emits warning but has no other effect
4152 print $bar; # still prints 30
4153 An "our" declaration may also have a list of attributes associated
4155 with it.
4156 The exact semantics and interface of TYPE and ATTRS are still
4158 evolving. TYPE is currently bound to the use of the fields pragma,
4159 and attributes are handled using the attributes pragma, or,
4160 starting from Perl 5.8.0, also via the Attribute::Handlers module.
4161 See "Private Variables via my()" in perlsub for details.
4162 Note that with a parenthesised list, "undef" can be used as a dummy
4164 placeholder, for example to skip assignment of initial values:
4165 our ( undef, $min, $hour ) = localtime;
4167 "our" differs from "use vars", which allows use of an unqualified
4169 name only within the affected package, but across scopes.
4170 pack TEMPLATE,LIST
4172 Takes a LIST of values and converts it into a string using the
4173 rules given by the TEMPLATE. The resulting string is the
4174 concatenation of the converted values. Typically, each converted
4175 value looks like its machine-level representation. For example, on
4176 32-bit machines an integer may be represented by a sequence of 4
4177 bytes, which will in Perl be presented as a string that's 4
4178 characters long.
4179 See perlpacktut for an introduction to this function.
4181 The TEMPLATE is a sequence of characters that give the order and
4183 type of values, as follows:
4184 a A string with arbitrary binary data, will be null padded.
4186 A A text (ASCII) string, will be space padded.
4187 Z A null-terminated (ASCIZ) string, will be null padded.
4188 b A bit string (ascending bit order inside each byte,
4190 like vec()).
4191 B A bit string (descending bit order inside each byte).
4192 h A hex string (low nybble first).
4193 H A hex string (high nybble first).
4194 c A signed char (8-bit) value.
4196 C An unsigned char (octet) value.
4197 W An unsigned char value (can be greater than 255).
4198 s A signed short (16-bit) value.
4200 S An unsigned short value.
4201 l A signed long (32-bit) value.
4203 L An unsigned long value.
4204 q A signed quad (64-bit) value.
4206 Q An unsigned quad value.
4207 (Quads are available only if your system supports 64-bit
4208 integer values _and_ if Perl has been compiled to support
4209 those. Raises an exception otherwise.)
4210 i A signed integer value.
4212 I An unsigned integer value.
4213 (This 'integer' is _at_least_ 32 bits wide. Its exact
4214 size depends on what a local C compiler calls 'int'.)
4215 n An unsigned short (16-bit) in "network" (big-endian) order.
4217 N An unsigned long (32-bit) in "network" (big-endian) order.
4218 v An unsigned short (16-bit) in "VAX" (little-endian) order.
4219 V An unsigned long (32-bit) in "VAX" (little-endian) order.
4220 j A Perl internal signed integer value (IV).
4222 J A Perl internal unsigned integer value (UV).
4223 f A single-precision float in native format.
4225 d A double-precision float in native format.
4226 F A Perl internal floating-point value (NV) in native format
4228 D A float of long-double precision in native format.
4229 (Long doubles are available only if your system supports
4230 long double values. Raises an exception otherwise.
4231 Note that there are different long double formats.)
4232 p A pointer to a null-terminated string.
4234 P A pointer to a structure (fixed-length string).
4235 u A uuencoded string.
4237 U A Unicode character number. Encodes to a character in char-
4238 acter mode and UTF-8 (or UTF-EBCDIC in EBCDIC platforms) in
4239 byte mode.
4240 w A BER compressed integer (not an ASN.1 BER, see perlpacktut
4242 for details). Its bytes represent an unsigned integer in
4243 base 128, most significant digit first, with as few digits
4244 as possible. Bit eight (the high bit) is set on each byte
4245 except the last.
4246 x A null byte (a.k.a ASCII NUL, "\000", chr(0))
4248 X Back up a byte.
4249 @ Null-fill or truncate to absolute position, counted from the
4250 start of the innermost ()-group.
4251 . Null-fill or truncate to absolute position specified by
4252 the value.
4253 ( Start of a ()-group.
4254 One or more modifiers below may optionally follow certain letters
4256 in the TEMPLATE (the second column lists letters for which the
4257 modifier is valid):
4258 ! sSlLiI Forces native (short, long, int) sizes instead
4260 of fixed (16-/32-bit) sizes.
4261 ! xX Make x and X act as alignment commands.
4263 ! nNvV Treat integers as signed instead of unsigned.
4265 ! @. Specify position as byte offset in the internal
4267 representation of the packed string. Efficient
4268 but dangerous.
4269 > sSiIlLqQ Force big-endian byte-order on the type.
4271 jJfFdDpP (The "big end" touches the construct.)
4272 < sSiIlLqQ Force little-endian byte-order on the type.
4274 jJfFdDpP (The "little end" touches the construct.)
4275 The ">" and "<" modifiers can also be used on "()" groups to force
4277 a particular byte-order on all components in that group, including
4278 all its subgroups.
4279 The following rules apply:
4281 • Each letter may optionally be followed by a number indicating
4283 the repeat count. A numeric repeat count may optionally be
4284 enclosed in brackets, as in "pack("C[80]", @arr)". The repeat
4285 count gobbles that many values from the LIST when used with all
4286 format types other than "a", "A", "Z", "b", "B", "h", "H", "@",
4287 ".", "x", "X", and "P", where it means something else,
4288 described below. Supplying a "*" for the repeat count instead
4289 of a number means to use however many items are left, except
4290 for:
4291 • "@", "x", and "X", where it is equivalent to 0.
4293 • <.>, where it means relative to the start of the string.
4295 • "u", where it is equivalent to 1 (or 45, which here is
4297 equivalent).
4298 One can replace a numeric repeat count with a template letter
4300 enclosed in brackets to use the packed byte length of the
4301 bracketed template for the repeat count.
4302 For example, the template "x[L]" skips as many bytes as in a
4304 packed long, and the template "$t X[$t] $t" unpacks twice
4305 whatever $t (when variable-expanded) unpacks. If the template
4306 in brackets contains alignment commands (such as "x![d]"), its
4307 packed length is calculated as if the start of the template had
4308 the maximal possible alignment.
4309 When used with "Z", a "*" as the repeat count is guaranteed to
4311 add a trailing null byte, so the resulting string is always one
4312 byte longer than the byte length of the item itself.
4313 When used with "@", the repeat count represents an offset from
4315 the start of the innermost "()" group.
4316 When used with ".", the repeat count determines the starting
4318 position to calculate the value offset as follows:
4319 • If the repeat count is 0, it's relative to the current
4321 position.
4322 • If the repeat count is "*", the offset is relative to the
4324 start of the packed string.
4325 • And if it's an integer n, the offset is relative to the
4327 start of the nth innermost "( )" group, or to the start of
4328 the string if n is bigger then the group level.
4329 The repeat count for "u" is interpreted as the maximal number
4331 of bytes to encode per line of output, with 0, 1 and 2 replaced
4332 by 45. The repeat count should not be more than 65.
4333 • The "a", "A", and "Z" types gobble just one value, but pack it
4335 as a string of length count, padding with nulls or spaces as
4336 needed. When unpacking, "A" strips trailing whitespace and
4337 nulls, "Z" strips everything after the first null, and "a"
4338 returns data with no stripping at all.
4339 If the value to pack is too long, the result is truncated. If
4341 it's too long and an explicit count is provided, "Z" packs only
4342 "$count-1" bytes, followed by a null byte. Thus "Z" always
4343 packs a trailing null, except when the count is 0.
4344 • Likewise, the "b" and "B" formats pack a string that's that
4346 many bits long. Each such format generates 1 bit of the
4347 result. These are typically followed by a repeat count like
4348 "B8" or "B64".
4349 Each result bit is based on the least-significant bit of the
4351 corresponding input character, i.e., on "ord($char)%2". In
4352 particular, characters "0" and "1" generate bits 0 and 1, as do
4353 characters "\000" and "\001".
4354 Starting from the beginning of the input string, each 8-tuple
4356 of characters is converted to 1 character of output. With
4357 format "b", the first character of the 8-tuple determines the
4358 least-significant bit of a character; with format "B", it
4359 determines the most-significant bit of a character.
4360 If the length of the input string is not evenly divisible by 8,
4362 the remainder is packed as if the input string were padded by
4363 null characters at the end. Similarly during unpacking,
4364 "extra" bits are ignored.
4365 If the input string is longer than needed, remaining characters
4367 are ignored.
4368 A "*" for the repeat count uses all characters of the input
4370 field. On unpacking, bits are converted to a string of 0s and
4371 1s.
4372 • The "h" and "H" formats pack a string that many nybbles (4-bit
4374 groups, representable as hexadecimal digits, "0".."9" "a".."f")
4375 long.
4376 For each such format, "pack" generates 4 bits of result. With
4378 non-alphabetical characters, the result is based on the 4
4379 least-significant bits of the input character, i.e., on
4380 "ord($char)%16". In particular, characters "0" and "1"
4381 generate nybbles 0 and 1, as do bytes "\000" and "\001". For
4382 characters "a".."f" and "A".."F", the result is compatible with
4383 the usual hexadecimal digits, so that "a" and "A" both generate
4384 the nybble "0xA==10". Use only these specific hex characters
4385 with this format.
4386 Starting from the beginning of the template to "pack", each
4388 pair of characters is converted to 1 character of output. With
4389 format "h", the first character of the pair determines the
4390 least-significant nybble of the output character; with format
4391 "H", it determines the most-significant nybble.
4392 If the length of the input string is not even, it behaves as if
4394 padded by a null character at the end. Similarly, "extra"
4395 nybbles are ignored during unpacking.
4396 If the input string is longer than needed, extra characters are
4398 ignored.
4399 A "*" for the repeat count uses all characters of the input
4401 field. For "unpack", nybbles are converted to a string of
4402 hexadecimal digits.
4403 • The "p" format packs a pointer to a null-terminated string.
4405 You are responsible for ensuring that the string is not a
4406 temporary value, as that could potentially get deallocated
4407 before you got around to using the packed result. The "P"
4408 format packs a pointer to a structure of the size indicated by
4409 the length. A null pointer is created if the corresponding
4410 value for "p" or "P" is "undef"; similarly with "unpack", where
4411 a null pointer unpacks into "undef".
4412 If your system has a strange pointer size--meaning a pointer is
4414 neither as big as an int nor as big as a long--it may not be
4415 possible to pack or unpack pointers in big- or little-endian
4416 byte order. Attempting to do so raises an exception.
4417 • The "/" template character allows packing and unpacking of a
4419 sequence of items where the packed structure contains a packed
4420 item count followed by the packed items themselves. This is
4421 useful when the structure you're unpacking has encoded the
4422 sizes or repeat counts for some of its fields within the
4423 structure itself as separate fields.
4424 For "pack", you write length-item"/"sequence-item, and the
4426 length-item describes how the length value is packed. Formats
4427 likely to be of most use are integer-packing ones like "n" for
4428 Java strings, "w" for ASN.1 or SNMP, and "N" for Sun XDR.
4429 For "pack", sequence-item may have a repeat count, in which
4431 case the minimum of that and the number of available items is
4432 used as the argument for length-item. If it has no repeat
4433 count or uses a '*', the number of available items is used.
4434 For "unpack", an internal stack of integer arguments unpacked
4436 so far is used. You write "/"sequence-item and the repeat
4437 count is obtained by popping off the last element from the
4438 stack. The sequence-item must not have a repeat count.
4439 If sequence-item refers to a string type ("A", "a", or "Z"),
4441 the length-item is the string length, not the number of
4442 strings. With an explicit repeat count for pack, the packed
4443 string is adjusted to that length. For example:
4444 This code: gives this result:
4446 unpack("W/a", "\004Gurusamy") ("Guru")
4448 unpack("a3/A A*", "007 Bond J ") (" Bond", "J")
4449 unpack("a3 x2 /A A*", "007: Bond, J.") ("Bond, J", ".")
4450 pack("n/a* w/a","hello,","world") "\000\006hello,\005world"
4452 pack("a/W2", ord("a") .. ord("z")) "2ab"
4453 The length-item is not returned explicitly from "unpack".
4455 Supplying a count to the length-item format letter is only
4457 useful with "A", "a", or "Z". Packing with a length-item of
4458 "a" or "Z" may introduce "\000" characters, which Perl does not
4459 regard as legal in numeric strings.
4460 • The integer types "s", "S", "l", and "L" may be followed by a
4462 "!" modifier to specify native shorts or longs. As shown in
4463 the example above, a bare "l" means exactly 32 bits, although
4464 the native "long" as seen by the local C compiler may be
4465 larger. This is mainly an issue on 64-bit platforms. You can
4466 see whether using "!" makes any difference this way:
4467 printf "format s is %d, s! is %d\n",
4469 length pack("s"), length pack("s!");
4470 printf "format l is %d, l! is %d\n",
4472 length pack("l"), length pack("l!");
4473 "i!" and "I!" are also allowed, but only for completeness'
4475 sake: they are identical to "i" and "I".
4476 The actual sizes (in bytes) of native shorts, ints, longs, and
4478 long longs on the platform where Perl was built are also
4479 available from the command line:
4480 $ perl -V:{short,int,long{,long}}size
4482 shortsize='2';
4483 intsize='4';
4484 longsize='4';
4485 longlongsize='8';
4486 or programmatically via the "Config" module:
4488 use Config;
4490 print $Config{shortsize}, "\n";
4491 print $Config{intsize}, "\n";
4492 print $Config{longsize}, "\n";
4493 print $Config{longlongsize}, "\n";
4494 $Config{longlongsize} is undefined on systems without long long
4496 support.
4497 • The integer formats "s", "S", "i", "I", "l", "L", "j", and "J"
4499 are inherently non-portable between processors and operating
4500 systems because they obey native byteorder and endianness. For
4501 example, a 4-byte integer 0x12345678 (305419896 decimal) would
4502 be ordered natively (arranged in and handled by the CPU
4503 registers) into bytes as
4504 0x12 0x34 0x56 0x78 # big-endian
4506 0x78 0x56 0x34 0x12 # little-endian
4507 Basically, Intel and VAX CPUs are little-endian, while
4509 everybody else, including Motorola m68k/88k, PPC, Sparc, HP PA,
4510 Power, and Cray, are big-endian. Alpha and MIPS can be either:
4511 Digital/Compaq uses (well, used) them in little-endian mode,
4512 but SGI/Cray uses them in big-endian mode.
4513 The names big-endian and little-endian are comic references to
4515 the egg-eating habits of the little-endian Lilliputians and the
4516 big-endian Blefuscudians from the classic Jonathan Swift
4517 satire, Gulliver's Travels. This entered computer lingo via
4518 the paper "On Holy Wars and a Plea for Peace" by Danny Cohen,
4519 USC/ISI IEN 137, April 1, 1980.
4520 Some systems may have even weirder byte orders such as
4522 0x56 0x78 0x12 0x34
4524 0x34 0x12 0x78 0x56
4525 These are called mid-endian, middle-endian, mixed-endian, or
4527 just weird.
4528 You can determine your system endianness with this incantation:
4530 printf("%#02x ", $_) for unpack("W*", pack L=>0x12345678);
4532 The byteorder on the platform where Perl was built is also
4534 available via Config:
4535 use Config;
4537 print "$Config{byteorder}\n";
4538 or from the command line:
4540 $ perl -V:byteorder
4542 Byteorders "1234" and "12345678" are little-endian; "4321" and
4544 "87654321" are big-endian. Systems with multiarchitecture
4545 binaries will have "ffff", signifying that static information
4546 doesn't work, one must use runtime probing.
4547 For portably packed integers, either use the formats "n", "N",
4549 "v", and "V" or else use the ">" and "<" modifiers described
4550 immediately below. See also perlport.
4551 • Also floating point numbers have endianness. Usually (but not
4553 always) this agrees with the integer endianness. Even though
4554 most platforms these days use the IEEE 754 binary format, there
4555 are differences, especially if the long doubles are involved.
4556 You can see the "Config" variables "doublekind" and
4557 "longdblkind" (also "doublesize", "longdblsize"): the "kind"
4558 values are enums, unlike "byteorder".
4559 Portability-wise the best option is probably to keep to the
4561 IEEE 754 64-bit doubles, and of agreed-upon endianness.
4562 Another possibility is the "%a") format of "printf".
4563 • Starting with Perl 5.10.0, integer and floating-point formats,
4565 along with the "p" and "P" formats and "()" groups, may all be
4566 followed by the ">" or "<" endianness modifiers to respectively
4567 enforce big- or little-endian byte-order. These modifiers are
4568 especially useful given how "n", "N", "v", and "V" don't cover
4569 signed integers, 64-bit integers, or floating-point values.
4570 Here are some concerns to keep in mind when using an endianness
4572 modifier:
4573 • Exchanging signed integers between different platforms
4575 works only when all platforms store them in the same
4576 format. Most platforms store signed integers in two's-
4577 complement notation, so usually this is not an issue.
4578 • The ">" or "<" modifiers can only be used on floating-point
4580 formats on big- or little-endian machines. Otherwise,
4581 attempting to use them raises an exception.
4582 • Forcing big- or little-endian byte-order on floating-point
4584 values for data exchange can work only if all platforms use
4585 the same binary representation such as IEEE floating-point.
4586 Even if all platforms are using IEEE, there may still be
4587 subtle differences. Being able to use ">" or "<" on
4588 floating-point values can be useful, but also dangerous if
4589 you don't know exactly what you're doing. It is not a
4590 general way to portably store floating-point values.
4591 • When using ">" or "<" on a "()" group, this affects all
4593 types inside the group that accept byte-order modifiers,
4594 including all subgroups. It is silently ignored for all
4595 other types. You are not allowed to override the byte-
4596 order within a group that already has a byte-order modifier
4597 suffix.
4598 • Real numbers (floats and doubles) are in native machine format
4600 only. Due to the multiplicity of floating-point formats and
4601 the lack of a standard "network" representation for them, no
4602 facility for interchange has been made. This means that packed
4603 floating-point data written on one machine may not be readable
4604 on another, even if both use IEEE floating-point arithmetic
4605 (because the endianness of the memory representation is not
4606 part of the IEEE spec). See also perlport.
4607 If you know exactly what you're doing, you can use the ">" or
4609 "<" modifiers to force big- or little-endian byte-order on
4610 floating-point values.
4611 Because Perl uses doubles (or long doubles, if configured)
4613 internally for all numeric calculation, converting from double
4614 into float and thence to double again loses precision, so
4615 "unpack("f", pack("f", $foo)") will not in general equal $foo.
4616 • Pack and unpack can operate in two modes: character mode ("C0"
4618 mode) where the packed string is processed per character, and
4619 UTF-8 byte mode ("U0" mode) where the packed string is
4620 processed in its UTF-8-encoded Unicode form on a byte-by-byte
4621 basis. Character mode is the default unless the format string
4622 starts with "U". You can always switch mode mid-format with an
4623 explicit "C0" or "U0" in the format. This mode remains in
4624 effect until the next mode change, or until the end of the "()"
4625 group it (directly) applies to.
4626 Using "C0" to get Unicode characters while using "U0" to get
4628 non-Unicode bytes is not necessarily obvious. Probably only
4629 the first of these is what you want:
4630 $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
4632 perl -CS -ne 'printf "%v04X\n", $_ for unpack("C0A*", $_)'
4633 03B1.03C9
4634 $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
4635 perl -CS -ne 'printf "%v02X\n", $_ for unpack("U0A*", $_)'
4636 CE.B1.CF.89
4637 $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
4638 perl -C0 -ne 'printf "%v02X\n", $_ for unpack("C0A*", $_)'
4639 CE.B1.CF.89
4640 $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
4641 perl -C0 -ne 'printf "%v02X\n", $_ for unpack("U0A*", $_)'
4642 C3.8E.C2.B1.C3.8F.C2.89
4643 Those examples also illustrate that you should not try to use
4645 "pack"/"unpack" as a substitute for the Encode module.
4646 • You must yourself do any alignment or padding by inserting, for
4648 example, enough "x"es while packing. There is no way for
4649 "pack" and "unpack" to know where characters are going to or
4650 coming from, so they handle their output and input as flat
4651 sequences of characters.
4652 • A "()" group is a sub-TEMPLATE enclosed in parentheses. A
4654 group may take a repeat count either as postfix, or for
4655 "unpack", also via the "/" template character. Within each
4656 repetition of a group, positioning with "@" starts over at 0.
4657 Therefore, the result of
4658 pack("@1A((@2A)@3A)", qw[X Y Z])
4660 is the string "\0X\0\0YZ".
4662 • "x" and "X" accept the "!" modifier to act as alignment
4664 commands: they jump forward or back to the closest position
4665 aligned at a multiple of "count" characters. For example, to
4666 "pack" or "unpack" a C structure like
4667 struct {
4669 char c; /* one signed, 8-bit character */
4670 double d;
4671 char cc[2];
4672 }
4673 one may need to use the template "c x![d] d c[2]". This
4675 assumes that doubles must be aligned to the size of double.
4676 For alignment commands, a "count" of 0 is equivalent to a
4678 "count" of 1; both are no-ops.
4679 • "n", "N", "v" and "V" accept the "!" modifier to represent
4681 signed 16-/32-bit integers in big-/little-endian order. This
4682 is portable only when all platforms sharing packed data use the
4683 same binary representation for signed integers; for example,
4684 when all platforms use two's-complement representation.
4685 • Comments can be embedded in a TEMPLATE using "#" through the
4687 end of line. White space can separate pack codes from each
4688 other, but modifiers and repeat counts must follow immediately.
4689 Breaking complex templates into individual line-by-line
4690 components, suitably annotated, can do as much to improve
4691 legibility and maintainability of pack/unpack formats as "/x"
4692 can for complicated pattern matches.
4693 • If TEMPLATE requires more arguments than "pack" is given,
4695 "pack" assumes additional "" arguments. If TEMPLATE requires
4696 fewer arguments than given, extra arguments are ignored.
4697 • Attempting to pack the special floating point values "Inf" and
4699 "NaN" (infinity, also in negative, and not-a-number) into
4700 packed integer values (like "L") is a fatal error. The reason
4701 for this is that there simply isn't any sensible mapping for
4702 these special values into integers.
4703 Examples:
4705 $foo = pack("WWWW",65,66,67,68);
4707 # foo eq "ABCD"
4708 $foo = pack("W4",65,66,67,68);
4709 # same thing
4710 $foo = pack("W4",0x24b6,0x24b7,0x24b8,0x24b9);
4711 # same thing with Unicode circled letters.
4712 $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9);
4713 # same thing with Unicode circled letters. You don't get the
4714 # UTF-8 bytes because the U at the start of the format caused
4715 # a switch to U0-mode, so the UTF-8 bytes get joined into
4716 # characters
4717 $foo = pack("C0U4",0x24b6,0x24b7,0x24b8,0x24b9);
4718 # foo eq "\xe2\x92\xb6\xe2\x92\xb7\xe2\x92\xb8\xe2\x92\xb9"
4719 # This is the UTF-8 encoding of the string in the
4720 # previous example
4721 $foo = pack("ccxxcc",65,66,67,68);
4723 # foo eq "AB\0\0CD"
4724 # NOTE: The examples above featuring "W" and "c" are true
4726 # only on ASCII and ASCII-derived systems such as ISO Latin 1
4727 # and UTF-8. On EBCDIC systems, the first example would be
4728 # $foo = pack("WWWW",193,194,195,196);
4729 $foo = pack("s2",1,2);
4731 # "\001\000\002\000" on little-endian
4732 # "\000\001\000\002" on big-endian
4733 $foo = pack("a4","abcd","x","y","z");
4735 # "abcd"
4736 $foo = pack("aaaa","abcd","x","y","z");
4738 # "axyz"
4739 $foo = pack("a14","abcdefg");
4741 # "abcdefg\0\0\0\0\0\0\0"
4742 $foo = pack("i9pl", gmtime);
4744 # a real struct tm (on my system anyway)
4745 $utmp_template = "Z8 Z8 Z16 L";
4747 $utmp = pack($utmp_template, @utmp1);
4748 # a struct utmp (BSDish)
4749 @utmp2 = unpack($utmp_template, $utmp);
4751 # "@utmp1" eq "@utmp2"
4752 sub bintodec {
4754 unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
4755 }
4756 $foo = pack('sx2l', 12, 34);
4758 # short 12, two zero bytes padding, long 34
4759 $bar = pack('s@4l', 12, 34);
4760 # short 12, zero fill to position 4, long 34
4761 # $foo eq $bar
4762 $baz = pack('s.l', 12, 4, 34);
4763 # short 12, zero fill to position 4, long 34
4764 $foo = pack('nN', 42, 4711);
4766 # pack big-endian 16- and 32-bit unsigned integers
4767 $foo = pack('S>L>', 42, 4711);
4768 # exactly the same
4769 $foo = pack('s<l<', -42, 4711);
4770 # pack little-endian 16- and 32-bit signed integers
4771 $foo = pack('(sl)<', -42, 4711);
4772 # exactly the same
4773 The same template may generally also be used in "unpack".
4775 package NAMESPACE
4777 package NAMESPACE VERSION
4778 package NAMESPACE BLOCK
4779 package NAMESPACE VERSION BLOCK
4780 Declares the BLOCK or the rest of the compilation unit as being in
4781 the given namespace. The scope of the package declaration is
4782 either the supplied code BLOCK or, in the absence of a BLOCK, from
4783 the declaration itself through the end of current scope (the
4784 enclosing block, file, or "eval"). That is, the forms without a
4785 BLOCK are operative through the end of the current scope, just like
4786 the "my", "state", and "our" operators. All unqualified dynamic
4787 identifiers in this scope will be in the given namespace, except
4788 where overridden by another "package" declaration or when they're
4789 one of the special identifiers that qualify into "main::", like
4790 "STDOUT", "ARGV", "ENV", and the punctuation variables.
4791 A package statement affects dynamic variables only, including those
4793 you've used "local" on, but not lexically-scoped variables, which
4794 are created with "my", "state", or "our". Typically it would be
4795 the first declaration in a file included by "require" or "use".
4796 You can switch into a package in more than one place, since this
4797 only determines which default symbol table the compiler uses for
4798 the rest of that block. You can refer to identifiers in other
4799 packages than the current one by prefixing the identifier with the
4800 package name and a double colon, as in $SomePack::var or
4801 "ThatPack::INPUT_HANDLE". If package name is omitted, the "main"
4802 package is assumed. That is, $::sail is equivalent to $main::sail
4803 (as well as to "$main'sail", still seen in ancient code, mostly
4804 from Perl 4).
4805 If VERSION is provided, "package" sets the $VERSION variable in the
4807 given namespace to a version object with the VERSION provided.
4808 VERSION must be a "strict" style version number as defined by the
4809 version module: a positive decimal number (integer or decimal-
4810 fraction) without exponentiation or else a dotted-decimal v-string
4811 with a leading 'v' character and at least three components. You
4812 should set $VERSION only once per package.
4813 See "Packages" in perlmod for more information about packages,
4815 modules, and classes. See perlsub for other scoping issues.
4816 __PACKAGE__
4818 A special token that returns the name of the package in which it
4819 occurs.
4820 pipe READHANDLE,WRITEHANDLE
4822 Opens a pair of connected pipes like the corresponding system call.
4823 Note that if you set up a loop of piped processes, deadlock can
4824 occur unless you are very careful. In addition, note that Perl's
4825 pipes use IO buffering, so you may need to set $| to flush your
4826 WRITEHANDLE after each command, depending on the application.
4827 Returns true on success.
4829 See IPC::Open2, IPC::Open3, and "Bidirectional Communication with
4831 Another Process" in perlipc for examples of such things.
4832 On systems that support a close-on-exec flag on files, that flag is
4834 set on all newly opened file descriptors whose "fileno"s are higher
4835 than the current value of $^F (by default 2 for "STDERR"). See
4836 "$^F" in perlvar.
4837 pop ARRAY
4839 pop Pops and returns the last value of the array, shortening the array
4840 by one element.
4841 Returns the undefined value if the array is empty, although this
4843 may also happen at other times. If ARRAY is omitted, pops the
4844 @ARGV array in the main program, but the @_ array in subroutines,
4845 just like "shift".
4846 Starting with Perl 5.14, an experimental feature allowed "pop" to
4848 take a scalar expression. This experiment has been deemed
4849 unsuccessful, and was removed as of Perl 5.24.
4850 pos SCALAR
4852 pos Returns the offset of where the last "m//g" search left off for the
4853 variable in question ($_ is used when the variable is not
4854 specified). This offset is in characters unless the (no-longer-
4855 recommended) "use bytes" pragma is in effect, in which case the
4856 offset is in bytes. Note that 0 is a valid match offset. "undef"
4857 indicates that the search position is reset (usually due to match
4858 failure, but can also be because no match has yet been run on the
4859 scalar).
4860 "pos" directly accesses the location used by the regexp engine to
4862 store the offset, so assigning to "pos" will change that offset,
4863 and so will also influence the "\G" zero-width assertion in regular
4864 expressions. Both of these effects take place for the next match,
4865 so you can't affect the position with "pos" during the current
4866 match, such as in "(?{pos() = 5})" or "s//pos() = 5/e".
4867 Setting "pos" also resets the matched with zero-length flag,
4869 described under "Repeated Patterns Matching a Zero-length
4870 Substring" in perlre.
4871 Because a failed "m//gc" match doesn't reset the offset, the return
4873 from "pos" won't change either in this case. See perlre and
4874 perlop.
4875 print FILEHANDLE LIST
4877 print FILEHANDLE
4878 print LIST
4879 print
4880 Prints a string or a list of strings. Returns true if successful.
4881 FILEHANDLE may be a scalar variable containing the name of or a
4882 reference to the filehandle, thus introducing one level of
4883 indirection. (NOTE: If FILEHANDLE is a variable and the next token
4884 is a term, it may be misinterpreted as an operator unless you
4885 interpose a "+" or put parentheses around the arguments.) If
4886 FILEHANDLE is omitted, prints to the last selected (see "select")
4887 output handle. If LIST is omitted, prints $_ to the currently
4888 selected output handle. To use FILEHANDLE alone to print the
4889 content of $_ to it, you must use a bareword filehandle like "FH",
4890 not an indirect one like $fh. To set the default output handle to
4891 something other than STDOUT, use the select operation.
4892 The current value of $, (if any) is printed between each LIST item.
4894 The current value of "$\" (if any) is printed after the entire LIST
4895 has been printed. Because print takes a LIST, anything in the LIST
4896 is evaluated in list context, including any subroutines whose
4897 return lists you pass to "print". Be careful not to follow the
4898 print keyword with a left parenthesis unless you want the
4899 corresponding right parenthesis to terminate the arguments to the
4900 print; put parentheses around all arguments (or interpose a "+",
4901 but that doesn't look as good).
4902 If you're storing handles in an array or hash, or in general
4904 whenever you're using any expression more complex than a bareword
4905 handle or a plain, unsubscripted scalar variable to retrieve it,
4906 you will have to use a block returning the filehandle value
4907 instead, in which case the LIST may not be omitted:
4908 print { $files[$i] } "stuff\n";
4910 print { $OK ? *STDOUT : *STDERR } "stuff\n";
4911 Printing to a closed pipe or socket will generate a SIGPIPE signal.
4913 See perlipc for more on signal handling.
4914 printf FILEHANDLE FORMAT, LIST
4916 printf FILEHANDLE
4917 printf FORMAT, LIST
4918 printf
4919 Equivalent to "print FILEHANDLE sprintf(FORMAT, LIST)", except that
4920 "$\" (the output record separator) is not appended. The FORMAT and
4921 the LIST are actually parsed as a single list. The first argument
4922 of the list will be interpreted as the "printf" format. This means
4923 that "printf(@_)" will use $_[0] as the format. See sprintf for an
4924 explanation of the format argument. If "use locale" (including
4925 "use locale ':not_characters'") is in effect and "POSIX::setlocale"
4926 has been called, the character used for the decimal separator in
4927 formatted floating-point numbers is affected by the "LC_NUMERIC"
4928 locale setting. See perllocale and POSIX.
4929 For historical reasons, if you omit the list, $_ is used as the
4931 format; to use FILEHANDLE without a list, you must use a bareword
4932 filehandle like "FH", not an indirect one like $fh. However, this
4933 will rarely do what you want; if $_ contains formatting codes, they
4934 will be replaced with the empty string and a warning will be
4935 emitted if warnings are enabled. Just use "print" if you want to
4936 print the contents of $_.
4937 Don't fall into the trap of using a "printf" when a simple "print"
4939 would do. The "print" is more efficient and less error prone.
4940 prototype FUNCTION
4942 prototype
4943 Returns the prototype of a function as a string (or "undef" if the
4944 function has no prototype). FUNCTION is a reference to, or the
4945 name of, the function whose prototype you want to retrieve. If
4946 FUNCTION is omitted, $_ is used.
4947 If FUNCTION is a string starting with "CORE::", the rest is taken
4949 as a name for a Perl builtin. If the builtin's arguments cannot be
4950 adequately expressed by a prototype (such as "system"), "prototype"
4951 returns "undef", because the builtin does not really behave like a
4952 Perl function. Otherwise, the string describing the equivalent
4953 prototype is returned.
4954 push ARRAY,LIST
4956 Treats ARRAY as a stack by appending the values of LIST to the end
4957 of ARRAY. The length of ARRAY increases by the length of LIST.
4958 Has the same effect as
4959 for my $value (LIST) {
4961 $ARRAY[++$#ARRAY] = $value;
4962 }
4963 but is more efficient. Returns the number of elements in the array
4965 following the completed "push".
4966 Starting with Perl 5.14, an experimental feature allowed "push" to
4968 take a scalar expression. This experiment has been deemed
4969 unsuccessful, and was removed as of Perl 5.24.
4970 q/STRING/
4972 qq/STRING/
4973 qw/STRING/
4974 qx/STRING/
4975 Generalized quotes. See "Quote-Like Operators" in perlop.
4976 qr/STRING/
4978 Regexp-like quote. See "Regexp Quote-Like Operators" in perlop.
4979 quotemeta EXPR
4981 quotemeta
4982 Returns the value of EXPR with all the ASCII non-"word" characters
4983 backslashed. (That is, all ASCII characters not matching
4984 "/[A-Za-z_0-9]/" will be preceded by a backslash in the returned
4985 string, regardless of any locale settings.) This is the internal
4986 function implementing the "\Q" escape in double-quoted strings.
4987 (See below for the behavior on non-ASCII code points.)
4988 If EXPR is omitted, uses $_.
4990 quotemeta (and "\Q" ... "\E") are useful when interpolating strings
4992 into regular expressions, because by default an interpolated
4993 variable will be considered a mini-regular expression. For
4994 example:
4995 my $sentence = 'The quick brown fox jumped over the lazy dog';
4997 my $substring = 'quick.*?fox';
4998 $sentence =~ s{$substring}{big bad wolf};
4999 Will cause $sentence to become 'The big bad wolf jumped over...'.
5001 On the other hand:
5003 my $sentence = 'The quick brown fox jumped over the lazy dog';
5005 my $substring = 'quick.*?fox';
5006 $sentence =~ s{\Q$substring\E}{big bad wolf};
5007 Or:
5009 my $sentence = 'The quick brown fox jumped over the lazy dog';
5011 my $substring = 'quick.*?fox';
5012 my $quoted_substring = quotemeta($substring);
5013 $sentence =~ s{$quoted_substring}{big bad wolf};
5014 Will both leave the sentence as is. Normally, when accepting
5016 literal string input from the user, "quotemeta" or "\Q" must be
5017 used.
5018 Beware that if you put literal backslashes (those not inside
5020 interpolated variables) between "\Q" and "\E", double-quotish
5021 backslash interpolation may lead to confusing results. If you need
5022 to use literal backslashes within "\Q...\E", consult "Gory details
5023 of parsing quoted constructs" in perlop.
5024 Because the result of "\Q STRING \E" has all metacharacters quoted,
5026 there is no way to insert a literal "$" or "@" inside a "\Q\E"
5027 pair. If protected by "\", "$" will be quoted to become "\\\$"; if
5028 not, it is interpreted as the start of an interpolated scalar.
5029 In Perl v5.14, all non-ASCII characters are quoted in
5031 non-UTF-8-encoded strings, but not quoted in UTF-8 strings.
5032 Starting in Perl v5.16, Perl adopted a Unicode-defined strategy for
5034 quoting non-ASCII characters; the quoting of ASCII characters is
5035 unchanged.
5036 Also unchanged is the quoting of non-UTF-8 strings when outside the
5038 scope of a "use feature 'unicode_strings'", which is to quote all
5039 characters in the upper Latin1 range. This provides complete
5040 backwards compatibility for old programs which do not use Unicode.
5041 (Note that "unicode_strings" is automatically enabled within the
5042 scope of a "use v5.12" or greater.)
5043 Within the scope of "use locale", all non-ASCII Latin1 code points
5045 are quoted whether the string is encoded as UTF-8 or not. As
5046 mentioned above, locale does not affect the quoting of ASCII-range
5047 characters. This protects against those locales where characters
5048 such as "|" are considered to be word characters.
5049 Otherwise, Perl quotes non-ASCII characters using an adaptation
5051 from Unicode (see <https://www.unicode.org/reports/tr31/>). The
5052 only code points that are quoted are those that have any of the
5053 Unicode properties: Pattern_Syntax, Pattern_White_Space,
5054 White_Space, Default_Ignorable_Code_Point, or
5055 General_Category=Control.
5056 Of these properties, the two important ones are Pattern_Syntax and
5058 Pattern_White_Space. They have been set up by Unicode for exactly
5059 this purpose of deciding which characters in a regular expression
5060 pattern should be quoted. No character that can be in an
5061 identifier has these properties.
5062 Perl promises, that if we ever add regular expression pattern
5064 metacharacters to the dozen already defined ("\ | ( ) [ { ^ $ * + ?
5065 ."), that we will only use ones that have the Pattern_Syntax
5066 property. Perl also promises, that if we ever add characters that
5067 are considered to be white space in regular expressions (currently
5068 mostly affected by "/x"), they will all have the
5069 Pattern_White_Space property.
5070 Unicode promises that the set of code points that have these two
5072 properties will never change, so something that is not quoted in
5073 v5.16 will never need to be quoted in any future Perl release.
5074 (Not all the code points that match Pattern_Syntax have actually
5075 had characters assigned to them; so there is room to grow, but they
5076 are quoted whether assigned or not. Perl, of course, would never
5077 use an unassigned code point as an actual metacharacter.)
5078 Quoting characters that have the other 3 properties is done to
5080 enhance the readability of the regular expression and not because
5081 they actually need to be quoted for regular expression purposes
5082 (characters with the White_Space property are likely to be
5083 indistinguishable on the page or screen from those with the
5084 Pattern_White_Space property; and the other two properties contain
5085 non-printing characters).
5086 rand EXPR
5088 rand
5089 Returns a random fractional number greater than or equal to 0 and
5090 less than the value of EXPR. (EXPR should be positive.) If EXPR
5091 is omitted, the value 1 is used. Currently EXPR with the value 0
5092 is also special-cased as 1 (this was undocumented before Perl 5.8.0
5093 and is subject to change in future versions of Perl).
5094 Automatically calls "srand" unless "srand" has already been called.
5095 See also "srand".
5096 Apply "int" to the value returned by "rand" if you want random
5098 integers instead of random fractional numbers. For example,
5099 int(rand(10))
5101 returns a random integer between 0 and 9, inclusive.
5103 (Note: If your rand function consistently returns numbers that are
5105 too large or too small, then your version of Perl was probably
5106 compiled with the wrong number of RANDBITS.)
5107 "rand" is not cryptographically secure. You should not rely on it
5109 in security-sensitive situations. As of this writing, a number of
5110 third-party CPAN modules offer random number generators intended by
5111 their authors to be cryptographically secure, including:
5112 Data::Entropy, Crypt::Random, Math::Random::Secure, and
5113 Math::TrulyRandom.
5114 read FILEHANDLE,SCALAR,LENGTH,OFFSET
5116 read FILEHANDLE,SCALAR,LENGTH
5117 Attempts to read LENGTH characters of data into variable SCALAR
5118 from the specified FILEHANDLE. Returns the number of characters
5119 actually read, 0 at end of file, or undef if there was an error (in
5120 the latter case $! is also set). SCALAR will be grown or shrunk so
5121 that the last character actually read is the last character of the
5122 scalar after the read.
5123 An OFFSET may be specified to place the read data at some place in
5125 the string other than the beginning. A negative OFFSET specifies
5126 placement at that many characters counting backwards from the end
5127 of the string. A positive OFFSET greater than the length of SCALAR
5128 results in the string being padded to the required size with "\0"
5129 bytes before the result of the read is appended.
5130 The call is implemented in terms of either Perl's or your system's
5132 native fread(3) library function, via the PerlIO layers applied to
5133 the handle. To get a true read(2) system call, see sysread.
5134 Note the characters: depending on the status of the filehandle,
5136 either (8-bit) bytes or characters are read. By default, all
5137 filehandles operate on bytes, but for example if the filehandle has
5138 been opened with the ":utf8" I/O layer (see "open", and the open
5139 pragma), the I/O will operate on UTF8-encoded Unicode characters,
5140 not bytes. Similarly for the ":encoding" layer: in that case
5141 pretty much any characters can be read.
5142 readdir DIRHANDLE
5144 Returns the next directory entry for a directory opened by
5145 "opendir". If used in list context, returns all the rest of the
5146 entries in the directory. If there are no more entries, returns
5147 the undefined value in scalar context and the empty list in list
5148 context.
5149 If you're planning to filetest the return values out of a
5151 "readdir", you'd better prepend the directory in question.
5152 Otherwise, because we didn't "chdir" there, it would have been
5153 testing the wrong file.
5154 opendir(my $dh, $some_dir) || die "Can't opendir $some_dir: $!";
5156 my @dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh);
5157 closedir $dh;
5158 As of Perl 5.12 you can use a bare "readdir" in a "while" loop,
5160 which will set $_ on every iteration. If either a "readdir"
5161 expression or an explicit assignment of a "readdir" expression to a
5162 scalar is used as a "while"/"for" condition, then the condition
5163 actually tests for definedness of the expression's value, not for
5164 its regular truth value.
5165 opendir(my $dh, $some_dir) || die "Can't open $some_dir: $!";
5167 while (readdir $dh) {
5168 print "$some_dir/$_\n";
5169 }
5170 closedir $dh;
5171 To avoid confusing would-be users of your code who are running
5173 earlier versions of Perl with mysterious failures, put this sort of
5174 thing at the top of your file to signal that your code will work
5175 only on Perls of a recent vintage:
5176 use 5.012; # so readdir assigns to $_ in a lone while test
5178 readline EXPR
5180 readline
5181 Reads from the filehandle whose typeglob is contained in EXPR (or
5182 from *ARGV if EXPR is not provided). In scalar context, each call
5183 reads and returns the next line until end-of-file is reached,
5184 whereupon the subsequent call returns "undef". In list context,
5185 reads until end-of-file is reached and returns a list of lines.
5186 Note that the notion of "line" used here is whatever you may have
5187 defined with $/ (or $INPUT_RECORD_SEPARATOR in English). See "$/"
5188 in perlvar.
5189 When $/ is set to "undef", when "readline" is in scalar context
5191 (i.e., file slurp mode), and when an empty file is read, it returns
5192 '' the first time, followed by "undef" subsequently.
5193 This is the internal function implementing the "<EXPR>" operator,
5195 but you can use it directly. The "<EXPR>" operator is discussed in
5196 more detail in "I/O Operators" in perlop.
5197 my $line = <STDIN>;
5199 my $line = readline(STDIN); # same thing
5200 If "readline" encounters an operating system error, $! will be set
5202 with the corresponding error message. It can be helpful to check
5203 $! when you are reading from filehandles you don't trust, such as a
5204 tty or a socket. The following example uses the operator form of
5205 "readline" and dies if the result is not defined.
5206 while ( ! eof($fh) ) {
5208 defined( $_ = readline $fh ) or die "readline failed: $!";
5209 ...
5210 }
5211 Note that you have can't handle "readline" errors that way with the
5213 "ARGV" filehandle. In that case, you have to open each element of
5214 @ARGV yourself since "eof" handles "ARGV" differently.
5215 foreach my $arg (@ARGV) {
5217 open(my $fh, $arg) or warn "Can't open $arg: $!";
5218 while ( ! eof($fh) ) {
5220 defined( $_ = readline $fh )
5221 or die "readline failed for $arg: $!";
5222 ...
5223 }
5224 }
5225 Like the "<EXPR>" operator, if a "readline" expression is used as
5227 the condition of a "while" or "for" loop, then it will be
5228 implicitly assigned to $_. If either a "readline" expression or an
5229 explicit assignment of a "readline" expression to a scalar is used
5230 as a "while"/"for" condition, then the condition actually tests for
5231 definedness of the expression's value, not for its regular truth
5232 value.
5233 readlink EXPR
5235 readlink
5236 Returns the value of a symbolic link, if symbolic links are
5237 implemented. If not, raises an exception. If there is a system
5238 error, returns the undefined value and sets $! (errno). If EXPR is
5239 omitted, uses $_.
5240 Portability issues: "readlink" in perlport.
5242 readpipe EXPR
5244 readpipe
5245 EXPR is executed as a system command. The collected standard
5246 output of the command is returned. In scalar context, it comes
5247 back as a single (potentially multi-line) string. In list context,
5248 returns a list of lines (however you've defined lines with $/ (or
5249 $INPUT_RECORD_SEPARATOR in English)). This is the internal
5250 function implementing the "qx/EXPR/" operator, but you can use it
5251 directly. The "qx/EXPR/" operator is discussed in more detail in
5252 ""qx/STRING/"" in perlop. If EXPR is omitted, uses $_.
5253 recv SOCKET,SCALAR,LENGTH,FLAGS
5255 Receives a message on a socket. Attempts to receive LENGTH
5256 characters of data into variable SCALAR from the specified SOCKET
5257 filehandle. SCALAR will be grown or shrunk to the length actually
5258 read. Takes the same flags as the system call of the same name.
5259 Returns the address of the sender if SOCKET's protocol supports
5260 this; returns an empty string otherwise. If there's an error,
5261 returns the undefined value. This call is actually implemented in
5262 terms of the recvfrom(2) system call. See "UDP: Message Passing"
5263 in perlipc for examples.
5264 Note that if the socket has been marked as ":utf8", "recv" will
5266 throw an exception. The ":encoding(...)" layer implicitly
5267 introduces the ":utf8" layer. See "binmode".
5268 redo LABEL
5270 redo EXPR
5271 redo
5272 The "redo" command restarts the loop block without evaluating the
5273 conditional again. The "continue" block, if any, is not executed.
5274 If the LABEL is omitted, the command refers to the innermost
5275 enclosing loop. The "redo EXPR" form, available starting in Perl
5276 5.18.0, allows a label name to be computed at run time, and is
5277 otherwise identical to "redo LABEL". Programs that want to lie to
5278 themselves about what was just input normally use this command:
5279 # a simpleminded Pascal comment stripper
5281 # (warning: assumes no { or } in strings)
5282 LINE: while (<STDIN>) {
5283 while (s|({.*}.*){.*}|$1 |) {}
5284 s|{.*}| |;
5285 if (s|{.*| |) {
5286 my $front = $_;
5287 while (<STDIN>) {
5288 if (/}/) { # end of comment?
5289 s|^|$front\{|;
5290 redo LINE;
5291 }
5292 }
5293 }
5294 print;
5295 }
5296 "redo" cannot return a value from a block that typically returns a
5298 value, such as "eval {}", "sub {}", or "do {}". It will perform its
5299 flow control behavior, which precludes any return value. It should
5300 not be used to exit a "grep" or "map" operation.
5301 Note that a block by itself is semantically identical to a loop
5303 that executes once. Thus "redo" inside such a block will
5304 effectively turn it into a looping construct.
5305 See also "continue" for an illustration of how "last", "next", and
5307 "redo" work.
5308 Unlike most named operators, this has the same precedence as
5310 assignment. It is also exempt from the looks-like-a-function rule,
5311 so "redo ("foo")."bar"" will cause "bar" to be part of the argument
5312 to "redo".
5313 ref EXPR
5315 ref Examines the value of EXPR, expecting it to be a reference, and
5316 returns a string giving information about the reference and the
5317 type of referent. If EXPR is not specified, $_ will be used.
5318 If the operand is not a reference, then the empty string will be
5320 returned. An empty string will only be returned in this situation.
5321 "ref" is often useful to just test whether a value is a reference,
5322 which can be done by comparing the result to the empty string. It
5323 is a common mistake to use the result of "ref" directly as a truth
5324 value: this goes wrong because 0 (which is false) can be returned
5325 for a reference.
5326 If the operand is a reference to a blessed object, then the name of
5328 the class into which the referent is blessed will be returned.
5329 "ref" doesn't care what the physical type of the referent is;
5330 blessing takes precedence over such concerns. Beware that exact
5331 comparison of "ref" results against a class name doesn't perform a
5332 class membership test: a class's members also include objects
5333 blessed into subclasses, for which "ref" will return the name of
5334 the subclass. Also beware that class names can clash with the
5335 built-in type names (described below).
5336 If the operand is a reference to an unblessed object, then the
5338 return value indicates the type of object. If the unblessed
5339 referent is not a scalar, then the return value will be one of the
5340 strings "ARRAY", "HASH", "CODE", "FORMAT", or "IO", indicating only
5341 which kind of object it is. If the unblessed referent is a scalar,
5342 then the return value will be one of the strings "SCALAR",
5343 "VSTRING", "REF", "GLOB", "LVALUE", or "REGEXP", depending on the
5344 kind of value the scalar currently has. But note that "qr//"
5345 scalars are created already blessed, so "ref qr/.../" will likely
5346 return "Regexp". Beware that these built-in type names can also be
5347 used as class names, so "ref" returning one of these names doesn't
5348 unambiguously indicate that the referent is of the kind to which
5349 the name refers.
5350 The ambiguity between built-in type names and class names
5352 significantly limits the utility of "ref". For unambiguous
5353 information, use "Scalar::Util::blessed()" for information about
5354 blessing, and "Scalar::Util::reftype()" for information about
5355 physical types. Use the "isa" method for class membership tests,
5356 though one must be sure of blessedness before attempting a method
5357 call.
5358 See also perlref and perlobj.
5360 rename OLDNAME,NEWNAME
5362 Changes the name of a file; an existing file NEWNAME will be
5363 clobbered. Returns true for success; on failure returns false and
5364 sets $!.
5365 Behavior of this function varies wildly depending on your system
5367 implementation. For example, it will usually not work across file
5368 system boundaries, even though the system mv command sometimes
5369 compensates for this. Other restrictions include whether it works
5370 on directories, open files, or pre-existing files. Check perlport
5371 and either the rename(2) manpage or equivalent system documentation
5372 for details.
5373 For a platform independent "move" function look at the File::Copy
5375 module.
5376 Portability issues: "rename" in perlport.
5378 require VERSION
5380 require EXPR
5381 require
5382 Demands a version of Perl specified by VERSION, or demands some
5383 semantics specified by EXPR or by $_ if EXPR is not supplied.
5384 VERSION may be either a literal such as v5.24.1, which will be
5386 compared to $^V (or $PERL_VERSION in English), or a numeric
5387 argument of the form 5.024001, which will be compared to $]. An
5388 exception is raised if VERSION is greater than the version of the
5389 current Perl interpreter. Compare with "use", which can do a
5390 similar check at compile time.
5391 Specifying VERSION as a numeric argument of the form 5.024001
5393 should generally be avoided as older less readable syntax compared
5394 to v5.24.1. Before perl 5.8.0 (released in 2002), the more verbose
5395 numeric form was the only supported syntax, which is why you might
5396 see it in older code.
5397 require v5.24.1; # run time version check
5399 require 5.24.1; # ditto
5400 require 5.024_001; # ditto; older syntax compatible
5401 with perl 5.6
5402 Otherwise, "require" demands that a library file be included if it
5404 hasn't already been included. The file is included via the do-FILE
5405 mechanism, which is essentially just a variety of "eval" with the
5406 caveat that lexical variables in the invoking script will be
5407 invisible to the included code. If it were implemented in pure
5408 Perl, it would have semantics similar to the following:
5409 use Carp 'croak';
5411 use version;
5412 sub require {
5414 my ($filename) = @_;
5415 if ( my $version = eval { version->parse($filename) } ) {
5416 if ( $version > $^V ) {
5417 my $vn = $version->normal;
5418 croak "Perl $vn required--this is only $^V, stopped";
5419 }
5420 return 1;
5421 }
5422 if (exists $INC{$filename}) {
5424 return 1 if $INC{$filename};
5425 croak "Compilation failed in require";
5426 }
5427 foreach $prefix (@INC) {
5429 if (ref($prefix)) {
5430 #... do other stuff - see text below ....
5431 }
5432 # (see text below about possible appending of .pmc
5433 # suffix to $filename)
5434 my $realfilename = "$prefix/$filename";
5435 next if ! -e $realfilename || -d _ || -b _;
5436 $INC{$filename} = $realfilename;
5437 my $result = do($realfilename);
5438 # but run in caller's namespace
5439 if (!defined $result) {
5441 $INC{$filename} = undef;
5442 croak $@ ? "$@Compilation failed in require"
5443 : "Can't locate $filename: $!\n";
5444 }
5445 if (!$result) {
5446 delete $INC{$filename};
5447 croak "$filename did not return true value";
5448 }
5449 $! = 0;
5450 return $result;
5451 }
5452 croak "Can't locate $filename in \@INC ...";
5453 }
5454 Note that the file will not be included twice under the same
5456 specified name.
5457 The file must return true as the last statement to indicate
5459 successful execution of any initialization code, so it's customary
5460 to end such a file with "1;" unless you're sure it'll return true
5461 otherwise. But it's better just to put the "1;", in case you add
5462 more statements.
5463 If EXPR is a bareword, "require" assumes a .pm extension and
5465 replaces "::" with "/" in the filename for you, to make it easy to
5466 load standard modules. This form of loading of modules does not
5467 risk altering your namespace, however it will autovivify the stash
5468 for the required module.
5469 In other words, if you try this:
5471 require Foo::Bar; # a splendid bareword
5473 The require function will actually look for the Foo/Bar.pm file in
5475 the directories specified in the @INC array, and it will autovivify
5476 the "Foo::Bar::" stash at compile time.
5477 But if you try this:
5479 my $class = 'Foo::Bar';
5481 require $class; # $class is not a bareword
5482 #or
5483 require "Foo::Bar"; # not a bareword because of the ""
5484 The require function will look for the Foo::Bar file in the @INC
5486 array and will complain about not finding Foo::Bar there. In this
5487 case you can do:
5488 eval "require $class";
5490 or you could do
5492 require "Foo/Bar.pm";
5494 Neither of these forms will autovivify any stashes at compile time
5496 and only have run time effects.
5497 Now that you understand how "require" looks for files with a
5499 bareword argument, there is a little extra functionality going on
5500 behind the scenes. Before "require" looks for a .pm extension, it
5501 will first look for a similar filename with a .pmc extension. If
5502 this file is found, it will be loaded in place of any file ending
5503 in a .pm extension. This applies to both the explicit "require
5504 "Foo/Bar.pm";" form and the "require Foo::Bar;" form.
5505 You can also insert hooks into the import facility by putting Perl
5507 code directly into the @INC array. There are three forms of hooks:
5508 subroutine references, array references, and blessed objects.
5509 Subroutine references are the simplest case. When the inclusion
5511 system walks through @INC and encounters a subroutine, this
5512 subroutine gets called with two parameters, the first a reference
5513 to itself, and the second the name of the file to be included
5514 (e.g., Foo/Bar.pm). The subroutine should return either nothing or
5515 else a list of up to four values in the following order:
5516 1. A reference to a scalar, containing any initial source code to
5518 prepend to the file or generator output.
5519 2. A filehandle, from which the file will be read.
5521 3. A reference to a subroutine. If there is no filehandle
5523 (previous item), then this subroutine is expected to generate
5524 one line of source code per call, writing the line into $_ and
5525 returning 1, then finally at end of file returning 0. If there
5526 is a filehandle, then the subroutine will be called to act as a
5527 simple source filter, with the line as read in $_. Again,
5528 return 1 for each valid line, and 0 after all lines have been
5529 returned. For historical reasons the subroutine will receive a
5530 meaningless argument (in fact always the numeric value zero) as
5531 $_[0].
5532 4. Optional state for the subroutine. The state is passed in as
5534 $_[1].
5535 If an empty list, "undef", or nothing that matches the first 3
5537 values above is returned, then "require" looks at the remaining
5538 elements of @INC. Note that this filehandle must be a real
5539 filehandle (strictly a typeglob or reference to a typeglob, whether
5540 blessed or unblessed); tied filehandles will be ignored and
5541 processing will stop there.
5542 If the hook is an array reference, its first element must be a
5544 subroutine reference. This subroutine is called as above, but the
5545 first parameter is the array reference. This lets you indirectly
5546 pass arguments to the subroutine.
5547 In other words, you can write:
5549 push @INC, \&my_sub;
5551 sub my_sub {
5552 my ($coderef, $filename) = @_; # $coderef is \&my_sub
5553 ...
5554 }
5555 or:
5557 push @INC, [ \&my_sub, $x, $y, ... ];
5559 sub my_sub {
5560 my ($arrayref, $filename) = @_;
5561 # Retrieve $x, $y, ...
5562 my (undef, @parameters) = @$arrayref;
5563 ...
5564 }
5565 If the hook is an object, it must provide an "INC" method that will
5567 be called as above, the first parameter being the object itself.
5568 (Note that you must fully qualify the sub's name, as unqualified
5569 "INC" is always forced into package "main".) Here is a typical
5570 code layout:
5571 # In Foo.pm
5573 package Foo;
5574 sub new { ... }
5575 sub Foo::INC {
5576 my ($self, $filename) = @_;
5577 ...
5578 }
5579 # In the main program
5581 push @INC, Foo->new(...);
5582 These hooks are also permitted to set the %INC entry corresponding
5584 to the files they have loaded. See "%INC" in perlvar.
5585 For a yet-more-powerful import facility, see "use" and perlmod.
5587 reset EXPR
5589 reset
5590 Generally used in a "continue" block at the end of a loop to clear
5591 variables and reset "m?pattern?" searches so that they work again.
5592 The expression is interpreted as a list of single characters
5593 (hyphens allowed for ranges). All variables (scalars, arrays, and
5594 hashes) in the current package beginning with one of those letters
5595 are reset to their pristine state. If the expression is omitted,
5596 one-match searches ("m?pattern?") are reset to match again. Only
5597 resets variables or searches in the current package. Always
5598 returns 1. Examples:
5599 reset 'X'; # reset all X variables
5601 reset 'a-z'; # reset lower case variables
5602 reset; # just reset m?one-time? searches
5603 Resetting "A-Z" is not recommended because you'll wipe out your
5605 @ARGV and @INC arrays and your %ENV hash.
5606 Resets only package variables; lexical variables are unaffected,
5608 but they clean themselves up on scope exit anyway, so you'll
5609 probably want to use them instead. See "my".
5610 return EXPR
5612 return
5613 Returns from a subroutine, "eval", "do FILE", "sort" block or regex
5614 eval block (but not a "grep", "map", or "do BLOCK" block) with the
5615 value given in EXPR. Evaluation of EXPR may be in list, scalar, or
5616 void context, depending on how the return value will be used, and
5617 the context may vary from one execution to the next (see
5618 "wantarray"). If no EXPR is given, returns an empty list in list
5619 context, the undefined value in scalar context, and (of course)
5620 nothing at all in void context.
5621 (In the absence of an explicit "return", a subroutine, "eval", or
5623 "do FILE" automatically returns the value of the last expression
5624 evaluated.)
5625 Unlike most named operators, this is also exempt from the looks-
5627 like-a-function rule, so "return ("foo")."bar"" will cause "bar" to
5628 be part of the argument to "return".
5629 reverse LIST
5631 In list context, returns a list value consisting of the elements of
5632 LIST in the opposite order. In scalar context, concatenates the
5633 elements of LIST and returns a string value with all characters in
5634 the opposite order.
5635 print join(", ", reverse "world", "Hello"); # Hello, world
5637 print scalar reverse "dlrow ,", "olleH"; # Hello, world
5639 Used without arguments in scalar context, "reverse" reverses $_.
5641 $_ = "dlrow ,olleH";
5643 print reverse; # No output, list context
5644 print scalar reverse; # Hello, world
5645 Note that reversing an array to itself (as in "@a = reverse @a")
5647 will preserve non-existent elements whenever possible; i.e., for
5648 non-magical arrays or for tied arrays with "EXISTS" and "DELETE"
5649 methods.
5650 This operator is also handy for inverting a hash, although there
5652 are some caveats. If a value is duplicated in the original hash,
5653 only one of those can be represented as a key in the inverted hash.
5654 Also, this has to unwind one hash and build a whole new one, which
5655 may take some time on a large hash, such as from a DBM file.
5656 my %by_name = reverse %by_address; # Invert the hash
5658 rewinddir DIRHANDLE
5660 Sets the current position to the beginning of the directory for the
5661 "readdir" routine on DIRHANDLE.
5662 Portability issues: "rewinddir" in perlport.
5664 rindex STR,SUBSTR,POSITION
5666 rindex STR,SUBSTR
5667 Works just like "index" except that it returns the position of the
5668 last occurrence of SUBSTR in STR. If POSITION is specified,
5669 returns the last occurrence beginning at or before that position.
5670 rmdir FILENAME
5672 rmdir
5673 Deletes the directory specified by FILENAME if that directory is
5674 empty. If it succeeds it returns true; otherwise it returns false
5675 and sets $! (errno). If FILENAME is omitted, uses $_.
5676 To remove a directory tree recursively ("rm -rf" on Unix) look at
5678 the "rmtree" function of the File::Path module.
5679 s///
5681 The substitution operator. See "Regexp Quote-Like Operators" in
5682 perlop.
5683 say FILEHANDLE LIST
5685 say FILEHANDLE
5686 say LIST
5687 say Just like "print", but implicitly appends a newline at the end of
5688 the LIST instead of any value "$\" might have. To use FILEHANDLE
5689 without a LIST to print the contents of $_ to it, you must use a
5690 bareword filehandle like "FH", not an indirect one like $fh.
5691 "say" is available only if the "say" feature is enabled or if it is
5693 prefixed with "CORE::". The "say" feature is enabled automatically
5694 with a "use v5.10" (or higher) declaration in the current scope.
5695 scalar EXPR
5697 Forces EXPR to be interpreted in scalar context and returns the
5698 value of EXPR.
5699 my @counts = ( scalar @a, scalar @b, scalar @c );
5701 There is no equivalent operator to force an expression to be
5703 interpolated in list context because in practice, this is never
5704 needed. If you really wanted to do so, however, you could use the
5705 construction "@{[ (some expression) ]}", but usually a simple
5706 "(some expression)" suffices.
5707 Because "scalar" is a unary operator, if you accidentally use a
5709 parenthesized list for the EXPR, this behaves as a scalar comma
5710 expression, evaluating all but the last element in void context and
5711 returning the final element evaluated in scalar context. This is
5712 seldom what you want.
5713 The following single statement:
5715 print uc(scalar(foo(), $bar)), $baz;
5717 is the moral equivalent of these two:
5719 foo();
5721 print(uc($bar), $baz);
5722 See perlop for more details on unary operators and the comma
5724 operator, and perldata for details on evaluating a hash in scalar
5725 context.
5726 seek FILEHANDLE,POSITION,WHENCE
5728 Sets FILEHANDLE's position, just like the fseek(3) call of C
5729 "stdio". FILEHANDLE may be an expression whose value gives the
5730 name of the filehandle. The values for WHENCE are 0 to set the new
5731 position in bytes to POSITION; 1 to set it to the current position
5732 plus POSITION; and 2 to set it to EOF plus POSITION, typically
5733 negative. For WHENCE you may use the constants "SEEK_SET",
5734 "SEEK_CUR", and "SEEK_END" (start of the file, current position,
5735 end of the file) from the Fcntl module. Returns 1 on success,
5736 false otherwise.
5737 Note the emphasis on bytes: even if the filehandle has been set to
5739 operate on characters (for example using the ":encoding(UTF-8)" I/O
5740 layer), the "seek", "tell", and "sysseek" family of functions use
5741 byte offsets, not character offsets, because seeking to a character
5742 offset would be very slow in a UTF-8 file.
5743 If you want to position the file for "sysread" or "syswrite", don't
5745 use "seek", because buffering makes its effect on the file's read-
5746 write position unpredictable and non-portable. Use "sysseek"
5747 instead.
5748 Due to the rules and rigors of ANSI C, on some systems you have to
5750 do a seek whenever you switch between reading and writing. Amongst
5751 other things, this may have the effect of calling stdio's
5752 clearerr(3). A WHENCE of 1 ("SEEK_CUR") is useful for not moving
5753 the file position:
5754 seek($fh, 0, 1);
5756 This is also useful for applications emulating "tail -f". Once you
5758 hit EOF on your read and then sleep for a while, you (probably)
5759 have to stick in a dummy "seek" to reset things. The "seek"
5760 doesn't change the position, but it does clear the end-of-file
5761 condition on the handle, so that the next "readline FILE" makes
5762 Perl try again to read something. (We hope.)
5763 If that doesn't work (some I/O implementations are particularly
5765 cantankerous), you might need something like this:
5766 for (;;) {
5768 for ($curpos = tell($fh); $_ = readline($fh);
5769 $curpos = tell($fh)) {
5770 # search for some stuff and put it into files
5771 }
5772 sleep($for_a_while);
5773 seek($fh, $curpos, 0);
5774 }
5775 seekdir DIRHANDLE,POS
5777 Sets the current position for the "readdir" routine on DIRHANDLE.
5778 POS must be a value returned by "telldir". "seekdir" also has the
5779 same caveats about possible directory compaction as the
5780 corresponding system library routine.
5781 select FILEHANDLE
5783 select
5784 Returns the currently selected filehandle. If FILEHANDLE is
5785 supplied, sets the new current default filehandle for output. This
5786 has two effects: first, a "write" or a "print" without a filehandle
5787 default to this FILEHANDLE. Second, references to variables
5788 related to output will refer to this output channel.
5789 For example, to set the top-of-form format for more than one output
5791 channel, you might do the following:
5792 select(REPORT1);
5794 $^ = 'report1_top';
5795 select(REPORT2);
5796 $^ = 'report2_top';
5797 FILEHANDLE may be an expression whose value gives the name of the
5799 actual filehandle. Thus:
5800 my $oldfh = select(STDERR); $| = 1; select($oldfh);
5802 Some programmers may prefer to think of filehandles as objects with
5804 methods, preferring to write the last example as:
5805 STDERR->autoflush(1);
5807 (Prior to Perl version 5.14, you have to "use IO::Handle;"
5809 explicitly first.)
5810 Portability issues: "select" in perlport.
5812 select RBITS,WBITS,EBITS,TIMEOUT
5814 This calls the select(2) syscall with the bit masks specified,
5815 which can be constructed using "fileno" and "vec", along these
5816 lines:
5817 my $rin = my $win = my $ein = '';
5819 vec($rin, fileno(STDIN), 1) = 1;
5820 vec($win, fileno(STDOUT), 1) = 1;
5821 $ein = $rin | $win;
5822 If you want to select on many filehandles, you may wish to write a
5824 subroutine like this:
5825 sub fhbits {
5827 my @fhlist = @_;
5828 my $bits = "";
5829 for my $fh (@fhlist) {
5830 vec($bits, fileno($fh), 1) = 1;
5831 }
5832 return $bits;
5833 }
5834 my $rin = fhbits(\*STDIN, $tty, $mysock);
5835 The usual idiom is:
5837 my ($nfound, $timeleft) =
5839 select(my $rout = $rin, my $wout = $win, my $eout = $ein,
5840 $timeout);
5841 or to block until something becomes ready just do this
5843 my $nfound =
5845 select(my $rout = $rin, my $wout = $win, my $eout = $ein, undef);
5846 Most systems do not bother to return anything useful in $timeleft,
5848 so calling "select" in scalar context just returns $nfound.
5849 Any of the bit masks can also be "undef". The timeout, if
5851 specified, is in seconds, which may be fractional. Note: not all
5852 implementations are capable of returning the $timeleft. If not,
5853 they always return $timeleft equal to the supplied $timeout.
5854 You can effect a sleep of 250 milliseconds this way:
5856 select(undef, undef, undef, 0.25);
5858 Note that whether "select" gets restarted after signals (say,
5860 SIGALRM) is implementation-dependent. See also perlport for notes
5861 on the portability of "select".
5862 On error, "select" behaves just like select(2): it returns "-1" and
5864 sets $!.
5865 On some Unixes, select(2) may report a socket file descriptor as
5867 "ready for reading" even when no data is available, and thus any
5868 subsequent "read" would block. This can be avoided if you always
5869 use "O_NONBLOCK" on the socket. See select(2) and fcntl(2) for
5870 further details.
5871 The standard "IO::Select" module provides a user-friendlier
5873 interface to "select", mostly because it does all the bit-mask work
5874 for you.
5875 WARNING: One should not attempt to mix buffered I/O (like "read" or
5877 "readline") with "select", except as permitted by POSIX, and even
5878 then only on POSIX systems. You have to use "sysread" instead.
5879 Portability issues: "select" in perlport.
5881 semctl ID,SEMNUM,CMD,ARG
5883 Calls the System V IPC function semctl(2). You'll probably have to
5884 say
5885 use IPC::SysV;
5887 first to get the correct constant definitions. If CMD is IPC_STAT
5889 or GETALL, then ARG must be a variable that will hold the returned
5890 semid_ds structure or semaphore value array. Returns like "ioctl":
5891 the undefined value for error, ""0 but true"" for zero, or the
5892 actual return value otherwise. The ARG must consist of a vector of
5893 native short integers, which may be created with
5894 "pack("s!",(0)x$nsem)". See also "SysV IPC" in perlipc and the
5895 documentation for "IPC::SysV" and "IPC::Semaphore".
5896 Portability issues: "semctl" in perlport.
5898 semget KEY,NSEMS,FLAGS
5900 Calls the System V IPC function semget(2). Returns the semaphore
5901 id, or the undefined value on error. See also "SysV IPC" in
5902 perlipc and the documentation for "IPC::SysV" and "IPC::Semaphore".
5903 Portability issues: "semget" in perlport.
5905 semop KEY,OPSTRING
5907 Calls the System V IPC function semop(2) for semaphore operations
5908 such as signalling and waiting. OPSTRING must be a packed array of
5909 semop structures. Each semop structure can be generated with
5910 "pack("s!3", $semnum, $semop, $semflag)". The length of OPSTRING
5911 implies the number of semaphore operations. Returns true if
5912 successful, false on error. As an example, the following code
5913 waits on semaphore $semnum of semaphore id $semid:
5914 my $semop = pack("s!3", $semnum, -1, 0);
5916 die "Semaphore trouble: $!\n" unless semop($semid, $semop);
5917 To signal the semaphore, replace "-1" with 1. See also "SysV IPC"
5919 in perlipc and the documentation for "IPC::SysV" and
5920 "IPC::Semaphore".
5921 Portability issues: "semop" in perlport.
5923 send SOCKET,MSG,FLAGS,TO
5925 send SOCKET,MSG,FLAGS
5926 Sends a message on a socket. Attempts to send the scalar MSG to
5927 the SOCKET filehandle. Takes the same flags as the system call of
5928 the same name. On unconnected sockets, you must specify a
5929 destination to send to, in which case it does a sendto(2) syscall.
5930 Returns the number of characters sent, or the undefined value on
5931 error. The sendmsg(2) syscall is currently unimplemented. See
5932 "UDP: Message Passing" in perlipc for examples.
5933 Note that if the socket has been marked as ":utf8", "send" will
5935 throw an exception. The ":encoding(...)" layer implicitly
5936 introduces the ":utf8" layer. See "binmode".
5937 setpgrp PID,PGRP
5939 Sets the current process group for the specified PID, 0 for the
5940 current process. Raises an exception when used on a machine that
5941 doesn't implement POSIX setpgid(2) or BSD setpgrp(2). If the
5942 arguments are omitted, it defaults to "0,0". Note that the BSD 4.2
5943 version of "setpgrp" does not accept any arguments, so only
5944 "setpgrp(0,0)" is portable. See also "POSIX::setsid()".
5945 Portability issues: "setpgrp" in perlport.
5947 setpriority WHICH,WHO,PRIORITY
5949 Sets the current priority for a process, a process group, or a
5950 user. (See setpriority(2).) Raises an exception when used on a
5951 machine that doesn't implement setpriority(2).
5952 "WHICH" can be any of "PRIO_PROCESS", "PRIO_PGRP" or "PRIO_USER"
5954 imported from "RESOURCE CONSTANTS" in POSIX.
5955 Portability issues: "setpriority" in perlport.
5957 setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
5959 Sets the socket option requested. Returns "undef" on error. Use
5960 integer constants provided by the "Socket" module for LEVEL and
5961 OPNAME. Values for LEVEL can also be obtained from getprotobyname.
5962 OPTVAL might either be a packed string or an integer. An integer
5963 OPTVAL is shorthand for pack("i", OPTVAL).
5964 An example disabling Nagle's algorithm on a socket:
5966 use Socket qw(IPPROTO_TCP TCP_NODELAY);
5968 setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
5969 Portability issues: "setsockopt" in perlport.
5971 shift ARRAY
5973 shift
5974 Shifts the first value of the array off and returns it, shortening
5975 the array by 1 and moving everything down. If there are no
5976 elements in the array, returns the undefined value. If ARRAY is
5977 omitted, shifts the @_ array within the lexical scope of
5978 subroutines and formats, and the @ARGV array outside a subroutine
5979 and also within the lexical scopes established by the "eval
5980 STRING", "BEGIN {}", "INIT {}", "CHECK {}", "UNITCHECK {}", and
5981 "END {}" constructs.
5982 Starting with Perl 5.14, an experimental feature allowed "shift" to
5984 take a scalar expression. This experiment has been deemed
5985 unsuccessful, and was removed as of Perl 5.24.
5986 See also "unshift", "push", and "pop". "shift" and "unshift" do
5988 the same thing to the left end of an array that "pop" and "push" do
5989 to the right end.
5990 shmctl ID,CMD,ARG
5992 Calls the System V IPC function shmctl. You'll probably have to
5993 say
5994 use IPC::SysV;
5996 first to get the correct constant definitions. If CMD is
5998 "IPC_STAT", then ARG must be a variable that will hold the returned
5999 "shmid_ds" structure. Returns like ioctl: "undef" for error; "0
6000 but true" for zero; and the actual return value otherwise. See
6001 also "SysV IPC" in perlipc and the documentation for "IPC::SysV".
6002 Portability issues: "shmctl" in perlport.
6004 shmget KEY,SIZE,FLAGS
6006 Calls the System V IPC function shmget. Returns the shared memory
6007 segment id, or "undef" on error. See also "SysV IPC" in perlipc
6008 and the documentation for "IPC::SysV".
6009 Portability issues: "shmget" in perlport.
6011 shmread ID,VAR,POS,SIZE
6013 shmwrite ID,STRING,POS,SIZE
6014 Reads or writes the System V shared memory segment ID starting at
6015 position POS for size SIZE by attaching to it, copying in/out, and
6016 detaching from it. When reading, VAR must be a variable that will
6017 hold the data read. When writing, if STRING is too long, only SIZE
6018 bytes are used; if STRING is too short, nulls are written to fill
6019 out SIZE bytes. Return true if successful, false on error.
6020 "shmread" taints the variable. See also "SysV IPC" in perlipc and
6021 the documentation for "IPC::SysV" and the "IPC::Shareable" module
6022 from CPAN.
6023 Portability issues: "shmread" in perlport and "shmwrite" in
6025 perlport.
6026 shutdown SOCKET,HOW
6028 Shuts down a socket connection in the manner indicated by HOW,
6029 which has the same interpretation as in the syscall of the same
6030 name.
6031 shutdown($socket, 0); # I/we have stopped reading data
6033 shutdown($socket, 1); # I/we have stopped writing data
6034 shutdown($socket, 2); # I/we have stopped using this socket
6035 This is useful with sockets when you want to tell the other side
6037 you're done writing but not done reading, or vice versa. It's also
6038 a more insistent form of close because it also disables the file
6039 descriptor in any forked copies in other processes.
6040 Returns 1 for success; on error, returns "undef" if the first
6042 argument is not a valid filehandle, or returns 0 and sets $! for
6043 any other failure.
6044 sin EXPR
6046 sin Returns the sine of EXPR (expressed in radians). If EXPR is
6047 omitted, returns sine of $_.
6048 For the inverse sine operation, you may use the "Math::Trig::asin"
6050 function, or use this relation:
6051 sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
6053 sleep EXPR
6055 sleep
6056 Causes the script to sleep for (integer) EXPR seconds, or forever
6057 if no argument is given. Returns the integer number of seconds
6058 actually slept.
6059 EXPR should be a positive integer. If called with a negative
6061 integer, "sleep" does not sleep but instead emits a warning, sets
6062 $! ("errno"), and returns zero.
6063 "sleep 0" is permitted, but a function call to the underlying
6065 platform implementation still occurs, with any side effects that
6066 may have. "sleep 0" is therefore not exactly identical to not
6067 sleeping at all.
6068 May be interrupted if the process receives a signal such as
6070 "SIGALRM".
6071 eval {
6073 local $SIG{ALRM} = sub { die "Alarm!\n" };
6074 sleep;
6075 };
6076 die $@ unless $@ eq "Alarm!\n";
6077 You probably cannot mix "alarm" and "sleep" calls, because "sleep"
6079 is often implemented using "alarm".
6080 On some older systems, it may sleep up to a full second less than
6082 what you requested, depending on how it counts seconds. Most
6083 modern systems always sleep the full amount. They may appear to
6084 sleep longer than that, however, because your process might not be
6085 scheduled right away in a busy multitasking system.
6086 For delays of finer granularity than one second, the Time::HiRes
6088 module (from CPAN, and starting from Perl 5.8 part of the standard
6089 distribution) provides "usleep". You may also use Perl's four-
6090 argument version of "select" leaving the first three arguments
6091 undefined, or you might be able to use the "syscall" interface to
6092 access setitimer(2) if your system supports it. See perlfaq8 for
6093 details.
6094 See also the POSIX module's "pause" function.
6096 socket SOCKET,DOMAIN,TYPE,PROTOCOL
6098 Opens a socket of the specified kind and attaches it to filehandle
6099 SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for
6100 the syscall of the same name. You should "use Socket" first to get
6101 the proper definitions imported. See the examples in "Sockets:
6102 Client/Server Communication" in perlipc.
6103 On systems that support a close-on-exec flag on files, the flag
6105 will be set for the newly opened file descriptor, as determined by
6106 the value of $^F. See "$^F" in perlvar.
6107 socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
6109 Creates an unnamed pair of sockets in the specified domain, of the
6110 specified type. DOMAIN, TYPE, and PROTOCOL are specified the same
6111 as for the syscall of the same name. If unimplemented, raises an
6112 exception. Returns true if successful.
6113 On systems that support a close-on-exec flag on files, the flag
6115 will be set for the newly opened file descriptors, as determined by
6116 the value of $^F. See "$^F" in perlvar.
6117 Some systems define "pipe" in terms of "socketpair", in which a
6119 call to "pipe($rdr, $wtr)" is essentially:
6120 use Socket;
6122 socketpair(my $rdr, my $wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC);
6123 shutdown($rdr, 1); # no more writing for reader
6124 shutdown($wtr, 0); # no more reading for writer
6125 See perlipc for an example of socketpair use. Perl 5.8 and later
6127 will emulate socketpair using IP sockets to localhost if your
6128 system implements sockets but not socketpair.
6129 Portability issues: "socketpair" in perlport.
6131 sort SUBNAME LIST
6133 sort BLOCK LIST
6134 sort LIST
6135 In list context, this sorts the LIST and returns the sorted list
6136 value. In scalar context, the behaviour of "sort" is undefined.
6137 If SUBNAME or BLOCK is omitted, "sort"s in standard string
6139 comparison order. If SUBNAME is specified, it gives the name of a
6140 subroutine that returns an integer less than, equal to, or greater
6141 than 0, depending on how the elements of the list are to be
6142 ordered. (The "<=>" and "cmp" operators are extremely useful in
6143 such routines.) SUBNAME may be a scalar variable name
6144 (unsubscripted), in which case the value provides the name of (or a
6145 reference to) the actual subroutine to use. In place of a SUBNAME,
6146 you can provide a BLOCK as an anonymous, in-line sort subroutine.
6147 If the subroutine's prototype is "($$)", the elements to be
6149 compared are passed by reference in @_, as for a normal subroutine.
6150 This is slower than unprototyped subroutines, where the elements to
6151 be compared are passed into the subroutine as the package global
6152 variables $a and $b (see example below).
6153 If the subroutine is an XSUB, the elements to be compared are
6155 pushed on to the stack, the way arguments are usually passed to
6156 XSUBs. $a and $b are not set.
6157 The values to be compared are always passed by reference and should
6159 not be modified.
6160 You also cannot exit out of the sort block or subroutine using any
6162 of the loop control operators described in perlsyn or with "goto".
6163 When "use locale" (but not "use locale ':not_characters'") is in
6165 effect, "sort LIST" sorts LIST according to the current collation
6166 locale. See perllocale.
6167 "sort" returns aliases into the original list, much as a for loop's
6169 index variable aliases the list elements. That is, modifying an
6170 element of a list returned by "sort" (for example, in a "foreach",
6171 "map" or "grep") actually modifies the element in the original
6172 list. This is usually something to be avoided when writing clear
6173 code.
6174 Historically Perl has varied in whether sorting is stable by
6176 default. If stability matters, it can be controlled explicitly by
6177 using the sort pragma.
6178 Examples:
6180 # sort lexically
6182 my @articles = sort @files;
6183 # same thing, but with explicit sort routine
6185 my @articles = sort {$a cmp $b} @files;
6186 # now case-insensitively
6188 my @articles = sort {fc($a) cmp fc($b)} @files;
6189 # same thing in reversed order
6191 my @articles = sort {$b cmp $a} @files;
6192 # sort numerically ascending
6194 my @articles = sort {$a <=> $b} @files;
6195 # sort numerically descending
6197 my @articles = sort {$b <=> $a} @files;
6198 # this sorts the %age hash by value instead of key
6200 # using an in-line function
6201 my @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
6202 # sort using explicit subroutine name
6204 sub byage {
6205 $age{$a} <=> $age{$b}; # presuming numeric
6206 }
6207 my @sortedclass = sort byage @class;
6208 sub backwards { $b cmp $a }
6210 my @harry = qw(dog cat x Cain Abel);
6211 my @george = qw(gone chased yz Punished Axed);
6212 print sort @harry;
6213 # prints AbelCaincatdogx
6214 print sort backwards @harry;
6215 # prints xdogcatCainAbel
6216 print sort @george, 'to', @harry;
6217 # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
6218 # inefficiently sort by descending numeric compare using
6220 # the first integer after the first = sign, or the
6221 # whole record case-insensitively otherwise
6222 my @new = sort {
6224 ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
6225 ||
6226 fc($a) cmp fc($b)
6227 } @old;
6228 # same thing, but much more efficiently;
6230 # we'll build auxiliary indices instead
6231 # for speed
6232 my (@nums, @caps);
6233 for (@old) {
6234 push @nums, ( /=(\d+)/ ? $1 : undef );
6235 push @caps, fc($_);
6236 }
6237 my @new = @old[ sort {
6239 $nums[$b] <=> $nums[$a]
6240 ||
6241 $caps[$a] cmp $caps[$b]
6242 } 0..$#old
6243 ];
6244 # same thing, but without any temps
6246 my @new = map { $_->[0] }
6247 sort { $b->[1] <=> $a->[1]
6248 ||
6249 $a->[2] cmp $b->[2]
6250 } map { [$_, /=(\d+)/, fc($_)] } @old;
6251 # using a prototype allows you to use any comparison subroutine
6253 # as a sort subroutine (including other package's subroutines)
6254 package Other;
6255 sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are
6256 # not set here
6257 package main;
6258 my @new = sort Other::backwards @old;
6259 # guarantee stability
6261 use sort 'stable';
6262 my @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
6263 Warning: syntactical care is required when sorting the list
6265 returned from a function. If you want to sort the list returned by
6266 the function call "find_records(@key)", you can use:
6267 my @contact = sort { $a cmp $b } find_records @key;
6269 my @contact = sort +find_records(@key);
6270 my @contact = sort &find_records(@key);
6271 my @contact = sort(find_records(@key));
6272 If instead you want to sort the array @key with the comparison
6274 routine "find_records()" then you can use:
6275 my @contact = sort { find_records() } @key;
6277 my @contact = sort find_records(@key);
6278 my @contact = sort(find_records @key);
6279 my @contact = sort(find_records (@key));
6280 $a and $b are set as package globals in the package the sort() is
6282 called from. That means $main::a and $main::b (or $::a and $::b)
6283 in the "main" package, $FooPack::a and $FooPack::b in the "FooPack"
6284 package, etc. If the sort block is in scope of a "my" or "state"
6285 declaration of $a and/or $b, you must spell out the full name of
6286 the variables in the sort block :
6287 package main;
6289 my $a = "C"; # DANGER, Will Robinson, DANGER !!!
6290 print sort { $a cmp $b } qw(A C E G B D F H);
6292 # WRONG
6293 sub badlexi { $a cmp $b }
6294 print sort badlexi qw(A C E G B D F H);
6295 # WRONG
6296 # the above prints BACFEDGH or some other incorrect ordering
6297 print sort { $::a cmp $::b } qw(A C E G B D F H);
6299 # OK
6300 print sort { our $a cmp our $b } qw(A C E G B D F H);
6301 # also OK
6302 print sort { our ($a, $b); $a cmp $b } qw(A C E G B D F H);
6303 # also OK
6304 sub lexi { our $a cmp our $b }
6305 print sort lexi qw(A C E G B D F H);
6306 # also OK
6307 # the above print ABCDEFGH
6308 With proper care you may mix package and my (or state) $a and/or
6310 $b:
6311 my $a = {
6313 tiny => -2,
6314 small => -1,
6315 normal => 0,
6316 big => 1,
6317 huge => 2
6318 };
6319 say sort { $a->{our $a} <=> $a->{our $b} }
6321 qw{ huge normal tiny small big};
6322 # prints tinysmallnormalbighuge
6324 $a and $b are implicitly local to the sort() execution and regain
6326 their former values upon completing the sort.
6327 Sort subroutines written using $a and $b are bound to their calling
6329 package. It is possible, but of limited interest, to define them in
6330 a different package, since the subroutine must still refer to the
6331 calling package's $a and $b :
6332 package Foo;
6334 sub lexi { $Bar::a cmp $Bar::b }
6335 package Bar;
6336 ... sort Foo::lexi ...
6337 Use the prototyped versions (see above) for a more generic
6339 alternative.
6340 The comparison function is required to behave. If it returns
6342 inconsistent results (sometimes saying $x[1] is less than $x[2] and
6343 sometimes saying the opposite, for example) the results are not
6344 well-defined.
6345 Because "<=>" returns "undef" when either operand is "NaN" (not-a-
6347 number), be careful when sorting with a comparison function like
6348 "$a <=> $b" any lists that might contain a "NaN". The following
6349 example takes advantage that "NaN != NaN" to eliminate any "NaN"s
6350 from the input list.
6351 my @result = sort { $a <=> $b } grep { $_ == $_ } @input;
6353 In this version of perl, the "sort" function is implemented via the
6355 mergesort algorithm.
6356 splice ARRAY,OFFSET,LENGTH,LIST
6358 splice ARRAY,OFFSET,LENGTH
6359 splice ARRAY,OFFSET
6360 splice ARRAY
6361 Removes the elements designated by OFFSET and LENGTH from an array,
6362 and replaces them with the elements of LIST, if any. In list
6363 context, returns the elements removed from the array. In scalar
6364 context, returns the last element removed, or "undef" if no
6365 elements are removed. The array grows or shrinks as necessary. If
6366 OFFSET is negative then it starts that far from the end of the
6367 array. If LENGTH is omitted, removes everything from OFFSET
6368 onward. If LENGTH is negative, removes the elements from OFFSET
6369 onward except for -LENGTH elements at the end of the array. If
6370 both OFFSET and LENGTH are omitted, removes everything. If OFFSET
6371 is past the end of the array and a LENGTH was provided, Perl issues
6372 a warning, and splices at the end of the array.
6373 The following equivalences hold (assuming "$#a >= $i" )
6375 push(@a,$x,$y) splice(@a,@a,0,$x,$y)
6377 pop(@a) splice(@a,-1)
6378 shift(@a) splice(@a,0,1)
6379 unshift(@a,$x,$y) splice(@a,0,0,$x,$y)
6380 $a[$i] = $y splice(@a,$i,1,$y)
6381 "splice" can be used, for example, to implement n-ary queue
6383 processing:
6384 sub nary_print {
6386 my $n = shift;
6387 while (my @next_n = splice @_, 0, $n) {
6388 say join q{ -- }, @next_n;
6389 }
6390 }
6391 nary_print(3, qw(a b c d e f g h));
6393 # prints:
6394 # a -- b -- c
6395 # d -- e -- f
6396 # g -- h
6397 Starting with Perl 5.14, an experimental feature allowed "splice"
6399 to take a scalar expression. This experiment has been deemed
6400 unsuccessful, and was removed as of Perl 5.24.
6401 split /PATTERN/,EXPR,LIMIT
6403 split /PATTERN/,EXPR
6404 split /PATTERN/
6405 split
6406 Splits the string EXPR into a list of strings and returns the list
6407 in list context, or the size of the list in scalar context. (Prior
6408 to Perl 5.11, it also overwrote @_ with the list in void and scalar
6409 context. If you target old perls, beware.)
6410 If only PATTERN is given, EXPR defaults to $_.
6412 Anything in EXPR that matches PATTERN is taken to be a separator
6414 that separates the EXPR into substrings (called "fields") that do
6415 not include the separator. Note that a separator may be longer
6416 than one character or even have no characters at all (the empty
6417 string, which is a zero-width match).
6418 The PATTERN need not be constant; an expression may be used to
6420 specify a pattern that varies at runtime.
6421 If PATTERN matches the empty string, the EXPR is split at the match
6423 position (between characters). As an example, the following:
6424 my @x = split(/b/, "abc"); # ("a", "c")
6426 uses the "b" in 'abc' as a separator to produce the list ("a",
6428 "c"). However, this:
6429 my @x = split(//, "abc"); # ("a", "b", "c")
6431 uses empty string matches as separators; thus, the empty string may
6433 be used to split EXPR into a list of its component characters.
6434 As a special case for "split", the empty pattern given in match
6436 operator syntax ("//") specifically matches the empty string, which
6437 is contrary to its usual interpretation as the last successful
6438 match.
6439 If PATTERN is "/^/", then it is treated as if it used the multiline
6441 modifier ("/^/m"), since it isn't much use otherwise.
6442 "/m" and any of the other pattern modifiers valid for "qr"
6444 (summarized in "qr/STRING/msixpodualn" in perlop) may be specified
6445 explicitly.
6446 As another special case, "split" emulates the default behavior of
6448 the command line tool awk when the PATTERN is either omitted or a
6449 string composed of a single space character (such as ' ' or "\x20",
6450 but not e.g. "/ /"). In this case, any leading whitespace in EXPR
6451 is removed before splitting occurs, and the PATTERN is instead
6452 treated as if it were "/\s+/"; in particular, this means that any
6453 contiguous whitespace (not just a single space character) is used
6454 as a separator.
6455 my @x = split(" ", " Quick brown fox\n");
6457 # ("Quick", "brown", "fox")
6458 my @x = split(" ", "RED\tGREEN\tBLUE");
6460 # ("RED", "GREEN", "BLUE")
6461 Using split in this fashion is very similar to how "qw//" works.
6463 However, this special treatment can be avoided by specifying the
6465 pattern "/ /" instead of the string " ", thereby allowing only a
6466 single space character to be a separator. In earlier Perls this
6467 special case was restricted to the use of a plain " " as the
6468 pattern argument to split; in Perl 5.18.0 and later this special
6469 case is triggered by any expression which evaluates to the simple
6470 string " ".
6471 As of Perl 5.28, this special-cased whitespace splitting works as
6473 expected in the scope of "use feature 'unicode_strings'". In
6474 previous versions, and outside the scope of that feature, it
6475 exhibits "The "Unicode Bug"" in perlunicode: characters that are
6476 whitespace according to Unicode rules but not according to ASCII
6477 rules can be treated as part of fields rather than as field
6478 separators, depending on the string's internal encoding.
6479 If omitted, PATTERN defaults to a single space, " ", triggering the
6481 previously described awk emulation.
6482 If LIMIT is specified and positive, it represents the maximum
6484 number of fields into which the EXPR may be split; in other words,
6485 LIMIT is one greater than the maximum number of times EXPR may be
6486 split. Thus, the LIMIT value 1 means that EXPR may be split a
6487 maximum of zero times, producing a maximum of one field (namely,
6488 the entire value of EXPR). For instance:
6489 my @x = split(//, "abc", 1); # ("abc")
6491 my @x = split(//, "abc", 2); # ("a", "bc")
6492 my @x = split(//, "abc", 3); # ("a", "b", "c")
6493 my @x = split(//, "abc", 4); # ("a", "b", "c")
6494 If LIMIT is negative, it is treated as if it were instead
6496 arbitrarily large; as many fields as possible are produced.
6497 If LIMIT is omitted (or, equivalently, zero), then it is usually
6499 treated as if it were instead negative but with the exception that
6500 trailing empty fields are stripped (empty leading fields are always
6501 preserved); if all fields are empty, then all fields are considered
6502 to be trailing (and are thus stripped in this case). Thus, the
6503 following:
6504 my @x = split(/,/, "a,b,c,,,"); # ("a", "b", "c")
6506 produces only a three element list.
6508 my @x = split(/,/, "a,b,c,,,", -1); # ("a", "b", "c", "", "", "")
6510 produces a six element list.
6512 In time-critical applications, it is worthwhile to avoid splitting
6514 into more fields than necessary. Thus, when assigning to a list,
6515 if LIMIT is omitted (or zero), then LIMIT is treated as though it
6516 were one larger than the number of variables in the list; for the
6517 following, LIMIT is implicitly 3:
6518 my ($login, $passwd) = split(/:/);
6520 Note that splitting an EXPR that evaluates to the empty string
6522 always produces zero fields, regardless of the LIMIT specified.
6523 An empty leading field is produced when there is a positive-width
6525 match at the beginning of EXPR. For instance:
6526 my @x = split(/ /, " abc"); # ("", "abc")
6528 splits into two elements. However, a zero-width match at the
6530 beginning of EXPR never produces an empty field, so that:
6531 my @x = split(//, " abc"); # (" ", "a", "b", "c")
6533 splits into four elements instead of five.
6535 An empty trailing field, on the other hand, is produced when there
6537 is a match at the end of EXPR, regardless of the length of the
6538 match (of course, unless a non-zero LIMIT is given explicitly, such
6539 fields are removed, as in the last example). Thus:
6540 my @x = split(//, " abc", -1); # (" ", "a", "b", "c", "")
6542 If the PATTERN contains capturing groups, then for each separator,
6544 an additional field is produced for each substring captured by a
6545 group (in the order in which the groups are specified, as per
6546 backreferences); if any group does not match, then it captures the
6547 "undef" value instead of a substring. Also, note that any such
6548 additional field is produced whenever there is a separator (that
6549 is, whenever a split occurs), and such an additional field does not
6550 count towards the LIMIT. Consider the following expressions
6551 evaluated in list context (each returned list is provided in the
6552 associated comment):
6553 my @x = split(/-|,/ , "1-10,20", 3);
6555 # ("1", "10", "20")
6556 my @x = split(/(-|,)/ , "1-10,20", 3);
6558 # ("1", "-", "10", ",", "20")
6559 my @x = split(/-|(,)/ , "1-10,20", 3);
6561 # ("1", undef, "10", ",", "20")
6562 my @x = split(/(-)|,/ , "1-10,20", 3);
6564 # ("1", "-", "10", undef, "20")
6565 my @x = split(/(-)|(,)/, "1-10,20", 3);
6567 # ("1", "-", undef, "10", undef, ",", "20")
6568 sprintf FORMAT, LIST
6570 Returns a string formatted by the usual "printf" conventions of the
6571 C library function "sprintf". See below for more details and see
6572 sprintf(3) or printf(3) on your system for an explanation of the
6573 general principles.
6574 For example:
6576 # Format number with up to 8 leading zeroes
6578 my $result = sprintf("%08d", $number);
6579 # Round number to 3 digits after decimal point
6581 my $rounded = sprintf("%.3f", $number);
6582 Perl does its own "sprintf" formatting: it emulates the C function
6584 sprintf(3), but doesn't use it except for floating-point numbers,
6585 and even then only standard modifiers are allowed. Non-standard
6586 extensions in your local sprintf(3) are therefore unavailable from
6587 Perl.
6588 Unlike "printf", "sprintf" does not do what you probably mean when
6590 you pass it an array as your first argument. The array is given
6591 scalar context, and instead of using the 0th element of the array
6592 as the format, Perl will use the count of elements in the array as
6593 the format, which is almost never useful.
6594 Perl's "sprintf" permits the following universally-known
6596 conversions:
6597 %% a percent sign
6599 %c a character with the given number
6600 %s a string
6601 %d a signed integer, in decimal
6602 %u an unsigned integer, in decimal
6603 %o an unsigned integer, in octal
6604 %x an unsigned integer, in hexadecimal
6605 %e a floating-point number, in scientific notation
6606 %f a floating-point number, in fixed decimal notation
6607 %g a floating-point number, in %e or %f notation
6608 In addition, Perl permits the following widely-supported
6610 conversions:
6611 %X like %x, but using upper-case letters
6613 %E like %e, but using an upper-case "E"
6614 %G like %g, but with an upper-case "E" (if applicable)
6615 %b an unsigned integer, in binary
6616 %B like %b, but using an upper-case "B" with the # flag
6617 %p a pointer (outputs the Perl value's address in hexadecimal)
6618 %n special: *stores* the number of characters output so far
6619 into the next argument in the parameter list
6620 %a hexadecimal floating point
6621 %A like %a, but using upper-case letters
6622 Finally, for backward (and we do mean "backward") compatibility,
6624 Perl permits these unnecessary but widely-supported conversions:
6625 %i a synonym for %d
6627 %D a synonym for %ld
6628 %U a synonym for %lu
6629 %O a synonym for %lo
6630 %F a synonym for %f
6631 Note that the number of exponent digits in the scientific notation
6633 produced by %e, %E, %g and %G for numbers with the modulus of the
6634 exponent less than 100 is system-dependent: it may be three or less
6635 (zero-padded as necessary). In other words, 1.23 times ten to the
6636 99th may be either "1.23e99" or "1.23e099". Similarly for %a and
6637 %A: the exponent or the hexadecimal digits may float: especially
6638 the "long doubles" Perl configuration option may cause surprises.
6639 Between the "%" and the format letter, you may specify several
6641 additional attributes controlling the interpretation of the format.
6642 In order, these are:
6643 format parameter index
6645 An explicit format parameter index, such as "2$". By default
6646 sprintf will format the next unused argument in the list, but
6647 this allows you to take the arguments out of order:
6648 printf '%2$d %1$d', 12, 34; # prints "34 12"
6650 printf '%3$d %d %1$d', 1, 2, 3; # prints "3 1 1"
6651 flags
6653 one or more of:
6654 space prefix non-negative number with a space
6656 + prefix non-negative number with a plus sign
6657 - left-justify within the field
6658 0 use zeros, not spaces, to right-justify
6659 # ensure the leading "0" for any octal,
6660 prefix non-zero hexadecimal with "0x" or "0X",
6661 prefix non-zero binary with "0b" or "0B"
6662 For example:
6664 printf '<% d>', 12; # prints "< 12>"
6666 printf '<% d>', 0; # prints "< 0>"
6667 printf '<% d>', -12; # prints "<-12>"
6668 printf '<%+d>', 12; # prints "<+12>"
6669 printf '<%+d>', 0; # prints "<+0>"
6670 printf '<%+d>', -12; # prints "<-12>"
6671 printf '<%6s>', 12; # prints "< 12>"
6672 printf '<%-6s>', 12; # prints "<12 >"
6673 printf '<%06s>', 12; # prints "<000012>"
6674 printf '<%#o>', 12; # prints "<014>"
6675 printf '<%#x>', 12; # prints "<0xc>"
6676 printf '<%#X>', 12; # prints "<0XC>"
6677 printf '<%#b>', 12; # prints "<0b1100>"
6678 printf '<%#B>', 12; # prints "<0B1100>"
6679 When a space and a plus sign are given as the flags at once,
6681 the space is ignored.
6682 printf '<%+ d>', 12; # prints "<+12>"
6684 printf '<% +d>', 12; # prints "<+12>"
6685 When the # flag and a precision are given in the %o conversion,
6687 the precision is incremented if it's necessary for the leading
6688 "0".
6689 printf '<%#.5o>', 012; # prints "<00012>"
6691 printf '<%#.5o>', 012345; # prints "<012345>"
6692 printf '<%#.0o>', 0; # prints "<0>"
6693 vector flag
6695 This flag tells Perl to interpret the supplied string as a
6696 vector of integers, one for each character in the string. Perl
6697 applies the format to each integer in turn, then joins the
6698 resulting strings with a separator (a dot "." by default).
6699 This can be useful for displaying ordinal values of characters
6700 in arbitrary strings:
6701 printf "%vd", "AB\x{100}"; # prints "65.66.256"
6703 printf "version is v%vd\n", $^V; # Perl's version
6704 Put an asterisk "*" before the "v" to override the string to
6706 use to separate the numbers:
6707 printf "address is %*vX\n", ":", $addr; # IPv6 address
6709 printf "bits are %0*v8b\n", " ", $bits; # random bitstring
6710 You can also explicitly specify the argument number to use for
6712 the join string using something like "*2$v"; for example:
6713 printf '%*4$vX %*4$vX %*4$vX', # 3 IPv6 addresses
6715 @addr[1..3], ":";
6716 (minimum) width
6718 Arguments are usually formatted to be only as wide as required
6719 to display the given value. You can override the width by
6720 putting a number here, or get the width from the next argument
6721 (with "*") or from a specified argument (e.g., with "*2$"):
6722 printf "<%s>", "a"; # prints "<a>"
6724 printf "<%6s>", "a"; # prints "< a>"
6725 printf "<%*s>", 6, "a"; # prints "< a>"
6726 printf '<%*2$s>', "a", 6; # prints "< a>"
6727 printf "<%2s>", "long"; # prints "<long>" (does not truncate)
6728 If a field width obtained through "*" is negative, it has the
6730 same effect as the "-" flag: left-justification.
6731 precision, or maximum width
6733 You can specify a precision (for numeric conversions) or a
6734 maximum width (for string conversions) by specifying a "."
6735 followed by a number. For floating-point formats except "g"
6736 and "G", this specifies how many places right of the decimal
6737 point to show (the default being 6). For example:
6738 # these examples are subject to system-specific variation
6740 printf '<%f>', 1; # prints "<1.000000>"
6741 printf '<%.1f>', 1; # prints "<1.0>"
6742 printf '<%.0f>', 1; # prints "<1>"
6743 printf '<%e>', 10; # prints "<1.000000e+01>"
6744 printf '<%.1e>', 10; # prints "<1.0e+01>"
6745 For "g" and "G", this specifies the maximum number of
6747 significant digits to show; for example:
6748 # These examples are subject to system-specific variation.
6750 printf '<%g>', 1; # prints "<1>"
6751 printf '<%.10g>', 1; # prints "<1>"
6752 printf '<%g>', 100; # prints "<100>"
6753 printf '<%.1g>', 100; # prints "<1e+02>"
6754 printf '<%.2g>', 100.01; # prints "<1e+02>"
6755 printf '<%.5g>', 100.01; # prints "<100.01>"
6756 printf '<%.4g>', 100.01; # prints "<100>"
6757 printf '<%.1g>', 0.0111; # prints "<0.01>"
6758 printf '<%.2g>', 0.0111; # prints "<0.011>"
6759 printf '<%.3g>', 0.0111; # prints "<0.0111>"
6760 For integer conversions, specifying a precision implies that
6762 the output of the number itself should be zero-padded to this
6763 width, where the 0 flag is ignored:
6764 printf '<%.6d>', 1; # prints "<000001>"
6766 printf '<%+.6d>', 1; # prints "<+000001>"
6767 printf '<%-10.6d>', 1; # prints "<000001 >"
6768 printf '<%10.6d>', 1; # prints "< 000001>"
6769 printf '<%010.6d>', 1; # prints "< 000001>"
6770 printf '<%+10.6d>', 1; # prints "< +000001>"
6771 printf '<%.6x>', 1; # prints "<000001>"
6773 printf '<%#.6x>', 1; # prints "<0x000001>"
6774 printf '<%-10.6x>', 1; # prints "<000001 >"
6775 printf '<%10.6x>', 1; # prints "< 000001>"
6776 printf '<%010.6x>', 1; # prints "< 000001>"
6777 printf '<%#10.6x>', 1; # prints "< 0x000001>"
6778 For string conversions, specifying a precision truncates the
6780 string to fit the specified width:
6781 printf '<%.5s>', "truncated"; # prints "<trunc>"
6783 printf '<%10.5s>', "truncated"; # prints "< trunc>"
6784 You can also get the precision from the next argument using
6786 ".*", or from a specified argument (e.g., with ".*2$"):
6787 printf '<%.6x>', 1; # prints "<000001>"
6789 printf '<%.*x>', 6, 1; # prints "<000001>"
6790 printf '<%.*2$x>', 1, 6; # prints "<000001>"
6792 printf '<%6.*2$x>', 1, 4; # prints "< 0001>"
6794 If a precision obtained through "*" is negative, it counts as
6796 having no precision at all.
6797 printf '<%.*s>', 7, "string"; # prints "<string>"
6799 printf '<%.*s>', 3, "string"; # prints "<str>"
6800 printf '<%.*s>', 0, "string"; # prints "<>"
6801 printf '<%.*s>', -1, "string"; # prints "<string>"
6802 printf '<%.*d>', 1, 0; # prints "<0>"
6804 printf '<%.*d>', 0, 0; # prints "<>"
6805 printf '<%.*d>', -1, 0; # prints "<0>"
6806 size
6808 For numeric conversions, you can specify the size to interpret
6809 the number as using "l", "h", "V", "q", "L", or "ll". For
6810 integer conversions ("d u o x X b i D U O"), numbers are
6811 usually assumed to be whatever the default integer size is on
6812 your platform (usually 32 or 64 bits), but you can override
6813 this to use instead one of the standard C types, as supported
6814 by the compiler used to build Perl:
6815 hh interpret integer as C type "char" or "unsigned
6817 char" on Perl 5.14 or later
6818 h interpret integer as C type "short" or
6819 "unsigned short"
6820 j interpret integer as C type "intmax_t" on Perl
6821 5.14 or later; and prior to Perl 5.30, only with
6822 a C99 compiler (unportable)
6823 l interpret integer as C type "long" or
6824 "unsigned long"
6825 q, L, or ll interpret integer as C type "long long",
6826 "unsigned long long", or "quad" (typically
6827 64-bit integers)
6828 t interpret integer as C type "ptrdiff_t" on Perl
6829 5.14 or later
6830 z interpret integer as C types "size_t" or
6831 "ssize_t" on Perl 5.14 or later
6832 Note that, in general, using the "l" modifier (for example,
6834 when writing "%ld" or "%lu" instead of "%d" and "%u") is
6835 unnecessary when used from Perl code. Moreover, it may be
6836 harmful, for example on Windows 64-bit where a long is 32-bits.
6837 As of 5.14, none of these raises an exception if they are not
6839 supported on your platform. However, if warnings are enabled,
6840 a warning of the "printf" warning class is issued on an
6841 unsupported conversion flag. Should you instead prefer an
6842 exception, do this:
6843 use warnings FATAL => "printf";
6845 If you would like to know about a version dependency before you
6847 start running the program, put something like this at its top:
6848 use 5.014; # for hh/j/t/z/ printf modifiers
6850 You can find out whether your Perl supports quads via Config:
6852 use Config;
6854 if ($Config{use64bitint} eq "define"
6855 || $Config{longsize} >= 8) {
6856 print "Nice quads!\n";
6857 }
6858 For floating-point conversions ("e f g E F G"), numbers are
6860 usually assumed to be the default floating-point size on your
6861 platform (double or long double), but you can force "long
6862 double" with "q", "L", or "ll" if your platform supports them.
6863 You can find out whether your Perl supports long doubles via
6864 Config:
6865 use Config;
6867 print "long doubles\n" if $Config{d_longdbl} eq "define";
6868 You can find out whether Perl considers "long double" to be the
6870 default floating-point size to use on your platform via Config:
6871 use Config;
6873 if ($Config{uselongdouble} eq "define") {
6874 print "long doubles by default\n";
6875 }
6876 It can also be that long doubles and doubles are the same
6878 thing:
6879 use Config;
6881 ($Config{doublesize} == $Config{longdblsize}) &&
6882 print "doubles are long doubles\n";
6883 The size specifier "V" has no effect for Perl code, but is
6885 supported for compatibility with XS code. It means "use the
6886 standard size for a Perl integer or floating-point number",
6887 which is the default.
6888 order of arguments
6890 Normally, "sprintf" takes the next unused argument as the value
6891 to format for each format specification. If the format
6892 specification uses "*" to require additional arguments, these
6893 are consumed from the argument list in the order they appear in
6894 the format specification before the value to format. Where an
6895 argument is specified by an explicit index, this does not
6896 affect the normal order for the arguments, even when the
6897 explicitly specified index would have been the next argument.
6898 So:
6900 printf "<%*.*s>", $a, $b, $c;
6902 uses $a for the width, $b for the precision, and $c as the
6904 value to format; while:
6905 printf '<%*1$.*s>', $a, $b;
6907 would use $a for the width and precision, and $b as the value
6909 to format.
6910 Here are some more examples; be aware that when using an
6912 explicit index, the "$" may need escaping:
6913 printf "%2\$d %d\n", 12, 34; # will print "34 12\n"
6915 printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n"
6916 printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n"
6917 printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n"
6918 printf "%*1\$.*f\n", 4, 5, 10; # will print "5.0000\n"
6919 If "use locale" (including "use locale ':not_characters'") is in
6921 effect and "POSIX::setlocale" has been called, the character used
6922 for the decimal separator in formatted floating-point numbers is
6923 affected by the "LC_NUMERIC" locale. See perllocale and POSIX.
6924 sqrt EXPR
6926 sqrt
6927 Return the positive square root of EXPR. If EXPR is omitted, uses
6928 $_. Works only for non-negative operands unless you've loaded the
6929 "Math::Complex" module.
6930 use Math::Complex;
6932 print sqrt(-4); # prints 2i
6933 srand EXPR
6935 srand
6936 Sets and returns the random number seed for the "rand" operator.
6937 The point of the function is to "seed" the "rand" function so that
6939 "rand" can produce a different sequence each time you run your
6940 program. When called with a parameter, "srand" uses that for the
6941 seed; otherwise it (semi-)randomly chooses a seed. In either case,
6942 starting with Perl 5.14, it returns the seed. To signal that your
6943 code will work only on Perls of a recent vintage:
6944 use 5.014; # so srand returns the seed
6946 If "srand" is not called explicitly, it is called implicitly
6948 without a parameter at the first use of the "rand" operator.
6949 However, there are a few situations where programs are likely to
6950 want to call "srand". One is for generating predictable results,
6951 generally for testing or debugging. There, you use "srand($seed)",
6952 with the same $seed each time. Another case is that you may want
6953 to call "srand" after a "fork" to avoid child processes sharing the
6954 same seed value as the parent (and consequently each other).
6955 Do not call "srand()" (i.e., without an argument) more than once
6957 per process. The internal state of the random number generator
6958 should contain more entropy than can be provided by any seed, so
6959 calling "srand" again actually loses randomness.
6960 Most implementations of "srand" take an integer and will silently
6962 truncate decimal numbers. This means "srand(42)" will usually
6963 produce the same results as "srand(42.1)". To be safe, always pass
6964 "srand" an integer.
6965 A typical use of the returned seed is for a test program which has
6967 too many combinations to test comprehensively in the time available
6968 to it each run. It can test a random subset each time, and should
6969 there be a failure, log the seed used for that run so that it can
6970 later be used to reproduce the same results.
6971 "rand" is not cryptographically secure. You should not rely on it
6973 in security-sensitive situations. As of this writing, a number of
6974 third-party CPAN modules offer random number generators intended by
6975 their authors to be cryptographically secure, including:
6976 Data::Entropy, Crypt::Random, Math::Random::Secure, and
6977 Math::TrulyRandom.
6978 stat FILEHANDLE
6980 stat EXPR
6981 stat DIRHANDLE
6982 stat
6983 Returns a 13-element list giving the status info for a file, either
6984 the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR. If
6985 EXPR is omitted, it stats $_ (not "_"!). Returns the empty list if
6986 "stat" fails. Typically used as follows:
6987 my ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
6989 $atime,$mtime,$ctime,$blksize,$blocks)
6990 = stat($filename);
6991 Not all fields are supported on all filesystem types. Here are the
6993 meanings of the fields:
6994 0 dev device number of filesystem
6996 1 ino inode number
6997 2 mode file mode (type and permissions)
6998 3 nlink number of (hard) links to the file
6999 4 uid numeric user ID of file's owner
7000 5 gid numeric group ID of file's owner
7001 6 rdev the device identifier (special files only)
7002 7 size total size of file, in bytes
7003 8 atime last access time in seconds since the epoch
7004 9 mtime last modify time in seconds since the epoch
7005 10 ctime inode change time in seconds since the epoch (*)
7006 11 blksize preferred I/O size in bytes for interacting with the
7007 file (may vary from file to file)
7008 12 blocks actual number of system-specific blocks allocated
7009 on disk (often, but not always, 512 bytes each)
7010 (The epoch was at 00:00 January 1, 1970 GMT.)
7012 (*) Not all fields are supported on all filesystem types. Notably,
7014 the ctime field is non-portable. In particular, you cannot expect
7015 it to be a "creation time"; see "Files and Filesystems" in perlport
7016 for details.
7017 If "stat" is passed the special filehandle consisting of an
7019 underline, no stat is done, but the current contents of the stat
7020 structure from the last "stat", "lstat", or filetest are returned.
7021 Example:
7022 if (-x $file && (($d) = stat(_)) && $d < 0) {
7024 print "$file is executable NFS file\n";
7025 }
7026 (This works on machines only for which the device number is
7028 negative under NFS.)
7029 On some platforms inode numbers are of a type larger than perl
7031 knows how to handle as integer numerical values. If necessary, an
7032 inode number will be returned as a decimal string in order to
7033 preserve the entire value. If used in a numeric context, this will
7034 be converted to a floating-point numerical value, with rounding, a
7035 fate that is best avoided. Therefore, you should prefer to compare
7036 inode numbers using "eq" rather than "==". "eq" will work fine on
7037 inode numbers that are represented numerically, as well as those
7038 represented as strings.
7039 Because the mode contains both the file type and its permissions,
7041 you should mask off the file type portion and (s)printf using a
7042 "%o" if you want to see the real permissions.
7043 my $mode = (stat($filename))[2];
7045 printf "Permissions are %04o\n", $mode & 07777;
7046 In scalar context, "stat" returns a boolean value indicating
7048 success or failure, and, if successful, sets the information
7049 associated with the special filehandle "_".
7050 The File::stat module provides a convenient, by-name access
7052 mechanism:
7053 use File::stat;
7055 my $sb = stat($filename);
7056 printf "File is %s, size is %s, perm %04o, mtime %s\n",
7057 $filename, $sb->size, $sb->mode & 07777,
7058 scalar localtime $sb->mtime;
7059 You can import symbolic mode constants ("S_IF*") and functions
7061 ("S_IS*") from the Fcntl module:
7062 use Fcntl ':mode';
7064 my $mode = (stat($filename))[2];
7066 my $user_rwx = ($mode & S_IRWXU) >> 6;
7068 my $group_read = ($mode & S_IRGRP) >> 3;
7069 my $other_execute = $mode & S_IXOTH;
7070 printf "Permissions are %04o\n", S_IMODE($mode), "\n";
7072 my $is_setuid = $mode & S_ISUID;
7074 my $is_directory = S_ISDIR($mode);
7075 You could write the last two using the "-u" and "-d" operators.
7077 Commonly available "S_IF*" constants are:
7078 # Permissions: read, write, execute, for user, group, others.
7080 S_IRWXU S_IRUSR S_IWUSR S_IXUSR
7082 S_IRWXG S_IRGRP S_IWGRP S_IXGRP
7083 S_IRWXO S_IROTH S_IWOTH S_IXOTH
7084 # Setuid/Setgid/Stickiness/SaveText.
7086 # Note that the exact meaning of these is system-dependent.
7087 S_ISUID S_ISGID S_ISVTX S_ISTXT
7089 # File types. Not all are necessarily available on
7091 # your system.
7092 S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR
7094 S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
7095 # The following are compatibility aliases for S_IRUSR,
7097 # S_IWUSR, and S_IXUSR.
7098 S_IREAD S_IWRITE S_IEXEC
7100 and the "S_IF*" functions are
7102 S_IMODE($mode) the part of $mode containing the permission
7104 bits and the setuid/setgid/sticky bits
7105 S_IFMT($mode) the part of $mode containing the file type
7107 which can be bit-anded with (for example)
7108 S_IFREG or with the following functions
7109 # The operators -f, -d, -l, -b, -c, -p, and -S.
7111 S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
7113 S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
7114 # No direct -X operator counterpart, but for the first one
7116 # the -g operator is often equivalent. The ENFMT stands for
7117 # record flocking enforcement, a platform-dependent feature.
7118 S_ISENFMT($mode) S_ISWHT($mode)
7120 See your native chmod(2) and stat(2) documentation for more details
7122 about the "S_*" constants. To get status info for a symbolic link
7123 instead of the target file behind the link, use the "lstat"
7124 function.
7125 Portability issues: "stat" in perlport.
7127 state VARLIST
7129 state TYPE VARLIST
7130 state VARLIST : ATTRS
7131 state TYPE VARLIST : ATTRS
7132 "state" declares a lexically scoped variable, just like "my".
7133 However, those variables will never be reinitialized, contrary to
7134 lexical variables that are reinitialized each time their enclosing
7135 block is entered. See "Persistent Private Variables" in perlsub
7136 for details.
7137 If more than one variable is listed, the list must be placed in
7139 parentheses. With a parenthesised list, "undef" can be used as a
7140 dummy placeholder. However, since initialization of state
7141 variables in such lists is currently not possible this would serve
7142 no purpose.
7143 Redeclaring a variable in the same scope or statement will "shadow"
7145 the previous declaration, creating a new instance and preventing
7146 access to the previous one. This is usually undesired and, if
7147 warnings are enabled, will result in a warning in the "shadow"
7148 category.
7149 "state" is available only if the "state" feature is enabled or if
7151 it is prefixed with "CORE::". The "state" feature is enabled
7152 automatically with a "use v5.10" (or higher) declaration in the
7153 current scope.
7154 study SCALAR
7156 study
7157 At this time, "study" does nothing. This may change in the future.
7158 Prior to Perl version 5.16, it would create an inverted index of
7160 all characters that occurred in the given SCALAR (or $_ if
7161 unspecified). When matching a pattern, the rarest character from
7162 the pattern would be looked up in this index. Rarity was based on
7163 some static frequency tables constructed from some C programs and
7164 English text.
7165 sub NAME BLOCK
7167 sub NAME (PROTO) BLOCK
7168 sub NAME : ATTRS BLOCK
7169 sub NAME (PROTO) : ATTRS BLOCK
7170 This is subroutine definition, not a real function per se. Without
7171 a BLOCK it's just a forward declaration. Without a NAME, it's an
7172 anonymous function declaration, so does return a value: the CODE
7173 ref of the closure just created.
7174 See perlsub and perlref for details about subroutines and
7176 references; see attributes and Attribute::Handlers for more
7177 information about attributes.
7178 __SUB__
7180 A special token that returns a reference to the current subroutine,
7181 or "undef" outside of a subroutine.
7182 The behaviour of "__SUB__" within a regex code block (such as
7184 "/(?{...})/") is subject to change.
7185 This token is only available under "use v5.16" or the "current_sub"
7187 feature. See feature.
7188 substr EXPR,OFFSET,LENGTH,REPLACEMENT
7190 substr EXPR,OFFSET,LENGTH
7191 substr EXPR,OFFSET
7192 Extracts a substring out of EXPR and returns it. First character
7193 is at offset zero. If OFFSET is negative, starts that far back
7194 from the end of the string. If LENGTH is omitted, returns
7195 everything through the end of the string. If LENGTH is negative,
7196 leaves that many characters off the end of the string.
7197 my $s = "The black cat climbed the green tree";
7199 my $color = substr $s, 4, 5; # black
7200 my $middle = substr $s, 4, -11; # black cat climbed the
7201 my $end = substr $s, 14; # climbed the green tree
7202 my $tail = substr $s, -4; # tree
7203 my $z = substr $s, -4, 2; # tr
7204 You can use the "substr" function as an lvalue, in which case EXPR
7206 must itself be an lvalue. If you assign something shorter than
7207 LENGTH, the string will shrink, and if you assign something longer
7208 than LENGTH, the string will grow to accommodate it. To keep the
7209 string the same length, you may need to pad or chop your value
7210 using "sprintf".
7211 If OFFSET and LENGTH specify a substring that is partly outside the
7213 string, only the part within the string is returned. If the
7214 substring is beyond either end of the string, "substr" returns the
7215 undefined value and produces a warning. When used as an lvalue,
7216 specifying a substring that is entirely outside the string raises
7217 an exception. Here's an example showing the behavior for boundary
7218 cases:
7219 my $name = 'fred';
7221 substr($name, 4) = 'dy'; # $name is now 'freddy'
7222 my $null = substr $name, 6, 2; # returns "" (no warning)
7223 my $oops = substr $name, 7; # returns undef, with warning
7224 substr($name, 7) = 'gap'; # raises an exception
7225 An alternative to using "substr" as an lvalue is to specify the
7227 replacement string as the 4th argument. This allows you to replace
7228 parts of the EXPR and return what was there before in one
7229 operation, just as you can with "splice".
7230 my $s = "The black cat climbed the green tree";
7232 my $z = substr $s, 14, 7, "jumped from"; # climbed
7233 # $s is now "The black cat jumped from the green tree"
7234 Note that the lvalue returned by the three-argument version of
7236 "substr" acts as a 'magic bullet'; each time it is assigned to, it
7237 remembers which part of the original string is being modified; for
7238 example:
7239 my $x = '1234';
7241 for (substr($x,1,2)) {
7242 $_ = 'a'; print $x,"\n"; # prints 1a4
7243 $_ = 'xyz'; print $x,"\n"; # prints 1xyz4
7244 $x = '56789';
7245 $_ = 'pq'; print $x,"\n"; # prints 5pq9
7246 }
7247 With negative offsets, it remembers its position from the end of
7249 the string when the target string is modified:
7250 my $x = '1234';
7252 for (substr($x, -3, 2)) {
7253 $_ = 'a'; print $x,"\n"; # prints 1a4, as above
7254 $x = 'abcdefg';
7255 print $_,"\n"; # prints f
7256 }
7257 Prior to Perl version 5.10, the result of using an lvalue multiple
7259 times was unspecified. Prior to 5.16, the result with negative
7260 offsets was unspecified.
7261 symlink OLDFILE,NEWFILE
7263 Creates a new filename symbolically linked to the old filename.
7264 Returns 1 for success, 0 otherwise. On systems that don't support
7265 symbolic links, raises an exception. To check for that, use eval:
7266 my $symlink_exists = eval { symlink("",""); 1 };
7268 Portability issues: "symlink" in perlport.
7270 syscall NUMBER, LIST
7272 Calls the system call specified as the first element of the list,
7273 passing the remaining elements as arguments to the system call. If
7274 unimplemented, raises an exception. The arguments are interpreted
7275 as follows: if a given argument is numeric, the argument is passed
7276 as an int. If not, the pointer to the string value is passed. You
7277 are responsible to make sure a string is pre-extended long enough
7278 to receive any result that might be written into a string. You
7279 can't use a string literal (or other read-only string) as an
7280 argument to "syscall" because Perl has to assume that any string
7281 pointer might be written through. If your integer arguments are
7282 not literals and have never been interpreted in a numeric context,
7283 you may need to add 0 to them to force them to look like numbers.
7284 This emulates the "syswrite" function (or vice versa):
7285 require 'syscall.ph'; # may need to run h2ph
7287 my $s = "hi there\n";
7288 syscall(SYS_write(), fileno(STDOUT), $s, length $s);
7289 Note that Perl supports passing of up to only 14 arguments to your
7291 syscall, which in practice should (usually) suffice.
7292 Syscall returns whatever value returned by the system call it
7294 calls. If the system call fails, "syscall" returns "-1" and sets
7295 $! (errno). Note that some system calls can legitimately return
7296 "-1". The proper way to handle such calls is to assign "$! = 0"
7297 before the call, then check the value of $! if "syscall" returns
7298 "-1".
7299 There's a problem with "syscall(SYS_pipe())": it returns the file
7301 number of the read end of the pipe it creates, but there is no way
7302 to retrieve the file number of the other end. You can avoid this
7303 problem by using "pipe" instead.
7304 Portability issues: "syscall" in perlport.
7306 sysopen FILEHANDLE,FILENAME,MODE
7308 sysopen FILEHANDLE,FILENAME,MODE,PERMS
7309 Opens the file whose filename is given by FILENAME, and associates
7310 it with FILEHANDLE. If FILEHANDLE is an expression, its value is
7311 used as the real filehandle wanted; an undefined scalar will be
7312 suitably autovivified. This function calls the underlying
7313 operating system's open(2) function with the parameters FILENAME,
7314 MODE, and PERMS.
7315 Returns true on success and "undef" otherwise.
7317 PerlIO layers will be applied to the handle the same way they would
7319 in an "open" call that does not specify layers. That is, the
7320 current value of "${^OPEN}" as set by the open pragma in a lexical
7321 scope, or the "-C" commandline option or "PERL_UNICODE" environment
7322 variable in the main program scope, falling back to the platform
7323 defaults as described in "Defaults and how to override them" in
7324 PerlIO. If you want to remove any layers that may transform the
7325 byte stream, use "binmode" after opening it.
7326 The possible values and flag bits of the MODE parameter are system-
7328 dependent; they are available via the standard module "Fcntl". See
7329 the documentation of your operating system's open(2) syscall to see
7330 which values and flag bits are available. You may combine several
7331 flags using the "|"-operator.
7332 Some of the most common values are "O_RDONLY" for opening the file
7334 in read-only mode, "O_WRONLY" for opening the file in write-only
7335 mode, and "O_RDWR" for opening the file in read-write mode.
7336 For historical reasons, some values work on almost every system
7338 supported by Perl: 0 means read-only, 1 means write-only, and 2
7339 means read/write. We know that these values do not work under
7340 OS/390 and on the Macintosh; you probably don't want to use them in
7341 new code.
7342 If the file named by FILENAME does not exist and the "open" call
7344 creates it (typically because MODE includes the "O_CREAT" flag),
7345 then the value of PERMS specifies the permissions of the newly
7346 created file. If you omit the PERMS argument to "sysopen", Perl
7347 uses the octal value 0666. These permission values need to be in
7348 octal, and are modified by your process's current "umask".
7349 In many systems the "O_EXCL" flag is available for opening files in
7351 exclusive mode. This is not locking: exclusiveness means here that
7352 if the file already exists, "sysopen" fails. "O_EXCL" may not work
7353 on network filesystems, and has no effect unless the "O_CREAT" flag
7354 is set as well. Setting "O_CREAT|O_EXCL" prevents the file from
7355 being opened if it is a symbolic link. It does not protect against
7356 symbolic links in the file's path.
7357 Sometimes you may want to truncate an already-existing file. This
7359 can be done using the "O_TRUNC" flag. The behavior of "O_TRUNC"
7360 with "O_RDONLY" is undefined.
7361 You should seldom if ever use 0644 as argument to "sysopen",
7363 because that takes away the user's option to have a more permissive
7364 umask. Better to omit it. See "umask" for more on this.
7365 This function has no direct relation to the usage of "sysread",
7367 "syswrite", or "sysseek". A handle opened with this function can
7368 be used with buffered IO just as one opened with "open" can be used
7369 with unbuffered IO.
7370 Note that under Perls older than 5.8.0, "sysopen" depends on the
7372 fdopen(3) C library function. On many Unix systems, fdopen(3) is
7373 known to fail when file descriptors exceed a certain value,
7374 typically 255. If you need more file descriptors than that,
7375 consider using the "POSIX::open" function. For Perls 5.8.0 and
7376 later, PerlIO is (most often) the default.
7377 See perlopentut for a kinder, gentler explanation of opening files.
7379 Portability issues: "sysopen" in perlport.
7381 sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
7383 sysread FILEHANDLE,SCALAR,LENGTH
7384 Attempts to read LENGTH bytes of data into variable SCALAR from the
7385 specified FILEHANDLE, using read(2). It bypasses any PerlIO layers
7386 including buffered IO (but is affected by the presence of the
7387 ":utf8" layer as described later), so mixing this with other kinds
7388 of reads, "print", "write", "seek", "tell", or "eof" can cause
7389 confusion because the ":perlio" or ":crlf" layers usually buffer
7390 data. Returns the number of bytes actually read, 0 at end of file,
7391 or undef if there was an error (in the latter case $! is also set).
7392 SCALAR will be grown or shrunk so that the last byte actually read
7393 is the last byte of the scalar after the read.
7394 An OFFSET may be specified to place the read data at some place in
7396 the string other than the beginning. A negative OFFSET specifies
7397 placement at that many characters counting backwards from the end
7398 of the string. A positive OFFSET greater than the length of SCALAR
7399 results in the string being padded to the required size with "\0"
7400 bytes before the result of the read is appended.
7401 There is no syseof() function, which is ok, since "eof" doesn't
7403 work well on device files (like ttys) anyway. Use "sysread" and
7404 check for a return value of 0 to decide whether you're done.
7405 Note that if the filehandle has been marked as ":utf8", "sysread"
7407 will throw an exception. The ":encoding(...)" layer implicitly
7408 introduces the ":utf8" layer. See "binmode", "open", and the open
7409 pragma.
7410 sysseek FILEHANDLE,POSITION,WHENCE
7412 Sets FILEHANDLE's system position in bytes using lseek(2).
7413 FILEHANDLE may be an expression whose value gives the name of the
7414 filehandle. The values for WHENCE are 0 to set the new position to
7415 POSITION; 1 to set it to the current position plus POSITION; and 2
7416 to set it to EOF plus POSITION, typically negative.
7417 Note the emphasis on bytes: even if the filehandle has been set to
7419 operate on characters (for example using the ":encoding(UTF-8)" I/O
7420 layer), the "seek", "tell", and "sysseek" family of functions use
7421 byte offsets, not character offsets, because seeking to a character
7422 offset would be very slow in a UTF-8 file.
7423 "sysseek" bypasses normal buffered IO, so mixing it with reads
7425 other than "sysread" (for example "readline" or "read"), "print",
7426 "write", "seek", "tell", or "eof" may cause confusion.
7427 For WHENCE, you may also use the constants "SEEK_SET", "SEEK_CUR",
7429 and "SEEK_END" (start of the file, current position, end of the
7430 file) from the Fcntl module. Use of the constants is also more
7431 portable than relying on 0, 1, and 2. For example to define a
7432 "systell" function:
7433 use Fcntl 'SEEK_CUR';
7435 sub systell { sysseek($_[0], 0, SEEK_CUR) }
7436 Returns the new position, or the undefined value on failure. A
7438 position of zero is returned as the string "0 but true"; thus
7439 "sysseek" returns true on success and false on failure, yet you can
7440 still easily determine the new position.
7441 system LIST
7443 system PROGRAM LIST
7444 Does exactly the same thing as "exec", except that a fork is done
7445 first and the parent process waits for the child process to exit.
7446 Note that argument processing varies depending on the number of
7447 arguments. If there is more than one argument in LIST, or if LIST
7448 is an array with more than one value, starts the program given by
7449 the first element of the list with arguments given by the rest of
7450 the list. If there is only one scalar argument, the argument is
7451 checked for shell metacharacters, and if there are any, the entire
7452 argument is passed to the system's command shell for parsing (this
7453 is "/bin/sh -c" on Unix platforms, but varies on other platforms).
7454 If there are no shell metacharacters in the argument, it is split
7455 into words and passed directly to "execvp", which is more
7456 efficient. On Windows, only the "system PROGRAM LIST" syntax will
7457 reliably avoid using the shell; "system LIST", even with more than
7458 one element, will fall back to the shell if the first spawn fails.
7459 Perl will attempt to flush all files opened for output before any
7461 operation that may do a fork, but this may not be supported on some
7462 platforms (see perlport). To be safe, you may need to set $|
7463 ($AUTOFLUSH in English) or call the "autoflush" method of
7464 "IO::Handle" on any open handles.
7465 The return value is the exit status of the program as returned by
7467 the "wait" call. To get the actual exit value, shift right by
7468 eight (see below). See also "exec". This is not what you want to
7469 use to capture the output from a command; for that you should use
7470 merely backticks or "qx//", as described in "`STRING`" in perlop.
7471 Return value of -1 indicates a failure to start the program or an
7472 error of the wait(2) system call (inspect $! for the reason).
7473 If you'd like to make "system" (and many other bits of Perl) die on
7475 error, have a look at the autodie pragma.
7476 Like "exec", "system" allows you to lie to a program about its name
7478 if you use the "system PROGRAM LIST" syntax. Again, see "exec".
7479 Since "SIGINT" and "SIGQUIT" are ignored during the execution of
7481 "system", if you expect your program to terminate on receipt of
7482 these signals you will need to arrange to do so yourself based on
7483 the return value.
7484 my @args = ("command", "arg1", "arg2");
7486 system(@args) == 0
7487 or die "system @args failed: $?";
7488 If you'd like to manually inspect "system"'s failure, you can check
7490 all possible failure modes by inspecting $? like this:
7491 if ($? == -1) {
7493 print "failed to execute: $!\n";
7494 }
7495 elsif ($? & 127) {
7496 printf "child died with signal %d, %s coredump\n",
7497 ($? & 127), ($? & 128) ? 'with' : 'without';
7498 }
7499 else {
7500 printf "child exited with value %d\n", $? >> 8;
7501 }
7502 Alternatively, you may inspect the value of
7504 "${^CHILD_ERROR_NATIVE}" with the "W*()" calls from the POSIX
7505 module.
7506 When "system"'s arguments are executed indirectly by the shell,
7508 results and return codes are subject to its quirks. See "`STRING`"
7509 in perlop and "exec" for details.
7510 Since "system" does a "fork" and "wait" it may affect a "SIGCHLD"
7512 handler. See perlipc for details.
7513 Portability issues: "system" in perlport.
7515 syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
7517 syswrite FILEHANDLE,SCALAR,LENGTH
7518 syswrite FILEHANDLE,SCALAR
7519 Attempts to write LENGTH bytes of data from variable SCALAR to the
7520 specified FILEHANDLE, using write(2). If LENGTH is not specified,
7521 writes whole SCALAR. It bypasses any PerlIO layers including
7522 buffered IO (but is affected by the presence of the ":utf8" layer
7523 as described later), so mixing this with reads (other than
7524 "sysread)"), "print", "write", "seek", "tell", or "eof" may cause
7525 confusion because the ":perlio" and ":crlf" layers usually buffer
7526 data. Returns the number of bytes actually written, or "undef" if
7527 there was an error (in this case the errno variable $! is also
7528 set). If the LENGTH is greater than the data available in the
7529 SCALAR after the OFFSET, only as much data as is available will be
7530 written.
7531 An OFFSET may be specified to write the data from some part of the
7533 string other than the beginning. A negative OFFSET specifies
7534 writing that many characters counting backwards from the end of the
7535 string. If SCALAR is of length zero, you can only use an OFFSET of
7536 0.
7537 WARNING: If the filehandle is marked ":utf8", "syswrite" will raise
7539 an exception. The ":encoding(...)" layer implicitly introduces the
7540 ":utf8" layer. Alternately, if the handle is not marked with an
7541 encoding but you attempt to write characters with code points over
7542 255, raises an exception. See "binmode", "open", and the open
7543 pragma.
7544 tell FILEHANDLE
7546 tell
7547 Returns the current position in bytes for FILEHANDLE, or -1 on
7548 error. FILEHANDLE may be an expression whose value gives the name
7549 of the actual filehandle. If FILEHANDLE is omitted, assumes the
7550 file last read.
7551 Note the emphasis on bytes: even if the filehandle has been set to
7553 operate on characters (for example using the ":encoding(UTF-8)" I/O
7554 layer), the "seek", "tell", and "sysseek" family of functions use
7555 byte offsets, not character offsets, because seeking to a character
7556 offset would be very slow in a UTF-8 file.
7557 The return value of "tell" for the standard streams like the STDIN
7559 depends on the operating system: it may return -1 or something
7560 else. "tell" on pipes, fifos, and sockets usually returns -1.
7561 There is no "systell" function. Use "sysseek($fh, 0, 1)" for that.
7563 Do not use "tell" (or other buffered I/O operations) on a
7565 filehandle that has been manipulated by "sysread", "syswrite", or
7566 "sysseek". Those functions ignore the buffering, while "tell" does
7567 not.
7568 telldir DIRHANDLE
7570 Returns the current position of the "readdir" routines on
7571 DIRHANDLE. Value may be given to "seekdir" to access a particular
7572 location in a directory. "telldir" has the same caveats about
7573 possible directory compaction as the corresponding system library
7574 routine.
7575 tie VARIABLE,CLASSNAME,LIST
7577 This function binds a variable to a package class that will provide
7578 the implementation for the variable. VARIABLE is the name of the
7579 variable to be enchanted. CLASSNAME is the name of a class
7580 implementing objects of correct type. Any additional arguments are
7581 passed to the appropriate constructor method of the class (meaning
7582 "TIESCALAR", "TIEHANDLE", "TIEARRAY", or "TIEHASH"). Typically
7583 these are arguments such as might be passed to the dbm_open(3)
7584 function of C. The object returned by the constructor is also
7585 returned by the "tie" function, which would be useful if you want
7586 to access other methods in CLASSNAME.
7587 Note that functions such as "keys" and "values" may return huge
7589 lists when used on large objects, like DBM files. You may prefer
7590 to use the "each" function to iterate over such. Example:
7591 # print out history file offsets
7593 use NDBM_File;
7594 tie(my %HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
7595 while (my ($key,$val) = each %HIST) {
7596 print $key, ' = ', unpack('L', $val), "\n";
7597 }
7598 A class implementing a hash should have the following methods:
7600 TIEHASH classname, LIST
7602 FETCH this, key
7603 STORE this, key, value
7604 DELETE this, key
7605 CLEAR this
7606 EXISTS this, key
7607 FIRSTKEY this
7608 NEXTKEY this, lastkey
7609 SCALAR this
7610 DESTROY this
7611 UNTIE this
7612 A class implementing an ordinary array should have the following
7614 methods:
7615 TIEARRAY classname, LIST
7617 FETCH this, key
7618 STORE this, key, value
7619 FETCHSIZE this
7620 STORESIZE this, count
7621 CLEAR this
7622 PUSH this, LIST
7623 POP this
7624 SHIFT this
7625 UNSHIFT this, LIST
7626 SPLICE this, offset, length, LIST
7627 EXTEND this, count
7628 DELETE this, key
7629 EXISTS this, key
7630 DESTROY this
7631 UNTIE this
7632 A class implementing a filehandle should have the following
7634 methods:
7635 TIEHANDLE classname, LIST
7637 READ this, scalar, length, offset
7638 READLINE this
7639 GETC this
7640 WRITE this, scalar, length, offset
7641 PRINT this, LIST
7642 PRINTF this, format, LIST
7643 BINMODE this
7644 EOF this
7645 FILENO this
7646 SEEK this, position, whence
7647 TELL this
7648 OPEN this, mode, LIST
7649 CLOSE this
7650 DESTROY this
7651 UNTIE this
7652 A class implementing a scalar should have the following methods:
7654 TIESCALAR classname, LIST
7656 FETCH this,
7657 STORE this, value
7658 DESTROY this
7659 UNTIE this
7660 Not all methods indicated above need be implemented. See perltie,
7662 Tie::Hash, Tie::Array, Tie::Scalar, and Tie::Handle.
7663 Unlike "dbmopen", the "tie" function will not "use" or "require" a
7665 module for you; you need to do that explicitly yourself. See
7666 DB_File or the Config module for interesting "tie" implementations.
7667 For further details see perltie, "tied".
7669 tied VARIABLE
7671 Returns a reference to the object underlying VARIABLE (the same
7672 value that was originally returned by the "tie" call that bound the
7673 variable to a package.) Returns the undefined value if VARIABLE
7674 isn't tied to a package.
7675 time
7677 Returns the number of non-leap seconds since whatever time the
7678 system considers to be the epoch, suitable for feeding to "gmtime"
7679 and "localtime". On most systems the epoch is 00:00:00 UTC,
7680 January 1, 1970; a prominent exception being Mac OS Classic which
7681 uses 00:00:00, January 1, 1904 in the current local time zone for
7682 its epoch.
7683 For measuring time in better granularity than one second, use the
7685 Time::HiRes module from Perl 5.8 onwards (or from CPAN before
7686 then), or, if you have gettimeofday(2), you may be able to use the
7687 "syscall" interface of Perl. See perlfaq8 for details.
7688 For date and time processing look at the many related modules on
7690 CPAN. For a comprehensive date and time representation look at the
7691 DateTime module.
7692 times
7694 Returns a four-element list giving the user and system times in
7695 seconds for this process and any exited children of this process.
7696 my ($user,$system,$cuser,$csystem) = times;
7698 In scalar context, "times" returns $user.
7700 Children's times are only included for terminated children.
7702 Portability issues: "times" in perlport.
7704 tr///
7706 The transliteration operator. Same as "y///". See "Quote-Like
7707 Operators" in perlop.
7708 truncate FILEHANDLE,LENGTH
7710 truncate EXPR,LENGTH
7711 Truncates the file opened on FILEHANDLE, or named by EXPR, to the
7712 specified length. Raises an exception if truncate isn't
7713 implemented on your system. Returns true if successful, "undef" on
7714 error.
7715 The behavior is undefined if LENGTH is greater than the length of
7717 the file.
7718 The position in the file of FILEHANDLE is left unchanged. You may
7720 want to call seek before writing to the file.
7721 Portability issues: "truncate" in perlport.
7723 uc EXPR
7725 uc Returns an uppercased version of EXPR. This is the internal
7726 function implementing the "\U" escape in double-quoted strings. It
7727 does not attempt to do titlecase mapping on initial letters. See
7728 "ucfirst" for that.
7729 If EXPR is omitted, uses $_.
7731 This function behaves the same way under various pragmas, such as
7733 in a locale, as "lc" does.
7734 ucfirst EXPR
7736 ucfirst
7737 Returns the value of EXPR with the first character in uppercase
7738 (titlecase in Unicode). This is the internal function implementing
7739 the "\u" escape in double-quoted strings.
7740 If EXPR is omitted, uses $_.
7742 This function behaves the same way under various pragmas, such as
7744 in a locale, as "lc" does.
7745 umask EXPR
7747 umask
7748 Sets the umask for the process to EXPR and returns the previous
7749 value. If EXPR is omitted, merely returns the current umask.
7750 The Unix permission "rwxr-x---" is represented as three sets of
7752 three bits, or three octal digits: 0750 (the leading 0 indicates
7753 octal and isn't one of the digits). The "umask" value is such a
7754 number representing disabled permissions bits. The permission (or
7755 "mode") values you pass "mkdir" or "sysopen" are modified by your
7756 umask, so even if you tell "sysopen" to create a file with
7757 permissions 0777, if your umask is 0022, then the file will
7758 actually be created with permissions 0755. If your "umask" were
7759 0027 (group can't write; others can't read, write, or execute),
7760 then passing "sysopen" 0666 would create a file with mode 0640
7761 (because "0666 &~ 027" is 0640).
7762 Here's some advice: supply a creation mode of 0666 for regular
7764 files (in "sysopen") and one of 0777 for directories (in "mkdir")
7765 and executable files. This gives users the freedom of choice: if
7766 they want protected files, they might choose process umasks of 022,
7767 027, or even the particularly antisocial mask of 077. Programs
7768 should rarely if ever make policy decisions better left to the
7769 user. The exception to this is when writing files that should be
7770 kept private: mail files, web browser cookies, .rhosts files, and
7771 so on.
7772 If umask(2) is not implemented on your system and you are trying to
7774 restrict access for yourself (i.e., "(EXPR & 0700) > 0"), raises an
7775 exception. If umask(2) is not implemented and you are not trying
7776 to restrict access for yourself, returns "undef".
7777 Remember that a umask is a number, usually given in octal; it is
7779 not a string of octal digits. See also "oct", if all you have is a
7780 string.
7781 Portability issues: "umask" in perlport.
7783 undef EXPR
7785 undef
7786 Undefines the value of EXPR, which must be an lvalue. Use only on
7787 a scalar value, an array (using "@"), a hash (using "%"), a
7788 subroutine (using "&"), or a typeglob (using "*"). Saying "undef
7789 $hash{$key}" will probably not do what you expect on most
7790 predefined variables or DBM list values, so don't do that; see
7791 "delete". Always returns the undefined value. You can omit the
7792 EXPR, in which case nothing is undefined, but you still get an
7793 undefined value that you could, for instance, return from a
7794 subroutine, assign to a variable, or pass as a parameter.
7795 Examples:
7796 undef $foo;
7798 undef $bar{'blurfl'}; # Compare to: delete $bar{'blurfl'};
7799 undef @ary;
7800 undef %hash;
7801 undef &mysub;
7802 undef *xyz; # destroys $xyz, @xyz, %xyz, &xyz, etc.
7803 return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
7804 select undef, undef, undef, 0.25;
7805 my ($x, $y, undef, $z) = foo(); # Ignore third value returned
7806 Note that this is a unary operator, not a list operator.
7808 unlink LIST
7810 unlink
7811 Deletes a list of files. On success, it returns the number of
7812 files it successfully deleted. On failure, it returns false and
7813 sets $! (errno):
7814 my $unlinked = unlink 'a', 'b', 'c';
7816 unlink @goners;
7817 unlink glob "*.bak";
7818 On error, "unlink" will not tell you which files it could not
7820 remove. If you want to know which files you could not remove, try
7821 them one at a time:
7822 foreach my $file ( @goners ) {
7824 unlink $file or warn "Could not unlink $file: $!";
7825 }
7826 Note: "unlink" will not attempt to delete directories unless you
7828 are superuser and the -U flag is supplied to Perl. Even if these
7829 conditions are met, be warned that unlinking a directory can
7830 inflict damage on your filesystem. Finally, using "unlink" on
7831 directories is not supported on many operating systems. Use
7832 "rmdir" instead.
7833 If LIST is omitted, "unlink" uses $_.
7835 unpack TEMPLATE,EXPR
7837 unpack TEMPLATE
7838 "unpack" does the reverse of "pack": it takes a string and expands
7839 it out into a list of values. (In scalar context, it returns
7840 merely the first value produced.)
7841 If EXPR is omitted, unpacks the $_ string. See perlpacktut for an
7843 introduction to this function.
7844 The string is broken into chunks described by the TEMPLATE. Each
7846 chunk is converted separately to a value. Typically, either the
7847 string is a result of "pack", or the characters of the string
7848 represent a C structure of some kind.
7849 The TEMPLATE has the same format as in the "pack" function. Here's
7851 a subroutine that does substring:
7852 sub substr {
7854 my ($what, $where, $howmuch) = @_;
7855 unpack("x$where a$howmuch", $what);
7856 }
7857 and then there's
7859 sub ordinal { unpack("W",$_[0]); } # same as ord()
7861 In addition to fields allowed in "pack", you may prefix a field
7863 with a %<number> to indicate that you want a <number>-bit checksum
7864 of the items instead of the items themselves. Default is a 16-bit
7865 checksum. The checksum is calculated by summing numeric values of
7866 expanded values (for string fields the sum of "ord($char)" is
7867 taken; for bit fields the sum of zeroes and ones).
7868 For example, the following computes the same number as the System V
7870 sum program:
7871 my $checksum = do {
7873 local $/; # slurp!
7874 unpack("%32W*", readline) % 65535;
7875 };
7876 The following efficiently counts the number of set bits in a bit
7878 vector:
7879 my $setbits = unpack("%32b*", $selectmask);
7881 The "p" and "P" formats should be used with care. Since Perl has
7883 no way of checking whether the value passed to "unpack" corresponds
7884 to a valid memory location, passing a pointer value that's not
7885 known to be valid is likely to have disastrous consequences.
7886 If there are more pack codes or if the repeat count of a field or a
7888 group is larger than what the remainder of the input string allows,
7889 the result is not well defined: the repeat count may be decreased,
7890 or "unpack" may produce empty strings or zeros, or it may raise an
7891 exception. If the input string is longer than one described by the
7892 TEMPLATE, the remainder of that input string is ignored.
7893 See "pack" for more examples and notes.
7895 unshift ARRAY,LIST
7897 Does the opposite of a "shift". Or the opposite of a "push",
7898 depending on how you look at it. Prepends list to the front of the
7899 array and returns the new number of elements in the array.
7900 unshift(@ARGV, '-e') unless $ARGV[0] =~ /^-/;
7902 Note the LIST is prepended whole, not one element at a time, so the
7904 prepended elements stay in the same order. Use "reverse" to do the
7905 reverse.
7906 Starting with Perl 5.14, an experimental feature allowed "unshift"
7908 to take a scalar expression. This experiment has been deemed
7909 unsuccessful, and was removed as of Perl 5.24.
7910 untie VARIABLE
7912 Breaks the binding between a variable and a package. (See tie.)
7913 Has no effect if the variable is not tied.
7914 use Module VERSION LIST
7916 use Module VERSION
7917 use Module LIST
7918 use Module
7919 use VERSION
7920 Imports some semantics into the current package from the named
7921 module, generally by aliasing certain subroutine or variable names
7922 into your package. It is exactly equivalent to
7923 BEGIN { require Module; Module->import( LIST ); }
7925 except that Module must be a bareword. The importation can be made
7927 conditional by using the if module.
7928 In the "use VERSION" form, VERSION may be either a v-string such as
7930 v5.24.1, which will be compared to $^V (aka $PERL_VERSION), or a
7931 numeric argument of the form 5.024001, which will be compared to
7932 $]. An exception is raised if VERSION is greater than the version
7933 of the current Perl interpreter; Perl will not attempt to parse the
7934 rest of the file. Compare with "require", which can do a similar
7935 check at run time. Symmetrically, "no VERSION" allows you to
7936 specify that you want a version of Perl older than the specified
7937 one.
7938 Specifying VERSION as a numeric argument of the form 5.024001
7940 should generally be avoided as older less readable syntax compared
7941 to v5.24.1. Before perl 5.8.0 released in 2002 the more verbose
7942 numeric form was the only supported syntax, which is why you might
7943 see it in
7944 use v5.24.1; # compile time version check
7946 use 5.24.1; # ditto
7947 use 5.024_001; # ditto; older syntax compatible with perl 5.6
7948 This is often useful if you need to check the current Perl version
7950 before "use"ing library modules that won't work with older versions
7951 of Perl. (We try not to do this more than we have to.)
7952 "use VERSION" also lexically enables all features available in the
7954 requested version as defined by the feature pragma, disabling any
7955 features not in the requested version's feature bundle. See
7956 feature. Similarly, if the specified Perl version is greater than
7957 or equal to 5.12.0, strictures are enabled lexically as with "use
7958 strict". Any explicit use of "use strict" or "no strict" overrides
7959 "use VERSION", even if it comes before it. Later use of "use
7960 VERSION" will override all behavior of a previous "use VERSION",
7961 possibly removing the "strict" and "feature" added by "use
7962 VERSION". "use VERSION" does not load the feature.pm or strict.pm
7963 files.
7964 The "BEGIN" forces the "require" and "import" to happen at compile
7966 time. The "require" makes sure the module is loaded into memory if
7967 it hasn't been yet. The "import" is not a builtin; it's just an
7968 ordinary static method call into the "Module" package to tell the
7969 module to import the list of features back into the current
7970 package. The module can implement its "import" method any way it
7971 likes, though most modules just choose to derive their "import"
7972 method via inheritance from the "Exporter" class that is defined in
7973 the "Exporter" module. See Exporter. If no "import" method can be
7974 found, then the call is skipped, even if there is an AUTOLOAD
7975 method.
7976 If you do not want to call the package's "import" method (for
7978 instance, to stop your namespace from being altered), explicitly
7979 supply the empty list:
7980 use Module ();
7982 That is exactly equivalent to
7984 BEGIN { require Module }
7986 If the VERSION argument is present between Module and LIST, then
7988 the "use" will call the "VERSION" method in class Module with the
7989 given version as an argument:
7990 use Module 12.34;
7992 is equivalent to:
7994 BEGIN { require Module; Module->VERSION(12.34) }
7996 The default "VERSION" method, inherited from the "UNIVERSAL" class,
7998 croaks if the given version is larger than the value of the
7999 variable $Module::VERSION.
8000 The VERSION argument cannot be an arbitrary expression. It only
8002 counts as a VERSION argument if it is a version number literal,
8003 starting with either a digit or "v" followed by a digit. Anything
8004 that doesn't look like a version literal will be parsed as the
8005 start of the LIST. Nevertheless, many attempts to use an arbitrary
8006 expression as a VERSION argument will appear to work, because
8007 Exporter's "import" method handles numeric arguments specially,
8008 performing version checks rather than treating them as things to
8009 export.
8010 Again, there is a distinction between omitting LIST ("import"
8012 called with no arguments) and an explicit empty LIST "()" ("import"
8013 not called). Note that there is no comma after VERSION!
8014 Because this is a wide-open interface, pragmas (compiler
8016 directives) are also implemented this way. Some of the currently
8017 implemented pragmas are:
8018 use constant;
8020 use diagnostics;
8021 use integer;
8022 use sigtrap qw(SEGV BUS);
8023 use strict qw(subs vars refs);
8024 use subs qw(afunc blurfl);
8025 use warnings qw(all);
8026 use sort qw(stable);
8027 Some of these pseudo-modules import semantics into the current
8029 block scope (like "strict" or "integer", unlike ordinary modules,
8030 which import symbols into the current package (which are effective
8031 through the end of the file).
8032 Because "use" takes effect at compile time, it doesn't respect the
8034 ordinary flow control of the code being compiled. In particular,
8035 putting a "use" inside the false branch of a conditional doesn't
8036 prevent it from being processed. If a module or pragma only needs
8037 to be loaded conditionally, this can be done using the if pragma:
8038 use if $] < 5.008, "utf8";
8040 use if WANT_WARNINGS, warnings => qw(all);
8041 There's a corresponding "no" declaration that unimports meanings
8043 imported by "use", i.e., it calls "Module->unimport(LIST)" instead
8044 of "import". It behaves just as "import" does with VERSION, an
8045 omitted or empty LIST, or no unimport method being found.
8046 no integer;
8048 no strict 'refs';
8049 no warnings;
8050 Care should be taken when using the "no VERSION" form of "no". It
8052 is only meant to be used to assert that the running Perl is of a
8053 earlier version than its argument and not to undo the feature-
8054 enabling side effects of "use VERSION".
8055 See perlmodlib for a list of standard modules and pragmas. See
8057 perlrun for the "-M" and "-m" command-line options to Perl that
8058 give "use" functionality from the command-line.
8059 utime LIST
8061 Changes the access and modification times on each file of a list of
8062 files. The first two elements of the list must be the NUMERIC
8063 access and modification times, in that order. Returns the number
8064 of files successfully changed. The inode change time of each file
8065 is set to the current time. For example, this code has the same
8066 effect as the Unix touch(1) command when the files already exist
8067 and belong to the user running the program:
8068 #!/usr/bin/perl
8070 my $atime = my $mtime = time;
8071 utime $atime, $mtime, @ARGV;
8072 Since Perl 5.8.0, if the first two elements of the list are
8074 "undef", the utime(2) syscall from your C library is called with a
8075 null second argument. On most systems, this will set the file's
8076 access and modification times to the current time (i.e., equivalent
8077 to the example above) and will work even on files you don't own
8078 provided you have write permission:
8079 for my $file (@ARGV) {
8081 utime(undef, undef, $file)
8082 || warn "Couldn't touch $file: $!";
8083 }
8084 Under NFS this will use the time of the NFS server, not the time of
8086 the local machine. If there is a time synchronization problem, the
8087 NFS server and local machine will have different times. The Unix
8088 touch(1) command will in fact normally use this form instead of the
8089 one shown in the first example.
8090 Passing only one of the first two elements as "undef" is equivalent
8092 to passing a 0 and will not have the effect described when both are
8093 "undef". This also triggers an uninitialized warning.
8094 On systems that support futimes(2), you may pass filehandles among
8096 the files. On systems that don't support futimes(2), passing
8097 filehandles raises an exception. Filehandles must be passed as
8098 globs or glob references to be recognized; barewords are considered
8099 filenames.
8100 Portability issues: "utime" in perlport.
8102 values HASH
8104 values ARRAY
8105 In list context, returns a list consisting of all the values of the
8106 named hash. In Perl 5.12 or later only, will also return a list of
8107 the values of an array; prior to that release, attempting to use an
8108 array argument will produce a syntax error. In scalar context,
8109 returns the number of values.
8110 Hash entries are returned in an apparently random order. The
8112 actual random order is specific to a given hash; the exact same
8113 series of operations on two hashes may result in a different order
8114 for each hash. Any insertion into the hash may change the order,
8115 as will any deletion, with the exception that the most recent key
8116 returned by "each" or "keys" may be deleted without changing the
8117 order. So long as a given hash is unmodified you may rely on
8118 "keys", "values" and "each" to repeatedly return the same order as
8119 each other. See "Algorithmic Complexity Attacks" in perlsec for
8120 details on why hash order is randomized. Aside from the guarantees
8121 provided here the exact details of Perl's hash algorithm and the
8122 hash traversal order are subject to change in any release of Perl.
8123 Tied hashes may behave differently to Perl's hashes with respect to
8124 changes in order on insertion and deletion of items.
8125 As a side effect, calling "values" resets the HASH or ARRAY's
8127 internal iterator (see "each") before yielding the values. In
8128 particular, calling "values" in void context resets the iterator
8129 with no other overhead.
8130 Apart from resetting the iterator, "values @array" in list context
8132 is the same as plain @array. (We recommend that you use void
8133 context "keys @array" for this, but reasoned that taking "values
8134 @array" out would require more documentation than leaving it in.)
8135 Note that the values are not copied, which means modifying them
8137 will modify the contents of the hash:
8138 for (values %hash) { s/foo/bar/g } # modifies %hash values
8140 for (@hash{keys %hash}) { s/foo/bar/g } # same
8141 Starting with Perl 5.14, an experimental feature allowed "values"
8143 to take a scalar expression. This experiment has been deemed
8144 unsuccessful, and was removed as of Perl 5.24.
8145 To avoid confusing would-be users of your code who are running
8147 earlier versions of Perl with mysterious syntax errors, put this
8148 sort of thing at the top of your file to signal that your code will
8149 work only on Perls of a recent vintage:
8150 use 5.012; # so keys/values/each work on arrays
8152 See also "keys", "each", and "sort".
8154 vec EXPR,OFFSET,BITS
8156 Treats the string in EXPR as a bit vector made up of elements of
8157 width BITS and returns the value of the element specified by OFFSET
8158 as an unsigned integer. BITS therefore specifies the number of
8159 bits that are reserved for each element in the bit vector. This
8160 must be a power of two from 1 to 32 (or 64, if your platform
8161 supports that).
8162 If BITS is 8, "elements" coincide with bytes of the input string.
8164 If BITS is 16 or more, bytes of the input string are grouped into
8166 chunks of size BITS/8, and each group is converted to a number as
8167 with "pack"/"unpack" with big-endian formats "n"/"N" (and
8168 analogously for BITS==64). See "pack" for details.
8169 If bits is 4 or less, the string is broken into bytes, then the
8171 bits of each byte are broken into 8/BITS groups. Bits of a byte
8172 are numbered in a little-endian-ish way, as in 0x01, 0x02, 0x04,
8173 0x08, 0x10, 0x20, 0x40, 0x80. For example, breaking the single
8174 input byte "chr(0x36)" into two groups gives a list "(0x6, 0x3)";
8175 breaking it into 4 groups gives "(0x2, 0x1, 0x3, 0x0)".
8176 "vec" may also be assigned to, in which case parentheses are needed
8178 to give the expression the correct precedence as in
8179 vec($image, $max_x * $x + $y, 8) = 3;
8181 If the selected element is outside the string, the value 0 is
8183 returned. If an element off the end of the string is written to,
8184 Perl will first extend the string with sufficiently many zero
8185 bytes. It is an error to try to write off the beginning of the
8186 string (i.e., negative OFFSET).
8187 If the string happens to be encoded as UTF-8 internally (and thus
8189 has the UTF8 flag set), "vec" tries to convert it to use a one-
8190 byte-per-character internal representation. However, if the string
8191 contains characters with values of 256 or higher, a fatal error
8192 will occur.
8193 Strings created with "vec" can also be manipulated with the logical
8195 operators "|", "&", "^", and "~". These operators will assume a
8196 bit vector operation is desired when both operands are strings.
8197 See "Bitwise String Operators" in perlop.
8198 The following code will build up an ASCII string saying
8200 'PerlPerlPerl'. The comments show the string after each step.
8201 Note that this code works in the same way on big-endian or little-
8202 endian machines.
8203 my $foo = '';
8205 vec($foo, 0, 32) = 0x5065726C; # 'Perl'
8206 # $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits
8208 print vec($foo, 0, 8); # prints 80 == 0x50 == ord('P')
8209 vec($foo, 2, 16) = 0x5065; # 'PerlPe'
8211 vec($foo, 3, 16) = 0x726C; # 'PerlPerl'
8212 vec($foo, 8, 8) = 0x50; # 'PerlPerlP'
8213 vec($foo, 9, 8) = 0x65; # 'PerlPerlPe'
8214 vec($foo, 20, 4) = 2; # 'PerlPerlPe' . "\x02"
8215 vec($foo, 21, 4) = 7; # 'PerlPerlPer'
8216 # 'r' is "\x72"
8217 vec($foo, 45, 2) = 3; # 'PerlPerlPer' . "\x0c"
8218 vec($foo, 93, 1) = 1; # 'PerlPerlPer' . "\x2c"
8219 vec($foo, 94, 1) = 1; # 'PerlPerlPerl'
8220 # 'l' is "\x6c"
8221 To transform a bit vector into a string or list of 0's and 1's, use
8223 these:
8224 my $bits = unpack("b*", $vector);
8226 my @bits = split(//, unpack("b*", $vector));
8227 If you know the exact length in bits, it can be used in place of
8229 the "*".
8230 Here is an example to illustrate how the bits actually fall in
8232 place:
8233 #!/usr/bin/perl -wl
8235 print <<'EOT';
8237 0 1 2 3
8238 unpack("V",$_) 01234567890123456789012345678901
8239 ------------------------------------------------------------------
8240 EOT
8241 for $w (0..3) {
8243 $width = 2**$w;
8244 for ($shift=0; $shift < $width; ++$shift) {
8245 for ($off=0; $off < 32/$width; ++$off) {
8246 $str = pack("B*", "0"x32);
8247 $bits = (1<<$shift);
8248 vec($str, $off, $width) = $bits;
8249 $res = unpack("b*",$str);
8250 $val = unpack("V", $str);
8251 write;
8252 }
8253 }
8254 }
8255 format STDOUT =
8257 vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
8258 $off, $width, $bits, $val, $res
8259 .
8260 __END__
8261 Regardless of the machine architecture on which it runs, the
8263 example above should print the following table:
8264 0 1 2 3
8266 unpack("V",$_) 01234567890123456789012345678901
8267 ------------------------------------------------------------------
8268 vec($_, 0, 1) = 1 == 1 10000000000000000000000000000000
8269 vec($_, 1, 1) = 1 == 2 01000000000000000000000000000000
8270 vec($_, 2, 1) = 1 == 4 00100000000000000000000000000000
8271 vec($_, 3, 1) = 1 == 8 00010000000000000000000000000000
8272 vec($_, 4, 1) = 1 == 16 00001000000000000000000000000000
8273 vec($_, 5, 1) = 1 == 32 00000100000000000000000000000000
8274 vec($_, 6, 1) = 1 == 64 00000010000000000000000000000000
8275 vec($_, 7, 1) = 1 == 128 00000001000000000000000000000000
8276 vec($_, 8, 1) = 1 == 256 00000000100000000000000000000000
8277 vec($_, 9, 1) = 1 == 512 00000000010000000000000000000000
8278 vec($_,10, 1) = 1 == 1024 00000000001000000000000000000000
8279 vec($_,11, 1) = 1 == 2048 00000000000100000000000000000000
8280 vec($_,12, 1) = 1 == 4096 00000000000010000000000000000000
8281 vec($_,13, 1) = 1 == 8192 00000000000001000000000000000000
8282 vec($_,14, 1) = 1 == 16384 00000000000000100000000000000000
8283 vec($_,15, 1) = 1 == 32768 00000000000000010000000000000000
8284 vec($_,16, 1) = 1 == 65536 00000000000000001000000000000000
8285 vec($_,17, 1) = 1 == 131072 00000000000000000100000000000000
8286 vec($_,18, 1) = 1 == 262144 00000000000000000010000000000000
8287 vec($_,19, 1) = 1 == 524288 00000000000000000001000000000000
8288 vec($_,20, 1) = 1 == 1048576 00000000000000000000100000000000
8289 vec($_,21, 1) = 1 == 2097152 00000000000000000000010000000000
8290 vec($_,22, 1) = 1 == 4194304 00000000000000000000001000000000
8291 vec($_,23, 1) = 1 == 8388608 00000000000000000000000100000000
8292 vec($_,24, 1) = 1 == 16777216 00000000000000000000000010000000
8293 vec($_,25, 1) = 1 == 33554432 00000000000000000000000001000000
8294 vec($_,26, 1) = 1 == 67108864 00000000000000000000000000100000
8295 vec($_,27, 1) = 1 == 134217728 00000000000000000000000000010000
8296 vec($_,28, 1) = 1 == 268435456 00000000000000000000000000001000
8297 vec($_,29, 1) = 1 == 536870912 00000000000000000000000000000100
8298 vec($_,30, 1) = 1 == 1073741824 00000000000000000000000000000010
8299 vec($_,31, 1) = 1 == 2147483648 00000000000000000000000000000001
8300 vec($_, 0, 2) = 1 == 1 10000000000000000000000000000000
8301 vec($_, 1, 2) = 1 == 4 00100000000000000000000000000000
8302 vec($_, 2, 2) = 1 == 16 00001000000000000000000000000000
8303 vec($_, 3, 2) = 1 == 64 00000010000000000000000000000000
8304 vec($_, 4, 2) = 1 == 256 00000000100000000000000000000000
8305 vec($_, 5, 2) = 1 == 1024 00000000001000000000000000000000
8306 vec($_, 6, 2) = 1 == 4096 00000000000010000000000000000000
8307 vec($_, 7, 2) = 1 == 16384 00000000000000100000000000000000
8308 vec($_, 8, 2) = 1 == 65536 00000000000000001000000000000000
8309 vec($_, 9, 2) = 1 == 262144 00000000000000000010000000000000
8310 vec($_,10, 2) = 1 == 1048576 00000000000000000000100000000000
8311 vec($_,11, 2) = 1 == 4194304 00000000000000000000001000000000
8312 vec($_,12, 2) = 1 == 16777216 00000000000000000000000010000000
8313 vec($_,13, 2) = 1 == 67108864 00000000000000000000000000100000
8314 vec($_,14, 2) = 1 == 268435456 00000000000000000000000000001000
8315 vec($_,15, 2) = 1 == 1073741824 00000000000000000000000000000010
8316 vec($_, 0, 2) = 2 == 2 01000000000000000000000000000000
8317 vec($_, 1, 2) = 2 == 8 00010000000000000000000000000000
8318 vec($_, 2, 2) = 2 == 32 00000100000000000000000000000000
8319 vec($_, 3, 2) = 2 == 128 00000001000000000000000000000000
8320 vec($_, 4, 2) = 2 == 512 00000000010000000000000000000000
8321 vec($_, 5, 2) = 2 == 2048 00000000000100000000000000000000
8322 vec($_, 6, 2) = 2 == 8192 00000000000001000000000000000000
8323 vec($_, 7, 2) = 2 == 32768 00000000000000010000000000000000
8324 vec($_, 8, 2) = 2 == 131072 00000000000000000100000000000000
8325 vec($_, 9, 2) = 2 == 524288 00000000000000000001000000000000
8326 vec($_,10, 2) = 2 == 2097152 00000000000000000000010000000000
8327 vec($_,11, 2) = 2 == 8388608 00000000000000000000000100000000
8328 vec($_,12, 2) = 2 == 33554432 00000000000000000000000001000000
8329 vec($_,13, 2) = 2 == 134217728 00000000000000000000000000010000
8330 vec($_,14, 2) = 2 == 536870912 00000000000000000000000000000100
8331 vec($_,15, 2) = 2 == 2147483648 00000000000000000000000000000001
8332 vec($_, 0, 4) = 1 == 1 10000000000000000000000000000000
8333 vec($_, 1, 4) = 1 == 16 00001000000000000000000000000000
8334 vec($_, 2, 4) = 1 == 256 00000000100000000000000000000000
8335 vec($_, 3, 4) = 1 == 4096 00000000000010000000000000000000
8336 vec($_, 4, 4) = 1 == 65536 00000000000000001000000000000000
8337 vec($_, 5, 4) = 1 == 1048576 00000000000000000000100000000000
8338 vec($_, 6, 4) = 1 == 16777216 00000000000000000000000010000000
8339 vec($_, 7, 4) = 1 == 268435456 00000000000000000000000000001000
8340 vec($_, 0, 4) = 2 == 2 01000000000000000000000000000000
8341 vec($_, 1, 4) = 2 == 32 00000100000000000000000000000000
8342 vec($_, 2, 4) = 2 == 512 00000000010000000000000000000000
8343 vec($_, 3, 4) = 2 == 8192 00000000000001000000000000000000
8344 vec($_, 4, 4) = 2 == 131072 00000000000000000100000000000000
8345 vec($_, 5, 4) = 2 == 2097152 00000000000000000000010000000000
8346 vec($_, 6, 4) = 2 == 33554432 00000000000000000000000001000000
8347 vec($_, 7, 4) = 2 == 536870912 00000000000000000000000000000100
8348 vec($_, 0, 4) = 4 == 4 00100000000000000000000000000000
8349 vec($_, 1, 4) = 4 == 64 00000010000000000000000000000000
8350 vec($_, 2, 4) = 4 == 1024 00000000001000000000000000000000
8351 vec($_, 3, 4) = 4 == 16384 00000000000000100000000000000000
8352 vec($_, 4, 4) = 4 == 262144 00000000000000000010000000000000
8353 vec($_, 5, 4) = 4 == 4194304 00000000000000000000001000000000
8354 vec($_, 6, 4) = 4 == 67108864 00000000000000000000000000100000
8355 vec($_, 7, 4) = 4 == 1073741824 00000000000000000000000000000010
8356 vec($_, 0, 4) = 8 == 8 00010000000000000000000000000000
8357 vec($_, 1, 4) = 8 == 128 00000001000000000000000000000000
8358 vec($_, 2, 4) = 8 == 2048 00000000000100000000000000000000
8359 vec($_, 3, 4) = 8 == 32768 00000000000000010000000000000000
8360 vec($_, 4, 4) = 8 == 524288 00000000000000000001000000000000
8361 vec($_, 5, 4) = 8 == 8388608 00000000000000000000000100000000
8362 vec($_, 6, 4) = 8 == 134217728 00000000000000000000000000010000
8363 vec($_, 7, 4) = 8 == 2147483648 00000000000000000000000000000001
8364 vec($_, 0, 8) = 1 == 1 10000000000000000000000000000000
8365 vec($_, 1, 8) = 1 == 256 00000000100000000000000000000000
8366 vec($_, 2, 8) = 1 == 65536 00000000000000001000000000000000
8367 vec($_, 3, 8) = 1 == 16777216 00000000000000000000000010000000
8368 vec($_, 0, 8) = 2 == 2 01000000000000000000000000000000
8369 vec($_, 1, 8) = 2 == 512 00000000010000000000000000000000
8370 vec($_, 2, 8) = 2 == 131072 00000000000000000100000000000000
8371 vec($_, 3, 8) = 2 == 33554432 00000000000000000000000001000000
8372 vec($_, 0, 8) = 4 == 4 00100000000000000000000000000000
8373 vec($_, 1, 8) = 4 == 1024 00000000001000000000000000000000
8374 vec($_, 2, 8) = 4 == 262144 00000000000000000010000000000000
8375 vec($_, 3, 8) = 4 == 67108864 00000000000000000000000000100000
8376 vec($_, 0, 8) = 8 == 8 00010000000000000000000000000000
8377 vec($_, 1, 8) = 8 == 2048 00000000000100000000000000000000
8378 vec($_, 2, 8) = 8 == 524288 00000000000000000001000000000000
8379 vec($_, 3, 8) = 8 == 134217728 00000000000000000000000000010000
8380 vec($_, 0, 8) = 16 == 16 00001000000000000000000000000000
8381 vec($_, 1, 8) = 16 == 4096 00000000000010000000000000000000
8382 vec($_, 2, 8) = 16 == 1048576 00000000000000000000100000000000
8383 vec($_, 3, 8) = 16 == 268435456 00000000000000000000000000001000
8384 vec($_, 0, 8) = 32 == 32 00000100000000000000000000000000
8385 vec($_, 1, 8) = 32 == 8192 00000000000001000000000000000000
8386 vec($_, 2, 8) = 32 == 2097152 00000000000000000000010000000000
8387 vec($_, 3, 8) = 32 == 536870912 00000000000000000000000000000100
8388 vec($_, 0, 8) = 64 == 64 00000010000000000000000000000000
8389 vec($_, 1, 8) = 64 == 16384 00000000000000100000000000000000
8390 vec($_, 2, 8) = 64 == 4194304 00000000000000000000001000000000
8391 vec($_, 3, 8) = 64 == 1073741824 00000000000000000000000000000010
8392 vec($_, 0, 8) = 128 == 128 00000001000000000000000000000000
8393 vec($_, 1, 8) = 128 == 32768 00000000000000010000000000000000
8394 vec($_, 2, 8) = 128 == 8388608 00000000000000000000000100000000
8395 vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
8396 wait
8398 Behaves like wait(2) on your system: it waits for a child process
8399 to terminate and returns the pid of the deceased process, or "-1"
8400 if there are no child processes. The status is returned in $? and
8401 "${^CHILD_ERROR_NATIVE}". Note that a return value of "-1" could
8402 mean that child processes are being automatically reaped, as
8403 described in perlipc.
8404 If you use "wait" in your handler for $SIG{CHLD}, it may
8406 accidentally wait for the child created by "qx" or "system". See
8407 perlipc for details.
8408 Portability issues: "wait" in perlport.
8410 waitpid PID,FLAGS
8412 Waits for a particular child process to terminate and returns the
8413 pid of the deceased process, or "-1" if there is no such child
8414 process. A non-blocking wait (with WNOHANG in FLAGS) can return 0
8415 if there are child processes matching PID but none have terminated
8416 yet. The status is returned in $? and "${^CHILD_ERROR_NATIVE}".
8417 A PID of 0 indicates to wait for any child process whose process
8419 group ID is equal to that of the current process. A PID of less
8420 than "-1" indicates to wait for any child process whose process
8421 group ID is equal to -PID. A PID of "-1" indicates to wait for any
8422 child process.
8423 If you say
8425 use POSIX ":sys_wait_h";
8427 my $kid;
8429 do {
8430 $kid = waitpid(-1, WNOHANG);
8431 } while $kid > 0;
8432 or
8434 1 while waitpid(-1, WNOHANG) > 0;
8436 then you can do a non-blocking wait for all pending zombie
8438 processes (see "WAIT" in POSIX). Non-blocking wait is available on
8439 machines supporting either the waitpid(2) or wait4(2) syscalls.
8440 However, waiting for a particular pid with FLAGS of 0 is
8441 implemented everywhere. (Perl emulates the system call by
8442 remembering the status values of processes that have exited but
8443 have not been harvested by the Perl script yet.)
8444 Note that on some systems, a return value of "-1" could mean that
8446 child processes are being automatically reaped. See perlipc for
8447 details, and for other examples.
8448 Portability issues: "waitpid" in perlport.
8450 wantarray
8452 Returns true if the context of the currently executing subroutine
8453 or "eval" is looking for a list value. Returns false if the
8454 context is looking for a scalar. Returns the undefined value if
8455 the context is looking for no value (void context).
8456 return unless defined wantarray; # don't bother doing more
8458 my @a = complex_calculation();
8459 return wantarray ? @a : "@a";
8460 "wantarray"'s result is unspecified in the top level of a file, in
8462 a "BEGIN", "UNITCHECK", "CHECK", "INIT" or "END" block, or in a
8463 "DESTROY" method.
8464 This function should have been named wantlist() instead.
8466 warn LIST
8468 Emits a warning, usually by printing it to "STDERR". "warn"
8469 interprets its operand LIST in the same way as "die", but is
8470 slightly different in what it defaults to when LIST is empty or
8471 makes an empty string. If it is empty and $@ already contains an
8472 exception value then that value is used after appending
8473 "\t...caught". If it is empty and $@ is also empty then the string
8474 "Warning: Something's wrong" is used.
8475 By default, the exception derived from the operand LIST is
8477 stringified and printed to "STDERR". This behaviour can be altered
8478 by installing a $SIG{__WARN__} handler. If there is such a handler
8479 then no message is automatically printed; it is the handler's
8480 responsibility to deal with the exception as it sees fit (like, for
8481 instance, converting it into a "die"). Most handlers must
8482 therefore arrange to actually display the warnings that they are
8483 not prepared to deal with, by calling "warn" again in the handler.
8484 Note that this is quite safe and will not produce an endless loop,
8485 since "__WARN__" hooks are not called from inside one.
8486 You will find this behavior is slightly different from that of
8488 $SIG{__DIE__} handlers (which don't suppress the error text, but
8489 can instead call "die" again to change it).
8490 Using a "__WARN__" handler provides a powerful way to silence all
8492 warnings (even the so-called mandatory ones). An example:
8493 # wipe out *all* compile-time warnings
8495 BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
8496 my $foo = 10;
8497 my $foo = 20; # no warning about duplicate my $foo,
8498 # but hey, you asked for it!
8499 # no compile-time or run-time warnings before here
8500 $DOWARN = 1;
8501 # run-time warnings enabled after here
8503 warn "\$foo is alive and $foo!"; # does show up
8504 See perlvar for details on setting %SIG entries and for more
8506 examples. See the Carp module for other kinds of warnings using
8507 its "carp" and "cluck" functions.
8508 write FILEHANDLE
8510 write EXPR
8511 write
8512 Writes a formatted record (possibly multi-line) to the specified
8513 FILEHANDLE, using the format associated with that file. By default
8514 the format for a file is the one having the same name as the
8515 filehandle, but the format for the current output channel (see the
8516 "select" function) may be set explicitly by assigning the name of
8517 the format to the $~ variable.
8518 Top of form processing is handled automatically: if there is
8520 insufficient room on the current page for the formatted record, the
8521 page is advanced by writing a form feed and a special top-of-page
8522 format is used to format the new page header before the record is
8523 written. By default, the top-of-page format is the name of the
8524 filehandle with "_TOP" appended, or "top" in the current package if
8525 the former does not exist. This would be a problem with
8526 autovivified filehandles, but it may be dynamically set to the
8527 format of your choice by assigning the name to the $^ variable
8528 while that filehandle is selected. The number of lines remaining
8529 on the current page is in variable "$-", which can be set to 0 to
8530 force a new page.
8531 If FILEHANDLE is unspecified, output goes to the current default
8533 output channel, which starts out as STDOUT but may be changed by
8534 the "select" operator. If the FILEHANDLE is an EXPR, then the
8535 expression is evaluated and the resulting string is used to look up
8536 the name of the FILEHANDLE at run time. For more on formats, see
8537 perlform.
8538 Note that write is not the opposite of "read". Unfortunately.
8540 y///
8542 The transliteration operator. Same as "tr///". See "Quote-Like
8543 Operators" in perlop.
8544 Non-function Keywords by Cross-reference
8546 perldata
8547 __DATA__
8549 __END__
8550 These keywords are documented in "Special Literals" in perldata.
8551 perlmod
8553 BEGIN
8555 CHECK
8556 END
8557 INIT
8558 UNITCHECK
8559 These compile phase keywords are documented in "BEGIN, UNITCHECK,
8560 CHECK, INIT and END" in perlmod.
8561 perlobj
8563 DESTROY
8565 This method keyword is documented in "Destructors" in perlobj.
8566 perlop
8568 and
8570 cmp
8571 eq
8572 ge
8573 gt
8574 le
8575 lt
8576 ne
8577 not
8578 or
8579 x
8580 xor These operators are documented in perlop.
8581 perlsub
8583 AUTOLOAD
8585 This keyword is documented in "Autoloading" in perlsub.
8586 perlsyn
8588 else
8590 elsif
8591 for
8592 foreach
8593 if
8594 unless
8595 until
8596 while
8597 These flow-control keywords are documented in "Compound Statements"
8598 in perlsyn.
8599 elseif
8601 The "else if" keyword is spelled "elsif" in Perl. There's no
8602 "elif" or "else if" either. It does parse "elseif", but only to
8603 warn you about not using it.
8604 See the documentation for flow-control keywords in "Compound
8606 Statements" in perlsyn.
8607 default
8609 given
8610 when
8611 These flow-control keywords related to the experimental switch
8612 feature are documented in "Switch Statements" in perlsyn.
8613perl v5.34.1 2022-03-15 PERLFUNC(1)