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