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