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