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 a scalar context to its argument,
17 while a list operator may provide either scalar or list contexts for
18 its 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 -w switch it can warn you about this. For
47 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 a scalar context by
58 returning the undefined value, and in a 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 construction 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.) all 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 are "wait", "waitpid", and "syscall". System calls also set the
85 special $! variable on failure. Other functions do not, except
86 accidentally.
87 Extension modules can also hook into the Perl parser to define new
89 kinds of keyword-headed expression. These may look like functions, but
90 may also look completely different. The syntax following the keyword
91 is defined entirely by the extension. If you are an implementor, see
92 "PL_keyword_plugin" in perlapi for the mechanism. If you are using
93 such a module, see the module's documentation for details of the syntax
94 that it defines.
95 Perl Functions by Category
97 Here are Perl's functions (including things that look like functions,
98 like some keywords and named operators) arranged by category. Some
99 functions appear in more than one place.
100 Functions for SCALARs or strings
102 "chomp", "chop", "chr", "crypt", "hex", "index", "lc", "lcfirst",
103 "length", "oct", "ord", "pack", "q//", "qq//", "reverse", "rindex",
104 "sprintf", "substr", "tr///", "uc", "ucfirst", "y///"
105 Regular expressions and pattern matching
107 "m//", "pos", "quotemeta", "s///", "split", "study", "qr//"
108 Numeric functions
110 "abs", "atan2", "cos", "exp", "hex", "int", "log", "oct", "rand",
111 "sin", "sqrt", "srand"
112 Functions for real @ARRAYs
114 "each", "keys", "pop", "push", "shift", "splice", "unshift",
115 "values"
116 Functions for list data
118 "grep", "join", "map", "qw//", "reverse", "sort", "unpack"
119 Functions for real %HASHes
121 "delete", "each", "exists", "keys", "values"
122 Input and output functions
124 "binmode", "close", "closedir", "dbmclose", "dbmopen", "die",
125 "eof", "fileno", "flock", "format", "getc", "print", "printf",
126 "read", "readdir", "rewinddir", "say", "seek", "seekdir", "select",
127 "syscall", "sysread", "sysseek", "syswrite", "tell", "telldir",
128 "truncate", "warn", "write"
129 Functions for fixed length data or records
131 "pack", "read", "syscall", "sysread", "syswrite", "unpack", "vec"
132 Functions for filehandles, files, or directories
134 "-X", "chdir", "chmod", "chown", "chroot", "fcntl", "glob",
135 "ioctl", "link", "lstat", "mkdir", "open", "opendir", "readlink",
136 "rename", "rmdir", "stat", "symlink", "sysopen", "umask", "unlink",
137 "utime"
138 Keywords related to the control flow of your Perl program
140 "caller", "continue", "die", "do", "dump", "eval", "exit", "goto",
141 "last", "next", "redo", "return", "sub", "wantarray"
142 Keywords related to switch
144 "break", "continue", "given", "when", "default"
145 (These are available only if you enable the "switch" feature. See
147 feature and "Switch statements" in perlsyn.)
148 Keywords related to scoping
150 "caller", "import", "local", "my", "our", "state", "package", "use"
151 ("state" is available only if the "state" feature is enabled. See
153 feature.)
154 Miscellaneous functions
156 "defined", "dump", "eval", "formline", "local", "my", "our",
157 "reset", "scalar", "state", "undef", "wantarray"
158 Functions for processes and process groups
160 "alarm", "exec", "fork", "getpgrp", "getppid", "getpriority",
161 "kill", "pipe", "qx//", "setpgrp", "setpriority", "sleep",
162 "system", "times", "wait", "waitpid"
163 Keywords related to Perl modules
165 "do", "import", "no", "package", "require", "use"
166 Keywords related to classes and object-orientation
168 "bless", "dbmclose", "dbmopen", "package", "ref", "tie", "tied",
169 "untie", "use"
170 Low-level socket functions
172 "accept", "bind", "connect", "getpeername", "getsockname",
173 "getsockopt", "listen", "recv", "send", "setsockopt", "shutdown",
174 "socket", "socketpair"
175 System V interprocess communication functions
177 "msgctl", "msgget", "msgrcv", "msgsnd", "semctl", "semget",
178 "semop", "shmctl", "shmget", "shmread", "shmwrite"
179 Fetching user and group info
181 "endgrent", "endhostent", "endnetent", "endpwent", "getgrent",
182 "getgrgid", "getgrnam", "getlogin", "getpwent", "getpwnam",
183 "getpwuid", "setgrent", "setpwent"
184 Fetching network info
186 "endprotoent", "endservent", "gethostbyaddr", "gethostbyname",
187 "gethostent", "getnetbyaddr", "getnetbyname", "getnetent",
188 "getprotobyname", "getprotobynumber", "getprotoent",
189 "getservbyname", "getservbyport", "getservent", "sethostent",
190 "setnetent", "setprotoent", "setservent"
191 Time-related functions
193 "gmtime", "localtime", "time", "times"
194 Functions new in perl5
196 "abs", "bless", "break", "chomp", "chr", "continue", "default",
197 "exists", "formline", "given", "glob", "import", "lc", "lcfirst",
198 "lock", "map", "my", "no", "our", "prototype", "qr//", "qw//",
199 "qx//", "readline", "readpipe", "ref", "sub"*, "sysopen", "tie",
200 "tied", "uc", "ucfirst", "untie", "use", "when"
201 * "sub" was a keyword in Perl 4, but in Perl 5 it is an operator,
203 which can be used in expressions.
204 Functions obsoleted in perl5
206 "dbmclose", "dbmopen"
207 Portability
209 Perl was born in Unix and can therefore access all common Unix system
210 calls. In non-Unix environments, the functionality of some Unix system
211 calls may not be available, or details of the available functionality
212 may differ slightly. The Perl functions affected by this are:
213 "-X", "binmode", "chmod", "chown", "chroot", "crypt", "dbmclose",
215 "dbmopen", "dump", "endgrent", "endhostent", "endnetent",
216 "endprotoent", "endpwent", "endservent", "exec", "fcntl", "flock",
217 "fork", "getgrent", "getgrgid", "gethostbyname", "gethostent",
218 "getlogin", "getnetbyaddr", "getnetbyname", "getnetent", "getppid",
219 "getpgrp", "getpriority", "getprotobynumber", "getprotoent",
220 "getpwent", "getpwnam", "getpwuid", "getservbyport", "getservent",
221 "getsockopt", "glob", "ioctl", "kill", "link", "lstat", "msgctl",
222 "msgget", "msgrcv", "msgsnd", "open", "pipe", "readlink", "rename",
223 "select", "semctl", "semget", "semop", "setgrent", "sethostent",
224 "setnetent", "setpgrp", "setpriority", "setprotoent", "setpwent",
225 "setservent", "setsockopt", "shmctl", "shmget", "shmread", "shmwrite",
226 "socket", "socketpair", "stat", "symlink", "syscall", "sysopen",
227 "system", "times", "truncate", "umask", "unlink", "utime", "wait",
228 "waitpid"
229 For more information about the portability of these functions, see
231 perlport and other available platform-specific documentation.
232 Alphabetical Listing of Perl Functions
234 -X FILEHANDLE
235 -X EXPR
236 -X DIRHANDLE
237 -X A file test, where X is one of the letters listed below. This
238 unary operator takes one argument, either a filename, a filehandle,
239 or a dirhandle, and tests the associated file to see if something
240 is true about it. If the argument is omitted, tests $_, except for
241 "-t", which tests STDIN. Unless otherwise documented, it returns 1
242 for true and '' for false, or the undefined value if the file
243 doesn't exist. Despite the funny names, precedence is the same as
244 any other named unary operator. The operator may be any of:
245 -r File is readable by effective uid/gid.
247 -w File is writable by effective uid/gid.
248 -x File is executable by effective uid/gid.
249 -o File is owned by effective uid.
250 -R File is readable by real uid/gid.
252 -W File is writable by real uid/gid.
253 -X File is executable by real uid/gid.
254 -O File is owned by real uid.
255 -e File exists.
257 -z File has zero size (is empty).
258 -s File has nonzero size (returns size in bytes).
259 -f File is a plain file.
261 -d File is a directory.
262 -l File is a symbolic link.
263 -p File is a named pipe (FIFO), or Filehandle is a pipe.
264 -S File is a socket.
265 -b File is a block special file.
266 -c File is a character special file.
267 -t Filehandle is opened to a tty.
268 -u File has setuid bit set.
270 -g File has setgid bit set.
271 -k File has sticky bit set.
272 -T File is an ASCII text file (heuristic guess).
274 -B File is a "binary" file (opposite of -T).
275 -M Script start time minus file modification time, in days.
277 -A Same for access time.
278 -C Same for inode change time (Unix, may differ for other platforms)
279 Example:
281 while (<>) {
283 chomp;
284 next unless -f $_; # ignore specials
285 #...
286 }
287 The interpretation of the file permission operators "-r", "-R",
289 "-w", "-W", "-x", and "-X" is by default based solely on the mode
290 of the file and the uids and gids of the user. There may be other
291 reasons you can't actually read, write, or execute the file: for
292 example network filesystem access controls, ACLs (access control
293 lists), read-only filesystems, and unrecognized executable formats.
294 Note that the use of these six specific operators to verify if some
295 operation is possible is usually a mistake, because it may be open
296 to race conditions.
297 Also note that, for the superuser on the local filesystems, the
299 "-r", "-R", "-w", and "-W" tests always return 1, and "-x" and "-X"
300 return 1 if any execute bit is set in the mode. Scripts run by the
301 superuser may thus need to do a stat() to determine the actual mode
302 of the file, or temporarily set their effective uid to something
303 else.
304 If you are using ACLs, there is a pragma called "filetest" that may
306 produce more accurate results than the bare stat() mode bits. When
307 under the "use filetest 'access'" the above-mentioned filetests
308 test whether the permission can (not) be granted using the
309 access(2) family of system calls. Also note that the "-x" and "-X"
310 may under this pragma return true even if there are no execute
311 permission bits set (nor any extra execute permission ACLs). This
312 strangeness is due to the underlying system calls' definitions.
313 Note also that, due to the implementation of "use filetest
314 'access'", the "_" special filehandle won't cache the results of
315 the file tests when this pragma is in effect. Read the
316 documentation for the "filetest" pragma for more information.
317 Note that "-s/a/b/" does not do a negated substitution. Saying
319 "-exp($foo)" still works as expected, however: only single letters
320 following a minus are interpreted as file tests.
321 The "-T" and "-B" switches work as follows. The first block or so
323 of the file is examined for odd characters such as strange control
324 codes or characters with the high bit set. If too many strange
325 characters (>30%) are found, it's a "-B" file; otherwise it's a
326 "-T" file. Also, any file containing a zero byte in the first
327 block is considered a binary file. If "-T" or "-B" is used on a
328 filehandle, the current IO buffer is examined rather than the first
329 block. Both "-T" and "-B" return true on an empty file, or a file
330 at EOF when testing a filehandle. Because you have to read a file
331 to do the "-T" test, on most occasions you want to use a "-f"
332 against the file first, as in "next unless -f $file && -T $file".
333 If any of the file tests (or either the "stat" or "lstat"
335 operators) are given the special filehandle consisting of a
336 solitary underline, then the stat structure of the previous file
337 test (or stat operator) is used, saving a system call. (This
338 doesn't work with "-t", and you need to remember that lstat() and
339 "-l" leave values in the stat structure for the symbolic link, not
340 the real file.) (Also, if the stat buffer was filled by an "lstat"
341 call, "-T" and "-B" will reset it with the results of "stat _").
342 Example:
343 print "Can do.\n" if -r $a || -w _ || -x _;
345 stat($filename);
347 print "Readable\n" if -r _;
348 print "Writable\n" if -w _;
349 print "Executable\n" if -x _;
350 print "Setuid\n" if -u _;
351 print "Setgid\n" if -g _;
352 print "Sticky\n" if -k _;
353 print "Text\n" if -T _;
354 print "Binary\n" if -B _;
355 As of Perl 5.9.1, as a form of purely syntactic sugar, you can
357 stack file test operators, in a way that "-f -w -x $file" is
358 equivalent to "-x $file && -w _ && -f _". (This is only fancy
359 fancy: if you use the return value of "-f $file" as an argument to
360 another filetest operator, no special magic will happen.)
361 abs VALUE
363 abs Returns the absolute value of its argument. If VALUE is omitted,
364 uses $_.
365 accept NEWSOCKET,GENERICSOCKET
367 Accepts an incoming socket connect, just as accept(2) does.
368 Returns the packed address if it succeeded, false otherwise. See
369 the example in "Sockets: Client/Server Communication" in perlipc.
370 On systems that support a close-on-exec flag on files, the flag
372 will be set for the newly opened file descriptor, as determined by
373 the value of $^F. See "$^F" in perlvar.
374 alarm SECONDS
376 alarm
377 Arranges to have a SIGALRM delivered to this process after the
378 specified number of wallclock seconds has elapsed. If SECONDS is
379 not specified, the value stored in $_ is used. (On some machines,
380 unfortunately, the elapsed time may be up to one second less or
381 more than you specified because of how seconds are counted, and
382 process scheduling may delay the delivery of the signal even
383 further.)
384 Only one timer may be counting at once. Each call disables the
386 previous timer, and an argument of 0 may be supplied to cancel the
387 previous timer without starting a new one. The returned value is
388 the amount of time remaining on the previous timer.
389 For delays of finer granularity than one second, the Time::HiRes
391 module (from CPAN, and starting from Perl 5.8 part of the standard
392 distribution) provides ualarm(). You may also use Perl's four-
393 argument version of select() leaving the first three arguments
394 undefined, or you might be able to use the "syscall" interface to
395 access setitimer(2) if your system supports it. See perlfaq8 for
396 details.
397 It is usually a mistake to intermix "alarm" and "sleep" calls,
399 because "sleep" may be internally implemented on your system with
400 "alarm".
401 If you want to use "alarm" to time out a system call you need to
403 use an "eval"/"die" pair. You can't rely on the alarm causing the
404 system call to fail with $! set to "EINTR" because Perl sets up
405 signal handlers to restart system calls on some systems. Using
406 "eval"/"die" always works, modulo the caveats given in "Signals" in
407 perlipc.
408 eval {
410 local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
411 alarm $timeout;
412 $nread = sysread SOCKET, $buffer, $size;
413 alarm 0;
414 };
415 if ($@) {
416 die unless $@ eq "alarm\n"; # propagate unexpected errors
417 # timed out
418 }
419 else {
420 # didn't
421 }
422 For more information see perlipc.
424 atan2 Y,X
426 Returns the arctangent of Y/X in the range -PI to PI.
427 For the tangent operation, you may use the "Math::Trig::tan"
429 function, or use the familiar relation:
430 sub tan { sin($_[0]) / cos($_[0]) }
432 The return value for "atan2(0,0)" is implementation-defined;
434 consult your atan2(3) manpage for more information.
435 bind SOCKET,NAME
437 Binds a network address to a socket, just as bind(2) does. Returns
438 true if it succeeded, false otherwise. NAME should be a packed
439 address of the appropriate type for the socket. See the examples
440 in "Sockets: Client/Server Communication" in perlipc.
441 binmode FILEHANDLE, LAYER
443 binmode FILEHANDLE
444 Arranges for FILEHANDLE to be read or written in "binary" or "text"
445 mode on systems where the run-time libraries distinguish between
446 binary and text files. If FILEHANDLE is an expression, the value
447 is taken as the name of the filehandle. Returns true on success,
448 otherwise it returns "undef" and sets $! (errno).
449 On some systems (in general, DOS and Windows-based systems)
451 binmode() is necessary when you're not working with a text file.
452 For the sake of portability it is a good idea to always use it when
453 appropriate, and to never use it when it isn't appropriate. Also,
454 people can set their I/O to be by default UTF-8 encoded Unicode,
455 not bytes.
456 In other words: regardless of platform, use binmode() on binary
458 data, like for example images.
459 If LAYER is present it is a single string, but may contain multiple
461 directives. The directives alter the behaviour of the filehandle.
462 When LAYER is present using binmode on a text file makes sense.
463 If LAYER is omitted or specified as ":raw" the filehandle is made
465 suitable for passing binary data. This includes turning off
466 possible CRLF translation and marking it as bytes (as opposed to
467 Unicode characters). Note that, despite what may be implied in
468 "Programming Perl" (the Camel, 3rd edition) or elsewhere, ":raw" is
469 not simply the inverse of ":crlf". Other layers that would affect
470 the binary nature of the stream are also disabled. See PerlIO,
471 perlrun, and the discussion about the PERLIO environment variable.
472 The ":bytes", ":crlf", ":utf8", and any other directives of the
474 form ":...", are called I/O layers. The "open" pragma can be used
475 to establish default I/O layers. See open.
476 The LAYER parameter of the binmode() function is described as
478 "DISCIPLINE" in "Programming Perl, 3rd Edition". However, since
479 the publishing of this book, by many known as "Camel III", the
480 consensus of the naming of this functionality has moved from
481 "discipline" to "layer". All documentation of this version of Perl
482 therefore refers to "layers" rather than to "disciplines". Now
483 back to the regularly scheduled documentation...
484 To mark FILEHANDLE as UTF-8, use ":utf8" or ":encoding(utf8)".
486 ":utf8" just marks the data as UTF-8 without further checking,
487 while ":encoding(utf8)" checks the data for actually being valid
488 UTF-8. More details can be found in PerlIO::encoding.
489 In general, binmode() should be called after open() but before any
491 I/O is done on the filehandle. Calling binmode() normally flushes
492 any pending buffered output data (and perhaps pending input data)
493 on the handle. An exception to this is the ":encoding" layer that
494 changes the default character encoding of the handle, see open.
495 The ":encoding" layer sometimes needs to be called in mid-stream,
496 and it doesn't flush the stream. The ":encoding" also implicitly
497 pushes on top of itself the ":utf8" layer because internally Perl
498 operates on UTF8-encoded Unicode characters.
499 The operating system, device drivers, C libraries, and Perl run-
501 time system all work together to let the programmer treat a single
502 character ("\n") as the line terminator, irrespective of the
503 external representation. On many operating systems, the native
504 text file representation matches the internal representation, but
505 on some platforms the external representation of "\n" is made up of
506 more than one character.
507 Mac OS, all variants of Unix, and Stream_LF files on VMS use a
509 single character to end each line in the external representation of
510 text (even though that single character is CARRIAGE RETURN on Mac
511 OS and LINE FEED on Unix and most VMS files). In other systems like
512 OS/2, DOS and the various flavors of MS-Windows your program sees a
513 "\n" as a simple "\cJ", but what's stored in text files are the two
514 characters "\cM\cJ". That means that, if you don't use binmode()
515 on these systems, "\cM\cJ" sequences on disk will be converted to
516 "\n" on input, and any "\n" in your program will be converted back
517 to "\cM\cJ" on output. This is what you want for text files, but
518 it can be disastrous for binary files.
519 Another consequence of using binmode() (on some systems) is that
521 special end-of-file markers will be seen as part of the data
522 stream. For systems from the Microsoft family this means that if
523 your binary data contains "\cZ", the I/O subsystem will regard it
524 as the end of the file, unless you use binmode().
525 binmode() is important not only for readline() and print()
527 operations, but also when using read(), seek(), sysread(),
528 syswrite() and tell() (see perlport for more details). See the $/
529 and "$\" variables in perlvar for how to manually set your input
530 and output line-termination sequences.
531 bless REF,CLASSNAME
533 bless REF
534 This function tells the thingy referenced by REF that it is now an
535 object in the CLASSNAME package. If CLASSNAME is omitted, the
536 current package is used. Because a "bless" is often the last thing
537 in a constructor, it returns the reference for convenience. Always
538 use the two-argument version if a derived class might inherit the
539 function doing the blessing. See perltoot and perlobj for more
540 about the blessing (and blessings) of objects.
541 Consider always blessing objects in CLASSNAMEs that are mixed case.
543 Namespaces with all lowercase names are considered reserved for
544 Perl pragmata. Builtin types have all uppercase names. To prevent
545 confusion, you may wish to avoid such package names as well. Make
546 sure that CLASSNAME is a true value.
547 See "Perl Modules" in perlmod.
549 break
551 Break out of a "given()" block.
552 This keyword is enabled by the "switch" feature: see feature for
554 more information.
555 caller EXPR
557 caller
558 Returns the context of the current subroutine call. In scalar
559 context, returns the caller's package name if there is a caller
560 (that is, if we're in a subroutine or "eval" or "require") and the
561 undefined value otherwise. In list context, returns
562 # 0 1 2
564 ($package, $filename, $line) = caller;
565 With EXPR, it returns some extra information that the debugger uses
567 to print a stack trace. The value of EXPR indicates how many call
568 frames to go back before the current one.
569 # 0 1 2 3 4
571 ($package, $filename, $line, $subroutine, $hasargs,
572 # 5 6 7 8 9 10
574 $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
575 = caller($i);
576 Here $subroutine may be "(eval)" if the frame is not a subroutine
578 call, but an "eval". In such a case additional elements $evaltext
579 and $is_require are set: $is_require is true if the frame is
580 created by a "require" or "use" statement, $evaltext contains the
581 text of the "eval EXPR" statement. In particular, for an "eval
582 BLOCK" statement, $subroutine is "(eval)", but $evaltext is
583 undefined. (Note also that each "use" statement creates a
584 "require" frame inside an "eval EXPR" frame.) $subroutine may also
585 be "(unknown)" if this particular subroutine happens to have been
586 deleted from the symbol table. $hasargs is true if a new instance
587 of @_ was set up for the frame. $hints and $bitmask contain
588 pragmatic hints that the caller was compiled with. The $hints and
589 $bitmask values are subject to change between versions of Perl, and
590 are not meant for external use.
591 $hinthash is a reference to a hash containing the value of "%^H"
593 when the caller was compiled, or "undef" if "%^H" was empty. Do not
594 modify the values of this hash, as they are the actual values
595 stored in the optree.
596 Furthermore, when called from within the DB package, caller returns
598 more detailed information: it sets the list variable @DB::args to
599 be the arguments with which the subroutine was invoked.
600 Be aware that the optimizer might have optimized call frames away
602 before "caller" had a chance to get the information. That means
603 that caller(N) might not return information about the call frame
604 you expect it to, for "N > 1". In particular, @DB::args might have
605 information from the previous time "caller" was called.
606 Also be aware that setting @DB::args is best effort, intended for
608 debugging or generating backtraces, and should not be relied upon.
609 In particular, as @_ contains aliases to the caller's arguments,
610 Perl does not take a copy of @_, so @DB::args will contain
611 modifications the subroutine makes to @_ or its contents, not the
612 original values at call time. @DB::args, like @_, does not hold
613 explicit references to its elements, so under certain cases its
614 elements may have become freed and reallocated for other variables
615 or temporary values. Finally, a side effect of the current
616 implementation means that the effects of "shift @_" can normally be
617 undone (but not "pop @_" or other splicing, and not if a reference
618 to @_ has been taken, and subject to the caveat about reallocated
619 elements), so @DB::args is actually a hybrid of the current state
620 and initial state of @_. Buyer beware.
621 chdir EXPR
623 chdir FILEHANDLE
624 chdir DIRHANDLE
625 chdir
626 Changes the working directory to EXPR, if possible. If EXPR is
627 omitted, changes to the directory specified by $ENV{HOME}, if set;
628 if not, changes to the directory specified by $ENV{LOGDIR}. (Under
629 VMS, the variable $ENV{SYS$LOGIN} is also checked, and used if it
630 is set.) If neither is set, "chdir" does nothing. It returns true
631 on success, false otherwise. See the example under "die".
632 On systems that support fchdir(2), you may pass a filehandle or
634 directory handle as argument. On systems that don't support
635 fchdir(2), passing handles raises an exception.
636 chmod LIST
638 Changes the permissions of a list of files. The first element of
639 the list must be the numerical mode, which should probably be an
640 octal number, and which definitely should not be a string of octal
641 digits: 0644 is okay, but "0644" is not. Returns the number of
642 files successfully changed. See also "oct", if all you have is a
643 string.
644 $cnt = chmod 0755, "foo", "bar";
646 chmod 0755, @executables;
647 $mode = "0644"; chmod $mode, "foo"; # !!! sets mode to
648 # --w----r-T
649 $mode = "0644"; chmod oct($mode), "foo"; # this is better
650 $mode = 0644; chmod $mode, "foo"; # this is best
651 On systems that support fchmod(2), you may pass filehandles among
653 the files. On systems that don't support fchmod(2), passing
654 filehandles raises an exception. Filehandles must be passed as
655 globs or glob references to be recognized; barewords are considered
656 filenames.
657 open(my $fh, "<", "foo");
659 my $perm = (stat $fh)[2] & 07777;
660 chmod($perm | 0600, $fh);
661 You can also import the symbolic "S_I*" constants from the "Fcntl"
663 module:
664 use Fcntl qw( :mode );
666 chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
667 # Identical to the chmod 0755 of the example above.
668 chomp VARIABLE
670 chomp( LIST )
671 chomp
672 This safer version of "chop" removes any trailing string that
673 corresponds to the current value of $/ (also known as
674 $INPUT_RECORD_SEPARATOR in the "English" module). It returns the
675 total number of characters removed from all its arguments. It's
676 often used to remove the newline from the end of an input record
677 when you're worried that the final record may be missing its
678 newline. When in paragraph mode ("$/ = """), it removes all
679 trailing newlines from the string. When in slurp mode ("$/ =
680 undef") or fixed-length record mode ($/ is a reference to an
681 integer or the like, see perlvar) chomp() won't remove anything.
682 If VARIABLE is omitted, it chomps $_. Example:
683 while (<>) {
685 chomp; # avoid \n on last field
686 @array = split(/:/);
687 # ...
688 }
689 If VARIABLE is a hash, it chomps the hash's values, but not its
691 keys.
692 You can actually chomp anything that's an lvalue, including an
694 assignment:
695 chomp($cwd = `pwd`);
697 chomp($answer = <STDIN>);
698 If you chomp a list, each element is chomped, and the total number
700 of characters removed is returned.
701 Note that parentheses are necessary when you're chomping anything
703 that is not a simple variable. This is because "chomp $cwd =
704 `pwd`;" is interpreted as "(chomp $cwd) = `pwd`;", rather than as
705 "chomp( $cwd = `pwd` )" which you might expect. Similarly, "chomp
706 $a, $b" is interpreted as "chomp($a), $b" rather than as "chomp($a,
707 $b)".
708 chop VARIABLE
710 chop( LIST )
711 chop
712 Chops off the last character of a string and returns the character
713 chopped. It is much more efficient than "s/.$//s" because it
714 neither scans nor copies the string. If VARIABLE is omitted, chops
715 $_. If VARIABLE is a hash, it chops the hash's values, but not its
716 keys.
717 You can actually chop anything that's an lvalue, including an
719 assignment.
720 If you chop a list, each element is chopped. Only the value of the
722 last "chop" is returned.
723 Note that "chop" returns the last character. To return all but the
725 last character, use "substr($string, 0, -1)".
726 See also "chomp".
728 chown LIST
730 Changes the owner (and group) of a list of files. The first two
731 elements of the list must be the numeric uid and gid, in that
732 order. A value of -1 in either position is interpreted by most
733 systems to leave that value unchanged. Returns the number of files
734 successfully changed.
735 $cnt = chown $uid, $gid, 'foo', 'bar';
737 chown $uid, $gid, @filenames;
738 On systems that support fchown(2), you may pass filehandles among
740 the files. On systems that don't support fchown(2), passing
741 filehandles raises an exception. Filehandles must be passed as
742 globs or glob references to be recognized; barewords are considered
743 filenames.
744 Here's an example that looks up nonnumeric uids in the passwd file:
746 print "User: ";
748 chomp($user = <STDIN>);
749 print "Files: ";
750 chomp($pattern = <STDIN>);
751 ($login,$pass,$uid,$gid) = getpwnam($user)
753 or die "$user not in passwd file";
754 @ary = glob($pattern); # expand filenames
756 chown $uid, $gid, @ary;
757 On most systems, you are not allowed to change the ownership of the
759 file unless you're the superuser, although you should be able to
760 change the group to any of your secondary groups. On insecure
761 systems, these restrictions may be relaxed, but this is not a
762 portable assumption. On POSIX systems, you can detect this
763 condition this way:
764 use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
766 $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
767 chr NUMBER
769 chr Returns the character represented by that NUMBER in the character
770 set. For example, "chr(65)" is "A" in either ASCII or Unicode, and
771 chr(0x263a) is a Unicode smiley face.
772 Negative values give the Unicode replacement character
774 (chr(0xfffd)), except under the bytes pragma, where the low eight
775 bits of the value (truncated to an integer) are used.
776 If NUMBER is omitted, uses $_.
778 For the reverse, use "ord".
780 Note that characters from 128 to 255 (inclusive) are by default
782 internally not encoded as UTF-8 for backward compatibility reasons.
783 See perlunicode for more about Unicode.
785 chroot FILENAME
787 chroot
788 This function works like the system call by the same name: it makes
789 the named directory the new root directory for all further
790 pathnames that begin with a "/" by your process and all its
791 children. (It doesn't change your current working directory, which
792 is unaffected.) For security reasons, this call is restricted to
793 the superuser. If FILENAME is omitted, does a "chroot" to $_.
794 close FILEHANDLE
796 close
797 Closes the file or pipe associated with the filehandle, flushes the
798 IO buffers, and closes the system file descriptor. Returns true if
799 those operations have succeeded and if no error was reported by any
800 PerlIO layer. Closes the currently selected filehandle if the
801 argument is omitted.
802 You don't have to close FILEHANDLE if you are immediately going to
804 do another "open" on it, because "open" closes it for you. (See
805 "open".) However, an explicit "close" on an input file resets the
806 line counter ($.), while the implicit close done by "open" does
807 not.
808 If the filehandle came from a piped open, "close" returns false if
810 one of the other syscalls involved fails or if its program exits
811 with non-zero status. If the only problem was that the program
812 exited non-zero, $! will be set to 0. Closing a pipe also waits
813 for the process executing on the pipe to exit--in case you wish to
814 look at the output of the pipe afterwards--and implicitly puts the
815 exit status value of that command into $? and
816 "${^CHILD_ERROR_NATIVE}".
817 Closing the read end of a pipe before the process writing to it at
819 the other end is done writing results in the writer receiving a
820 SIGPIPE. If the other end can't handle that, be sure to read all
821 the data before closing the pipe.
822 Example:
824 open(OUTPUT, '|sort >foo') # pipe to sort
826 or die "Can't start sort: $!";
827 #... # print stuff to output
828 close OUTPUT # wait for sort to finish
829 or warn $! ? "Error closing sort pipe: $!"
830 : "Exit status $? from sort";
831 open(INPUT, 'foo') # get sort's results
832 or die "Can't open 'foo' for input: $!";
833 FILEHANDLE may be an expression whose value can be used as an
835 indirect filehandle, usually the real filehandle name.
836 closedir DIRHANDLE
838 Closes a directory opened by "opendir" and returns the success of
839 that system call.
840 connect SOCKET,NAME
842 Attempts to connect to a remote socket, just like connect(2).
843 Returns true if it succeeded, false otherwise. NAME should be a
844 packed address of the appropriate type for the socket. See the
845 examples in "Sockets: Client/Server Communication" in perlipc.
846 continue BLOCK
848 continue
849 "continue" is actually a flow control statement rather than a
850 function. If there is a "continue" BLOCK attached to a BLOCK
851 (typically in a "while" or "foreach"), it is always executed just
852 before the conditional is about to be evaluated again, just like
853 the third part of a "for" loop in C. Thus it can be used to
854 increment a loop variable, even when the loop has been continued
855 via the "next" statement (which is similar to the C "continue"
856 statement).
857 "last", "next", or "redo" may appear within a "continue" block;
859 "last" and "redo" behave as if they had been executed within the
860 main block. So will "next", but since it will execute a "continue"
861 block, it may be more entertaining.
862 while (EXPR) {
864 ### redo always comes here
865 do_something;
866 } continue {
867 ### next always comes here
868 do_something_else;
869 # then back the top to re-check EXPR
870 }
871 ### last always comes here
872 Omitting the "continue" section is equivalent to using an empty
874 one, logically enough, so "next" goes directly back to check the
875 condition at the top of the loop.
876 If the "switch" feature is enabled, "continue" is also a function
878 that exits the current "when" (or "default") block and falls
879 through to the next one. See feature and "Switch statements" in
880 perlsyn for more information.
881 cos EXPR
883 cos Returns the cosine of EXPR (expressed in radians). If EXPR is
884 omitted, takes cosine of $_.
885 For the inverse cosine operation, you may use the
887 "Math::Trig::acos()" function, or use this relation:
888 sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
890 crypt PLAINTEXT,SALT
892 Creates a digest string exactly like the crypt(3) function in the C
893 library (assuming that you actually have a version there that has
894 not been extirpated as a potential munition).
895 crypt() is a one-way hash function. The PLAINTEXT and SALT is
897 turned into a short string, called a digest, which is returned.
898 The same PLAINTEXT and SALT will always return the same string, but
899 there is no (known) way to get the original PLAINTEXT from the
900 hash. Small changes in the PLAINTEXT or SALT will result in large
901 changes in the digest.
902 There is no decrypt function. This function isn't all that useful
904 for cryptography (for that, look for Crypt modules on your nearby
905 CPAN mirror) and the name "crypt" is a bit of a misnomer. Instead
906 it is primarily used to check if two pieces of text are the same
907 without having to transmit or store the text itself. An example is
908 checking if a correct password is given. The digest of the
909 password is stored, not the password itself. The user types in a
910 password that is crypt()'d with the same salt as the stored digest.
911 If the two digests match the password is correct.
912 When verifying an existing digest string you should use the digest
914 as the salt (like "crypt($plain, $digest) eq $digest"). The SALT
915 used to create the digest is visible as part of the digest. This
916 ensures crypt() will hash the new string with the same salt as the
917 digest. This allows your code to work with the standard crypt and
918 with more exotic implementations. In other words, do not assume
919 anything about the returned string itself, or how many bytes in the
920 digest matter.
921 Traditionally the result is a string of 13 bytes: two first bytes
923 of the salt, followed by 11 bytes from the set "[./0-9A-Za-z]", and
924 only the first eight bytes of PLAINTEXT mattered. But alternative
925 hashing schemes (like MD5), higher level security schemes (like
926 C2), and implementations on non-Unix platforms may produce
927 different strings.
928 When choosing a new salt create a random two character string whose
930 characters come from the set "[./0-9A-Za-z]" (like "join '', ('.',
931 '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]"). This set of
932 characters is just a recommendation; the characters allowed in the
933 salt depend solely on your system's crypt library, and Perl can't
934 restrict what salts "crypt()" accepts.
935 Here's an example that makes sure that whoever runs this program
937 knows their password:
938 $pwd = (getpwuid($<))[1];
940 system "stty -echo";
942 print "Password: ";
943 chomp($word = <STDIN>);
944 print "\n";
945 system "stty echo";
946 if (crypt($word, $pwd) ne $pwd) {
948 die "Sorry...\n";
949 } else {
950 print "ok\n";
951 }
952 Of course, typing in your own password to whoever asks you for it
954 is unwise.
955 The crypt function is unsuitable for hashing large quantities of
957 data, not least of all because you can't get the information back.
958 Look at the Digest module for more robust algorithms.
959 If using crypt() on a Unicode string (which potentially has
961 characters with codepoints above 255), Perl tries to make sense of
962 the situation by trying to downgrade (a copy of the string) the
963 string back to an eight-bit byte string before calling crypt() (on
964 that copy). If that works, good. If not, crypt() dies with "Wide
965 character in crypt".
966 dbmclose HASH
968 [This function has been largely superseded by the "untie"
969 function.]
970 Breaks the binding between a DBM file and a hash.
972 dbmopen HASH,DBNAME,MASK
974 [This function has been largely superseded by the "tie" function.]
975 This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file
977 to a hash. HASH is the name of the hash. (Unlike normal "open",
978 the first argument is not a filehandle, even though it looks like
979 one). DBNAME is the name of the database (without the .dir or .pag
980 extension if any). If the database does not exist, it is created
981 with protection specified by MASK (as modified by the "umask"). If
982 your system supports only the older DBM functions, you may make
983 only one "dbmopen" call in your program. In older versions of
984 Perl, if your system had neither DBM nor ndbm, calling "dbmopen"
985 produced a fatal error; it now falls back to sdbm(3).
986 If you don't have write access to the DBM file, you can only read
988 hash variables, not set them. If you want to test whether you can
989 write, either use file tests or try setting a dummy hash entry
990 inside an "eval" to trap the error.
991 Note that functions such as "keys" and "values" may return huge
993 lists when used on large DBM files. You may prefer to use the
994 "each" function to iterate over large DBM files. Example:
995 # print out history file offsets
997 dbmopen(%HIST,'/usr/lib/news/history',0666);
998 while (($key,$val) = each %HIST) {
999 print $key, ' = ', unpack('L',$val), "\n";
1000 }
1001 dbmclose(%HIST);
1002 See also AnyDBM_File for a more general description of the pros and
1004 cons of the various dbm approaches, as well as DB_File for a
1005 particularly rich implementation.
1006 You can control which DBM library you use by loading that library
1008 before you call dbmopen():
1009 use DB_File;
1011 dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
1012 or die "Can't open netscape history file: $!";
1013 defined EXPR
1015 defined
1016 Returns a Boolean value telling whether EXPR has a value other than
1017 the undefined value "undef". If EXPR is not present, $_ is
1018 checked.
1019 Many operations return "undef" to indicate failure, end of file,
1021 system error, uninitialized variable, and other exceptional
1022 conditions. This function allows you to distinguish "undef" from
1023 other values. (A simple Boolean test will not distinguish among
1024 "undef", zero, the empty string, and "0", which are all equally
1025 false.) Note that since "undef" is a valid scalar, its presence
1026 doesn't necessarily indicate an exceptional condition: "pop"
1027 returns "undef" when its argument is an empty array, or when the
1028 element to return happens to be "undef".
1029 You may also use "defined(&func)" to check whether subroutine &func
1031 has ever been defined. The return value is unaffected by any
1032 forward declarations of &func. A subroutine that is not defined
1033 may still be callable: its package may have an "AUTOLOAD" method
1034 that makes it spring into existence the first time that it is
1035 called; see perlsub.
1036 Use of "defined" on aggregates (hashes and arrays) is deprecated.
1038 It used to report whether memory for that aggregate has ever been
1039 allocated. This behavior may disappear in future versions of Perl.
1040 You should instead use a simple test for size:
1041 if (@an_array) { print "has array elements\n" }
1043 if (%a_hash) { print "has hash members\n" }
1044 When used on a hash element, it tells you whether the value is
1046 defined, not whether the key exists in the hash. Use "exists" for
1047 the latter purpose.
1048 Examples:
1050 print if defined $switch{'D'};
1052 print "$val\n" while defined($val = pop(@ary));
1053 die "Can't readlink $sym: $!"
1054 unless defined($value = readlink $sym);
1055 sub foo { defined &$bar ? &$bar(@_) : die "No bar"; }
1056 $debugging = 0 unless defined $debugging;
1057 Note: Many folks tend to overuse "defined", and then are surprised
1059 to discover that the number 0 and "" (the zero-length string) are,
1060 in fact, defined values. For example, if you say
1061 "ab" =~ /a(.*)b/;
1063 The pattern match succeeds and $1 is defined, although it matched
1065 "nothing". It didn't really fail to match anything. Rather, it
1066 matched something that happened to be zero characters long. This
1067 is all very above-board and honest. When a function returns an
1068 undefined value, it's an admission that it couldn't give you an
1069 honest answer. So you should use "defined" only when questioning
1070 the integrity of what you're trying to do. At other times, a
1071 simple comparison to 0 or "" is what you want.
1072 See also "undef", "exists", "ref".
1074 delete EXPR
1076 Given an expression that specifies an element or slice of a hash,
1077 "delete" deletes the specified elements from that hash so that
1078 exists() on that element no longer returns true. Setting a hash
1079 element to the undefined value does not remove its key, but
1080 deleting it does; see "exists".
1081 It returns the value or values deleted in list context, or the last
1083 such element in scalar context. The return list's length always
1084 matches that of the argument list: deleting non-existent elements
1085 returns the undefined value in their corresponding positions.
1086 delete() may also be used on arrays and array slices, but its
1088 behavior is less straightforward. Although exists() will return
1089 false for deleted entries, deleting array elements never changes
1090 indices of existing values; use shift() or splice() for that.
1091 However, if all deleted elements fall at the end of an array, the
1092 array's size shrinks to the position of the highest element that
1093 still tests true for exists(), or to 0 if none do.
1094 Be aware that calling delete on array values is deprecated and
1096 likely to be removed in a future version of Perl.
1097 Deleting from %ENV modifies the environment. Deleting from a hash
1099 tied to a DBM file deletes the entry from the DBM file. Deleting
1100 from a "tied" hash or array may not necessarily return anything; it
1101 depends on the implementation of the "tied" package's DELETE
1102 method, which may do whatever it pleases.
1103 The "delete local EXPR" construct localizes the deletion to the
1105 current block at run time. Until the block exits, elements locally
1106 deleted temporarily no longer exist. See "Localized deletion of
1107 elements of composite types" in perlsub.
1108 %hash = (foo => 11, bar => 22, baz => 33);
1110 $scalar = delete $hash{foo}; # $scalar is 11
1111 $scalar = delete @hash{qw(foo bar)}; # $scalar is 22
1112 @array = delete @hash{qw(foo bar baz)}; # @array is (undef,undef,33)
1113 The following (inefficiently) deletes all the values of %HASH and
1115 @ARRAY:
1116 foreach $key (keys %HASH) {
1118 delete $HASH{$key};
1119 }
1120 foreach $index (0 .. $#ARRAY) {
1122 delete $ARRAY[$index];
1123 }
1124 And so do these:
1126 delete @HASH{keys %HASH};
1128 delete @ARRAY[0 .. $#ARRAY];
1130 But both are slower than assigning the empty list or undefining
1132 %HASH or @ARRAY, which is the customary way to empty out an
1133 aggregate:
1134 %HASH = (); # completely empty %HASH
1136 undef %HASH; # forget %HASH ever existed
1137 @ARRAY = (); # completely empty @ARRAY
1139 undef @ARRAY; # forget @ARRAY ever existed
1140 The EXPR can be arbitrarily complicated provided its final
1142 operation is an element or slice of an aggregate:
1143 delete $ref->[$x][$y]{$key};
1145 delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};
1146 delete $ref->[$x][$y][$index];
1148 delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
1149 die LIST
1151 "die" raises an exception. Inside an "eval" the error message is
1152 stuffed into $@ and the "eval" is terminated with the undefined
1153 value. If the exception is outside of all enclosing "eval"s, then
1154 the uncaught exception prints LIST to "STDERR" and exits with a
1155 non-zero value. If you need to exit the process with a specific
1156 exit code, see exit.
1157 Equivalent examples:
1159 die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
1161 chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
1162 If the last element of LIST does not end in a newline, the current
1164 script line number and input line number (if any) are also printed,
1165 and a newline is supplied. Note that the "input line number" (also
1166 known as "chunk") is subject to whatever notion of "line" happens
1167 to be currently in effect, and is also available as the special
1168 variable $.. See "$/" in perlvar and "$." in perlvar.
1169 Hint: sometimes appending ", stopped" to your message will cause it
1171 to make better sense when the string "at foo line 123" is appended.
1172 Suppose you are running script "canasta".
1173 die "/etc/games is no good";
1175 die "/etc/games is no good, stopped";
1176 produce, respectively
1178 /etc/games is no good at canasta line 123.
1180 /etc/games is no good, stopped at canasta line 123.
1181 If the output is empty and $@ already contains a value (typically
1183 from a previous eval) that value is reused after appending
1184 "\t...propagated". This is useful for propagating exceptions:
1185 eval { ... };
1187 die unless $@ =~ /Expected exception/;
1188 If the output is empty and $@ contains an object reference that has
1190 a "PROPAGATE" method, that method will be called with additional
1191 file and line number parameters. The return value replaces the
1192 value in $@. i.e., as if "$@ = eval { $@->PROPAGATE(__FILE__,
1193 __LINE__) };" were called.
1194 If $@ is empty then the string "Died" is used.
1196 If an uncaught exception results in interpreter exit, the exit code
1198 is determined from the values of $! and $? with this pseudocode:
1199 exit $! if $!; # errno
1201 exit $? >> 8 if $? >> 8; # child exit status
1202 exit 255; # last resort
1203 The intent is to squeeze as much possible information about the
1205 likely cause into the limited space of the system exit code.
1206 However, as $! is the value of C's "errno", which can be set by any
1207 system call, this means that the value of the exit code used by
1208 "die" can be non-predictable, so should not be relied upon, other
1209 than to be non-zero.
1210 You can also call "die" with a reference argument, and if this is
1212 trapped within an "eval", $@ contains that reference. This permits
1213 more elaborate exception handling using objects that maintain
1214 arbitrary state about the exception. Such a scheme is sometimes
1215 preferable to matching particular string values of $@ with regular
1216 expressions. Because $@ is a global variable and "eval" may be
1217 used within object implementations, be careful that analyzing the
1218 error object doesn't replace the reference in the global variable.
1219 It's easiest to make a local copy of the reference before any
1220 manipulations. Here's an example:
1221 use Scalar::Util "blessed";
1223 eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
1225 if (my $ev_err = $@) {
1226 if (blessed($ev_err) && $ev_err->isa("Some::Module::Exception")) {
1227 # handle Some::Module::Exception
1228 }
1229 else {
1230 # handle all other possible exceptions
1231 }
1232 }
1233 Because Perl stringifies uncaught exception messages before
1235 display, you'll probably want to overload stringification
1236 operations on exception objects. See overload for details about
1237 that.
1238 You can arrange for a callback to be run just before the "die" does
1240 its deed, by setting the $SIG{__DIE__} hook. The associated
1241 handler is called with the error text and can change the error
1242 message, if it sees fit, by calling "die" again. See "$SIG{expr}"
1243 in perlvar for details on setting %SIG entries, and "eval BLOCK"
1244 for some examples. Although this feature was to be run only right
1245 before your program was to exit, this is not currently so: the
1246 $SIG{__DIE__} hook is currently called even inside eval()ed
1247 blocks/strings! If one wants the hook to do nothing in such
1248 situations, put
1249 die @_ if $^S;
1251 as the first line of the handler (see "$^S" in perlvar). Because
1253 this promotes strange action at a distance, this counterintuitive
1254 behavior may be fixed in a future release.
1255 See also exit(), warn(), and the Carp module.
1257 do BLOCK
1259 Not really a function. Returns the value of the last command in
1260 the sequence of commands indicated by BLOCK. When modified by the
1261 "while" or "until" loop modifier, executes the BLOCK once before
1262 testing the loop condition. (On other statements the loop modifiers
1263 test the conditional first.)
1264 "do BLOCK" does not count as a loop, so the loop control statements
1266 "next", "last", or "redo" cannot be used to leave or restart the
1267 block. See perlsyn for alternative strategies.
1268 do SUBROUTINE(LIST)
1270 This form of subroutine call is deprecated. See perlsub.
1271 do EXPR
1273 Uses the value of EXPR as a filename and executes the contents of
1274 the file as a Perl script.
1275 do 'stat.pl';
1277 is just like
1279 eval `cat stat.pl`;
1281 except that it's more efficient and concise, keeps track of the
1283 current filename for error messages, searches the @INC directories,
1284 and updates %INC if the file is found. See "Predefined Names" in
1285 perlvar for these variables. It also differs in that code
1286 evaluated with "do FILENAME" cannot see lexicals in the enclosing
1287 scope; "eval STRING" does. It's the same, however, in that it does
1288 reparse the file every time you call it, so you probably don't want
1289 to do this inside a loop.
1290 If "do" cannot read the file, it returns undef and sets $! to the
1292 error. If "do" can read the file but cannot compile it, it returns
1293 undef and sets an error message in $@. If the file is
1294 successfully compiled, "do" returns the value of the last
1295 expression evaluated.
1296 Inclusion of library modules is better done with the "use" and
1298 "require" operators, which also do automatic error checking and
1299 raise an exception if there's a problem.
1300 You might like to use "do" to read in a program configuration file.
1302 Manual error checking can be done this way:
1303 # read in config files: system first, then user
1305 for $file ("/share/prog/defaults.rc",
1306 "$ENV{HOME}/.someprogrc")
1307 {
1308 unless ($return = do $file) {
1309 warn "couldn't parse $file: $@" if $@;
1310 warn "couldn't do $file: $!" unless defined $return;
1311 warn "couldn't run $file" unless $return;
1312 }
1313 }
1314 dump LABEL
1316 dump
1317 This function causes an immediate core dump. See also the -u
1318 command-line switch in perlrun, which does the same thing.
1319 Primarily this is so that you can use the undump program (not
1320 supplied) to turn your core dump into an executable binary after
1321 having initialized all your variables at the beginning of the
1322 program. When the new binary is executed it will begin by
1323 executing a "goto LABEL" (with all the restrictions that "goto"
1324 suffers). Think of it as a goto with an intervening core dump and
1325 reincarnation. If "LABEL" is omitted, restarts the program from
1326 the top.
1327 WARNING: Any files opened at the time of the dump will not be open
1329 any more when the program is reincarnated, with possible resulting
1330 confusion by Perl.
1331 This function is now largely obsolete, mostly because it's very
1333 hard to convert a core file into an executable. That's why you
1334 should now invoke it as "CORE::dump()", if you don't want to be
1335 warned against a possible typo.
1336 each HASH
1338 each ARRAY
1339 When called in list context, returns a 2-element list consisting of
1340 the key and value for the next element of a hash, or the index and
1341 value for the next element of an array, so that you can iterate
1342 over it. When called in scalar context, returns only the key (not
1343 the value) in a hash, or the index in an array.
1344 Hash entries are returned in an apparently random order. The
1346 actual random order is subject to change in future versions of
1347 Perl, but it is guaranteed to be in the same order as either the
1348 "keys" or "values" function would produce on the same (unmodified)
1349 hash. Since Perl 5.8.2 the ordering can be different even between
1350 different runs of Perl for security reasons (see "Algorithmic
1351 Complexity Attacks" in perlsec).
1352 After "each" has returned all entries from the hash or array, the
1354 next call to "each" returns the empty list in list context and
1355 "undef" in scalar context. The next call following that one
1356 restarts iteration. Each hash or array has its own internal
1357 iterator, accessed by "each", "keys", and "values". The iterator
1358 is implicitly reset when "each" has reached the end as just
1359 described; it can be explicitly reset by calling "keys" or "values"
1360 on the hash or array. If you add or delete a hash's elements while
1361 iterating over it, entries may be skipped or duplicated--so don't
1362 do that. Exception: It is always safe to delete the item most
1363 recently returned by "each()", so the following code works
1364 properly:
1365 while (($key, $value) = each %hash) {
1367 print $key, "\n";
1368 delete $hash{$key}; # This is safe
1369 }
1370 This prints out your environment like the printenv(1) program, but
1372 in a different order:
1373 while (($key,$value) = each %ENV) {
1375 print "$key=$value\n";
1376 }
1377 See also "keys", "values" and "sort".
1379 eof FILEHANDLE
1381 eof ()
1382 eof Returns 1 if the next read on FILEHANDLE will return end of file,
1383 or if FILEHANDLE is not open. FILEHANDLE may be an expression
1384 whose value gives the real filehandle. (Note that this function
1385 actually reads a character and then "ungetc"s it, so isn't useful
1386 in an interactive context.) Do not read from a terminal file (or
1387 call "eof(FILEHANDLE)" on it) after end-of-file is reached. File
1388 types such as terminals may lose the end-of-file condition if you
1389 do.
1390 An "eof" without an argument uses the last file read. Using
1392 "eof()" with empty parentheses is different. It refers to the
1393 pseudo file formed from the files listed on the command line and
1394 accessed via the "<>" operator. Since "<>" isn't explicitly
1395 opened, as a normal filehandle is, an "eof()" before "<>" has been
1396 used will cause @ARGV to be examined to determine if input is
1397 available. Similarly, an "eof()" after "<>" has returned end-of-
1398 file will assume you are processing another @ARGV list, and if you
1399 haven't set @ARGV, will read input from "STDIN"; see "I/O
1400 Operators" in perlop.
1401 In a "while (<>)" loop, "eof" or "eof(ARGV)" can be used to detect
1403 the end of each file, "eof()" will detect the end of only the last
1404 file. Examples:
1405 # reset line numbering on each input file
1407 while (<>) {
1408 next if /^\s*#/; # skip comments
1409 print "$.\t$_";
1410 } continue {
1411 close ARGV if eof; # Not eof()!
1412 }
1413 # insert dashes just before last line of last file
1415 while (<>) {
1416 if (eof()) { # check for end of last file
1417 print "--------------\n";
1418 }
1419 print;
1420 last if eof(); # needed if we're reading from a terminal
1421 }
1422 Practical hint: you almost never need to use "eof" in Perl, because
1424 the input operators typically return "undef" when they run out of
1425 data, or if there was an error.
1426 eval EXPR
1428 eval BLOCK
1429 eval
1430 In the first form, the return value of EXPR is parsed and executed
1431 as if it were a little Perl program. The value of the expression
1432 (which is itself determined within scalar context) is first parsed,
1433 and if there weren't any errors, executed in the lexical context of
1434 the current Perl program, so that any variable settings or
1435 subroutine and format definitions remain afterwards. Note that the
1436 value is parsed every time the "eval" executes. If EXPR is
1437 omitted, evaluates $_. This form is typically used to delay
1438 parsing and subsequent execution of the text of EXPR until run
1439 time.
1440 In the second form, the code within the BLOCK is parsed only
1442 once--at the same time the code surrounding the "eval" itself was
1443 parsed--and executed within the context of the current Perl
1444 program. This form is typically used to trap exceptions more
1445 efficiently than the first (see below), while also providing the
1446 benefit of checking the code within BLOCK at compile time.
1447 The final semicolon, if any, may be omitted from the value of EXPR
1449 or within the BLOCK.
1450 In both forms, the value returned is the value of the last
1452 expression evaluated inside the mini-program; a return statement
1453 may be also used, just as with subroutines. The expression
1454 providing the return value is evaluated in void, scalar, or list
1455 context, depending on the context of the "eval" itself. See
1456 "wantarray" for more on how the evaluation context can be
1457 determined.
1458 If there is a syntax error or runtime error, or a "die" statement
1460 is executed, "eval" returns an undefined value in scalar context or
1461 an empty list in list context, and $@ is set to the error message.
1462 If there was no error, $@ is guaranteed to be the empty string.
1463 Beware that using "eval" neither silences Perl from printing
1464 warnings to STDERR, nor does it stuff the text of warning messages
1465 into $@. To do either of those, you have to use the $SIG{__WARN__}
1466 facility, or turn off warnings inside the BLOCK or EXPR using
1467 "no warnings 'all'". See "warn", perlvar, warnings and
1468 perllexwarn.
1469 Note that, because "eval" traps otherwise-fatal errors, it is
1471 useful for determining whether a particular feature (such as
1472 "socket" or "symlink") is implemented. It is also Perl's exception
1473 trapping mechanism, where the die operator is used to raise
1474 exceptions.
1475 If you want to trap errors when loading an XS module, some problems
1477 with the binary interface (such as Perl version skew) may be fatal
1478 even with "eval" unless $ENV{PERL_DL_NONLAZY} is set. See perlrun.
1479 If the code to be executed doesn't vary, you may use the eval-BLOCK
1481 form to trap run-time errors without incurring the penalty of
1482 recompiling each time. The error, if any, is still returned in $@.
1483 Examples:
1484 # make divide-by-zero nonfatal
1486 eval { $answer = $a / $b; }; warn $@ if $@;
1487 # same thing, but less efficient
1489 eval '$answer = $a / $b'; warn $@ if $@;
1490 # a compile-time error
1492 eval { $answer = }; # WRONG
1493 # a run-time error
1495 eval '$answer ='; # sets $@
1496 Using the "eval{}" form as an exception trap in libraries does have
1498 some issues. Due to the current arguably broken state of "__DIE__"
1499 hooks, you may wish not to trigger any "__DIE__" hooks that user
1500 code may have installed. You can use the "local $SIG{__DIE__}"
1501 construct for this purpose, as this example shows:
1502 # a private exception trap for divide-by-zero
1504 eval { local $SIG{'__DIE__'}; $answer = $a / $b; };
1505 warn $@ if $@;
1506 This is especially significant, given that "__DIE__" hooks can call
1508 "die" again, which has the effect of changing their error messages:
1509 # __DIE__ hooks may modify error messages
1511 {
1512 local $SIG{'__DIE__'} =
1513 sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
1514 eval { die "foo lives here" };
1515 print $@ if $@; # prints "bar lives here"
1516 }
1517 Because this promotes action at a distance, this counterintuitive
1519 behavior may be fixed in a future release.
1520 With an "eval", you should be especially careful to remember what's
1522 being looked at when:
1523 eval $x; # CASE 1
1525 eval "$x"; # CASE 2
1526 eval '$x'; # CASE 3
1528 eval { $x }; # CASE 4
1529 eval "\$$x++"; # CASE 5
1531 $$x++; # CASE 6
1532 Cases 1 and 2 above behave identically: they run the code contained
1534 in the variable $x. (Although case 2 has misleading double quotes
1535 making the reader wonder what else might be happening (nothing
1536 is).) Cases 3 and 4 likewise behave in the same way: they run the
1537 code '$x', which does nothing but return the value of $x. (Case 4
1538 is preferred for purely visual reasons, but it also has the
1539 advantage of compiling at compile-time instead of at run-time.)
1540 Case 5 is a place where normally you would like to use double
1541 quotes, except that in this particular situation, you can just use
1542 symbolic references instead, as in case 6.
1543 The assignment to $@ occurs before restoration of localised
1545 variables, which means a temporary is required if you want to mask
1546 some but not all errors:
1547 # alter $@ on nefarious repugnancy only
1549 {
1550 my $e;
1551 {
1552 local $@; # protect existing $@
1553 eval { test_repugnancy() };
1554 # $@ =~ /nefarious/ and die $@; # DOES NOT WORK
1555 $@ =~ /nefarious/ and $e = $@;
1556 }
1557 die $e if defined $e
1558 }
1559 "eval BLOCK" does not count as a loop, so the loop control
1561 statements "next", "last", or "redo" cannot be used to leave or
1562 restart the block.
1563 An "eval ''" executed within the "DB" package doesn't see the usual
1565 surrounding lexical scope, but rather the scope of the first non-DB
1566 piece of code that called it. You don't normally need to worry
1567 about this unless you are writing a Perl debugger.
1568 exec LIST
1570 exec PROGRAM LIST
1571 The "exec" function executes a system command and never returns;
1572 use "system" instead of "exec" if you want it to return. It fails
1573 and returns false only if the command does not exist and it is
1574 executed directly instead of via your system's command shell (see
1575 below).
1576 Since it's a common mistake to use "exec" instead of "system", Perl
1578 warns you if there is a following statement that isn't "die",
1579 "warn", or "exit" (if "-w" is set--but you always do that, right?).
1580 If you really want to follow an "exec" with some other statement,
1581 you can use one of these styles to avoid the warning:
1582 exec ('foo') or print STDERR "couldn't exec foo: $!";
1584 { exec ('foo') }; print STDERR "couldn't exec foo: $!";
1585 If there is more than one argument in LIST, or if LIST is an array
1587 with more than one value, calls execvp(3) with the arguments in
1588 LIST. If there is only one scalar argument or an array with one
1589 element in it, the argument is checked for shell metacharacters,
1590 and if there are any, the entire argument is passed to the system's
1591 command shell for parsing (this is "/bin/sh -c" on Unix platforms,
1592 but varies on other platforms). If there are no shell
1593 metacharacters in the argument, it is split into words and passed
1594 directly to "execvp", which is more efficient. Examples:
1595 exec '/bin/echo', 'Your arguments are: ', @ARGV;
1597 exec "sort $outfile | uniq";
1598 If you don't really want to execute the first argument, but want to
1600 lie to the program you are executing about its own name, you can
1601 specify the program you actually want to run as an "indirect
1602 object" (without a comma) in front of the LIST. (This always
1603 forces interpretation of the LIST as a multivalued list, even if
1604 there is only a single scalar in the list.) Example:
1605 $shell = '/bin/csh';
1607 exec $shell '-sh'; # pretend it's a login shell
1608 or, more directly,
1610 exec {'/bin/csh'} '-sh'; # pretend it's a login shell
1612 When the arguments get executed via the system shell, results are
1614 subject to its quirks and capabilities. See "`STRING`" in perlop
1615 for details.
1616 Using an indirect object with "exec" or "system" is also more
1618 secure. This usage (which also works fine with system()) forces
1619 interpretation of the arguments as a multivalued list, even if the
1620 list had just one argument. That way you're safe from the shell
1621 expanding wildcards or splitting up words with whitespace in them.
1622 @args = ( "echo surprise" );
1624 exec @args; # subject to shell escapes
1626 # if @args == 1
1627 exec { $args[0] } @args; # safe even with one-arg list
1628 The first version, the one without the indirect object, ran the
1630 echo program, passing it "surprise" an argument. The second
1631 version didn't; it tried to run a program named "echo surprise",
1632 didn't find it, and set $? to a non-zero value indicating failure.
1633 Beginning with v5.6.0, Perl attempts to flush all files opened for
1635 output before the exec, but this may not be supported on some
1636 platforms (see perlport). To be safe, you may need to set $|
1637 ($AUTOFLUSH in English) or call the "autoflush()" method of
1638 "IO::Handle" on any open handles to avoid lost output.
1639 Note that "exec" will not call your "END" blocks, nor will it
1641 invoke "DESTROY" methods on your objects.
1642 exists EXPR
1644 Given an expression that specifies an element of a hash, returns
1645 true if the specified element in the hash has ever been
1646 initialized, even if the corresponding value is undefined.
1647 print "Exists\n" if exists $hash{$key};
1649 print "Defined\n" if defined $hash{$key};
1650 print "True\n" if $hash{$key};
1651 exists may also be called on array elements, but its behavior is
1653 much less obvious, and is strongly tied to the use of "delete" on
1654 arrays. Be aware that calling exists on array values is deprecated
1655 and likely to be removed in a future version of Perl.
1656 print "Exists\n" if exists $array[$index];
1658 print "Defined\n" if defined $array[$index];
1659 print "True\n" if $array[$index];
1660 A hash or array element can be true only if it's defined, and
1662 defined if it exists, but the reverse doesn't necessarily hold
1663 true.
1664 Given an expression that specifies the name of a subroutine,
1666 returns true if the specified subroutine has ever been declared,
1667 even if it is undefined. Mentioning a subroutine name for exists
1668 or defined does not count as declaring it. Note that a subroutine
1669 that does not exist may still be callable: its package may have an
1670 "AUTOLOAD" method that makes it spring into existence the first
1671 time that it is called; see perlsub.
1672 print "Exists\n" if exists &subroutine;
1674 print "Defined\n" if defined &subroutine;
1675 Note that the EXPR can be arbitrarily complicated as long as the
1677 final operation is a hash or array key lookup or subroutine name:
1678 if (exists $ref->{A}->{B}->{$key}) { }
1680 if (exists $hash{A}{B}{$key}) { }
1681 if (exists $ref->{A}->{B}->[$ix]) { }
1683 if (exists $hash{A}{B}[$ix]) { }
1684 if (exists &{$ref->{A}{B}{$key}}) { }
1686 Although the mostly deeply nested array or hash will not spring
1688 into existence just because its existence was tested, any
1689 intervening ones will. Thus "$ref->{"A"}" and "$ref->{"A"}->{"B"}"
1690 will spring into existence due to the existence test for the $key
1691 element above. This happens anywhere the arrow operator is used,
1692 including even here:
1693 undef $ref;
1695 if (exists $ref->{"Some key"}) { }
1696 print $ref; # prints HASH(0x80d3d5c)
1697 This surprising autovivification in what does not at first--or even
1699 second--glance appear to be an lvalue context may be fixed in a
1700 future release.
1701 Use of a subroutine call, rather than a subroutine name, as an
1703 argument to exists() is an error.
1704 exists ⊂ # OK
1706 exists &sub(); # Error
1707 exit EXPR
1709 exit
1710 Evaluates EXPR and exits immediately with that value. Example:
1711 $ans = <STDIN>;
1713 exit 0 if $ans =~ /^[Xx]/;
1714 See also "die". If EXPR is omitted, exits with 0 status. The only
1716 universally recognized values for EXPR are 0 for success and 1 for
1717 error; other values are subject to interpretation depending on the
1718 environment in which the Perl program is running. For example,
1719 exiting 69 (EX_UNAVAILABLE) from a sendmail incoming-mail filter
1720 will cause the mailer to return the item undelivered, but that's
1721 not true everywhere.
1722 Don't use "exit" to abort a subroutine if there's any chance that
1724 someone might want to trap whatever error happened. Use "die"
1725 instead, which can be trapped by an "eval".
1726 The exit() function does not always exit immediately. It calls any
1728 defined "END" routines first, but these "END" routines may not
1729 themselves abort the exit. Likewise any object destructors that
1730 need to be called are called before the real exit. If this is a
1731 problem, you can call "POSIX:_exit($status)" to avoid END and
1732 destructor processing. See perlmod for details.
1733 exp EXPR
1735 exp Returns e (the natural logarithm base) to the power of EXPR. If
1736 EXPR is omitted, gives "exp($_)".
1737 fcntl FILEHANDLE,FUNCTION,SCALAR
1739 Implements the fcntl(2) function. You'll probably have to say
1740 use Fcntl;
1742 first to get the correct constant definitions. Argument processing
1744 and value returned work just like "ioctl" below. For example:
1745 use Fcntl;
1747 fcntl($filehandle, F_GETFL, $packed_return_buffer)
1748 or die "can't fcntl F_GETFL: $!";
1749 You don't have to check for "defined" on the return from "fcntl".
1751 Like "ioctl", it maps a 0 return from the system call into "0 but
1752 true" in Perl. This string is true in boolean context and 0 in
1753 numeric context. It is also exempt from the normal -w warnings on
1754 improper numeric conversions.
1755 Note that "fcntl" raises an exception if used on a machine that
1757 doesn't implement fcntl(2). See the Fcntl module or your fcntl(2)
1758 manpage to learn what functions are available on your system.
1759 Here's an example of setting a filehandle named "REMOTE" to be non-
1761 blocking at the system level. You'll have to negotiate $| on your
1762 own, though.
1763 use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
1765 $flags = fcntl(REMOTE, F_GETFL, 0)
1767 or die "Can't get flags for the socket: $!\n";
1768 $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
1770 or die "Can't set flags for the socket: $!\n";
1771 fileno FILEHANDLE
1773 Returns the file descriptor for a filehandle, or undefined if the
1774 filehandle is not open. This is mainly useful for constructing
1775 bitmaps for "select" and low-level POSIX tty-handling operations.
1776 If FILEHANDLE is an expression, the value is taken as an indirect
1777 filehandle, generally its name.
1778 You can use this to find out whether two handles refer to the same
1780 underlying descriptor:
1781 if (fileno(THIS) == fileno(THAT)) {
1783 print "THIS and THAT are dups\n";
1784 }
1785 (Filehandles connected to memory objects via new features of "open"
1787 may return undefined even though they are open.)
1788 flock FILEHANDLE,OPERATION
1790 Calls flock(2), or an emulation of it, on FILEHANDLE. Returns true
1791 for success, false on failure. Produces a fatal error if used on a
1792 machine that doesn't implement flock(2), fcntl(2) locking, or
1793 lockf(3). "flock" is Perl's portable file locking interface,
1794 although it locks entire files only, not records.
1795 Two potentially non-obvious but traditional "flock" semantics are
1797 that it waits indefinitely until the lock is granted, and that its
1798 locks merely advisory. Such discretionary locks are more flexible,
1799 but offer fewer guarantees. This means that programs that do not
1800 also use "flock" may modify files locked with "flock". See
1801 perlport, your port's specific documentation, or your system-
1802 specific local manpages for details. It's best to assume
1803 traditional behavior if you're writing portable programs. (But if
1804 you're not, you should as always feel perfectly free to write for
1805 your own system's idiosyncrasies (sometimes called "features").
1806 Slavish adherence to portability concerns shouldn't get in the way
1807 of your getting your job done.)
1808 OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined
1810 with LOCK_NB. These constants are traditionally valued 1, 2, 8 and
1811 4, but you can use the symbolic names if you import them from the
1812 Fcntl module, either individually, or as a group using the ':flock'
1813 tag. LOCK_SH requests a shared lock, LOCK_EX requests an exclusive
1814 lock, and LOCK_UN releases a previously requested lock. If LOCK_NB
1815 is bitwise-or'ed with LOCK_SH or LOCK_EX then "flock" returns
1816 immediately rather than blocking waiting for the lock; check the
1817 return status to see if you got it.
1818 To avoid the possibility of miscoordination, Perl now flushes
1820 FILEHANDLE before locking or unlocking it.
1821 Note that the emulation built with lockf(3) doesn't provide shared
1823 locks, and it requires that FILEHANDLE be open with write intent.
1824 These are the semantics that lockf(3) implements. Most if not all
1825 systems implement lockf(3) in terms of fcntl(2) locking, though, so
1826 the differing semantics shouldn't bite too many people.
1827 Note that the fcntl(2) emulation of flock(3) requires that
1829 FILEHANDLE be open with read intent to use LOCK_SH and requires
1830 that it be open with write intent to use LOCK_EX.
1831 Note also that some versions of "flock" cannot lock things over the
1833 network; you would need to use the more system-specific "fcntl" for
1834 that. If you like you can force Perl to ignore your system's
1835 flock(2) function, and so provide its own fcntl(2)-based emulation,
1836 by passing the switch "-Ud_flock" to the Configure program when you
1837 configure Perl.
1838 Here's a mailbox appender for BSD systems.
1840 use Fcntl qw(:flock SEEK_END); # import LOCK_* and SEEK_END constants
1842 sub lock {
1844 my ($fh) = @_;
1845 flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n";
1846 # and, in case someone appended while we were waiting...
1848 seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n";
1849 }
1850 sub unlock {
1852 my ($fh) = @_;
1853 flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n";
1854 }
1855 open(my $mbox, ">>", "/usr/spool/mail/$ENV{'USER'}")
1857 or die "Can't open mailbox: $!";
1858 lock($mbox);
1860 print $mbox $msg,"\n\n";
1861 unlock($mbox);
1862 On systems that support a real flock(2), locks are inherited across
1864 fork() calls, whereas those that must resort to the more capricious
1865 fcntl(2) function lose their locks, making it seriously harder to
1866 write servers.
1867 See also DB_File for other flock() examples.
1869 fork
1871 Does a fork(2) system call to create a new process running the same
1872 program at the same point. It returns the child pid to the parent
1873 process, 0 to the child process, or "undef" if the fork is
1874 unsuccessful. File descriptors (and sometimes locks on those
1875 descriptors) are shared, while everything else is copied. On most
1876 systems supporting fork(), great care has gone into making it
1877 extremely efficient (for example, using copy-on-write technology on
1878 data pages), making it the dominant paradigm for multitasking over
1879 the last few decades.
1880 Beginning with v5.6.0, Perl attempts to flush all files opened for
1882 output before forking the child process, but this may not be
1883 supported on some platforms (see perlport). To be safe, you may
1884 need to set $| ($AUTOFLUSH in English) or call the "autoflush()"
1885 method of "IO::Handle" on any open handles to avoid duplicate
1886 output.
1887 If you "fork" without ever waiting on your children, you will
1889 accumulate zombies. On some systems, you can avoid this by setting
1890 $SIG{CHLD} to "IGNORE". See also perlipc for more examples of
1891 forking and reaping moribund children.
1892 Note that if your forked child inherits system file descriptors
1894 like STDIN and STDOUT that are actually connected by a pipe or
1895 socket, even if you exit, then the remote server (such as, say, a
1896 CGI script or a backgrounded job launched from a remote shell)
1897 won't think you're done. You should reopen those to /dev/null if
1898 it's any issue.
1899 format
1901 Declare a picture format for use by the "write" function. For
1902 example:
1903 format Something =
1905 Test: @<<<<<<<< @||||| @>>>>>
1906 $str, $%, '$' . int($num)
1907 .
1908 $str = "widget";
1910 $num = $cost/$quantity;
1911 $~ = 'Something';
1912 write;
1913 See perlform for many details and examples.
1915 formline PICTURE,LIST
1917 This is an internal function used by "format"s, though you may call
1918 it, too. It formats (see perlform) a list of values according to
1919 the contents of PICTURE, placing the output into the format output
1920 accumulator, $^A (or $ACCUMULATOR in English). Eventually, when a
1921 "write" is done, the contents of $^A are written to some
1922 filehandle. You could also read $^A and then set $^A back to "".
1923 Note that a format typically does one "formline" per line of form,
1924 but the "formline" function itself doesn't care how many newlines
1925 are embedded in the PICTURE. This means that the "~" and "~~"
1926 tokens treat the entire PICTURE as a single line. You may
1927 therefore need to use multiple formlines to implement a single
1928 record format, just like the "format" compiler.
1929 Be careful if you put double quotes around the picture, because an
1931 "@" character may be taken to mean the beginning of an array name.
1932 "formline" always returns true. See perlform for other examples.
1933 getc FILEHANDLE
1935 getc
1936 Returns the next character from the input file attached to
1937 FILEHANDLE, or the undefined value at end of file or if there was
1938 an error (in the latter case $! is set). If FILEHANDLE is omitted,
1939 reads from STDIN. This is not particularly efficient. However, it
1940 cannot be used by itself to fetch single characters without waiting
1941 for the user to hit enter. For that, try something more like:
1942 if ($BSD_STYLE) {
1944 system "stty cbreak </dev/tty >/dev/tty 2>&1";
1945 }
1946 else {
1947 system "stty", '-icanon', 'eol', "\001";
1948 }
1949 $key = getc(STDIN);
1951 if ($BSD_STYLE) {
1953 system "stty -cbreak </dev/tty >/dev/tty 2>&1";
1954 }
1955 else {
1956 system 'stty', 'icanon', 'eol', '^@'; # ASCII NUL
1957 }
1958 print "\n";
1959 Determination of whether $BSD_STYLE should be set is left as an
1961 exercise to the reader.
1962 The "POSIX::getattr" function can do this more portably on systems
1964 purporting POSIX compliance. See also the "Term::ReadKey" module
1965 from your nearest CPAN site; details on CPAN can be found on "CPAN"
1966 in perlmodlib.
1967 getlogin
1969 This implements the C library function of the same name, which on
1970 most systems returns the current login from /etc/utmp, if any. If
1971 it returns the empty string, use "getpwuid".
1972 $login = getlogin || getpwuid($<) || "Kilroy";
1974 Do not consider "getlogin" for authentication: it is not as secure
1976 as "getpwuid".
1977 getpeername SOCKET
1979 Returns the packed sockaddr address of other end of the SOCKET
1980 connection.
1981 use Socket;
1983 $hersockaddr = getpeername(SOCK);
1984 ($port, $iaddr) = sockaddr_in($hersockaddr);
1985 $herhostname = gethostbyaddr($iaddr, AF_INET);
1986 $herstraddr = inet_ntoa($iaddr);
1987 getpgrp PID
1989 Returns the current process group for the specified PID. Use a PID
1990 of 0 to get the current process group for the current process.
1991 Will raise an exception if used on a machine that doesn't implement
1992 getpgrp(2). If PID is omitted, returns process group of current
1993 process. Note that the POSIX version of "getpgrp" does not accept
1994 a PID argument, so only "PID==0" is truly portable.
1995 getppid
1997 Returns the process id of the parent process.
1998 Note for Linux users: on Linux, the C functions "getpid()" and
2000 "getppid()" return different values from different threads. In
2001 order to be portable, this behavior is not reflected by the Perl-
2002 level function "getppid()", that returns a consistent value across
2003 threads. If you want to call the underlying "getppid()", you may
2004 use the CPAN module "Linux::Pid".
2005 getpriority WHICH,WHO
2007 Returns the current priority for a process, a process group, or a
2008 user. (See getpriority(2).) Will raise a fatal exception if used
2009 on a machine that doesn't implement getpriority(2).
2010 getpwnam NAME
2012 getgrnam NAME
2013 gethostbyname NAME
2014 getnetbyname NAME
2015 getprotobyname NAME
2016 getpwuid UID
2017 getgrgid GID
2018 getservbyname NAME,PROTO
2019 gethostbyaddr ADDR,ADDRTYPE
2020 getnetbyaddr ADDR,ADDRTYPE
2021 getprotobynumber NUMBER
2022 getservbyport PORT,PROTO
2023 getpwent
2024 getgrent
2025 gethostent
2026 getnetent
2027 getprotoent
2028 getservent
2029 setpwent
2030 setgrent
2031 sethostent STAYOPEN
2032 setnetent STAYOPEN
2033 setprotoent STAYOPEN
2034 setservent STAYOPEN
2035 endpwent
2036 endgrent
2037 endhostent
2038 endnetent
2039 endprotoent
2040 endservent
2041 These routines are the same as their counterparts in the system C
2042 library. In list context, the return values from the various get
2043 routines are as follows:
2044 ($name,$passwd,$uid,$gid,
2046 $quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
2047 ($name,$passwd,$gid,$members) = getgr*
2048 ($name,$aliases,$addrtype,$length,@addrs) = gethost*
2049 ($name,$aliases,$addrtype,$net) = getnet*
2050 ($name,$aliases,$proto) = getproto*
2051 ($name,$aliases,$port,$proto) = getserv*
2052 (If the entry doesn't exist you get an empty list.)
2054 The exact meaning of the $gcos field varies but it usually contains
2056 the real name of the user (as opposed to the login name) and other
2057 information pertaining to the user. Beware, however, that in many
2058 system users are able to change this information and therefore it
2059 cannot be trusted and therefore the $gcos is tainted (see perlsec).
2060 The $passwd and $shell, user's encrypted password and login shell,
2061 are also tainted, because of the same reason.
2062 In scalar context, you get the name, unless the function was a
2064 lookup by name, in which case you get the other thing, whatever it
2065 is. (If the entry doesn't exist you get the undefined value.) For
2066 example:
2067 $uid = getpwnam($name);
2069 $name = getpwuid($num);
2070 $name = getpwent();
2071 $gid = getgrnam($name);
2072 $name = getgrgid($num);
2073 $name = getgrent();
2074 #etc.
2075 In getpw*() the fields $quota, $comment, and $expire are special in
2077 that they are unsupported on many systems. If the $quota is
2078 unsupported, it is an empty scalar. If it is supported, it usually
2079 encodes the disk quota. If the $comment field is unsupported, it
2080 is an empty scalar. If it is supported it usually encodes some
2081 administrative comment about the user. In some systems the $quota
2082 field may be $change or $age, fields that have to do with password
2083 aging. In some systems the $comment field may be $class. The
2084 $expire field, if present, encodes the expiration period of the
2085 account or the password. For the availability and the exact
2086 meaning of these fields in your system, please consult your
2087 getpwnam(3) documentation and your pwd.h file. You can also find
2088 out from within Perl what your $quota and $comment fields mean and
2089 whether you have the $expire field by using the "Config" module and
2090 the values "d_pwquota", "d_pwage", "d_pwchange", "d_pwcomment", and
2091 "d_pwexpire". Shadow password files are supported only if your
2092 vendor has implemented them in the intuitive fashion that calling
2093 the regular C library routines gets the shadow versions if you're
2094 running under privilege or if there exists the shadow(3) functions
2095 as found in System V (this includes Solaris and Linux.) Those
2096 systems that implement a proprietary shadow password facility are
2097 unlikely to be supported.
2098 The $members value returned by getgr*() is a space separated list
2100 of the login names of the members of the group.
2101 For the gethost*() functions, if the "h_errno" variable is
2103 supported in C, it will be returned to you via $? if the function
2104 call fails. The @addrs value returned by a successful call is a
2105 list of raw addresses returned by the corresponding library call.
2106 In the Internet domain, each address is four bytes long; you can
2107 unpack it by saying something like:
2108 ($a,$b,$c,$d) = unpack('W4',$addr[0]);
2110 The Socket library makes this slightly easier:
2112 use Socket;
2114 $iaddr = inet_aton("127.1"); # or whatever address
2115 $name = gethostbyaddr($iaddr, AF_INET);
2116 # or going the other way
2118 $straddr = inet_ntoa($iaddr);
2119 In the opposite way, to resolve a hostname to the IP address you
2121 can write this:
2122 use Socket;
2124 $packed_ip = gethostbyname("www.perl.org");
2125 if (defined $packed_ip) {
2126 $ip_address = inet_ntoa($packed_ip);
2127 }
2128 Make sure <gethostbyname()> is called in SCALAR context and that
2130 its return value is checked for definedness.
2131 If you get tired of remembering which element of the return list
2133 contains which return value, by-name interfaces are provided in
2134 standard modules: "File::stat", "Net::hostent", "Net::netent",
2135 "Net::protoent", "Net::servent", "Time::gmtime", "Time::localtime",
2136 and "User::grent". These override the normal built-ins, supplying
2137 versions that return objects with the appropriate names for each
2138 field. For example:
2139 use File::stat;
2141 use User::pwent;
2142 $is_his = (stat($filename)->uid == pwent($whoever)->uid);
2143 Even though it looks like they're the same method calls (uid), they
2145 aren't, because a "File::stat" object is different from a
2146 "User::pwent" object.
2147 getsockname SOCKET
2149 Returns the packed sockaddr address of this end of the SOCKET
2150 connection, in case you don't know the address because you have
2151 several different IPs that the connection might have come in on.
2152 use Socket;
2154 $mysockaddr = getsockname(SOCK);
2155 ($port, $myaddr) = sockaddr_in($mysockaddr);
2156 printf "Connect to %s [%s]\n",
2157 scalar gethostbyaddr($myaddr, AF_INET),
2158 inet_ntoa($myaddr);
2159 getsockopt SOCKET,LEVEL,OPTNAME
2161 Queries the option named OPTNAME associated with SOCKET at a given
2162 LEVEL. Options may exist at multiple protocol levels depending on
2163 the socket type, but at least the uppermost socket level SOL_SOCKET
2164 (defined in the "Socket" module) will exist. To query options at
2165 another level the protocol number of the appropriate protocol
2166 controlling the option should be supplied. For example, to indicate
2167 that an option is to be interpreted by the TCP protocol, LEVEL
2168 should be set to the protocol number of TCP, which you can get
2169 using "getprotobyname".
2170 The function returns a packed string representing the requested
2172 socket option, or "undef" on error, with the reason for the error
2173 placed in $!). Just what is in the packed string depends on LEVEL
2174 and OPTNAME; consult getsockopt(2) for details. A common case is
2175 that the option is an integer, in which case the result is a packed
2176 integer, which you can decode using "unpack" with the "i" (or "I")
2177 format.
2178 An example to test whether Nagle's algorithm is turned on on a
2180 socket:
2181 use Socket qw(:all);
2183 defined(my $tcp = getprotobyname("tcp"))
2185 or die "Could not determine the protocol number for tcp";
2186 # my $tcp = IPPROTO_TCP; # Alternative
2187 my $packed = getsockopt($socket, $tcp, TCP_NODELAY)
2188 or die "getsockopt TCP_NODELAY: $!";
2189 my $nodelay = unpack("I", $packed);
2190 print "Nagle's algorithm is turned ", $nodelay ? "off\n" : "on\n";
2191 glob EXPR
2193 glob
2194 In list context, returns a (possibly empty) list of filename
2195 expansions on the value of EXPR such as the standard Unix shell
2196 /bin/csh would do. In scalar context, glob iterates through such
2197 filename expansions, returning undef when the list is exhausted.
2198 This is the internal function implementing the "<*.c>" operator,
2199 but you can use it directly. If EXPR is omitted, $_ is used. The
2200 "<*.c>" operator is discussed in more detail in "I/O Operators" in
2201 perlop.
2202 Note that "glob" splits its arguments on whitespace and treats each
2204 segment as separate pattern. As such, "glob("*.c *.h")" matches
2205 all files with a .c or .h extension. The expression "glob(".* *")"
2206 matchs all files in the current working directory.
2207 If non-empty braces are the only wildcard characters used in the
2209 "glob", no filenames are matched, but potentially many strings are
2210 returned. For example, this produces nine strings, one for each
2211 pairing of fruits and colors:
2212 @many = glob "{apple,tomato,cherry}={green,yellow,red}";
2214 Beginning with v5.6.0, this operator is implemented using the
2216 standard "File::Glob" extension. See File::Glob for details,
2217 including "bsd_glob" which does not treat whitespace as a pattern
2218 separator.
2219 gmtime EXPR
2221 gmtime
2222 Works just like localtime but the returned values are localized for
2223 the standard Greenwich time zone.
2224 Note: when called in list context, $isdst, the last value returned
2226 by gmtime is always 0. There is no Daylight Saving Time in GMT.
2227 See "gmtime" in perlport for portability concerns.
2229 goto LABEL
2231 goto EXPR
2232 goto &NAME
2233 The "goto-LABEL" form finds the statement labeled with LABEL and
2234 resumes execution there. It can't be used to get out of a block or
2235 subroutine given to "sort". It can be used to go almost anywhere
2236 else within the dynamic scope, including out of subroutines, but
2237 it's usually better to use some other construct such as "last" or
2238 "die". The author of Perl has never felt the need to use this form
2239 of "goto" (in Perl, that is; C is another matter). (The difference
2240 is that C does not offer named loops combined with loop control.
2241 Perl does, and this replaces most structured uses of "goto" in
2242 other languages.)
2243 The "goto-EXPR" form expects a label name, whose scope will be
2245 resolved dynamically. This allows for computed "goto"s per
2246 FORTRAN, but isn't necessarily recommended if you're optimizing for
2247 maintainability:
2248 goto ("FOO", "BAR", "GLARCH")[$i];
2250 Use of "goto-LABEL" or "goto-EXPR" to jump into a construct is
2252 deprecated and will issue a warning. Even then, it may not be used
2253 to go into any construct that requires initialization, such as a
2254 subroutine or a "foreach" loop. It also can't be used to go into a
2255 construct that is optimized away.
2256 The "goto-&NAME" form is quite different from the other forms of
2258 "goto". In fact, it isn't a goto in the normal sense at all, and
2259 doesn't have the stigma associated with other gotos. Instead, it
2260 exits the current subroutine (losing any changes set by local())
2261 and immediately calls in its place the named subroutine using the
2262 current value of @_. This is used by "AUTOLOAD" subroutines that
2263 wish to load another subroutine and then pretend that the other
2264 subroutine had been called in the first place (except that any
2265 modifications to @_ in the current subroutine are propagated to the
2266 other subroutine.) After the "goto", not even "caller" will be
2267 able to tell that this routine was called first.
2268 NAME needn't be the name of a subroutine; it can be a scalar
2270 variable containing a code reference, or a block that evaluates to
2271 a code reference.
2272 grep BLOCK LIST
2274 grep EXPR,LIST
2275 This is similar in spirit to, but not the same as, grep(1) and its
2276 relatives. In particular, it is not limited to using regular
2277 expressions.
2278 Evaluates the BLOCK or EXPR for each element of LIST (locally
2280 setting $_ to each element) and returns the list value consisting
2281 of those elements for which the expression evaluated to true. In
2282 scalar context, returns the number of times the expression was
2283 true.
2284 @foo = grep(!/^#/, @bar); # weed out comments
2286 or equivalently,
2288 @foo = grep {!/^#/} @bar; # weed out comments
2290 Note that $_ is an alias to the list value, so it can be used to
2292 modify the elements of the LIST. While this is useful and
2293 supported, it can cause bizarre results if the elements of LIST are
2294 not variables. Similarly, grep returns aliases into the original
2295 list, much as a for loop's index variable aliases the list
2296 elements. That is, modifying an element of a list returned by grep
2297 (for example, in a "foreach", "map" or another "grep") actually
2298 modifies the element in the original list. This is usually
2299 something to be avoided when writing clear code.
2300 If $_ is lexical in the scope where the "grep" appears (because it
2302 has been declared with "my $_") then, in addition to being locally
2303 aliased to the list elements, $_ keeps being lexical inside the
2304 block; i.e., it can't be seen from the outside, avoiding any
2305 potential side-effects.
2306 See also "map" for a list composed of the results of the BLOCK or
2308 EXPR.
2309 hex EXPR
2311 hex Interprets EXPR as a hex string and returns the corresponding
2312 value. (To convert strings that might start with either 0, "0x",
2313 or "0b", see "oct".) If EXPR is omitted, uses $_.
2314 print hex '0xAf'; # prints '175'
2316 print hex 'aF'; # same
2317 Hex strings may only represent integers. Strings that would cause
2319 integer overflow trigger a warning. Leading whitespace is not
2320 stripped, unlike oct(). To present something as hex, look into
2321 "printf", "sprintf", or "unpack".
2322 import LIST
2324 There is no builtin "import" function. It is just an ordinary
2325 method (subroutine) defined (or inherited) by modules that wish to
2326 export names to another module. The "use" function calls the
2327 "import" method for the package used. See also "use", perlmod, and
2328 Exporter.
2329 index STR,SUBSTR,POSITION
2331 index STR,SUBSTR
2332 The index function searches for one string within another, but
2333 without the wildcard-like behavior of a full regular-expression
2334 pattern match. It returns the position of the first occurrence of
2335 SUBSTR in STR at or after POSITION. If POSITION is omitted, starts
2336 searching from the beginning of the string. POSITION before the
2337 beginning of the string or after its end is treated as if it were
2338 the beginning or the end, respectively. POSITION and the return
2339 value are based at 0 (or whatever you've set the $[ variable
2340 to--but don't do that). If the substring is not found, "index"
2341 returns one less than the base, ordinarily "-1".
2342 int EXPR
2344 int Returns the integer portion of EXPR. If EXPR is omitted, uses $_.
2345 You should not use this function for rounding: one because it
2346 truncates towards 0, and two because machine representations of
2347 floating-point numbers can sometimes produce counterintuitive
2348 results. For example, "int(-6.725/0.025)" produces -268 rather
2349 than the correct -269; that's because it's really more like
2350 -268.99999999999994315658 instead. Usually, the "sprintf",
2351 "printf", or the "POSIX::floor" and "POSIX::ceil" functions will
2352 serve you better than will int().
2353 ioctl FILEHANDLE,FUNCTION,SCALAR
2355 Implements the ioctl(2) function. You'll probably first have to
2356 say
2357 require "sys/ioctl.ph"; # probably in $Config{archlib}/sys/ioctl.ph
2359 to get the correct function definitions. If sys/ioctl.ph doesn't
2361 exist or doesn't have the correct definitions you'll have to roll
2362 your own, based on your C header files such as <sys/ioctl.h>.
2363 (There is a Perl script called h2ph that comes with the Perl kit
2364 that may help you in this, but it's nontrivial.) SCALAR will be
2365 read and/or written depending on the FUNCTION; a C pointer to the
2366 string value of SCALAR will be passed as the third argument of the
2367 actual "ioctl" call. (If SCALAR has no string value but does have
2368 a numeric value, that value will be passed rather than a pointer to
2369 the string value. To guarantee this to be true, add a 0 to the
2370 scalar before using it.) The "pack" and "unpack" functions may be
2371 needed to manipulate the values of structures used by "ioctl".
2372 The return value of "ioctl" (and "fcntl") is as follows:
2374 if OS returns: then Perl returns:
2376 -1 undefined value
2377 0 string "0 but true"
2378 anything else that number
2379 Thus Perl returns true on success and false on failure, yet you can
2381 still easily determine the actual value returned by the operating
2382 system:
2383 $retval = ioctl(...) || -1;
2385 printf "System returned %d\n", $retval;
2386 The special string "0 but true" is exempt from -w complaints about
2388 improper numeric conversions.
2389 join EXPR,LIST
2391 Joins the separate strings of LIST into a single string with fields
2392 separated by the value of EXPR, and returns that new string.
2393 Example:
2394 $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
2396 Beware that unlike "split", "join" doesn't take a pattern as its
2398 first argument. Compare "split".
2399 keys HASH
2401 keys ARRAY
2402 Returns a list consisting of all the keys of the named hash, or the
2403 indices of an array. (In scalar context, returns the number of keys
2404 or indices.)
2405 The keys of a hash are returned in an apparently random order. The
2407 actual random order is subject to change in future versions of
2408 Perl, but it is guaranteed to be the same order as either the
2409 "values" or "each" function produces (given that the hash has not
2410 been modified). Since Perl 5.8.1 the ordering is different even
2411 between different runs of Perl for security reasons (see
2412 "Algorithmic Complexity Attacks" in perlsec).
2413 As a side effect, calling keys() resets the HASH or ARRAY's
2415 internal iterator (see "each"). In particular, calling keys() in
2416 void context resets the iterator with no other overhead.
2417 Here is yet another way to print your environment:
2419 @keys = keys %ENV;
2421 @values = values %ENV;
2422 while (@keys) {
2423 print pop(@keys), '=', pop(@values), "\n";
2424 }
2425 or how about sorted by key:
2427 foreach $key (sort(keys %ENV)) {
2429 print $key, '=', $ENV{$key}, "\n";
2430 }
2431 The returned values are copies of the original keys in the hash, so
2433 modifying them will not affect the original hash. Compare
2434 "values".
2435 To sort a hash by value, you'll need to use a "sort" function.
2437 Here's a descending numeric sort of a hash by its values:
2438 foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
2440 printf "%4d %s\n", $hash{$key}, $key;
2441 }
2442 Used as an lvalue, "keys" allows you to increase the number of hash
2444 buckets allocated for the given hash. This can gain you a measure
2445 of efficiency if you know the hash is going to get big. (This is
2446 similar to pre-extending an array by assigning a larger number to
2447 $#array.) If you say
2448 keys %hash = 200;
2450 then %hash will have at least 200 buckets allocated for it--256 of
2452 them, in fact, since it rounds up to the next power of two. These
2453 buckets will be retained even if you do "%hash = ()", use "undef
2454 %hash" if you want to free the storage while %hash is still in
2455 scope. You can't shrink the number of buckets allocated for the
2456 hash using "keys" in this way (but you needn't worry about doing
2457 this by accident, as trying has no effect). "keys @array" in an
2458 lvalue context is a syntax error.
2459 See also "each", "values" and "sort".
2461 kill SIGNAL, LIST
2463 Sends a signal to a list of processes. Returns the number of
2464 processes successfully signaled (which is not necessarily the same
2465 as the number actually killed).
2466 $cnt = kill 1, $child1, $child2;
2468 kill 9, @goners;
2469 If SIGNAL is zero, no signal is sent to the process, but "kill"
2471 checks whether it's possible to send a signal to it (that means, to
2472 be brief, that the process is owned by the same user, or we are the
2473 super-user). This is useful to check that a child process is still
2474 alive (even if only as a zombie) and hasn't changed its UID. See
2475 perlport for notes on the portability of this construct.
2476 Unlike in the shell, if SIGNAL is negative, it kills process groups
2478 instead of processes. That means you usually want to use positive
2479 not negative signals. You may also use a signal name in quotes.
2480 The behavior of kill when a PROCESS number is zero or negative
2482 depends on the operating system. For example, on POSIX-conforming
2483 systems, zero will signal the current process group and -1 will
2484 signal all processes.
2485 See "Signals" in perlipc for more details.
2487 last LABEL
2489 last
2490 The "last" command is like the "break" statement in C (as used in
2491 loops); it immediately exits the loop in question. If the LABEL is
2492 omitted, the command refers to the innermost enclosing loop. The
2493 "continue" block, if any, is not executed:
2494 LINE: while (<STDIN>) {
2496 last LINE if /^$/; # exit when done with header
2497 #...
2498 }
2499 "last" cannot be used to exit a block that returns a value such as
2501 "eval {}", "sub {}" or "do {}", and should not be used to exit a
2502 grep() or map() operation.
2503 Note that a block by itself is semantically identical to a loop
2505 that executes once. Thus "last" can be used to effect an early
2506 exit out of such a block.
2507 See also "continue" for an illustration of how "last", "next", and
2509 "redo" work.
2510 lc EXPR
2512 lc Returns a lowercased version of EXPR. This is the internal
2513 function implementing the "\L" escape in double-quoted strings.
2514 If EXPR is omitted, uses $_.
2516 What gets returned depends on several factors:
2518 If "use bytes" is in effect:
2520 On EBCDIC platforms
2521 The results are what the C language system call "tolower()"
2522 returns.
2523 On ASCII platforms
2525 The results follow ASCII semantics. Only characters "A-Z"
2526 change, to "a-z" respectively.
2527 Otherwise, If EXPR has the UTF8 flag set
2529 If the current package has a subroutine named "ToLower", it
2530 will be used to change the case (See "User-Defined Case
2531 Mappings" in perlunicode.) Otherwise Unicode semantics are
2532 used for the case change.
2533 Otherwise, if "use locale" is in effect
2535 Respects current LC_CTYPE locale. See perllocale.
2536 Otherwise, if "use feature 'unicode_strings'" is in effect:
2538 Unicode semantics are used for the case change. Any subroutine
2539 named "ToLower" will not be used.
2540 Otherwise:
2542 On EBCDIC platforms
2543 The results are what the C language system call "tolower()"
2544 returns.
2545 On ASCII platforms
2547 ASCII semantics are used for the case change. The
2548 lowercase of any character outside the ASCII range is the
2549 character itself.
2550 lcfirst EXPR
2552 lcfirst
2553 Returns the value of EXPR with the first character lowercased.
2554 This is the internal function implementing the "\l" escape in
2555 double-quoted strings.
2556 If EXPR is omitted, uses $_.
2558 This function behaves the same way under various pragma, such as in
2560 a locale, as "lc" does.
2561 length EXPR
2563 length
2564 Returns the length in characters of the value of EXPR. If EXPR is
2565 omitted, returns length of $_. If EXPR is undefined, returns
2566 "undef".
2567 This function cannot be used on an entire array or hash to find out
2569 how many elements these have. For that, use "scalar @array" and
2570 "scalar keys %hash", respectively.
2571 Like all Perl character operations, length() normally deals in
2573 logical characters, not physical bytes. For how many bytes a
2574 string encoded as UTF-8 would take up, use
2575 "length(Encode::encode_utf8(EXPR))" (you'll have to "use Encode"
2576 first). See Encode and perlunicode.
2577 link OLDFILE,NEWFILE
2579 Creates a new filename linked to the old filename. Returns true
2580 for success, false otherwise.
2581 listen SOCKET,QUEUESIZE
2583 Does the same thing that the listen(2) system call does. Returns
2584 true if it succeeded, false otherwise. See the example in
2585 "Sockets: Client/Server Communication" in perlipc.
2586 local EXPR
2588 You really probably want to be using "my" instead, because "local"
2589 isn't what most people think of as "local". See "Private Variables
2590 via my()" in perlsub for details.
2591 A local modifies the listed variables to be local to the enclosing
2593 block, file, or eval. If more than one value is listed, the list
2594 must be placed in parentheses. See "Temporary Values via local()"
2595 in perlsub for details, including issues with tied arrays and
2596 hashes.
2597 The "delete local EXPR" construct can also be used to localize the
2599 deletion of array/hash elements to the current block. See
2600 "Localized deletion of elements of composite types" in perlsub.
2601 localtime EXPR
2603 localtime
2604 Converts a time as returned by the time function to a 9-element
2605 list with the time analyzed for the local time zone. Typically
2606 used as follows:
2607 # 0 1 2 3 4 5 6 7 8
2609 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
2610 localtime(time);
2611 All list elements are numeric, and come straight out of the C
2613 `struct tm'. $sec, $min, and $hour are the seconds, minutes, and
2614 hours of the specified time.
2615 $mday is the day of the month, and $mon is the month itself, in the
2617 range 0..11 with 0 indicating January and 11 indicating December.
2618 This makes it easy to get a month name from a list:
2619 my @abbr = qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec );
2621 print "$abbr[$mon] $mday";
2622 # $mon=9, $mday=18 gives "Oct 18"
2623 $year is the number of years since 1900, not just the last two
2625 digits of the year. That is, $year is 123 in year 2023. The
2626 proper way to get a 4-digit year is simply:
2627 $year += 1900;
2629 Otherwise you create non-Y2K-compliant programs--and you wouldn't
2631 want to do that, would you?
2632 To get the last two digits of the year (e.g., '01' in 2001) do:
2634 $year = sprintf("%02d", $year % 100);
2636 $wday is the day of the week, with 0 indicating Sunday and 3
2638 indicating Wednesday. $yday is the day of the year, in the range
2639 0..364 (or 0..365 in leap years.)
2640 $isdst is true if the specified time occurs during Daylight Saving
2642 Time, false otherwise.
2643 If EXPR is omitted, "localtime()" uses the current time (as
2645 returned by time(3)).
2646 In scalar context, "localtime()" returns the ctime(3) value:
2648 $now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
2650 This scalar value is not locale dependent but is a Perl builtin.
2652 For GMT instead of local time use the "gmtime" builtin. See also
2653 the "Time::Local" module (to convert the second, minutes, hours,
2654 ... back to the integer value returned by time()), and the POSIX
2655 module's strftime(3) and mktime(3) functions.
2656 To get somewhat similar but locale dependent date strings, set up
2658 your locale environment variables appropriately (please see
2659 perllocale) and try for example:
2660 use POSIX qw(strftime);
2662 $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
2663 # or for GMT formatted appropriately for your locale:
2664 $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
2665 Note that the %a and %b, the short forms of the day of the week and
2667 the month of the year, may not necessarily be three characters
2668 wide.
2669 See "localtime" in perlport for portability concerns.
2671 The Time::gmtime and Time::localtime modules provides a convenient,
2673 by-name access mechanism to the gmtime() and localtime() functions,
2674 respectively.
2675 For a comprehensive date and time representation look at the
2677 DateTime module on CPAN.
2678 lock THING
2680 This function places an advisory lock on a shared variable, or
2681 referenced object contained in THING until the lock goes out of
2682 scope.
2683 lock() is a "weak keyword" : this means that if you've defined a
2685 function by this name (before any calls to it), that function will
2686 be called instead. If you are not under "use threads::shared" this
2687 does nothing. See threads::shared.
2688 log EXPR
2690 log Returns the natural logarithm (base e) of EXPR. If EXPR is
2691 omitted, returns log of $_. To get the log of another base, use
2692 basic algebra: The base-N log of a number is equal to the natural
2693 log of that number divided by the natural log of N. For example:
2694 sub log10 {
2696 my $n = shift;
2697 return log($n)/log(10);
2698 }
2699 See also "exp" for the inverse operation.
2701 lstat EXPR
2703 lstat
2704 Does the same thing as the "stat" function (including setting the
2705 special "_" filehandle) but stats a symbolic link instead of the
2706 file the symbolic link points to. If symbolic links are
2707 unimplemented on your system, a normal "stat" is done. For much
2708 more detailed information, please see the documentation for "stat".
2709 If EXPR is omitted, stats $_.
2711 m// The match operator. See "Regexp Quote-Like Operators" in perlop.
2713 map BLOCK LIST
2715 map EXPR,LIST
2716 Evaluates the BLOCK or EXPR for each element of LIST (locally
2717 setting $_ to each element) and returns the list value composed of
2718 the results of each such evaluation. In scalar context, returns
2719 the total number of elements so generated. Evaluates BLOCK or EXPR
2720 in list context, so each element of LIST may produce zero, one, or
2721 more elements in the returned value.
2722 @chars = map(chr, @nums);
2724 translates a list of numbers to the corresponding characters. And
2726 %hash = map { get_a_key_for($_) => $_ } @array;
2728 is just a funny way to write
2730 %hash = ();
2732 foreach (@array) {
2733 $hash{get_a_key_for($_)} = $_;
2734 }
2735 Note that $_ is an alias to the list value, so it can be used to
2737 modify the elements of the LIST. While this is useful and
2738 supported, it can cause bizarre results if the elements of LIST are
2739 not variables. Using a regular "foreach" loop for this purpose
2740 would be clearer in most cases. See also "grep" for an array
2741 composed of those items of the original list for which the BLOCK or
2742 EXPR evaluates to true.
2743 If $_ is lexical in the scope where the "map" appears (because it
2745 has been declared with "my $_"), then, in addition to being locally
2746 aliased to the list elements, $_ keeps being lexical inside the
2747 block; that is, it can't be seen from the outside, avoiding any
2748 potential side-effects.
2749 "{" starts both hash references and blocks, so "map { ..." could be
2751 either the start of map BLOCK LIST or map EXPR, LIST. Because Perl
2752 doesn't look ahead for the closing "}" it has to take a guess at
2753 which it's dealing with based on what it finds just after the "{".
2754 Usually it gets it right, but if it doesn't it won't realize
2755 something is wrong until it gets to the "}" and encounters the
2756 missing (or unexpected) comma. The syntax error will be reported
2757 close to the "}", but you'll need to change something near the "{"
2758 such as using a unary "+" to give Perl some help:
2759 %hash = map { "\L$_" => 1 } @array # perl guesses EXPR. wrong
2761 %hash = map { +"\L$_" => 1 } @array # perl guesses BLOCK. right
2762 %hash = map { ("\L$_" => 1) } @array # this also works
2763 %hash = map { lc($_) => 1 } @array # as does this.
2764 %hash = map +( lc($_) => 1 ), @array # this is EXPR and works!
2765 %hash = map ( lc($_), 1 ), @array # evaluates to (1, @array)
2767 or to force an anon hash constructor use "+{":
2769 @hashes = map +{ lc($_) => 1 }, @array # EXPR, so needs comma at end
2771 to get a list of anonymous hashes each with only one entry apiece.
2773 mkdir FILENAME,MASK
2775 mkdir FILENAME
2776 mkdir
2777 Creates the directory specified by FILENAME, with permissions
2778 specified by MASK (as modified by "umask"). If it succeeds it
2779 returns true, otherwise it returns false and sets $! (errno). If
2780 omitted, MASK defaults to 0777. If omitted, FILENAME defaults to
2781 $_.
2782 In general, it is better to create directories with permissive
2784 MASK, and let the user modify that with their "umask", than it is
2785 to supply a restrictive MASK and give the user no way to be more
2786 permissive. The exceptions to this rule are when the file or
2787 directory should be kept private (mail files, for instance). The
2788 perlfunc(1) entry on "umask" discusses the choice of MASK in more
2789 detail.
2790 Note that according to the POSIX 1003.1-1996 the FILENAME may have
2792 any number of trailing slashes. Some operating and filesystems do
2793 not get this right, so Perl automatically removes all trailing
2794 slashes to keep everyone happy.
2795 To recursively create a directory structure, look at the "mkpath"
2797 function of the File::Path module.
2798 msgctl ID,CMD,ARG
2800 Calls the System V IPC function msgctl(2). You'll probably have to
2801 say
2802 use IPC::SysV;
2804 first to get the correct constant definitions. If CMD is
2806 "IPC_STAT", then ARG must be a variable that will hold the returned
2807 "msqid_ds" structure. Returns like "ioctl": the undefined value
2808 for error, "0 but true" for zero, or the actual return value
2809 otherwise. See also "SysV IPC" in perlipc, "IPC::SysV", and
2810 "IPC::Semaphore" documentation.
2811 msgget KEY,FLAGS
2813 Calls the System V IPC function msgget(2). Returns the message
2814 queue id, or the undefined value if there is an error. See also
2815 "SysV IPC" in perlipc and "IPC::SysV" and "IPC::Msg" documentation.
2816 msgrcv ID,VAR,SIZE,TYPE,FLAGS
2818 Calls the System V IPC function msgrcv to receive a message from
2819 message queue ID into variable VAR with a maximum message size of
2820 SIZE. Note that when a message is received, the message type as a
2821 native long integer will be the first thing in VAR, followed by the
2822 actual message. This packing may be opened with "unpack("l! a*")".
2823 Taints the variable. Returns true if successful, or false if there
2824 is an error. See also "SysV IPC" in perlipc, "IPC::SysV", and
2825 "IPC::SysV::Msg" documentation.
2826 msgsnd ID,MSG,FLAGS
2828 Calls the System V IPC function msgsnd to send the message MSG to
2829 the message queue ID. MSG must begin with the native long integer
2830 message type, and be followed by the length of the actual message,
2831 and finally the message itself. This kind of packing can be
2832 achieved with "pack("l! a*", $type, $message)". Returns true if
2833 successful, or false if there is an error. See also "IPC::SysV"
2834 and "IPC::SysV::Msg" documentation.
2835 my EXPR
2837 my TYPE EXPR
2838 my EXPR : ATTRS
2839 my TYPE EXPR : ATTRS
2840 A "my" declares the listed variables to be local (lexically) to the
2841 enclosing block, file, or "eval". If more than one value is
2842 listed, the list must be placed in parentheses.
2843 The exact semantics and interface of TYPE and ATTRS are still
2845 evolving. TYPE is currently bound to the use of "fields" pragma,
2846 and attributes are handled using the "attributes" pragma, or
2847 starting from Perl 5.8.0 also via the "Attribute::Handlers" module.
2848 See "Private Variables via my()" in perlsub for details, and
2849 fields, attributes, and Attribute::Handlers.
2850 next LABEL
2852 next
2853 The "next" command is like the "continue" statement in C; it starts
2854 the next iteration of the loop:
2855 LINE: while (<STDIN>) {
2857 next LINE if /^#/; # discard comments
2858 #...
2859 }
2860 Note that if there were a "continue" block on the above, it would
2862 get executed even on discarded lines. If LABEL is omitted, the
2863 command refers to the innermost enclosing loop.
2864 "next" cannot be used to exit a block which returns a value such as
2866 "eval {}", "sub {}" or "do {}", and should not be used to exit a
2867 grep() or map() operation.
2868 Note that a block by itself is semantically identical to a loop
2870 that executes once. Thus "next" will exit such a block early.
2871 See also "continue" for an illustration of how "last", "next", and
2873 "redo" work.
2874 no MODULE VERSION LIST
2876 no MODULE VERSION
2877 no MODULE LIST
2878 no MODULE
2879 no VERSION
2880 See the "use" function, of which "no" is the opposite.
2881 oct EXPR
2883 oct Interprets EXPR as an octal string and returns the corresponding
2884 value. (If EXPR happens to start off with "0x", interprets it as a
2885 hex string. If EXPR starts off with "0b", it is interpreted as a
2886 binary string. Leading whitespace is ignored in all three cases.)
2887 The following will handle decimal, binary, octal, and hex in
2888 standard Perl notation:
2889 $val = oct($val) if $val =~ /^0/;
2891 If EXPR is omitted, uses $_. To go the other way (produce a
2893 number in octal), use sprintf() or printf():
2894 $dec_perms = (stat("filename"))[2] & 07777;
2896 $oct_perm_str = sprintf "%o", $perms;
2897 The oct() function is commonly used when a string such as 644 needs
2899 to be converted into a file mode, for example. Although Perl
2900 automatically converts strings into numbers as needed, this
2901 automatic conversion assumes base 10.
2902 Leading white space is ignored without warning, as too are any
2904 trailing non-digits, such as a decimal point ("oct" only handles
2905 non-negative integers, not negative integers or floating point).
2906 open FILEHANDLE,EXPR
2908 open FILEHANDLE,MODE,EXPR
2909 open FILEHANDLE,MODE,EXPR,LIST
2910 open FILEHANDLE,MODE,REFERENCE
2911 open FILEHANDLE
2912 Opens the file whose filename is given by EXPR, and associates it
2913 with FILEHANDLE.
2914 Simple examples to open a file for reading:
2916 open(my $fh, '<', "input.txt") or die $!;
2918 and for writing:
2920 open(my $fh, '>', "output.txt") or die $!;
2922 (The following is a comprehensive reference to open(): for a
2924 gentler introduction you may consider perlopentut.)
2925 If FILEHANDLE is an undefined scalar variable (or array or hash
2927 element) the variable is assigned a reference to a new anonymous
2928 filehandle, otherwise if FILEHANDLE is an expression, its value is
2929 used as the name of the real filehandle wanted. (This is
2930 considered a symbolic reference, so "use strict 'refs'" should not
2931 be in effect.)
2932 If EXPR is omitted, the scalar variable of the same name as the
2934 FILEHANDLE contains the filename. (Note that lexical
2935 variables--those declared with "my"--will not work for this
2936 purpose; so if you're using "my", specify EXPR in your call to
2937 open.)
2938 If three or more arguments are specified then the mode of opening
2940 and the filename are separate. If MODE is '<' or nothing, the file
2941 is opened for input. If MODE is '>', the file is truncated and
2942 opened for output, being created if necessary. If MODE is '>>',
2943 the file is opened for appending, again being created if necessary.
2944 You can put a '+' in front of the '>' or '<' to indicate that you
2946 want both read and write access to the file; thus '+<' is almost
2947 always preferred for read/write updates--the '+>' mode would
2948 clobber the file first. You can't usually use either read-write
2949 mode for updating textfiles, since they have variable length
2950 records. See the -i switch in perlrun for a better approach. The
2951 file is created with permissions of 0666 modified by the process's
2952 "umask" value.
2953 These various prefixes correspond to the fopen(3) modes of 'r',
2955 'r+', 'w', 'w+', 'a', and 'a+'.
2956 In the two-argument (and one-argument) form of the call, the mode
2958 and filename should be concatenated (in that order), possibly
2959 separated by spaces. You may omit the mode in these forms when
2960 that mode is '<'.
2961 If the filename begins with '|', the filename is interpreted as a
2963 command to which output is to be piped, and if the filename ends
2964 with a '|', the filename is interpreted as a command that pipes
2965 output to us. See "Using open() for IPC" in perlipc for more
2966 examples of this. (You are not allowed to "open" to a command that
2967 pipes both in and out, but see IPC::Open2, IPC::Open3, and
2968 "Bidirectional Communication with Another Process" in perlipc for
2969 alternatives.)
2970 For three or more arguments if MODE is '|-', the filename is
2972 interpreted as a command to which output is to be piped, and if
2973 MODE is '-|', the filename is interpreted as a command that pipes
2974 output to us. In the two-argument (and one-argument) form, one
2975 should replace dash ('-') with the command. See "Using open() for
2976 IPC" in perlipc for more examples of this. (You are not allowed to
2977 "open" to a command that pipes both in and out, but see IPC::Open2,
2978 IPC::Open3, and "Bidirectional Communication" in perlipc for
2979 alternatives.)
2980 In the form of pipe opens taking three or more arguments, if LIST
2982 is specified (extra arguments after the command name) then LIST
2983 becomes arguments to the command invoked if the platform supports
2984 it. The meaning of "open" with more than three arguments for non-
2985 pipe modes is not yet defined, but experimental "layers" may give
2986 extra LIST arguments meaning.
2987 In the two-argument (and one-argument) form, opening '<-' or '-'
2989 opens STDIN and opening '>-' opens STDOUT.
2990 You may use the three-argument form of open to specify I/O layers
2992 (sometimes referred to as "disciplines") to apply to the handle
2993 that affect how the input and output are processed (see open and
2994 PerlIO for more details). For example:
2995 open(my $fh, "<:encoding(UTF-8)", "filename")
2997 || die "can't open UTF-8 encoded filename: $!";
2998 opens the UTF-8 encoded file containing Unicode characters; see
3000 perluniintro. Note that if layers are specified in the three-
3001 argument form, then default layers stored in ${^OPEN} (see perlvar;
3002 usually set by the open pragma or the switch -CioD) are ignored.
3003 Open returns nonzero on success, the undefined value otherwise. If
3005 the "open" involved a pipe, the return value happens to be the pid
3006 of the subprocess.
3007 If you're running Perl on a system that distinguishes between text
3009 files and binary files, then you should check out "binmode" for
3010 tips for dealing with this. The key distinction between systems
3011 that need "binmode" and those that don't is their text file
3012 formats. Systems like Unix, Mac OS, and Plan 9, that end lines
3013 with a single character and encode that character in C as "\n" do
3014 not need "binmode". The rest need it.
3015 When opening a file, it's seldom a good idea to continue if the
3017 request failed, so "open" is frequently used with "die". Even if
3018 "die" won't do what you want (say, in a CGI script, where you want
3019 to format a suitable error message (but there are modules that can
3020 help with that problem)) always check the return value from opening
3021 a file.
3022 As a special case the 3-arg form with a read/write mode and the
3024 third argument being "undef":
3025 open(my $tmp, "+>", undef) or die ...
3027 opens a filehandle to an anonymous temporary file. Also using "+<"
3029 works for symmetry, but you really should consider writing
3030 something to the temporary file first. You will need to seek() to
3031 do the reading.
3032 Since v5.8.0, Perl has built using PerlIO by default. Unless
3034 you've changed this (i.e., Configure -Uuseperlio), you can open
3035 filehandles directly to Perl scalars via:
3036 open($fh, '>', \$variable) || ..
3038 To (re)open "STDOUT" or "STDERR" as an in-memory file, close it
3040 first:
3041 close STDOUT;
3043 open STDOUT, '>', \$variable or die "Can't open STDOUT: $!";
3044 General examples:
3046 $ARTICLE = 100;
3048 open ARTICLE or die "Can't find article $ARTICLE: $!\n";
3049 while (<ARTICLE>) {...
3050 open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
3052 # if the open fails, output is discarded
3053 open(my $dbase, '+<', 'dbase.mine') # open for update
3055 or die "Can't open 'dbase.mine' for update: $!";
3056 open(my $dbase, '+<dbase.mine') # ditto
3058 or die "Can't open 'dbase.mine' for update: $!";
3059 open(ARTICLE, '-|', "caesar <$article") # decrypt article
3061 or die "Can't start caesar: $!";
3062 open(ARTICLE, "caesar <$article |") # ditto
3064 or die "Can't start caesar: $!";
3065 open(EXTRACT, "|sort >Tmp$$") # $$ is our process id
3067 or die "Can't start sort: $!";
3068 # in-memory files
3070 open(MEMORY,'>', \$var)
3071 or die "Can't open memory file: $!";
3072 print MEMORY "foo!\n"; # output will appear in $var
3073 # process argument list of files along with any includes
3075 foreach $file (@ARGV) {
3077 process($file, 'fh00');
3078 }
3079 sub process {
3081 my($filename, $input) = @_;
3082 $input++; # this is a string increment
3083 unless (open($input, $filename)) {
3084 print STDERR "Can't open $filename: $!\n";
3085 return;
3086 }
3087 local $_;
3089 while (<$input>) { # note use of indirection
3090 if (/^#include "(.*)"/) {
3091 process($1, $input);
3092 next;
3093 }
3094 #... # whatever
3095 }
3096 }
3097 See perliol for detailed info on PerlIO.
3099 You may also, in the Bourne shell tradition, specify an EXPR
3101 beginning with '>&', in which case the rest of the string is
3102 interpreted as the name of a filehandle (or file descriptor, if
3103 numeric) to be duped (as dup(2)) and opened. You may use "&" after
3104 ">", ">>", "<", "+>", "+>>", and "+<". The mode you specify should
3105 match the mode of the original filehandle. (Duping a filehandle
3106 does not take into account any existing contents of IO buffers.) If
3107 you use the 3-arg form then you can pass either a number, the name
3108 of a filehandle or the normal "reference to a glob".
3109 Here is a script that saves, redirects, and restores "STDOUT" and
3111 "STDERR" using various methods:
3112 #!/usr/bin/perl
3114 open my $oldout, ">&STDOUT" or die "Can't dup STDOUT: $!";
3115 open OLDERR, ">&", \*STDERR or die "Can't dup STDERR: $!";
3116 open STDOUT, '>', "foo.out" or die "Can't redirect STDOUT: $!";
3118 open STDERR, ">&STDOUT" or die "Can't dup STDOUT: $!";
3119 select STDERR; $| = 1; # make unbuffered
3121 select STDOUT; $| = 1; # make unbuffered
3122 print STDOUT "stdout 1\n"; # this works for
3124 print STDERR "stderr 1\n"; # subprocesses too
3125 open STDOUT, ">&", $oldout or die "Can't dup \$oldout: $!";
3127 open STDERR, ">&OLDERR" or die "Can't dup OLDERR: $!";
3128 print STDOUT "stdout 2\n";
3130 print STDERR "stderr 2\n";
3131 If you specify '<&=X', where "X" is a file descriptor number or a
3133 filehandle, then Perl will do an equivalent of C's "fdopen" of that
3134 file descriptor (and not call dup(2)); this is more parsimonious of
3135 file descriptors. For example:
3136 # open for input, reusing the fileno of $fd
3138 open(FILEHANDLE, "<&=$fd")
3139 or
3141 open(FILEHANDLE, "<&=", $fd)
3143 or
3145 # open for append, using the fileno of OLDFH
3147 open(FH, ">>&=", OLDFH)
3148 or
3150 open(FH, ">>&=OLDFH")
3152 Being parsimonious on filehandles is also useful (besides being
3154 parsimonious) for example when something is dependent on file
3155 descriptors, like for example locking using flock(). If you do
3156 just "open(A, '>>&B')", the filehandle A will not have the same
3157 file descriptor as B, and therefore flock(A) will not flock(B), and
3158 vice versa. But with "open(A, '>>&=B')" the filehandles will share
3159 the same file descriptor.
3160 Note that if you are using Perls older than 5.8.0, Perl will be
3162 using the standard C libraries' fdopen() to implement the "="
3163 functionality. On many Unix systems fdopen() fails when file
3164 descriptors exceed a certain value, typically 255. For Perls 5.8.0
3165 and later, PerlIO is most often the default.
3166 You can see whether Perl has been compiled with PerlIO or not by
3168 running "perl -V" and looking for "useperlio=" line. If
3169 "useperlio" is "define", you have PerlIO, otherwise you don't.
3170 If you open a pipe on the command '-', i.e., either '|-' or '-|'
3172 with 2-arguments (or 1-argument) form of open(), then there is an
3173 implicit fork done, and the return value of open is the pid of the
3174 child within the parent process, and 0 within the child process.
3175 (Use "defined($pid)" to determine whether the open was successful.)
3176 The filehandle behaves normally for the parent, but I/O to that
3177 filehandle is piped from/to the STDOUT/STDIN of the child process.
3178 In the child process, the filehandle isn't opened--I/O happens
3179 from/to the new STDOUT/STDIN. Typically this is used like the
3180 normal piped open when you want to exercise more control over just
3181 how the pipe command gets executed, such as when running setuid and
3182 you don't want to have to scan shell commands for metacharacters.
3183 The following triples are more or less equivalent:
3185 open(FOO, "|tr '[a-z]' '[A-Z]'");
3187 open(FOO, '|-', "tr '[a-z]' '[A-Z]'");
3188 open(FOO, '|-') || exec 'tr', '[a-z]', '[A-Z]';
3189 open(FOO, '|-', "tr", '[a-z]', '[A-Z]');
3190 open(FOO, "cat -n '$file'|");
3192 open(FOO, '-|', "cat -n '$file'");
3193 open(FOO, '-|') || exec 'cat', '-n', $file;
3194 open(FOO, '-|', "cat", '-n', $file);
3195 The last example in each block shows the pipe as "list form", which
3197 is not yet supported on all platforms. A good rule of thumb is
3198 that if your platform has true "fork()" (in other words, if your
3199 platform is Unix) you can use the list form.
3200 See "Safe Pipe Opens" in perlipc for more examples of this.
3202 Beginning with v5.6.0, Perl will attempt to flush all files opened
3204 for output before any operation that may do a fork, but this may
3205 not be supported on some platforms (see perlport). To be safe, you
3206 may need to set $| ($AUTOFLUSH in English) or call the
3207 "autoflush()" method of "IO::Handle" on any open handles.
3208 On systems that support a close-on-exec flag on files, the flag
3210 will be set for the newly opened file descriptor as determined by
3211 the value of $^F. See "$^F" in perlvar.
3212 Closing any piped filehandle causes the parent process to wait for
3214 the child to finish, and returns the status value in $? and
3215 "${^CHILD_ERROR_NATIVE}".
3216 The filename passed to 2-argument (or 1-argument) form of open()
3218 will have leading and trailing whitespace deleted, and the normal
3219 redirection characters honored. This property, known as "magic
3220 open", can often be used to good effect. A user could specify a
3221 filename of "rsh cat file |", or you could change certain filenames
3222 as needed:
3223 $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
3225 open(FH, $filename) or die "Can't open $filename: $!";
3226 Use 3-argument form to open a file with arbitrary weird characters
3228 in it,
3229 open(FOO, '<', $file);
3231 otherwise it's necessary to protect any leading and trailing
3233 whitespace:
3234 $file =~ s#^(\s)#./$1#;
3236 open(FOO, "< $file\0");
3237 (this may not work on some bizarre filesystems). One should
3239 conscientiously choose between the magic and 3-arguments form of
3240 open():
3241 open IN, $ARGV[0];
3243 will allow the user to specify an argument of the form "rsh cat
3245 file |", but will not work on a filename that happens to have a
3246 trailing space, while
3247 open IN, '<', $ARGV[0];
3249 will have exactly the opposite restrictions.
3251 If you want a "real" C "open" (see open(2) on your system), then
3253 you should use the "sysopen" function, which involves no such magic
3254 (but may use subtly different filemodes than Perl open(), which is
3255 mapped to C fopen()). This is another way to protect your
3256 filenames from interpretation. For example:
3257 use IO::Handle;
3259 sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL)
3260 or die "sysopen $path: $!";
3261 $oldfh = select(HANDLE); $| = 1; select($oldfh);
3262 print HANDLE "stuff $$\n";
3263 seek(HANDLE, 0, 0);
3264 print "File contains: ", <HANDLE>;
3265 Using the constructor from the "IO::Handle" package (or one of its
3267 subclasses, such as "IO::File" or "IO::Socket"), you can generate
3268 anonymous filehandles that have the scope of whatever variables
3269 hold references to them, and automatically close whenever and
3270 however you leave that scope:
3271 use IO::File;
3273 #...
3274 sub read_myfile_munged {
3275 my $ALL = shift;
3276 my $handle = IO::File->new;
3277 open($handle, "myfile") or die "myfile: $!";
3278 $first = <$handle>
3279 or return (); # Automatically closed here.
3280 mung $first or die "mung failed"; # Or here.
3281 return $first, <$handle> if $ALL; # Or here.
3282 $first; # Or here.
3283 }
3284 See "seek" for some details about mixing reading and writing.
3286 opendir DIRHANDLE,EXPR
3288 Opens a directory named EXPR for processing by "readdir",
3289 "telldir", "seekdir", "rewinddir", and "closedir". Returns true if
3290 successful. DIRHANDLE may be an expression whose value can be used
3291 as an indirect dirhandle, usually the real dirhandle name. If
3292 DIRHANDLE is an undefined scalar variable (or array or hash
3293 element), the variable is assigned a reference to a new anonymous
3294 dirhandle. DIRHANDLEs have their own namespace separate from
3295 FILEHANDLEs.
3296 See example at "readdir".
3298 ord EXPR
3300 ord Returns the numeric (the native 8-bit encoding, like ASCII or
3301 EBCDIC, or Unicode) value of the first character of EXPR. If EXPR
3302 is omitted, uses $_.
3303 For the reverse, see "chr". See perlunicode for more about
3305 Unicode.
3306 our EXPR
3308 our TYPE EXPR
3309 our EXPR : ATTRS
3310 our TYPE EXPR : ATTRS
3311 "our" associates a simple name with a package variable in the
3312 current package for use within the current scope. When "use strict
3313 'vars'" is in effect, "our" lets you use declared global variables
3314 without qualifying them with package names, within the lexical
3315 scope of the "our" declaration. In this way "our" differs from
3316 "use vars", which is package scoped.
3317 Unlike "my", which both allocates storage for a variable and
3319 associates a simple name with that storage for use within the
3320 current scope, "our" associates a simple name with a package
3321 variable in the current package, for use within the current scope.
3322 In other words, "our" has the same scoping rules as "my", but does
3323 not necessarily create a variable.
3324 If more than one value is listed, the list must be placed in
3326 parentheses.
3327 our $foo;
3329 our($bar, $baz);
3330 An "our" declaration declares a global variable that will be
3332 visible across its entire lexical scope, even across package
3333 boundaries. The package in which the variable is entered is
3334 determined at the point of the declaration, not at the point of
3335 use. This means the following behavior holds:
3336 package Foo;
3338 our $bar; # declares $Foo::bar for rest of lexical scope
3339 $bar = 20;
3340 package Bar;
3342 print $bar; # prints 20, as it refers to $Foo::bar
3343 Multiple "our" declarations with the same name in the same lexical
3345 scope are allowed if they are in different packages. If they
3346 happen to be in the same package, Perl will emit warnings if you
3347 have asked for them, just like multiple "my" declarations. Unlike
3348 a second "my" declaration, which will bind the name to a fresh
3349 variable, a second "our" declaration in the same package, in the
3350 same scope, is merely redundant.
3351 use warnings;
3353 package Foo;
3354 our $bar; # declares $Foo::bar for rest of lexical scope
3355 $bar = 20;
3356 package Bar;
3358 our $bar = 30; # declares $Bar::bar for rest of lexical scope
3359 print $bar; # prints 30
3360 our $bar; # emits warning but has no other effect
3362 print $bar; # still prints 30
3363 An "our" declaration may also have a list of attributes associated
3365 with it.
3366 The exact semantics and interface of TYPE and ATTRS are still
3368 evolving. TYPE is currently bound to the use of "fields" pragma,
3369 and attributes are handled using the "attributes" pragma, or
3370 starting from Perl 5.8.0 also via the "Attribute::Handlers" module.
3371 See "Private Variables via my()" in perlsub for details, and
3372 fields, attributes, and Attribute::Handlers.
3373 pack TEMPLATE,LIST
3375 Takes a LIST of values and converts it into a string using the
3376 rules given by the TEMPLATE. The resulting string is the
3377 concatenation of the converted values. Typically, each converted
3378 value looks like its machine-level representation. For example, on
3379 32-bit machines an integer may be represented by a sequence of 4
3380 bytes, which will in Perl be presented as a string that's 4
3381 characters long.
3382 See perlpacktut for an introduction to this function.
3384 The TEMPLATE is a sequence of characters that give the order and
3386 type of values, as follows:
3387 a A string with arbitrary binary data, will be null padded.
3389 A A text (ASCII) string, will be space padded.
3390 Z A null-terminated (ASCIZ) string, will be null padded.
3391 b A bit string (ascending bit order inside each byte, like vec()).
3393 B A bit string (descending bit order inside each byte).
3394 h A hex string (low nybble first).
3395 H A hex string (high nybble first).
3396 c A signed char (8-bit) value.
3398 C An unsigned char (octet) value.
3399 W An unsigned char value (can be greater than 255).
3400 s A signed short (16-bit) value.
3402 S An unsigned short value.
3403 l A signed long (32-bit) value.
3405 L An unsigned long value.
3406 q A signed quad (64-bit) value.
3408 Q An unsigned quad value.
3409 (Quads are available only if your system supports 64-bit
3410 integer values _and_ if Perl has been compiled to support those.
3411 Raises an exception otherwise.)
3412 i A signed integer value.
3414 I A unsigned integer value.
3415 (This 'integer' is _at_least_ 32 bits wide. Its exact
3416 size depends on what a local C compiler calls 'int'.)
3417 n An unsigned short (16-bit) in "network" (big-endian) order.
3419 N An unsigned long (32-bit) in "network" (big-endian) order.
3420 v An unsigned short (16-bit) in "VAX" (little-endian) order.
3421 V An unsigned long (32-bit) in "VAX" (little-endian) order.
3422 j A Perl internal signed integer value (IV).
3424 J A Perl internal unsigned integer value (UV).
3425 f A single-precision float in native format.
3427 d A double-precision float in native format.
3428 F A Perl internal floating-point value (NV) in native format
3430 D A float of long-double precision in native format.
3431 (Long doubles are available only if your system supports long
3432 double values _and_ if Perl has been compiled to support those.
3433 Raises an exception otherwise.)
3434 p A pointer to a null-terminated string.
3436 P A pointer to a structure (fixed-length string).
3437 u A uuencoded string.
3439 U A Unicode character number. Encodes to a character in character mode
3440 and UTF-8 (or UTF-EBCDIC in EBCDIC platforms) in byte mode.
3441 w A BER compressed integer (not an ASN.1 BER, see perlpacktut for
3443 details). Its bytes represent an unsigned integer in base 128,
3444 most significant digit first, with as few digits as possible. Bit
3445 eight (the high bit) is set on each byte except the last.
3446 x A null byte (a.k.a ASCII NUL, "\000", chr(0))
3448 X Back up a byte.
3449 @ Null-fill or truncate to absolute position, counted from the
3450 start of the innermost ()-group.
3451 . Null-fill or truncate to absolute position specified by the value.
3452 ( Start of a ()-group.
3453 One or more modifiers below may optionally follow certain letters
3455 in the TEMPLATE (the second column lists letters for which the
3456 modifier is valid):
3457 ! sSlLiI Forces native (short, long, int) sizes instead
3459 of fixed (16-/32-bit) sizes.
3460 xX Make x and X act as alignment commands.
3462 nNvV Treat integers as signed instead of unsigned.
3464 @. Specify position as byte offset in the internal
3466 representation of the packed string. Efficient but
3467 dangerous.
3468 > sSiIlLqQ Force big-endian byte-order on the type.
3470 jJfFdDpP (The "big end" touches the construct.)
3471 < sSiIlLqQ Force little-endian byte-order on the type.
3473 jJfFdDpP (The "little end" touches the construct.)
3474 The ">" and "<" modifiers can also be used on "()" groups to force
3476 a particular byte-order on all components in that group, including
3477 all its subgroups.
3478 The following rules apply:
3480 · Each letter may optionally be followed by a number indicating
3482 the repeat count. A numeric repeat count may optionally be
3483 enclosed in brackets, as in "pack("C[80]", @arr)". The repeat
3484 count gobbles that many values from the LIST when used with all
3485 format types other than "a", "A", "Z", "b", "B", "h", "H", "@",
3486 ".", "x", "X", and "P", where it means something else, dscribed
3487 below. Supplying a "*" for the repeat count instead of a
3488 number means to use however many items are left, except for:
3489 · "@", "x", and "X", where it is equivalent to 0.
3491 · <.>, where it means relative to the start of the string.
3493 · "u", where it is equivalent to 1 (or 45, which here is
3495 equivalent).
3496 One can replace a numeric repeat count with a template letter
3498 enclosed in brackets to use the packed byte length of the
3499 bracketed template for the repeat count.
3500 For example, the template "x[L]" skips as many bytes as in a
3502 packed long, and the template "$t X[$t] $t" unpacks twice
3503 whatever $t (when variable-expanded) unpacks. If the template
3504 in brackets contains alignment commands (such as "x![d]"), its
3505 packed length is calculated as if the start of the template had
3506 the maximal possible alignment.
3507 When used with "Z", a "*" as the repeat count is guaranteed to
3509 add a trailing null byte, so the resulting string is always one
3510 byte longer than the byte length of the item itself.
3511 When used with "@", the repeat count represents an offset from
3513 the start of the innermost "()" group.
3514 When used with ".", the repeat count determines the starting
3516 position to calculate the value offset as follows:
3517 · If the repeat count is 0, it's relative to the current
3519 position.
3520 · If the repeat count is "*", the offset is relative to the
3522 start of the packed string.
3523 · And if it's an integer n, the offset is relative to the
3525 start of the nth innermost "()" group, or to the start of
3526 the string if n is bigger then the group level.
3527 The repeat count for "u" is interpreted as the maximal number
3529 of bytes to encode per line of output, with 0, 1 and 2 replaced
3530 by 45. The repeat count should not be more than 65.
3531 · The "a", "A", and "Z" types gobble just one value, but pack it
3533 as a string of length count, padding with nulls or spaces as
3534 needed. When unpacking, "A" strips trailing whitespace and
3535 nulls, "Z" strips everything after the first null, and "a"
3536 returns data without any sort of trimming.
3537 If the value to pack is too long, the result is truncated. If
3539 it's too long and an explicit count is provided, "Z" packs only
3540 "$count-1" bytes, followed by a null byte. Thus "Z" always
3541 packs a trailing null, except for when the count is 0.
3542 · Likewise, the "b" and "B" formats pack a string that's that
3544 many bits long. Each such format generates 1 bit of the
3545 result.
3546 Each result bit is based on the least-significant bit of the
3548 corresponding input character, i.e., on "ord($char)%2". In
3549 particular, characters "0" and "1" generate bits 0 and 1, as do
3550 characters "\000" and "\001".
3551 Starting from the beginning of the input string, each 8-tuple
3553 of characters is converted to 1 character of output. With
3554 format "b", the first character of the 8-tuple determines the
3555 least-significant bit of a character; with format "B", it
3556 determines the most-significant bit of a character.
3557 If the length of the input string is not evenly divisible by 8,
3559 the remainder is packed as if the input string were padded by
3560 null characters at the end. Similarly during unpacking,
3561 "extra" bits are ignored.
3562 If the input string is longer than needed, remaining characters
3564 are ignored.
3565 A "*" for the repeat count uses all characters of the input
3567 field. On unpacking, bits are converted to a string of "0"s
3568 and "1"s.
3569 · The "h" and "H" formats pack a string that many nybbles (4-bit
3571 groups, representable as hexadecimal digits, "0".."9" "a".."f")
3572 long.
3573 For each such format, pack() generates 4 bits of the result.
3575 With non-alphabetical characters, the result is based on the 4
3576 least-significant bits of the input character, i.e., on
3577 "ord($char)%16". In particular, characters "0" and "1"
3578 generate nybbles 0 and 1, as do bytes "\0" and "\1". For
3579 characters "a".."f" and "A".."F", the result is compatible with
3580 the usual hexadecimal digits, so that "a" and "A" both generate
3581 the nybble "0xa==10". Do not use any characters but these with
3582 this format.
3583 Starting from the beginning of the template to pack(), each
3585 pair of characters is converted to 1 character of output. With
3586 format "h", the first character of the pair determines the
3587 least-significant nybble of the output character; with format
3588 "H", it determines the most-significant nybble.
3589 If the length of the input string is not even, it behaves as if
3591 padded by a null character at the end. Similarly, "extra"
3592 nybbles are ignored during unpacking.
3593 If the input string is longer than needed, extra characters are
3595 ignored.
3596 A "*" for the repeat count uses all characters of the input
3598 field. For unpack(), nybbles are converted to a string of
3599 hexadecimal digits.
3600 · The "p" format packs a pointer to a null-terminated string.
3602 You are responsible for ensuring that the string is not a
3603 temporary value, as that could potentially get deallocated
3604 before you got around to using the packed result. The "P"
3605 format packs a pointer to a structure of the size indicated by
3606 the length. A null pointer is created if the corresponding
3607 value for "p" or "P" is "undef"; similarly with unpack(), where
3608 a null pointer unpacks into "undef".
3609 If your system has a strange pointer size--meaning a pointer is
3611 neither as big as an int nor as big as a long--it may not be
3612 possible to pack or unpack pointers in big- or little-endian
3613 byte order. Attempting to do so raises an exception.
3614 · The "/" template character allows packing and unpacking of a
3616 sequence of items where the packed structure contains a packed
3617 item count followed by the packed items themselves. This is
3618 useful when the structure you're unpacking has encoded the
3619 sizes or repeat counts for some of its fields within the
3620 structure itself as separate fields.
3621 For "pack", you write length-item"/"sequence-item, and the
3623 length-item describes how the length value is packed. Formats
3624 likely to be of most use are integer-packing ones like "n" for
3625 Java strings, "w" for ASN.1 or SNMP, and "N" for Sun XDR.
3626 For "pack", sequence-item may have a repeat count, in which
3628 case the minimum of that and the number of available items is
3629 used as the argument for length-item. If it has no repeat count
3630 or uses a '*', the number of available items is used.
3631 For "unpack", an internal stack of integer arguments unpacked
3633 so far is used. You write "/"sequence-item and the repeat count
3634 is obtained by popping off the last element from the stack. The
3635 sequence-item must not have a repeat count.
3636 If sequence-item refers to a string type ("A", "a", or "Z"),
3638 the length-item is the string length, not the number of
3639 strings. With an explicit repeat count for pack, the packed
3640 string is adjusted to that length. For example:
3641 unpack("W/a", "\04Gurusamy") gives ("Guru")
3643 unpack("a3/A A*", "007 Bond J ") gives (" Bond", "J")
3644 unpack("a3 x2 /A A*", "007: Bond, J.") gives ("Bond, J", ".")
3645 pack("n/a* w/a","hello,","world") gives "\000\006hello,\005world"
3647 pack("a/W2", ord("a") .. ord("z")) gives "2ab"
3648 The length-item is not returned explicitly from "unpack".
3650 Supplying a count to the length-item format letter is only
3652 useful with "A", "a", or "Z". Packing with a length-item of
3653 "a" or "Z" may introduce "\000" characters, which Perl does not
3654 regard as legal in numeric strings.
3655 · The integer types "s", "S", "l", and "L" may be followed by a
3657 "!" modifier to specify native shorts or longs. As shown in
3658 the example above, a bare "l" means exactly 32 bits, although
3659 the native "long" as seen by the local C compiler may be
3660 larger. This is mainly an issue on 64-bit platforms. You can
3661 see whether using "!" makes any difference this way:
3662 printf "format s is %d, s! is %d\n",
3664 length pack("s"), length pack("s!");
3665 printf "format l is %d, l! is %d\n",
3667 length pack("l"), length pack("l!");
3668 "i!" and "I!" are also allowed, but only for completeness'
3670 sake: they are identical to "i" and "I".
3671 The actual sizes (in bytes) of native shorts, ints, longs, and
3673 long longs on the platform where Perl was built are also
3674 available from the command line:
3675 $ perl -V:{short,int,long{,long}}size
3677 shortsize='2';
3678 intsize='4';
3679 longsize='4';
3680 longlongsize='8';
3681 or programmatically via the "Config" module:
3683 use Config;
3685 print $Config{shortsize}, "\n";
3686 print $Config{intsize}, "\n";
3687 print $Config{longsize}, "\n";
3688 print $Config{longlongsize}, "\n";
3689 $Config{longlongsize} is undefined on systems without long long
3691 support.
3692 · The integer formats "s", "S", "i", "I", "l", "L", "j", and "J"
3694 are inherently non-portable between processors and operating
3695 systems because they obey native byteorder and endianness. For
3696 example, a 4-byte integer 0x12345678 (305419896 decimal) would
3697 be ordered natively (arranged in and handled by the CPU
3698 registers) into bytes as
3699 0x12 0x34 0x56 0x78 # big-endian
3701 0x78 0x56 0x34 0x12 # little-endian
3702 Basically, Intel and VAX CPUs are little-endian, while
3704 everybody else, including Motorola m68k/88k, PPC, Sparc, HP PA,
3705 Power, and Cray, are big-endian. Alpha and MIPS can be either:
3706 Digital/Compaq used/uses them in little-endian mode, but
3707 SGI/Cray uses them in big-endian mode.
3708 The names big-endian and little-endian are comic references to
3710 the egg-eating habits of the little-endian Lilliputians and the
3711 big-endian Blefuscudians from the classic Jonathan Swift
3712 satire, Gulliver's Travels. This entered computer lingo via
3713 the paper "On Holy Wars and a Plea for Peace" by Danny Cohen,
3714 USC/ISI IEN 137, April 1, 1980.
3715 Some systems may have even weirder byte orders such as
3717 0x56 0x78 0x12 0x34
3719 0x34 0x12 0x78 0x56
3720 You can determine your system endianness with this incantation:
3722 printf("%#02x ", $_) for unpack("W*", pack L=>0x12345678);
3724 The byteorder on the platform where Perl was built is also
3726 available via Config:
3727 use Config;
3729 print "$Config{byteorder}\n";
3730 or from the command line:
3732 $ perl -V:byteorder
3734 Byteorders "1234" and "12345678" are little-endian; "4321" and
3736 "87654321" are big-endian.
3737 For portably packed integers, either use the formats "n", "N",
3739 "v", and "V" or else use the ">" and "<" modifiers described
3740 immediately below. See also perlport.
3741 · Starting with Perl 5.9.2, integer and floating-point formats,
3743 along with the "p" and "P" formats and "()" groups, may all be
3744 followed by the ">" or "<" endianness modifiers to respectively
3745 enforce big- or little-endian byte-order. These modifiers are
3746 especially useful given how "n", "N", "v" and "V" don't cover
3747 signed integers, 64-bit integers, or floating-point values.
3748 Here are some concerns to keep in mind when using endianness
3750 modifier:
3751 · Exchanging signed integers between different platforms
3753 works only when all platforms store them in the same
3754 format. Most platforms store signed integers in two's-
3755 complement notation, so usually this is not an issue.
3756 · The ">" or "<" modifiers can only be used on floating-point
3758 formats on big- or little-endian machines. Otherwise,
3759 attempting to use them raises an exception.
3760 · Forcing big- or little-endian byte-order on floating-point
3762 values for data exchange can work only if all platforms use
3763 the same binary representation such as IEEE floating-point.
3764 Even if all platforms are using IEEE, there may still be
3765 subtle differences. Being able to use ">" or "<" on
3766 floating-point values can be useful, but also dangerous if
3767 you don't know exactly what you're doing. It is not a
3768 general way to portably store floating-point values.
3769 · When using ">" or "<" on a "()" group, this affects all
3771 types inside the group that accept byte-order modifiers,
3772 including all subgroups. It is silently ignored for all
3773 other types. You are not allowed to override the byte-
3774 order within a group that already has a byte-order modifier
3775 suffix.
3776 · Real numbers (floats and doubles) are in native machine format
3778 only. Due to the multiplicity of floating-point formats and
3779 the lack of a standard "network" representation for them, no
3780 facility for interchange has been made. This means that packed
3781 floating-point data written on one machine may not be readable
3782 on another, even if both use IEEE floating-point arithmetic
3783 (because the endianness of the memory representation is not
3784 part of the IEEE spec). See also perlport.
3785 If you know exactly what you're doing, you can use the ">" or
3787 "<" modifiers to force big- or little-endian byte-order on
3788 floating-point values.
3789 Because Perl uses doubles (or long doubles, if configured)
3791 internally for all numeric calculation, converting from double
3792 into float and thence to double again loses precision, so
3793 "unpack("f", pack("f", $foo)") will not in general equal $foo.
3794 · Pack and unpack can operate in two modes: character mode ("C0"
3796 mode) where the packed string is processed per character, and
3797 UTF-8 mode ("U0" mode) where the packed string is processed in
3798 its UTF-8-encoded Unicode form on a byte-by-byte basis.
3799 Character mode is the default unless the format string starts
3800 with "U". You can always switch mode mid-format with an
3801 explicit "C0" or "U0" in the format. This mode remains in
3802 effect until the next mode change, or until the end of the "()"
3803 group it (directly) applies to.
3804 · You must yourself do any alignment or padding by inserting, for
3806 example, enough "x"es while packing. There is no way for
3807 pack() and unpack() to know where characters are going to or
3808 coming from, so they handle their output and input as flat
3809 sequences of characters.
3810 · A "()" group is a sub-TEMPLATE enclosed in parentheses. A
3812 group may take a repeat count either as postfix, or for
3813 unpack(), also via the "/" template character. Within each
3814 repetition of a group, positioning with "@" starts over at 0.
3815 Therefore, the result of
3816 pack("@1A((@2A)@3A)", qw[X Y Z])
3818 is the string "\0X\0\0YZ".
3820 · "x" and "X" accept the "!" modifier to act as alignment
3822 commands: they jump forward or back to the closest position
3823 aligned at a multiple of "count" characters. For example, to
3824 pack() or unpack() a C structure like
3825 struct {
3827 char c; /* one signed, 8-bit character */
3828 double d;
3829 char cc[2];
3830 }
3831 one may need to use the template "c x![d] d c[2]". This
3833 assumes that doubles must be aligned to the size of double.
3834 For alignment commands, a "count" of 0 is equivalent to a
3836 "count" of 1; both are no-ops.
3837 · "n", "N", "v" and "V" accept the "!" modifier to represent
3839 signed 16-/32-bit integers in big-/little-endian order. This
3840 is portable only when all platforms sharing packed data use the
3841 same binary representation for signed integers; for example,
3842 when all platforms use two's-complement representation.
3843 · Comments can be embedded in a TEMPLATE using "#" through the
3845 end of line. White space can separate pack codes from each
3846 other, but modifiers and repeat counts must follow immediately.
3847 Breaking complex templates into individual line-by-line
3848 components, suitably annotated, can do as much to improve
3849 legibility and maintainability of pack/unpack formats as "/x"
3850 can for complicated pattern matches.
3851 · If TEMPLATE requires more arguments that pack() is given,
3853 pack() assumes additional "" arguments. If TEMPLATE requires
3854 fewer arguments than given, extra arguments are ignored.
3855 Examples:
3857 $foo = pack("WWWW",65,66,67,68);
3859 # foo eq "ABCD"
3860 $foo = pack("W4",65,66,67,68);
3861 # same thing
3862 $foo = pack("W4",0x24b6,0x24b7,0x24b8,0x24b9);
3863 # same thing with Unicode circled letters.
3864 $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9);
3865 # same thing with Unicode circled letters. You don't get the UTF-8
3866 # bytes because the U at the start of the format caused a switch to
3867 # U0-mode, so the UTF-8 bytes get joined into characters
3868 $foo = pack("C0U4",0x24b6,0x24b7,0x24b8,0x24b9);
3869 # foo eq "\xe2\x92\xb6\xe2\x92\xb7\xe2\x92\xb8\xe2\x92\xb9"
3870 # This is the UTF-8 encoding of the string in the previous example
3871 $foo = pack("ccxxcc",65,66,67,68);
3873 # foo eq "AB\0\0CD"
3874 # NOTE: The examples above featuring "W" and "c" are true
3876 # only on ASCII and ASCII-derived systems such as ISO Latin 1
3877 # and UTF-8. On EBCDIC systems, the first example would be
3878 # $foo = pack("WWWW",193,194,195,196);
3879 $foo = pack("s2",1,2);
3881 # "\1\0\2\0" on little-endian
3882 # "\0\1\0\2" on big-endian
3883 $foo = pack("a4","abcd","x","y","z");
3885 # "abcd"
3886 $foo = pack("aaaa","abcd","x","y","z");
3888 # "axyz"
3889 $foo = pack("a14","abcdefg");
3891 # "abcdefg\0\0\0\0\0\0\0"
3892 $foo = pack("i9pl", gmtime);
3894 # a real struct tm (on my system anyway)
3895 $utmp_template = "Z8 Z8 Z16 L";
3897 $utmp = pack($utmp_template, @utmp1);
3898 # a struct utmp (BSDish)
3899 @utmp2 = unpack($utmp_template, $utmp);
3901 # "@utmp1" eq "@utmp2"
3902 sub bintodec {
3904 unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
3905 }
3906 $foo = pack('sx2l', 12, 34);
3908 # short 12, two zero bytes padding, long 34
3909 $bar = pack('s@4l', 12, 34);
3910 # short 12, zero fill to position 4, long 34
3911 # $foo eq $bar
3912 $baz = pack('s.l', 12, 4, 34);
3913 # short 12, zero fill to position 4, long 34
3914 $foo = pack('nN', 42, 4711);
3916 # pack big-endian 16- and 32-bit unsigned integers
3917 $foo = pack('S>L>', 42, 4711);
3918 # exactly the same
3919 $foo = pack('s<l<', -42, 4711);
3920 # pack little-endian 16- and 32-bit signed integers
3921 $foo = pack('(sl)<', -42, 4711);
3922 # exactly the same
3923 The same template may generally also be used in unpack().
3925 package NAMESPACE VERSION
3927 package NAMESPACE
3928 Declares the compilation unit as being in the given namespace. The
3929 scope of the package declaration is from the declaration itself
3930 through the end of the enclosing block, file, or eval (the same as
3931 the "my" operator). All further unqualified dynamic identifiers
3932 will be in this namespace. A package statement affects dynamic
3933 variables only, including those you've used "local" on, but not
3934 lexical variables, which are created with "my" (or "our" (or
3935 "state")). Typically it would be the first declaration in a file
3936 included by "require" or "use". You can switch into a package in
3937 more than one place, since this only determines which default
3938 symbol table the compiler uses for the rest of that block. You can
3939 refer to identifiers in other packages than the current one by
3940 prefixing the identifier with the package name and a double colon,
3941 as in $SomePack::var or "ThatPack::INPUT_HANDLE". If package name
3942 is omitted, the "main" package as assumed. That is, $::sail is
3943 equivalent to $main::sail (as well as to "$main'sail", still seen
3944 in ancient code, mostly from Perl 4).
3945 If VERSION is provided, "package" sets the $VERSION variable in the
3947 given namespace to a version object with the VERSION provided.
3948 VERSION must be a "strict" style version number as defined by the
3949 version module: a positive decimal number (integer or decimal-
3950 fraction) without exponentiation or else a dotted-decimal v-string
3951 with a leading 'v' character and at least three components. You
3952 should set $VERSION only once per package.
3953 See "Packages" in perlmod for more information about packages,
3955 modules, and classes. See perlsub for other scoping issues.
3956 pipe READHANDLE,WRITEHANDLE
3958 Opens a pair of connected pipes like the corresponding system call.
3959 Note that if you set up a loop of piped processes, deadlock can
3960 occur unless you are very careful. In addition, note that Perl's
3961 pipes use IO buffering, so you may need to set $| to flush your
3962 WRITEHANDLE after each command, depending on the application.
3963 See IPC::Open2, IPC::Open3, and "Bidirectional Communication" in
3965 perlipc for examples of such things.
3966 On systems that support a close-on-exec flag on files, that flag is
3968 set on all newly opened file descriptors whose "fileno"s are higher
3969 than the current value of $^F (by default 2 for "STDERR"). See
3970 "$^F" in perlvar.
3971 pop ARRAY
3973 pop Pops and returns the last value of the array, shortening the array
3974 by one element.
3975 Returns the undefined value if the array is empty, although this
3977 may also happen at other times. If ARRAY is omitted, pops the
3978 @ARGV array in the main program, but the @_ array in subroutines,
3979 just like "shift".
3980 pos SCALAR
3982 pos Returns the offset of where the last "m//g" search left off for the
3983 variable in question ($_ is used when the variable is not
3984 specified). Note that 0 is a valid match offset. "undef"
3985 indicates that the search position is reset (usually due to match
3986 failure, but can also be because no match has yet been run on the
3987 scalar). "pos" directly accesses the location used by the regexp
3988 engine to store the offset, so assigning to "pos" will change that
3989 offset, and so will also influence the "\G" zero-width assertion in
3990 regular expressions. Because a failed "m//gc" match doesn't reset
3991 the offset, the return from "pos" won't change either in this case.
3992 See perlre and perlop.
3993 print FILEHANDLE LIST
3995 print LIST
3996 print
3997 Prints a string or a list of strings. Returns true if successful.
3998 FILEHANDLE may be a scalar variable containing the name of or a
3999 reference to the filehandle, thus introducing one level of
4000 indirection. (NOTE: If FILEHANDLE is a variable and the next token
4001 is a term, it may be misinterpreted as an operator unless you
4002 interpose a "+" or put parentheses around the arguments.) If
4003 FILEHANDLE is omitted, prints to standard output by default, or to
4004 the last selected output channel; see "select". If LIST is also
4005 omitted, prints $_ to the currently selected output handle. To set
4006 the default output handle to something other than STDOUT use the
4007 select operation. The current value of $, (if any) is printed
4008 between each LIST item. The current value of "$\" (if any) is
4009 printed after the entire LIST has been printed. Because print
4010 takes a LIST, anything in the LIST is evaluated in list context,
4011 and any subroutine that you call will have one or more of its
4012 expressions evaluated in list context. Also be careful not to
4013 follow the print keyword with a left parenthesis unless you want
4014 the corresponding right parenthesis to terminate the arguments to
4015 the print; put parentheses around all the arguments (or interpose a
4016 "+", but that doesn't look as good).
4017 Note that if you're storing FILEHANDLEs in an array, or if you're
4019 using any other expression more complex than a scalar variable to
4020 retrieve it, you will have to use a block returning the filehandle
4021 value instead:
4022 print { $files[$i] } "stuff\n";
4024 print { $OK ? STDOUT : STDERR } "stuff\n";
4025 Printing to a closed pipe or socket will generate a SIGPIPE signal.
4027 See perlipc for more on signal handling.
4028 printf FILEHANDLE FORMAT, LIST
4030 printf FORMAT, LIST
4031 Equivalent to "print FILEHANDLE sprintf(FORMAT, LIST)", except that
4032 "$\" (the output record separator) is not appended. The first
4033 argument of the list will be interpreted as the "printf" format.
4034 See "sprintf" for an explanation of the format argument. If "use
4035 locale" is in effect, and POSIX::setlocale() has been called, the
4036 character used for the decimal separator in formatted floating-
4037 point numbers is affected by the LC_NUMERIC locale. See perllocale
4038 and POSIX.
4039 Don't fall into the trap of using a "printf" when a simple "print"
4041 would do. The "print" is more efficient and less error prone.
4042 prototype FUNCTION
4044 Returns the prototype of a function as a string (or "undef" if the
4045 function has no prototype). FUNCTION is a reference to, or the
4046 name of, the function whose prototype you want to retrieve.
4047 If FUNCTION is a string starting with "CORE::", the rest is taken
4049 as a name for a Perl builtin. If the builtin is not overridable
4050 (such as "qw//") or if its arguments cannot be adequately expressed
4051 by a prototype (such as "system"), prototype() returns "undef",
4052 because the builtin does not really behave like a Perl function.
4053 Otherwise, the string describing the equivalent prototype is
4054 returned.
4055 push ARRAY,LIST
4057 Treats ARRAY as a stack, and pushes the values of LIST onto the end
4058 of ARRAY. The length of ARRAY increases by the length of LIST.
4059 Has the same effect as
4060 for $value (LIST) {
4062 $ARRAY[++$#ARRAY] = $value;
4063 }
4064 but is more efficient. Returns the number of elements in the array
4066 following the completed "push".
4067 q/STRING/
4069 qq/STRING/
4070 qx/STRING/
4071 qw/STRING/
4072 Generalized quotes. See "Quote-Like Operators" in perlop.
4073 qr/STRING/
4075 Regexp-like quote. See "Regexp Quote-Like Operators" in perlop.
4076 quotemeta EXPR
4078 quotemeta
4079 Returns the value of EXPR with all non-"word" characters
4080 backslashed. (That is, all characters not matching
4081 "/[A-Za-z_0-9]/" will be preceded by a backslash in the returned
4082 string, regardless of any locale settings.) This is the internal
4083 function implementing the "\Q" escape in double-quoted strings.
4084 If EXPR is omitted, uses $_.
4086 quotemeta (and "\Q" ... "\E") are useful when interpolating strings
4088 into regular expressions, because by default an interpolated
4089 variable will be considered a mini-regular expression. For example:
4090 my $sentence = 'The quick brown fox jumped over the lazy dog';
4092 my $substring = 'quick.*?fox';
4093 $sentence =~ s{$substring}{big bad wolf};
4094 Will cause $sentence to become 'The big bad wolf jumped over...'.
4096 On the other hand:
4098 my $sentence = 'The quick brown fox jumped over the lazy dog';
4100 my $substring = 'quick.*?fox';
4101 $sentence =~ s{\Q$substring\E}{big bad wolf};
4102 Or:
4104 my $sentence = 'The quick brown fox jumped over the lazy dog';
4106 my $substring = 'quick.*?fox';
4107 my $quoted_substring = quotemeta($substring);
4108 $sentence =~ s{$quoted_substring}{big bad wolf};
4109 Will both leave the sentence as is. Normally, when accepting string
4111 input from the user, quotemeta() or "\Q" must be used.
4112 rand EXPR
4114 rand
4115 Returns a random fractional number greater than or equal to 0 and
4116 less than the value of EXPR. (EXPR should be positive.) If EXPR
4117 is omitted, the value 1 is used. Currently EXPR with the value 0
4118 is also special-cased as 1 (this was undocumented before Perl 5.8.0
4119 and is subject to change in future versions of Perl).
4120 Automatically calls "srand" unless "srand" has already been called.
4121 See also "srand".
4122 Apply "int()" to the value returned by "rand()" if you want random
4124 integers instead of random fractional numbers. For example,
4125 int(rand(10))
4127 returns a random integer between 0 and 9, inclusive.
4129 (Note: If your rand function consistently returns numbers that are
4131 too large or too small, then your version of Perl was probably
4132 compiled with the wrong number of RANDBITS.)
4133 "rand()" is not cryptographically secure. You should not rely on
4135 it in security-sensitive situations. As of this writing, a number
4136 of third-party CPAN modules offer random number generators intended
4137 by their authors to be cryptographically secure, including:
4138 Math::Random::Secure, Math::Random::MT::Perl, and
4139 Math::TrulyRandom.
4140 read FILEHANDLE,SCALAR,LENGTH,OFFSET
4142 read FILEHANDLE,SCALAR,LENGTH
4143 Attempts to read LENGTH characters of data into variable SCALAR
4144 from the specified FILEHANDLE. Returns the number of characters
4145 actually read, 0 at end of file, or undef if there was an error (in
4146 the latter case $! is also set). SCALAR will be grown or shrunk so
4147 that the last character actually read is the last character of the
4148 scalar after the read.
4149 An OFFSET may be specified to place the read data at some place in
4151 the string other than the beginning. A negative OFFSET specifies
4152 placement at that many characters counting backwards from the end
4153 of the string. A positive OFFSET greater than the length of SCALAR
4154 results in the string being padded to the required size with "\0"
4155 bytes before the result of the read is appended.
4156 The call is implemented in terms of either Perl's or your system's
4158 native fread(3) library function. To get a true read(2) system
4159 call, see "sysread".
4160 Note the characters: depending on the status of the filehandle,
4162 either (8-bit) bytes or characters are read. By default all
4163 filehandles operate on bytes, but for example if the filehandle has
4164 been opened with the ":utf8" I/O layer (see "open", and the "open"
4165 pragma, open), the I/O will operate on UTF-8 encoded Unicode
4166 characters, not bytes. Similarly for the ":encoding" pragma: in
4167 that case pretty much any characters can be read.
4168 readdir DIRHANDLE
4170 Returns the next directory entry for a directory opened by
4171 "opendir". If used in list context, returns all the rest of the
4172 entries in the directory. If there are no more entries, returns
4173 the undefined value in scalar context and the empty list in list
4174 context.
4175 If you're planning to filetest the return values out of a
4177 "readdir", you'd better prepend the directory in question.
4178 Otherwise, because we didn't "chdir" there, it would have been
4179 testing the wrong file.
4180 opendir(my $dh, $some_dir) || die "can't opendir $some_dir: $!";
4182 @dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh);
4183 closedir $dh;
4184 As of Perl 5.11.2 you can use a bare "readdir" in a "while" loop,
4186 which will set $_ on every iteration.
4187 opendir(my $dh, $some_dir) || die;
4189 while(readdir $dh) {
4190 print "$some_dir/$_\n";
4191 }
4192 closedir $dh;
4193 readline EXPR
4195 readline
4196 Reads from the filehandle whose typeglob is contained in EXPR (or
4197 from *ARGV if EXPR is not provided). In scalar context, each call
4198 reads and returns the next line until end-of-file is reached,
4199 whereupon the subsequent call returns "undef". In list context,
4200 reads until end-of-file is reached and returns a list of lines.
4201 Note that the notion of "line" used here is whatever you may have
4202 defined with $/ or $INPUT_RECORD_SEPARATOR). See "$/" in perlvar.
4203 When $/ is set to "undef", when "readline" is in scalar context
4205 (i.e., file slurp mode), and when an empty file is read, it returns
4206 '' the first time, followed by "undef" subsequently.
4207 This is the internal function implementing the "<EXPR>" operator,
4209 but you can use it directly. The "<EXPR>" operator is discussed in
4210 more detail in "I/O Operators" in perlop.
4211 $line = <STDIN>;
4213 $line = readline(*STDIN); # same thing
4214 If "readline" encounters an operating system error, $! will be set
4216 with the corresponding error message. It can be helpful to check
4217 $! when you are reading from filehandles you don't trust, such as a
4218 tty or a socket. The following example uses the operator form of
4219 "readline" and dies if the result is not defined.
4220 while ( ! eof($fh) ) {
4222 defined( $_ = <$fh> ) or die "readline failed: $!";
4223 ...
4224 }
4225 Note that you have can't handle "readline" errors that way with the
4227 "ARGV" filehandle. In that case, you have to open each element of
4228 @ARGV yourself since "eof" handles "ARGV" differently.
4229 foreach my $arg (@ARGV) {
4231 open(my $fh, $arg) or warn "Can't open $arg: $!";
4232 while ( ! eof($fh) ) {
4234 defined( $_ = <$fh> )
4235 or die "readline failed for $arg: $!";
4236 ...
4237 }
4238 }
4239 readlink EXPR
4241 readlink
4242 Returns the value of a symbolic link, if symbolic links are
4243 implemented. If not, raises an exception. If there is a system
4244 error, returns the undefined value and sets $! (errno). If EXPR is
4245 omitted, uses $_.
4246 readpipe EXPR
4248 readpipe
4249 EXPR is executed as a system command. The collected standard
4250 output of the command is returned. In scalar context, it comes
4251 back as a single (potentially multi-line) string. In list context,
4252 returns a list of lines (however you've defined lines with $/ or
4253 $INPUT_RECORD_SEPARATOR). This is the internal function
4254 implementing the "qx/EXPR/" operator, but you can use it directly.
4255 The "qx/EXPR/" operator is discussed in more detail in "I/O
4256 Operators" in perlop. If EXPR is omitted, uses $_.
4257 recv SOCKET,SCALAR,LENGTH,FLAGS
4259 Receives a message on a socket. Attempts to receive LENGTH
4260 characters of data into variable SCALAR from the specified SOCKET
4261 filehandle. SCALAR will be grown or shrunk to the length actually
4262 read. Takes the same flags as the system call of the same name.
4263 Returns the address of the sender if SOCKET's protocol supports
4264 this; returns an empty string otherwise. If there's an error,
4265 returns the undefined value. This call is actually implemented in
4266 terms of recvfrom(2) system call. See "UDP: Message Passing" in
4267 perlipc for examples.
4268 Note the characters: depending on the status of the socket, either
4270 (8-bit) bytes or characters are received. By default all sockets
4271 operate on bytes, but for example if the socket has been changed
4272 using binmode() to operate with the ":encoding(utf8)" I/O layer
4273 (see the "open" pragma, open), the I/O will operate on UTF-8
4274 encoded Unicode characters, not bytes. Similarly for the
4275 ":encoding" pragma: in that case pretty much any characters can be
4276 read.
4277 redo LABEL
4279 redo
4280 The "redo" command restarts the loop block without evaluating the
4281 conditional again. The "continue" block, if any, is not executed.
4282 If the LABEL is omitted, the command refers to the innermost
4283 enclosing loop. Programs that want to lie to themselves about what
4284 was just input normally use this command:
4285 # a simpleminded Pascal comment stripper
4287 # (warning: assumes no { or } in strings)
4288 LINE: while (<STDIN>) {
4289 while (s|({.*}.*){.*}|$1 |) {}
4290 s|{.*}| |;
4291 if (s|{.*| |) {
4292 $front = $_;
4293 while (<STDIN>) {
4294 if (/}/) { # end of comment?
4295 s|^|$front\{|;
4296 redo LINE;
4297 }
4298 }
4299 }
4300 print;
4301 }
4302 "redo" cannot be used to retry a block that returns a value such as
4304 "eval {}", "sub {}" or "do {}", and should not be used to exit a
4305 grep() or map() operation.
4306 Note that a block by itself is semantically identical to a loop
4308 that executes once. Thus "redo" inside such a block will
4309 effectively turn it into a looping construct.
4310 See also "continue" for an illustration of how "last", "next", and
4312 "redo" work.
4313 ref EXPR
4315 ref Returns a non-empty string if EXPR is a reference, the empty string
4316 otherwise. If EXPR is not specified, $_ will be used. The value
4317 returned depends on the type of thing the reference is a reference
4318 to. Builtin types include:
4319 SCALAR
4321 ARRAY
4322 HASH
4323 CODE
4324 REF
4325 GLOB
4326 LVALUE
4327 FORMAT
4328 IO
4329 VSTRING
4330 Regexp
4331 If the referenced object has been blessed into a package, then that
4333 package name is returned instead. You can think of "ref" as a
4334 "typeof" operator.
4335 if (ref($r) eq "HASH") {
4337 print "r is a reference to a hash.\n";
4338 }
4339 unless (ref($r)) {
4340 print "r is not a reference at all.\n";
4341 }
4342 The return value "LVALUE" indicates a reference to an lvalue that
4344 is not a variable. You get this from taking the reference of
4345 function calls like "pos()" or "substr()". "VSTRING" is returned if
4346 the reference points to a version string.
4347 The result "Regexp" indicates that the argument is a regular
4349 expression resulting from "qr//".
4350 See also perlref.
4352 rename OLDNAME,NEWNAME
4354 Changes the name of a file; an existing file NEWNAME will be
4355 clobbered. Returns true for success, false otherwise.
4356 Behavior of this function varies wildly depending on your system
4358 implementation. For example, it will usually not work across file
4359 system boundaries, even though the system mv command sometimes
4360 compensates for this. Other restrictions include whether it works
4361 on directories, open files, or pre-existing files. Check perlport
4362 and either the rename(2) manpage or equivalent system documentation
4363 for details.
4364 For a platform independent "move" function look at the File::Copy
4366 module.
4367 require VERSION
4369 require EXPR
4370 require
4371 Demands a version of Perl specified by VERSION, or demands some
4372 semantics specified by EXPR or by $_ if EXPR is not supplied.
4373 VERSION may be either a numeric argument such as 5.006, which will
4375 be compared to $], or a literal of the form v5.6.1, which will be
4376 compared to $^V (aka $PERL_VERSION). An exception is raised if
4377 VERSION is greater than the version of the current Perl
4378 interpreter. Compare with "use", which can do a similar check at
4379 compile time.
4380 Specifying VERSION as a literal of the form v5.6.1 should generally
4382 be avoided, because it leads to misleading error messages under
4383 earlier versions of Perl that do not support this syntax. The
4384 equivalent numeric version should be used instead.
4385 require v5.6.1; # run time version check
4387 require 5.6.1; # ditto
4388 require 5.006_001; # ditto; preferred for backwards compatibility
4389 Otherwise, "require" demands that a library file be included if it
4391 hasn't already been included. The file is included via the do-FILE
4392 mechanism, which is essentially just a variety of "eval" with the
4393 caveat that lexical variables in the invoking script will be
4394 invisible to the included code. Has semantics similar to the
4395 following subroutine:
4396 sub require {
4398 my ($filename) = @_;
4399 if (exists $INC{$filename}) {
4400 return 1 if $INC{$filename};
4401 die "Compilation failed in require";
4402 }
4403 my ($realfilename,$result);
4404 ITER: {
4405 foreach $prefix (@INC) {
4406 $realfilename = "$prefix/$filename";
4407 if (-f $realfilename) {
4408 $INC{$filename} = $realfilename;
4409 $result = do $realfilename;
4410 last ITER;
4411 }
4412 }
4413 die "Can't find $filename in \@INC";
4414 }
4415 if ($@) {
4416 $INC{$filename} = undef;
4417 die $@;
4418 } elsif (!$result) {
4419 delete $INC{$filename};
4420 die "$filename did not return true value";
4421 } else {
4422 return $result;
4423 }
4424 }
4425 Note that the file will not be included twice under the same
4427 specified name.
4428 The file must return true as the last statement to indicate
4430 successful execution of any initialization code, so it's customary
4431 to end such a file with "1;" unless you're sure it'll return true
4432 otherwise. But it's better just to put the "1;", in case you add
4433 more statements.
4434 If EXPR is a bareword, the require assumes a ".pm" extension and
4436 replaces "::" with "/" in the filename for you, to make it easy to
4437 load standard modules. This form of loading of modules does not
4438 risk altering your namespace.
4439 In other words, if you try this:
4441 require Foo::Bar; # a splendid bareword
4443 The require function will actually look for the "Foo/Bar.pm" file
4445 in the directories specified in the @INC array.
4446 But if you try this:
4448 $class = 'Foo::Bar';
4450 require $class; # $class is not a bareword
4451 #or
4452 require "Foo::Bar"; # not a bareword because of the ""
4453 The require function will look for the "Foo::Bar" file in the @INC
4455 array and will complain about not finding "Foo::Bar" there. In
4456 this case you can do:
4457 eval "require $class";
4459 Now that you understand how "require" looks for files with a
4461 bareword argument, there is a little extra functionality going on
4462 behind the scenes. Before "require" looks for a ".pm" extension,
4463 it will first look for a similar filename with a ".pmc" extension.
4464 If this file is found, it will be loaded in place of any file
4465 ending in a ".pm" extension.
4466 You can also insert hooks into the import facility, by putting Perl
4468 code directly into the @INC array. There are three forms of hooks:
4469 subroutine references, array references and blessed objects.
4470 Subroutine references are the simplest case. When the inclusion
4472 system walks through @INC and encounters a subroutine, this
4473 subroutine gets called with two parameters, the first a reference
4474 to itself, and the second the name of the file to be included
4475 (e.g., "Foo/Bar.pm"). The subroutine should return either nothing
4476 or else a list of up to three values in the following order:
4477 1. A filehandle, from which the file will be read.
4479 2. A reference to a subroutine. If there is no filehandle
4481 (previous item), then this subroutine is expected to generate
4482 one line of source code per call, writing the line into $_ and
4483 returning 1, then returning 0 at end of file. If there is a
4484 filehandle, then the subroutine will be called to act as a
4485 simple source filter, with the line as read in $_. Again,
4486 return 1 for each valid line, and 0 after all lines have been
4487 returned.
4488 3. Optional state for the subroutine. The state is passed in as
4490 $_[1]. A reference to the subroutine itself is passed in as
4491 $_[0].
4492 If an empty list, "undef", or nothing that matches the first 3
4494 values above is returned, then "require" looks at the remaining
4495 elements of @INC. Note that this filehandle must be a real
4496 filehandle (strictly a typeglob or reference to a typeglob, blessed
4497 or unblessed); tied filehandles will be ignored and return value
4498 processing will stop there.
4499 If the hook is an array reference, its first element must be a
4501 subroutine reference. This subroutine is called as above, but the
4502 first parameter is the array reference. This lets you indirectly
4503 pass arguments to the subroutine.
4504 In other words, you can write:
4506 push @INC, \&my_sub;
4508 sub my_sub {
4509 my ($coderef, $filename) = @_; # $coderef is \&my_sub
4510 ...
4511 }
4512 or:
4514 push @INC, [ \&my_sub, $x, $y, ... ];
4516 sub my_sub {
4517 my ($arrayref, $filename) = @_;
4518 # Retrieve $x, $y, ...
4519 my @parameters = @$arrayref[1..$#$arrayref];
4520 ...
4521 }
4522 If the hook is an object, it must provide an INC method that will
4524 be called as above, the first parameter being the object itself.
4525 (Note that you must fully qualify the sub's name, as unqualified
4526 "INC" is always forced into package "main".) Here is a typical
4527 code layout:
4528 # In Foo.pm
4530 package Foo;
4531 sub new { ... }
4532 sub Foo::INC {
4533 my ($self, $filename) = @_;
4534 ...
4535 }
4536 # In the main program
4538 push @INC, Foo->new(...);
4539 These hooks are also permitted to set the %INC entry corresponding
4541 to the files they have loaded. See "%INC" in perlvar.
4542 For a yet-more-powerful import facility, see "use" and perlmod.
4544 reset EXPR
4546 reset
4547 Generally used in a "continue" block at the end of a loop to clear
4548 variables and reset "??" searches so that they work again. The
4549 expression is interpreted as a list of single characters (hyphens
4550 allowed for ranges). All variables and arrays beginning with one
4551 of those letters are reset to their pristine state. If the
4552 expression is omitted, one-match searches ("?pattern?") are reset
4553 to match again. Only resets variables or searches in the current
4554 package. Always returns 1. Examples:
4555 reset 'X'; # reset all X variables
4557 reset 'a-z'; # reset lower case variables
4558 reset; # just reset ?one-time? searches
4559 Resetting "A-Z" is not recommended because you'll wipe out your
4561 @ARGV and @INC arrays and your %ENV hash. Resets only package
4562 variables; lexical variables are unaffected, but they clean
4563 themselves up on scope exit anyway, so you'll probably want to use
4564 them instead. See "my".
4565 return EXPR
4567 return
4568 Returns from a subroutine, "eval", or "do FILE" with the value
4569 given in EXPR. Evaluation of EXPR may be in list, scalar, or void
4570 context, depending on how the return value will be used, and the
4571 context may vary from one execution to the next (see "wantarray").
4572 If no EXPR is given, returns an empty list in list context, the
4573 undefined value in scalar context, and (of course) nothing at all
4574 in void context.
4575 (In the absence of an explicit "return", a subroutine, eval, or do
4577 FILE automatically returns the value of the last expression
4578 evaluated.)
4579 reverse LIST
4581 In list context, returns a list value consisting of the elements of
4582 LIST in the opposite order. In scalar context, concatenates the
4583 elements of LIST and returns a string value with all characters in
4584 the opposite order.
4585 print join(", ", reverse "world", "Hello"); # Hello, world
4587 print scalar reverse "dlrow ,", "olleH"; # Hello, world
4589 Used without arguments in scalar context, reverse() reverses $_.
4591 $_ = "dlrow ,olleH";
4593 print reverse; # No output, list context
4594 print scalar reverse; # Hello, world
4595 Note that reversing an array to itself (as in "@a = reverse @a")
4597 will preserve non-existent elements whenever possible, i.e., for
4598 non magical arrays or tied arrays with "EXISTS" and "DELETE"
4599 methods.
4600 This operator is also handy for inverting a hash, although there
4602 are some caveats. If a value is duplicated in the original hash,
4603 only one of those can be represented as a key in the inverted hash.
4604 Also, this has to unwind one hash and build a whole new one, which
4605 may take some time on a large hash, such as from a DBM file.
4606 %by_name = reverse %by_address; # Invert the hash
4608 rewinddir DIRHANDLE
4610 Sets the current position to the beginning of the directory for the
4611 "readdir" routine on DIRHANDLE.
4612 rindex STR,SUBSTR,POSITION
4614 rindex STR,SUBSTR
4615 Works just like index() except that it returns the position of the
4616 last occurrence of SUBSTR in STR. If POSITION is specified,
4617 returns the last occurrence beginning at or before that position.
4618 rmdir FILENAME
4620 rmdir
4621 Deletes the directory specified by FILENAME if that directory is
4622 empty. If it succeeds it returns true, otherwise it returns false
4623 and sets $! (errno). If FILENAME is omitted, uses $_.
4624 To remove a directory tree recursively ("rm -rf" on Unix) look at
4626 the "rmtree" function of the File::Path module.
4627 s///
4629 The substitution operator. See "Regexp Quote-Like Operators" in
4630 perlop.
4631 say FILEHANDLE LIST
4633 say LIST
4634 say Just like "print", but implicitly appends a newline. "say LIST" is
4635 simply an abbreviation for "{ local $\ = "\n"; print LIST }".
4636 This keyword is available only when the "say" feature is enabled:
4638 see feature.
4639 scalar EXPR
4641 Forces EXPR to be interpreted in scalar context and returns the
4642 value of EXPR.
4643 @counts = ( scalar @a, scalar @b, scalar @c );
4645 There is no equivalent operator to force an expression to be
4647 interpolated in list context because in practice, this is never
4648 needed. If you really wanted to do so, however, you could use the
4649 construction "@{[ (some expression) ]}", but usually a simple
4650 "(some expression)" suffices.
4651 Because "scalar" is a unary operator, if you accidentally use for
4653 EXPR a parenthesized list, this behaves as a scalar comma
4654 expression, evaluating all but the last element in void context and
4655 returning the final element evaluated in scalar context. This is
4656 seldom what you want.
4657 The following single statement:
4659 print uc(scalar(&foo,$bar)),$baz;
4661 is the moral equivalent of these two:
4663 &foo;
4665 print(uc($bar),$baz);
4666 See perlop for more details on unary operators and the comma
4668 operator.
4669 seek FILEHANDLE,POSITION,WHENCE
4671 Sets FILEHANDLE's position, just like the "fseek" call of "stdio".
4672 FILEHANDLE may be an expression whose value gives the name of the
4673 filehandle. The values for WHENCE are 0 to set the new position in
4674 bytes to POSITION, 1 to set it to the current position plus
4675 POSITION, and 2 to set it to EOF plus POSITION (typically
4676 negative). For WHENCE you may use the constants "SEEK_SET",
4677 "SEEK_CUR", and "SEEK_END" (start of the file, current position,
4678 end of the file) from the Fcntl module. Returns 1 on success, 0
4679 otherwise.
4680 Note the in bytes: even if the filehandle has been set to operate
4682 on characters (for example by using the ":encoding(utf8)" open
4683 layer), tell() will return byte offsets, not character offsets
4684 (because implementing that would render seek() and tell() rather
4685 slow).
4686 If you want to position the file for "sysread" or "syswrite", don't
4688 use "seek", because buffering makes its effect on the file's read-
4689 write position unpredictable and non-portable. Use "sysseek"
4690 instead.
4691 Due to the rules and rigors of ANSI C, on some systems you have to
4693 do a seek whenever you switch between reading and writing. Amongst
4694 other things, this may have the effect of calling stdio's
4695 clearerr(3). A WHENCE of 1 ("SEEK_CUR") is useful for not moving
4696 the file position:
4697 seek(TEST,0,1);
4699 This is also useful for applications emulating "tail -f". Once you
4701 hit EOF on your read and then sleep for a while, you (probably)
4702 have to stick in a dummy seek() to reset things. The "seek"
4703 doesn't change the position, but it does clear the end-of-file
4704 condition on the handle, so that the next "<FILE>" makes Perl try
4705 again to read something. (We hope.)
4706 If that doesn't work (some I/O implementations are particularly
4708 cantankerous), you might need something like this:
4709 for (;;) {
4711 for ($curpos = tell(FILE); $_ = <FILE>;
4712 $curpos = tell(FILE)) {
4713 # search for some stuff and put it into files
4714 }
4715 sleep($for_a_while);
4716 seek(FILE, $curpos, 0);
4717 }
4718 seekdir DIRHANDLE,POS
4720 Sets the current position for the "readdir" routine on DIRHANDLE.
4721 POS must be a value returned by "telldir". "seekdir" also has the
4722 same caveats about possible directory compaction as the
4723 corresponding system library routine.
4724 select FILEHANDLE
4726 select
4727 Returns the currently selected filehandle. If FILEHANDLE is
4728 supplied, sets the new current default filehandle for output. This
4729 has two effects: first, a "write" or a "print" without a filehandle
4730 will default to this FILEHANDLE. Second, references to variables
4731 related to output will refer to this output channel. For example,
4732 if you have to set the top of form format for more than one output
4733 channel, you might do the following:
4734 select(REPORT1);
4736 $^ = 'report1_top';
4737 select(REPORT2);
4738 $^ = 'report2_top';
4739 FILEHANDLE may be an expression whose value gives the name of the
4741 actual filehandle. Thus:
4742 $oldfh = select(STDERR); $| = 1; select($oldfh);
4744 Some programmers may prefer to think of filehandles as objects with
4746 methods, preferring to write the last example as:
4747 use IO::Handle;
4749 STDERR->autoflush(1);
4750 select RBITS,WBITS,EBITS,TIMEOUT
4752 This calls the select(2) syscall with the bit masks specified,
4753 which can be constructed using "fileno" and "vec", along these
4754 lines:
4755 $rin = $win = $ein = '';
4757 vec($rin,fileno(STDIN),1) = 1;
4758 vec($win,fileno(STDOUT),1) = 1;
4759 $ein = $rin | $win;
4760 If you want to select on many filehandles, you may wish to write a
4762 subroutine like this:
4763 sub fhbits {
4765 my(@fhlist) = split(' ',$_[0]);
4766 my($bits);
4767 for (@fhlist) {
4768 vec($bits,fileno($_),1) = 1;
4769 }
4770 $bits;
4771 }
4772 $rin = fhbits('STDIN TTY SOCK');
4773 The usual idiom is:
4775 ($nfound,$timeleft) =
4777 select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
4778 or to block until something becomes ready just do this
4780 $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
4782 Most systems do not bother to return anything useful in $timeleft,
4784 so calling select() in scalar context just returns $nfound.
4785 Any of the bit masks can also be undef. The timeout, if specified,
4787 is in seconds, which may be fractional. Note: not all
4788 implementations are capable of returning the $timeleft. If not,
4789 they always return $timeleft equal to the supplied $timeout.
4790 You can effect a sleep of 250 milliseconds this way:
4792 select(undef, undef, undef, 0.25);
4794 Note that whether "select" gets restarted after signals (say,
4796 SIGALRM) is implementation-dependent. See also perlport for notes
4797 on the portability of "select".
4798 On error, "select" behaves like select(2): it returns -1 and sets
4800 $!.
4801 On some Unixes, select(2) may report a socket file descriptor as
4803 "ready for reading" when no data is available, and thus a
4804 subsequent read blocks. This can be avoided if you always use
4805 O_NONBLOCK on the socket. See select(2) and fcntl(2) for further
4806 details.
4807 WARNING: One should not attempt to mix buffered I/O (like "read" or
4809 <FH>) with "select", except as permitted by POSIX, and even then
4810 only on POSIX systems. You have to use "sysread" instead.
4811 semctl ID,SEMNUM,CMD,ARG
4813 Calls the System V IPC function semctl(2). You'll probably have to
4814 say
4815 use IPC::SysV;
4817 first to get the correct constant definitions. If CMD is IPC_STAT
4819 or GETALL, then ARG must be a variable that will hold the returned
4820 semid_ds structure or semaphore value array. Returns like "ioctl":
4821 the undefined value for error, ""0 but true"" for zero, or the
4822 actual return value otherwise. The ARG must consist of a vector of
4823 native short integers, which may be created with
4824 "pack("s!",(0)x$nsem)". See also "SysV IPC" in perlipc,
4825 "IPC::SysV", "IPC::Semaphore" documentation.
4826 semget KEY,NSEMS,FLAGS
4828 Calls the System V IPC function semget(2). Returns the semaphore
4829 id, or the undefined value if there is an error. See also "SysV
4830 IPC" in perlipc, "IPC::SysV", "IPC::SysV::Semaphore" documentation.
4831 semop KEY,OPSTRING
4833 Calls the System V IPC function semop(2) for semaphore operations
4834 such as signalling and waiting. OPSTRING must be a packed array of
4835 semop structures. Each semop structure can be generated with
4836 "pack("s!3", $semnum, $semop, $semflag)". The length of OPSTRING
4837 implies the number of semaphore operations. Returns true if
4838 successful, or false if there is an error. As an example, the
4839 following code waits on semaphore $semnum of semaphore id $semid:
4840 $semop = pack("s!3", $semnum, -1, 0);
4842 die "Semaphore trouble: $!\n" unless semop($semid, $semop);
4843 To signal the semaphore, replace "-1" with 1. See also "SysV IPC"
4845 in perlipc, "IPC::SysV", and "IPC::SysV::Semaphore" documentation.
4846 send SOCKET,MSG,FLAGS,TO
4848 send SOCKET,MSG,FLAGS
4849 Sends a message on a socket. Attempts to send the scalar MSG to
4850 the SOCKET filehandle. Takes the same flags as the system call of
4851 the same name. On unconnected sockets, you must specify a
4852 destination to send to, in which case it does a sendto(2) syscall.
4853 Returns the number of characters sent, or the undefined value on
4854 error. The sendmsg(2) syscall is currently unimplemented. See
4855 "UDP: Message Passing" in perlipc for examples.
4856 Note the characters: depending on the status of the socket, either
4858 (8-bit) bytes or characters are sent. By default all sockets
4859 operate on bytes, but for example if the socket has been changed
4860 using binmode() to operate with the ":encoding(utf8)" I/O layer
4861 (see "open", or the "open" pragma, open), the I/O will operate on
4862 UTF-8 encoded Unicode characters, not bytes. Similarly for the
4863 ":encoding" pragma: in that case pretty much any characters can be
4864 sent.
4865 setpgrp PID,PGRP
4867 Sets the current process group for the specified PID, 0 for the
4868 current process. Raises an exception when used on a machine that
4869 doesn't implement POSIX setpgid(2) or BSD setpgrp(2). If the
4870 arguments are omitted, it defaults to "0,0". Note that the BSD 4.2
4871 version of "setpgrp" does not accept any arguments, so only
4872 "setpgrp(0,0)" is portable. See also "POSIX::setsid()".
4873 setpriority WHICH,WHO,PRIORITY
4875 Sets the current priority for a process, a process group, or a
4876 user. (See setpriority(2).) Raises an exception when used on a
4877 machine that doesn't implement setpriority(2).
4878 setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
4880 Sets the socket option requested. Returns undefined if there is an
4881 error. Use integer constants provided by the "Socket" module for
4882 LEVEL and OPNAME. Values for LEVEL can also be obtained from
4883 getprotobyname. OPTVAL might either be a packed string or an
4884 integer. An integer OPTVAL is shorthand for pack("i", OPTVAL).
4885 An example disabling Nagle's algorithm on a socket:
4887 use Socket qw(IPPROTO_TCP TCP_NODELAY);
4889 setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
4890 shift ARRAY
4892 shift
4893 Shifts the first value of the array off and returns it, shortening
4894 the array by 1 and moving everything down. If there are no
4895 elements in the array, returns the undefined value. If ARRAY is
4896 omitted, shifts the @_ array within the lexical scope of
4897 subroutines and formats, and the @ARGV array outside a subroutine
4898 and also within the lexical scopes established by the "eval
4899 STRING", "BEGIN {}", "INIT {}", "CHECK {}", "UNITCHECK {}" and "END
4900 {}" constructs.
4901 See also "unshift", "push", and "pop". "shift" and "unshift" do
4903 the same thing to the left end of an array that "pop" and "push" do
4904 to the right end.
4905 shmctl ID,CMD,ARG
4907 Calls the System V IPC function shmctl. You'll probably have to
4908 say
4909 use IPC::SysV;
4911 first to get the correct constant definitions. If CMD is
4913 "IPC_STAT", then ARG must be a variable that will hold the returned
4914 "shmid_ds" structure. Returns like ioctl: the undefined value for
4915 error, "0 but true" for zero, or the actual return value otherwise.
4916 See also "SysV IPC" in perlipc and "IPC::SysV" documentation.
4917 shmget KEY,SIZE,FLAGS
4919 Calls the System V IPC function shmget. Returns the shared memory
4920 segment id, or the undefined value if there is an error. See also
4921 "SysV IPC" in perlipc and "IPC::SysV" documentation.
4922 shmread ID,VAR,POS,SIZE
4924 shmwrite ID,STRING,POS,SIZE
4925 Reads or writes the System V shared memory segment ID starting at
4926 position POS for size SIZE by attaching to it, copying in/out, and
4927 detaching from it. When reading, VAR must be a variable that will
4928 hold the data read. When writing, if STRING is too long, only SIZE
4929 bytes are used; if STRING is too short, nulls are written to fill
4930 out SIZE bytes. Return true if successful, or false if there is an
4931 error. shmread() taints the variable. See also "SysV IPC" in
4932 perlipc, "IPC::SysV" documentation, and the "IPC::Shareable" module
4933 from CPAN.
4934 shutdown SOCKET,HOW
4936 Shuts down a socket connection in the manner indicated by HOW,
4937 which has the same interpretation as in the syscall of the same
4938 name.
4939 shutdown(SOCKET, 0); # I/we have stopped reading data
4941 shutdown(SOCKET, 1); # I/we have stopped writing data
4942 shutdown(SOCKET, 2); # I/we have stopped using this socket
4943 This is useful with sockets when you want to tell the other side
4945 you're done writing but not done reading, or vice versa. It's also
4946 a more insistent form of close because it also disables the file
4947 descriptor in any forked copies in other processes.
4948 Returns 1 for success; on error, returns "undef" if the first
4950 argument is not a valid filehandle, or returns 0 and sets $! for
4951 any other failure.
4952 sin EXPR
4954 sin Returns the sine of EXPR (expressed in radians). If EXPR is
4955 omitted, returns sine of $_.
4956 For the inverse sine operation, you may use the "Math::Trig::asin"
4958 function, or use this relation:
4959 sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
4961 sleep EXPR
4963 sleep
4964 Causes the script to sleep for (integer) EXPR seconds, or forever
4965 if no argument is given. Returns the integer number of seconds
4966 actually slept.
4967 May be interrupted if the process receives a signal such as
4969 "SIGALRM".
4970 eval {
4972 local $SIG{ALARM} = sub { die "Alarm!\n" };
4973 sleep;
4974 };
4975 die $@ unless $@ eq "Alarm!\n";
4976 You probably cannot mix "alarm" and "sleep" calls, because "sleep"
4978 is often implemented using "alarm".
4979 On some older systems, it may sleep up to a full second less than
4981 what you requested, depending on how it counts seconds. Most
4982 modern systems always sleep the full amount. They may appear to
4983 sleep longer than that, however, because your process might not be
4984 scheduled right away in a busy multitasking system.
4985 For delays of finer granularity than one second, the Time::HiRes
4987 module (from CPAN, and starting from Perl 5.8 part of the standard
4988 distribution) provides usleep(). You may also use Perl's four-
4989 argument version of select() leaving the first three arguments
4990 undefined, or you might be able to use the "syscall" interface to
4991 access setitimer(2) if your system supports it. See perlfaq8 for
4992 details.
4993 See also the POSIX module's "pause" function.
4995 socket SOCKET,DOMAIN,TYPE,PROTOCOL
4997 Opens a socket of the specified kind and attaches it to filehandle
4998 SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for
4999 the syscall of the same name. You should "use Socket" first to get
5000 the proper definitions imported. See the examples in "Sockets:
5001 Client/Server Communication" in perlipc.
5002 On systems that support a close-on-exec flag on files, the flag
5004 will be set for the newly opened file descriptor, as determined by
5005 the value of $^F. See "$^F" in perlvar.
5006 socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
5008 Creates an unnamed pair of sockets in the specified domain, of the
5009 specified type. DOMAIN, TYPE, and PROTOCOL are specified the same
5010 as for the syscall of the same name. If unimplemented, raises an
5011 exception. Returns true if successful.
5012 On systems that support a close-on-exec flag on files, the flag
5014 will be set for the newly opened file descriptors, as determined by
5015 the value of $^F. See "$^F" in perlvar.
5016 Some systems defined "pipe" in terms of "socketpair", in which a
5018 call to "pipe(Rdr, Wtr)" is essentially:
5019 use Socket;
5021 socketpair(Rdr, Wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC);
5022 shutdown(Rdr, 1); # no more writing for reader
5023 shutdown(Wtr, 0); # no more reading for writer
5024 See perlipc for an example of socketpair use. Perl 5.8 and later
5026 will emulate socketpair using IP sockets to localhost if your
5027 system implements sockets but not socketpair.
5028 sort SUBNAME LIST
5030 sort BLOCK LIST
5031 sort LIST
5032 In list context, this sorts the LIST and returns the sorted list
5033 value. In scalar context, the behaviour of "sort()" is undefined.
5034 If SUBNAME or BLOCK is omitted, "sort"s in standard string
5036 comparison order. If SUBNAME is specified, it gives the name of a
5037 subroutine that returns an integer less than, equal to, or greater
5038 than 0, depending on how the elements of the list are to be
5039 ordered. (The "<=>" and "cmp" operators are extremely useful in
5040 such routines.) SUBNAME may be a scalar variable name
5041 (unsubscripted), in which case the value provides the name of (or a
5042 reference to) the actual subroutine to use. In place of a SUBNAME,
5043 you can provide a BLOCK as an anonymous, in-line sort subroutine.
5044 If the subroutine's prototype is "($$)", the elements to be
5046 compared are passed by reference in @_, as for a normal subroutine.
5047 This is slower than unprototyped subroutines, where the elements to
5048 be compared are passed into the subroutine as the package global
5049 variables $a and $b (see example below). Note that in the latter
5050 case, it is usually counter-productive to declare $a and $b as
5051 lexicals.
5052 The values to be compared are always passed by reference and should
5054 not be modified.
5055 You also cannot exit out of the sort block or subroutine using any
5057 of the loop control operators described in perlsyn or with "goto".
5058 When "use locale" is in effect, "sort LIST" sorts LIST according to
5060 the current collation locale. See perllocale.
5061 sort() returns aliases into the original list, much as a for loop's
5063 index variable aliases the list elements. That is, modifying an
5064 element of a list returned by sort() (for example, in a "foreach",
5065 "map" or "grep") actually modifies the element in the original
5066 list. This is usually something to be avoided when writing clear
5067 code.
5068 Perl 5.6 and earlier used a quicksort algorithm to implement sort.
5070 That algorithm was not stable, and could go quadratic. (A stable
5071 sort preserves the input order of elements that compare equal.
5072 Although quicksort's run time is O(NlogN) when averaged over all
5073 arrays of length N, the time can be O(N**2), quadratic behavior,
5074 for some inputs.) In 5.7, the quicksort implementation was
5075 replaced with a stable mergesort algorithm whose worst-case
5076 behavior is O(NlogN). But benchmarks indicated that for some
5077 inputs, on some platforms, the original quicksort was faster. 5.8
5078 has a sort pragma for limited control of the sort. Its rather
5079 blunt control of the underlying algorithm may not persist into
5080 future Perls, but the ability to characterize the input or output
5081 in implementation independent ways quite probably will. See the
5082 sort pragma.
5083 Examples:
5085 # sort lexically
5087 @articles = sort @files;
5088 # same thing, but with explicit sort routine
5090 @articles = sort {$a cmp $b} @files;
5091 # now case-insensitively
5093 @articles = sort {uc($a) cmp uc($b)} @files;
5094 # same thing in reversed order
5096 @articles = sort {$b cmp $a} @files;
5097 # sort numerically ascending
5099 @articles = sort {$a <=> $b} @files;
5100 # sort numerically descending
5102 @articles = sort {$b <=> $a} @files;
5103 # this sorts the %age hash by value instead of key
5105 # using an in-line function
5106 @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
5107 # sort using explicit subroutine name
5109 sub byage {
5110 $age{$a} <=> $age{$b}; # presuming numeric
5111 }
5112 @sortedclass = sort byage @class;
5113 sub backwards { $b cmp $a }
5115 @harry = qw(dog cat x Cain Abel);
5116 @george = qw(gone chased yz Punished Axed);
5117 print sort @harry;
5118 # prints AbelCaincatdogx
5119 print sort backwards @harry;
5120 # prints xdogcatCainAbel
5121 print sort @george, 'to', @harry;
5122 # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
5123 # inefficiently sort by descending numeric compare using
5125 # the first integer after the first = sign, or the
5126 # whole record case-insensitively otherwise
5127 my @new = sort {
5129 ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
5130 ||
5131 uc($a) cmp uc($b)
5132 } @old;
5133 # same thing, but much more efficiently;
5135 # we'll build auxiliary indices instead
5136 # for speed
5137 my @nums = @caps = ();
5138 for (@old) {
5139 push @nums, ( /=(\d+)/ ? $1 : undef );
5140 push @caps, uc($_);
5141 }
5142 my @new = @old[ sort {
5144 $nums[$b] <=> $nums[$a]
5145 ||
5146 $caps[$a] cmp $caps[$b]
5147 } 0..$#old
5148 ];
5149 # same thing, but without any temps
5151 @new = map { $_->[0] }
5152 sort { $b->[1] <=> $a->[1]
5153 ||
5154 $a->[2] cmp $b->[2]
5155 } map { [$_, /=(\d+)/, uc($_)] } @old;
5156 # using a prototype allows you to use any comparison subroutine
5158 # as a sort subroutine (including other package's subroutines)
5159 package other;
5160 sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are not set here
5161 package main;
5163 @new = sort other::backwards @old;
5164 # guarantee stability, regardless of algorithm
5166 use sort 'stable';
5167 @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
5168 # force use of mergesort (not portable outside Perl 5.8)
5170 use sort '_mergesort'; # note discouraging _
5171 @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
5172 Warning: syntactical care is required when sorting the list
5174 returned from a function. If you want to sort the list returned by
5175 the function call "find_records(@key)", you can use:
5176 @contact = sort { $a cmp $b } find_records @key;
5178 @contact = sort +find_records(@key);
5179 @contact = sort &find_records(@key);
5180 @contact = sort(find_records(@key));
5181 If instead you want to sort the array @key with the comparison
5183 routine "find_records()" then you can use:
5184 @contact = sort { find_records() } @key;
5186 @contact = sort find_records(@key);
5187 @contact = sort(find_records @key);
5188 @contact = sort(find_records (@key));
5189 If you're using strict, you must not declare $a and $b as lexicals.
5191 They are package globals. That means that if you're in the "main"
5192 package and type
5193 @articles = sort {$b <=> $a} @files;
5195 then $a and $b are $main::a and $main::b (or $::a and $::b), but if
5197 you're in the "FooPack" package, it's the same as typing
5198 @articles = sort {$FooPack::b <=> $FooPack::a} @files;
5200 The comparison function is required to behave. If it returns
5202 inconsistent results (sometimes saying $x[1] is less than $x[2] and
5203 sometimes saying the opposite, for example) the results are not
5204 well-defined.
5205 Because "<=>" returns "undef" when either operand is "NaN" (not-a-
5207 number), and because "sort" raises an exception unless the result
5208 of a comparison is defined, when sorting with a comparison function
5209 like "$a <=> $b", be careful about lists that might contain a
5210 "NaN". The following example takes advantage that "NaN != NaN" to
5211 eliminate any "NaN"s from the input list.
5212 @result = sort { $a <=> $b } grep { $_ == $_ } @input;
5214 splice ARRAY,OFFSET,LENGTH,LIST
5216 splice ARRAY,OFFSET,LENGTH
5217 splice ARRAY,OFFSET
5218 splice ARRAY
5219 Removes the elements designated by OFFSET and LENGTH from an array,
5220 and replaces them with the elements of LIST, if any. In list
5221 context, returns the elements removed from the array. In scalar
5222 context, returns the last element removed, or "undef" if no
5223 elements are removed. The array grows or shrinks as necessary. If
5224 OFFSET is negative then it starts that far from the end of the
5225 array. If LENGTH is omitted, removes everything from OFFSET
5226 onward. If LENGTH is negative, removes the elements from OFFSET
5227 onward except for -LENGTH elements at the end of the array. If
5228 both OFFSET and LENGTH are omitted, removes everything. If OFFSET
5229 is past the end of the array, Perl issues a warning, and splices at
5230 the end of the array.
5231 The following equivalences hold (assuming "$[ == 0 and $#a >= $i" )
5233 push(@a,$x,$y) splice(@a,@a,0,$x,$y)
5235 pop(@a) splice(@a,-1)
5236 shift(@a) splice(@a,0,1)
5237 unshift(@a,$x,$y) splice(@a,0,0,$x,$y)
5238 $a[$i] = $y splice(@a,$i,1,$y)
5239 Example, assuming array lengths are passed before arrays:
5241 sub aeq { # compare two list values
5243 my(@a) = splice(@_,0,shift);
5244 my(@b) = splice(@_,0,shift);
5245 return 0 unless @a == @b; # same len?
5246 while (@a) {
5247 return 0 if pop(@a) ne pop(@b);
5248 }
5249 return 1;
5250 }
5251 if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
5252 split /PATTERN/,EXPR,LIMIT
5254 split /PATTERN/,EXPR
5255 split /PATTERN/
5256 split
5257 Splits the string EXPR into a list of strings and returns that
5258 list. By default, empty leading fields are preserved, and empty
5259 trailing ones are deleted. (If all fields are empty, they are
5260 considered to be trailing.)
5261 In scalar context, returns the number of fields found.
5263 If EXPR is omitted, splits the $_ string. If PATTERN is also
5265 omitted, splits on whitespace (after skipping any leading
5266 whitespace). Anything matching PATTERN is taken to be a delimiter
5267 separating the fields. (Note that the delimiter may be longer than
5268 one character.)
5269 If LIMIT is specified and positive, it represents the maximum
5271 number of fields the EXPR will be split into, though the actual
5272 number of fields returned depends on the number of times PATTERN
5273 matches within EXPR. If LIMIT is unspecified or zero, trailing
5274 null fields are stripped (which potential users of "pop" would do
5275 well to remember). If LIMIT is negative, it is treated as if an
5276 arbitrarily large LIMIT had been specified. Note that splitting an
5277 EXPR that evaluates to the empty string always returns the empty
5278 list, regardless of the LIMIT specified.
5279 A pattern matching the empty string (not to be confused with an
5281 empty pattern "//", which is just one member of the set of patterns
5282 matching the epmty string), splits EXPR into individual characters.
5283 For example:
5284 print join(':', split(/ */, 'hi there')), "\n";
5286 produces the output 'h:i:t:h:e:r:e'.
5288 As a special case for "split", the empty pattern "//" specifically
5290 matches the empty string; this is not be confused with the normal
5291 use of an empty pattern to mean the last successful match. So to
5292 split a string into individual characters, the following:
5293 print join(':', split(//, 'hi there')), "\n";
5295 produces the output 'h:i: :t:h:e:r:e'.
5297 Empty leading fields are produced when there are positive-width
5299 matches at the beginning of the string; a zero-width match at the
5300 beginning of the string does not produce an empty field. For
5301 example:
5302 print join(':', split(/(?=\w)/, 'hi there!'));
5304 produces the output 'h:i :t:h:e:r:e!'. Empty trailing fields, on
5306 the other hand, are produced when there is a match at the end of
5307 the string (and when LIMIT is given and is not 0), regardless of
5308 the length of the match. For example:
5309 print join(':', split(//, 'hi there!', -1)), "\n";
5311 print join(':', split(/\W/, 'hi there!', -1)), "\n";
5312 produce the output 'h:i: :t:h:e:r:e:!:' and 'hi:there:',
5314 respectively, both with an empty trailing field.
5315 The LIMIT parameter can be used to split a line partially
5317 ($login, $passwd, $remainder) = split(/:/, $_, 3);
5319 When assigning to a list, if LIMIT is omitted, or zero, Perl
5321 supplies a LIMIT one larger than the number of variables in the
5322 list, to avoid unnecessary work. For the list above LIMIT would
5323 have been 4 by default. In time critical applications it behooves
5324 you not to split into more fields than you really need.
5325 If the PATTERN contains parentheses, additional list elements are
5327 created from each matching substring in the delimiter.
5328 split(/([,-])/, "1-10,20", 3);
5330 produces the list value
5332 (1, '-', 10, ',', 20)
5334 If you had the entire header of a normal Unix email message in
5336 $header, you could split it up into fields and their values this
5337 way:
5338 $header =~ s/\n(?=\s)//g; # fix continuation lines
5340 %hdrs = (UNIX_FROM => split /^(\S*?):\s*/m, $header);
5341 The pattern "/PATTERN/" may be replaced with an expression to
5343 specify patterns that vary at runtime. (To do runtime compilation
5344 only once, use "/$variable/o".)
5345 As a special case, specifying a PATTERN of space (' ') will split
5347 on white space just as "split" with no arguments does. Thus,
5348 "split(' ')" can be used to emulate awk's default behavior, whereas
5349 "split(/ /)" will give you as many initial null fields (empty
5350 string) as there are leading spaces. A "split" on "/\s+/" is like
5351 a "split(' ')" except that any leading whitespace produces a null
5352 first field. A "split" with no arguments really does a
5353 "split(' ', $_)" internally.
5354 A PATTERN of "/^/" is treated as if it were "/^/m", since it isn't
5356 much use otherwise.
5357 Example:
5359 open(PASSWD, '/etc/passwd');
5361 while (<PASSWD>) {
5362 chomp;
5363 ($login, $passwd, $uid, $gid,
5364 $gcos, $home, $shell) = split(/:/);
5365 #...
5366 }
5367 As with regular pattern matching, any capturing parentheses that
5369 are not matched in a "split()" will be set to "undef" when
5370 returned:
5371 @fields = split /(A)|B/, "1A2B3";
5373 # @fields is (1, 'A', 2, undef, 3)
5374 sprintf FORMAT, LIST
5376 Returns a string formatted by the usual "printf" conventions of the
5377 C library function "sprintf". See below for more details and see
5378 sprintf(3) or printf(3) on your system for an explanation of the
5379 general principles.
5380 For example:
5382 # Format number with up to 8 leading zeroes
5384 $result = sprintf("%08d", $number);
5385 # Round number to 3 digits after decimal point
5387 $rounded = sprintf("%.3f", $number);
5388 Perl does its own "sprintf" formatting: it emulates the C function
5390 sprintf(3), but doesn't use it except for floating-point numbers,
5391 and even then only standard modifiers are allowed. Non-standard
5392 extensions in your local sprintf(3) are therefore unavailable from
5393 Perl.
5394 Unlike "printf", "sprintf" does not do what you probably mean when
5396 you pass it an array as your first argument. The array is given
5397 scalar context, and instead of using the 0th element of the array
5398 as the format, Perl will use the count of elements in the array as
5399 the format, which is almost never useful.
5400 Perl's "sprintf" permits the following universally-known
5402 conversions:
5403 %% a percent sign
5405 %c a character with the given number
5406 %s a string
5407 %d a signed integer, in decimal
5408 %u an unsigned integer, in decimal
5409 %o an unsigned integer, in octal
5410 %x an unsigned integer, in hexadecimal
5411 %e a floating-point number, in scientific notation
5412 %f a floating-point number, in fixed decimal notation
5413 %g a floating-point number, in %e or %f notation
5414 In addition, Perl permits the following widely-supported
5416 conversions:
5417 %X like %x, but using upper-case letters
5419 %E like %e, but using an upper-case "E"
5420 %G like %g, but with an upper-case "E" (if applicable)
5421 %b an unsigned integer, in binary
5422 %B like %b, but using an upper-case "B" with the # flag
5423 %p a pointer (outputs the Perl value's address in hexadecimal)
5424 %n special: *stores* the number of characters output so far
5425 into the next variable in the parameter list
5426 Finally, for backward (and we do mean "backward") compatibility,
5428 Perl permits these unnecessary but widely-supported conversions:
5429 %i a synonym for %d
5431 %D a synonym for %ld
5432 %U a synonym for %lu
5433 %O a synonym for %lo
5434 %F a synonym for %f
5435 Note that the number of exponent digits in the scientific notation
5437 produced by %e, %E, %g and %G for numbers with the modulus of the
5438 exponent less than 100 is system-dependent: it may be three or less
5439 (zero-padded as necessary). In other words, 1.23 times ten to the
5440 99th may be either "1.23e99" or "1.23e099".
5441 Between the "%" and the format letter, you may specify several
5443 additional attributes controlling the interpretation of the format.
5444 In order, these are:
5445 format parameter index
5447 An explicit format parameter index, such as "2$". By default
5448 sprintf will format the next unused argument in the list, but
5449 this allows you to take the arguments out of order:
5450 printf '%2$d %1$d', 12, 34; # prints "34 12"
5452 printf '%3$d %d %1$d', 1, 2, 3; # prints "3 1 1"
5453 flags
5455 one or more of:
5456 space prefix non-negative number with a space
5458 + prefix non-negative number with a plus sign
5459 - left-justify within the field
5460 0 use zeros, not spaces, to right-justify
5461 # ensure the leading "0" for any octal,
5462 prefix non-zero hexadecimal with "0x" or "0X",
5463 prefix non-zero binary with "0b" or "0B"
5464 For example:
5466 printf '<% d>', 12; # prints "< 12>"
5468 printf '<%+d>', 12; # prints "<+12>"
5469 printf '<%6s>', 12; # prints "< 12>"
5470 printf '<%-6s>', 12; # prints "<12 >"
5471 printf '<%06s>', 12; # prints "<000012>"
5472 printf '<%#o>', 12; # prints "<014>"
5473 printf '<%#x>', 12; # prints "<0xc>"
5474 printf '<%#X>', 12; # prints "<0XC>"
5475 printf '<%#b>', 12; # prints "<0b1100>"
5476 printf '<%#B>', 12; # prints "<0B1100>"
5477 When a space and a plus sign are given as the flags at once, a
5479 plus sign is used to prefix a positive number.
5480 printf '<%+ d>', 12; # prints "<+12>"
5482 printf '<% +d>', 12; # prints "<+12>"
5483 When the # flag and a precision are given in the %o conversion,
5485 the precision is incremented if it's necessary for the leading
5486 "0".
5487 printf '<%#.5o>', 012; # prints "<00012>"
5489 printf '<%#.5o>', 012345; # prints "<012345>"
5490 printf '<%#.0o>', 0; # prints "<0>"
5491 vector flag
5493 This flag tells Perl to interpret the supplied string as a
5494 vector of integers, one for each character in the string. Perl
5495 applies the format to each integer in turn, then joins the
5496 resulting strings with a separator (a dot "." by default). This
5497 can be useful for displaying ordinal values of characters in
5498 arbitrary strings:
5499 printf "%vd", "AB\x{100}"; # prints "65.66.256"
5501 printf "version is v%vd\n", $^V; # Perl's version
5502 Put an asterisk "*" before the "v" to override the string to
5504 use to separate the numbers:
5505 printf "address is %*vX\n", ":", $addr; # IPv6 address
5507 printf "bits are %0*v8b\n", " ", $bits; # random bitstring
5508 You can also explicitly specify the argument number to use for
5510 the join string using something like "*2$v"; for example:
5511 printf '%*4$vX %*4$vX %*4$vX', @addr[1..3], ":"; # 3 IPv6 addresses
5513 (minimum) width
5515 Arguments are usually formatted to be only as wide as required
5516 to display the given value. You can override the width by
5517 putting a number here, or get the width from the next argument
5518 (with "*") or from a specified argument (e.g., with "*2$"):
5519 printf '<%s>', "a"; # prints "<a>"
5521 printf '<%6s>', "a"; # prints "< a>"
5522 printf '<%*s>', 6, "a"; # prints "< a>"
5523 printf '<%*2$s>', "a", 6; # prints "< a>"
5524 printf '<%2s>', "long"; # prints "<long>" (does not truncate)
5525 If a field width obtained through "*" is negative, it has the
5527 same effect as the "-" flag: left-justification.
5528 precision, or maximum width
5530 You can specify a precision (for numeric conversions) or a
5531 maximum width (for string conversions) by specifying a "."
5532 followed by a number. For floating-point formats except 'g'
5533 and 'G', this specifies how many places right of the decimal
5534 point to show (the default being 6). For example:
5535 # these examples are subject to system-specific variation
5537 printf '<%f>', 1; # prints "<1.000000>"
5538 printf '<%.1f>', 1; # prints "<1.0>"
5539 printf '<%.0f>', 1; # prints "<1>"
5540 printf '<%e>', 10; # prints "<1.000000e+01>"
5541 printf '<%.1e>', 10; # prints "<1.0e+01>"
5542 For "g" and "G", this specifies the maximum number of digits to
5544 show, including thoe prior to the decimal point and those after
5545 it; for example:
5546 # These examples are subject to system-specific variation.
5548 printf '<%g>', 1; # prints "<1>"
5549 printf '<%.10g>', 1; # prints "<1>"
5550 printf '<%g>', 100; # prints "<100>"
5551 printf '<%.1g>', 100; # prints "<1e+02>"
5552 printf '<%.2g>', 100.01; # prints "<1e+02>"
5553 printf '<%.5g>', 100.01; # prints "<100.01>"
5554 printf '<%.4g>', 100.01; # prints "<100>"
5555 For integer conversions, specifying a precision implies that
5557 the output of the number itself should be zero-padded to this
5558 width, where the 0 flag is ignored:
5559 printf '<%.6d>', 1; # prints "<000001>"
5561 printf '<%+.6d>', 1; # prints "<+000001>"
5562 printf '<%-10.6d>', 1; # prints "<000001 >"
5563 printf '<%10.6d>', 1; # prints "< 000001>"
5564 printf '<%010.6d>', 1; # prints "< 000001>"
5565 printf '<%+10.6d>', 1; # prints "< +000001>"
5566 printf '<%.6x>', 1; # prints "<000001>"
5568 printf '<%#.6x>', 1; # prints "<0x000001>"
5569 printf '<%-10.6x>', 1; # prints "<000001 >"
5570 printf '<%10.6x>', 1; # prints "< 000001>"
5571 printf '<%010.6x>', 1; # prints "< 000001>"
5572 printf '<%#10.6x>', 1; # prints "< 0x000001>"
5573 For string conversions, specifying a precision truncates the
5575 string to fit the specified width:
5576 printf '<%.5s>', "truncated"; # prints "<trunc>"
5578 printf '<%10.5s>', "truncated"; # prints "< trunc>"
5579 You can also get the precision from the next argument using
5581 ".*":
5582 printf '<%.6x>', 1; # prints "<000001>"
5584 printf '<%.*x>', 6, 1; # prints "<000001>"
5585 If a precision obtained through "*" is negative, it counts as
5587 having no precision at all.
5588 printf '<%.*s>', 7, "string"; # prints "<string>"
5590 printf '<%.*s>', 3, "string"; # prints "<str>"
5591 printf '<%.*s>', 0, "string"; # prints "<>"
5592 printf '<%.*s>', -1, "string"; # prints "<string>"
5593 printf '<%.*d>', 1, 0; # prints "<0>"
5595 printf '<%.*d>', 0, 0; # prints "<>"
5596 printf '<%.*d>', -1, 0; # prints "<0>"
5597 You cannot currently get the precision from a specified number,
5599 but it is intended that this will be possible in the future,
5600 for example using ".*2$":
5601 printf "<%.*2$x>", 1, 6; # INVALID, but in future will print "<000001>"
5603 size
5605 For numeric conversions, you can specify the size to interpret
5606 the number as using "l", "h", "V", "q", "L", or "ll". For
5607 integer conversions ("d u o x X b i D U O"), numbers are
5608 usually assumed to be whatever the default integer size is on
5609 your platform (usually 32 or 64 bits), but you can override
5610 this to use instead one of the standard C types, as supported
5611 by the compiler used to build Perl:
5612 l interpret integer as C type "long" or "unsigned long"
5614 h interpret integer as C type "short" or "unsigned short"
5615 q, L or ll interpret integer as C type "long long", "unsigned long long".
5616 or "quads" (typically 64-bit integers)
5617 The last will raise an exception if Perl does not understand
5619 "quads" in your installation. (This requires either that the
5620 platform natively support quads, or that Perl were specifically
5621 compiled to support quads.) You can find out whether your Perl
5622 supports quads via Config:
5623 use Config;
5625 if ($Config{use64bitint} eq "define" || $Config{longsize} >= 8) {
5626 print "Nice quads!\n";
5627 }
5628 For floating-point conversions ("e f g E F G"), numbers are
5630 usually assumed to be the default floating-point size on your
5631 platform (double or long double), but you can force "long
5632 double" with "q", "L", or "ll" if your platform supports them.
5633 You can find out whether your Perl supports long doubles via
5634 Config:
5635 use Config;
5637 print "long doubles\n" if $Config{d_longdbl} eq "define";
5638 You can find out whether Perl considers "long double" to be the
5640 default floating-point size to use on your platform via Config:
5641 use Config;
5643 if ($Config{uselongdouble} eq "define") {
5644 print "long doubles by default\n";
5645 }
5646 It can also be that long doubles and doubles are the same
5648 thing:
5649 use Config;
5651 ($Config{doublesize} == $Config{longdblsize}) &&
5652 print "doubles are long doubles\n";
5653 The size specifier "V" has no effect for Perl code, but is
5655 supported for compatibility with XS code. It means "use the
5656 standard size for a Perl integer or floating-point number",
5657 which is the default.
5658 order of arguments
5660 Normally, sprintf() takes the next unused argument as the value
5661 to format for each format specification. If the format
5662 specification uses "*" to require additional arguments, these
5663 are consumed from the argument list in the order they appear in
5664 the format specification before the value to format. Where an
5665 argument is specified by an explicit index, this does not
5666 affect the normal order for the arguments, even when the
5667 explicitly specified index would have been the next argument.
5668 So:
5670 printf "<%*.*s>", $a, $b, $c;
5672 uses $a for the width, $b for the precision, and $c as the
5674 value to format; while:
5675 printf "<%*1$.*s>", $a, $b;
5677 would use $a for the width and precision, and $b as the value
5679 to format.
5680 Here are some more examples; be aware that when using an
5682 explicit index, the "$" may need escaping:
5683 printf "%2\$d %d\n", 12, 34; # will print "34 12\n"
5685 printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n"
5686 printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n"
5687 printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n"
5688 If "use locale" is in effect and POSIX::setlocale() has been
5690 called, the character used for the decimal separator in formatted
5691 floating-point numbers is affected by the LC_NUMERIC locale. See
5692 perllocale and POSIX.
5693 sqrt EXPR
5695 sqrt
5696 Return the positive square root of EXPR. If EXPR is omitted, uses
5697 $_. Works only for non-negative operands unless you've loaded the
5698 "Math::Complex" module.
5699 use Math::Complex;
5701 print sqrt(-4); # prints 2i
5702 srand EXPR
5704 srand
5705 Sets the random number seed for the "rand" operator.
5706 The point of the function is to "seed" the "rand" function so that
5708 "rand" can produce a different sequence each time you run your
5709 program.
5710 If srand() is not called explicitly, it is called implicitly at the
5712 first use of the "rand" operator. However, this was not true of
5713 versions of Perl before 5.004, so if your script will run under
5714 older Perl versions, it should call "srand".
5715 Most programs won't even call srand() at all, except those that
5717 need a cryptographically-strong starting point rather than the
5718 generally acceptable default, which is based on time of day,
5719 process ID, and memory allocation, or the /dev/urandom device if
5720 available. You may also want to call srand() after a fork() to
5721 avoid child processes sharing the same seed value as the parent
5722 (and consequently each other).
5723 You can call srand($seed) with the same $seed to reproduce the same
5725 sequence from rand(), but this is usually reserved for generating
5726 predictable results for testing or debugging. Otherwise, don't
5727 call srand() more than once in your program.
5728 Do not call srand() (i.e., without an argument) more than once per
5730 process. The internal state of the random number generator should
5731 contain more entropy than can be provided by any seed, so calling
5732 srand() again actually loses randomness.
5733 Most implementations of "srand" take an integer and will silently
5735 truncate decimal numbers. This means "srand(42)" will usually
5736 produce the same results as "srand(42.1)". To be safe, always pass
5737 "srand" an integer.
5738 In versions of Perl prior to 5.004 the default seed was just the
5740 current "time". This isn't a particularly good seed, so many old
5741 programs supply their own seed value (often "time ^ $$" or "time ^
5742 ($$ + ($$ << 15))"), but that isn't necessary any more.
5743 For cryptographic purposes, however, you need something much more
5745 random than the default seed. Checksumming the compressed output
5746 of one or more rapidly changing operating system status programs is
5747 the usual method. For example:
5748 srand (time ^ $$ ^ unpack "%L*", `ps axww | gzip -f`);
5750 If you're particularly concerned with this, search the CPAN for
5752 random number generator modules instead of rolling out your own.
5753 Frequently called programs (like CGI scripts) that simply use
5755 time ^ $$
5757 for a seed can fall prey to the mathematical property that
5759 a^b == (a+1)^(b+1)
5761 one-third of the time. So don't do that.
5763 stat FILEHANDLE
5765 stat EXPR
5766 stat DIRHANDLE
5767 stat
5768 Returns a 13-element list giving the status info for a file, either
5769 the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR. If
5770 EXPR is omitted, it stats $_. Returns the empty list if "stat"
5771 fails. Typically used as follows:
5772 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
5774 $atime,$mtime,$ctime,$blksize,$blocks)
5775 = stat($filename);
5776 Not all fields are supported on all filesystem types. Here are the
5778 meanings of the fields:
5779 0 dev device number of filesystem
5781 1 ino inode number
5782 2 mode file mode (type and permissions)
5783 3 nlink number of (hard) links to the file
5784 4 uid numeric user ID of file's owner
5785 5 gid numeric group ID of file's owner
5786 6 rdev the device identifier (special files only)
5787 7 size total size of file, in bytes
5788 8 atime last access time in seconds since the epoch
5789 9 mtime last modify time in seconds since the epoch
5790 10 ctime inode change time in seconds since the epoch (*)
5791 11 blksize preferred block size for file system I/O
5792 12 blocks actual number of blocks allocated
5793 (The epoch was at 00:00 January 1, 1970 GMT.)
5795 (*) Not all fields are supported on all filesystem types. Notably,
5797 the ctime field is non-portable. In particular, you cannot expect
5798 it to be a "creation time", see "Files and Filesystems" in perlport
5799 for details.
5800 If "stat" is passed the special filehandle consisting of an
5802 underline, no stat is done, but the current contents of the stat
5803 structure from the last "stat", "lstat", or filetest are returned.
5804 Example:
5805 if (-x $file && (($d) = stat(_)) && $d < 0) {
5807 print "$file is executable NFS file\n";
5808 }
5809 (This works on machines only for which the device number is
5811 negative under NFS.)
5812 Because the mode contains both the file type and its permissions,
5814 you should mask off the file type portion and (s)printf using a
5815 "%o" if you want to see the real permissions.
5816 $mode = (stat($filename))[2];
5818 printf "Permissions are %04o\n", $mode & 07777;
5819 In scalar context, "stat" returns a boolean value indicating
5821 success or failure, and, if successful, sets the information
5822 associated with the special filehandle "_".
5823 The File::stat module provides a convenient, by-name access
5825 mechanism:
5826 use File::stat;
5828 $sb = stat($filename);
5829 printf "File is %s, size is %s, perm %04o, mtime %s\n",
5830 $filename, $sb->size, $sb->mode & 07777,
5831 scalar localtime $sb->mtime;
5832 You can import symbolic mode constants ("S_IF*") and functions
5834 ("S_IS*") from the Fcntl module:
5835 use Fcntl ':mode';
5837 $mode = (stat($filename))[2];
5839 $user_rwx = ($mode & S_IRWXU) >> 6;
5841 $group_read = ($mode & S_IRGRP) >> 3;
5842 $other_execute = $mode & S_IXOTH;
5843 printf "Permissions are %04o\n", S_IMODE($mode), "\n";
5845 $is_setuid = $mode & S_ISUID;
5847 $is_directory = S_ISDIR($mode);
5848 You could write the last two using the "-u" and "-d" operators.
5850 Commonly available "S_IF*" constants are:
5851 # Permissions: read, write, execute, for user, group, others.
5853 S_IRWXU S_IRUSR S_IWUSR S_IXUSR
5855 S_IRWXG S_IRGRP S_IWGRP S_IXGRP
5856 S_IRWXO S_IROTH S_IWOTH S_IXOTH
5857 # Setuid/Setgid/Stickiness/SaveText.
5859 # Note that the exact meaning of these is system dependent.
5860 S_ISUID S_ISGID S_ISVTX S_ISTXT
5862 # File types. Not necessarily all are available on your system.
5864 S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
5866 # The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.
5868 S_IREAD S_IWRITE S_IEXEC
5870 and the "S_IF*" functions are
5872 S_IMODE($mode) the part of $mode containing the permission bits
5874 and the setuid/setgid/sticky bits
5875 S_IFMT($mode) the part of $mode containing the file type
5877 which can be bit-anded with (for example) S_IFREG
5878 or with the following functions
5879 # The operators -f, -d, -l, -b, -c, -p, and -S.
5881 S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
5883 S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
5884 # No direct -X operator counterpart, but for the first one
5886 # the -g operator is often equivalent. The ENFMT stands for
5887 # record flocking enforcement, a platform-dependent feature.
5888 S_ISENFMT($mode) S_ISWHT($mode)
5890 See your native chmod(2) and stat(2) documentation for more details
5892 about the "S_*" constants. To get status info for a symbolic link
5893 instead of the target file behind the link, use the "lstat"
5894 function.
5895 state EXPR
5897 state TYPE EXPR
5898 state EXPR : ATTRS
5899 state TYPE EXPR : ATTRS
5900 "state" declares a lexically scoped variable, just like "my" does.
5901 However, those variables will never be reinitialized, contrary to
5902 lexical variables that are reinitialized each time their enclosing
5903 block is entered.
5904 "state" variables are enabled only when the "use feature "state""
5906 pragma is in effect. See feature.
5907 study SCALAR
5909 study
5910 Takes extra time to study SCALAR ($_ if unspecified) in
5911 anticipation of doing many pattern matches on the string before it
5912 is next modified. This may or may not save time, depending on the
5913 nature and number of patterns you are searching on, and on the
5914 distribution of character frequencies in the string to be searched;
5915 you probably want to compare run times with and without it to see
5916 which runs faster. Those loops that scan for many short constant
5917 strings (including the constant parts of more complex patterns)
5918 will benefit most. You may have only one "study" active at a time:
5919 if you study a different scalar the first is "unstudied". (The way
5920 "study" works is this: a linked list of every character in the
5921 string to be searched is made, so we know, for example, where all
5922 the 'k' characters are. From each search string, the rarest
5923 character is selected, based on some static frequency tables
5924 constructed from some C programs and English text. Only those
5925 places that contain this "rarest" character are examined.)
5926 For example, here is a loop that inserts index producing entries
5928 before any line containing a certain pattern:
5929 while (<>) {
5931 study;
5932 print ".IX foo\n" if /\bfoo\b/;
5933 print ".IX bar\n" if /\bbar\b/;
5934 print ".IX blurfl\n" if /\bblurfl\b/;
5935 # ...
5936 print;
5937 }
5938 In searching for "/\bfoo\b/", only locations in $_ that contain "f"
5940 will be looked at, because "f" is rarer than "o". In general, this
5941 is a big win except in pathological cases. The only question is
5942 whether it saves you more time than it took to build the linked
5943 list in the first place.
5944 Note that if you have to look for strings that you don't know till
5946 runtime, you can build an entire loop as a string and "eval" that
5947 to avoid recompiling all your patterns all the time. Together with
5948 undefining $/ to input entire files as one record, this can be
5949 quite fast, often faster than specialized programs like fgrep(1).
5950 The following scans a list of files (@files) for a list of words
5951 (@words), and prints out the names of those files that contain a
5952 match:
5953 $search = 'while (<>) { study;';
5955 foreach $word (@words) {
5956 $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n";
5957 }
5958 $search .= "}";
5959 @ARGV = @files;
5960 undef $/;
5961 eval $search; # this screams
5962 $/ = "\n"; # put back to normal input delimiter
5963 foreach $file (sort keys(%seen)) {
5964 print $file, "\n";
5965 }
5966 sub NAME BLOCK
5968 sub NAME (PROTO) BLOCK
5969 sub NAME : ATTRS BLOCK
5970 sub NAME (PROTO) : ATTRS BLOCK
5971 This is subroutine definition, not a real function per se. Without
5972 a BLOCK it's just a forward declaration. Without a NAME, it's an
5973 anonymous function declaration, and does actually return a value:
5974 the CODE ref of the closure you just created.
5975 See perlsub and perlref for details about subroutines and
5977 references, and attributes and Attribute::Handlers for more
5978 information about attributes.
5979 substr EXPR,OFFSET,LENGTH,REPLACEMENT
5981 substr EXPR,OFFSET,LENGTH
5982 substr EXPR,OFFSET
5983 Extracts a substring out of EXPR and returns it. First character
5984 is at offset 0, or whatever you've set $[ to (but don't do that).
5985 If OFFSET is negative (or more precisely, less than $[), starts
5986 that far from the end of the string. If LENGTH is omitted, returns
5987 everything to the end of the string. If LENGTH is negative, leaves
5988 that many characters off the end of the string.
5989 my $s = "The black cat climbed the green tree";
5991 my $color = substr $s, 4, 5; # black
5992 my $middle = substr $s, 4, -11; # black cat climbed the
5993 my $end = substr $s, 14; # climbed the green tree
5994 my $tail = substr $s, -4; # tree
5995 my $z = substr $s, -4, 2; # tr
5996 You can use the substr() function as an lvalue, in which case EXPR
5998 must itself be an lvalue. If you assign something shorter than
5999 LENGTH, the string will shrink, and if you assign something longer
6000 than LENGTH, the string will grow to accommodate it. To keep the
6001 string the same length, you may need to pad or chop your value
6002 using "sprintf".
6003 If OFFSET and LENGTH specify a substring that is partly outside the
6005 string, only the part within the string is returned. If the
6006 substring is beyond either end of the string, substr() returns the
6007 undefined value and produces a warning. When used as an lvalue,
6008 specifying a substring that is entirely outside the string raises
6009 an exception. Here's an example showing the behavior for boundary
6010 cases:
6011 my $name = 'fred';
6013 substr($name, 4) = 'dy'; # $name is now 'freddy'
6014 my $null = substr $name, 6, 2; # returns "" (no warning)
6015 my $oops = substr $name, 7; # returns undef, with warning
6016 substr($name, 7) = 'gap'; # raises an exception
6017 An alternative to using substr() as an lvalue is to specify the
6019 replacement string as the 4th argument. This allows you to replace
6020 parts of the EXPR and return what was there before in one
6021 operation, just as you can with splice().
6022 my $s = "The black cat climbed the green tree";
6024 my $z = substr $s, 14, 7, "jumped from"; # climbed
6025 # $s is now "The black cat jumped from the green tree"
6026 Note that the lvalue returned by the 3-arg version of substr() acts
6028 as a 'magic bullet'; each time it is assigned to, it remembers
6029 which part of the original string is being modified; for example:
6030 $x = '1234';
6032 for (substr($x,1,2)) {
6033 $_ = 'a'; print $x,"\n"; # prints 1a4
6034 $_ = 'xyz'; print $x,"\n"; # prints 1xyz4
6035 $x = '56789';
6036 $_ = 'pq'; print $x,"\n"; # prints 5pq9
6037 }
6038 Prior to Perl version 5.9.1, the result of using an lvalue multiple
6040 times was unspecified.
6041 symlink OLDFILE,NEWFILE
6043 Creates a new filename symbolically linked to the old filename.
6044 Returns 1 for success, 0 otherwise. On systems that don't support
6045 symbolic links, raises an exception. To check for that, use eval:
6046 $symlink_exists = eval { symlink("",""); 1 };
6048 syscall NUMBER, LIST
6050 Calls the system call specified as the first element of the list,
6051 passing the remaining elements as arguments to the system call. If
6052 unimplemented, raises an exception. The arguments are interpreted
6053 as follows: if a given argument is numeric, the argument is passed
6054 as an int. If not, the pointer to the string value is passed. You
6055 are responsible to make sure a string is pre-extended long enough
6056 to receive any result that might be written into a string. You
6057 can't use a string literal (or other read-only string) as an
6058 argument to "syscall" because Perl has to assume that any string
6059 pointer might be written through. If your integer arguments are
6060 not literals and have never been interpreted in a numeric context,
6061 you may need to add 0 to them to force them to look like numbers.
6062 This emulates the "syswrite" function (or vice versa):
6063 require 'syscall.ph'; # may need to run h2ph
6065 $s = "hi there\n";
6066 syscall(&SYS_write, fileno(STDOUT), $s, length $s);
6067 Note that Perl supports passing of up to only 14 arguments to your
6069 syscall, which in practice should (usually) suffice.
6070 Syscall returns whatever value returned by the system call it
6072 calls. If the system call fails, "syscall" returns "-1" and sets
6073 $! (errno). Note that some system calls can legitimately return
6074 "-1". The proper way to handle such calls is to assign "$!=0;"
6075 before the call and check the value of $! if syscall returns "-1".
6076 There's a problem with "syscall(&SYS_pipe)": it returns the file
6078 number of the read end of the pipe it creates. There is no way to
6079 retrieve the file number of the other end. You can avoid this
6080 problem by using "pipe" instead.
6081 sysopen FILEHANDLE,FILENAME,MODE
6083 sysopen FILEHANDLE,FILENAME,MODE,PERMS
6084 Opens the file whose filename is given by FILENAME, and associates
6085 it with FILEHANDLE. If FILEHANDLE is an expression, its value is
6086 used as the name of the real filehandle wanted. This function
6087 calls the underlying operating system's "open" function with the
6088 parameters FILENAME, MODE, PERMS.
6089 The possible values and flag bits of the MODE parameter are system-
6091 dependent; they are available via the standard module "Fcntl". See
6092 the documentation of your operating system's "open" to see which
6093 values and flag bits are available. You may combine several flags
6094 using the "|"-operator.
6095 Some of the most common values are "O_RDONLY" for opening the file
6097 in read-only mode, "O_WRONLY" for opening the file in write-only
6098 mode, and "O_RDWR" for opening the file in read-write mode.
6099 For historical reasons, some values work on almost every system
6101 supported by Perl: 0 means read-only, 1 means write-only, and 2
6102 means read/write. We know that these values do not work under
6103 OS/390 & VM/ESA Unix and on the Macintosh; you probably don't want
6104 to use them in new code.
6105 If the file named by FILENAME does not exist and the "open" call
6107 creates it (typically because MODE includes the "O_CREAT" flag),
6108 then the value of PERMS specifies the permissions of the newly
6109 created file. If you omit the PERMS argument to "sysopen", Perl
6110 uses the octal value 0666. These permission values need to be in
6111 octal, and are modified by your process's current "umask".
6112 In many systems the "O_EXCL" flag is available for opening files in
6114 exclusive mode. This is not locking: exclusiveness means here that
6115 if the file already exists, sysopen() fails. "O_EXCL" may not work
6116 on network filesystems, and has no effect unless the "O_CREAT" flag
6117 is set as well. Setting "O_CREAT|O_EXCL" prevents the file from
6118 being opened if it is a symbolic link. It does not protect against
6119 symbolic links in the file's path.
6120 Sometimes you may want to truncate an already-existing file. This
6122 can be done using the "O_TRUNC" flag. The behavior of "O_TRUNC"
6123 with "O_RDONLY" is undefined.
6124 You should seldom if ever use 0644 as argument to "sysopen",
6126 because that takes away the user's option to have a more permissive
6127 umask. Better to omit it. See the perlfunc(1) entry on "umask"
6128 for more on this.
6129 Note that "sysopen" depends on the fdopen() C library function. On
6131 many Unix systems, fdopen() is known to fail when file descriptors
6132 exceed a certain value, typically 255. If you need more file
6133 descriptors than that, consider rebuilding Perl to use the "sfio"
6134 library, or perhaps using the POSIX::open() function.
6135 See perlopentut for a kinder, gentler explanation of opening files.
6137 sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
6139 sysread FILEHANDLE,SCALAR,LENGTH
6140 Attempts to read LENGTH bytes of data into variable SCALAR from the
6141 specified FILEHANDLE, using the read(2). It bypasses buffered IO,
6142 so mixing this with other kinds of reads, "print", "write", "seek",
6143 "tell", or "eof" can cause confusion because the perlio or stdio
6144 layers usually buffers data. Returns the number of bytes actually
6145 read, 0 at end of file, or undef if there was an error (in the
6146 latter case $! is also set). SCALAR will be grown or shrunk so
6147 that the last byte actually read is the last byte of the scalar
6148 after the read.
6149 An OFFSET may be specified to place the read data at some place in
6151 the string other than the beginning. A negative OFFSET specifies
6152 placement at that many characters counting backwards from the end
6153 of the string. A positive OFFSET greater than the length of SCALAR
6154 results in the string being padded to the required size with "\0"
6155 bytes before the result of the read is appended.
6156 There is no syseof() function, which is ok, since eof() doesn't
6158 work well on device files (like ttys) anyway. Use sysread() and
6159 check for a return value for 0 to decide whether you're done.
6160 Note that if the filehandle has been marked as ":utf8" Unicode
6162 characters are read instead of bytes (the LENGTH, OFFSET, and the
6163 return value of sysread() are in Unicode characters). The
6164 ":encoding(...)" layer implicitly introduces the ":utf8" layer.
6165 See "binmode", "open", and the "open" pragma, open.
6166 sysseek FILEHANDLE,POSITION,WHENCE
6168 Sets FILEHANDLE's system position in bytes using lseek(2).
6169 FILEHANDLE may be an expression whose value gives the name of the
6170 filehandle. The values for WHENCE are 0 to set the new position to
6171 POSITION, 1 to set the it to the current position plus POSITION,
6172 and 2 to set it to EOF plus POSITION (typically negative).
6173 Note the in bytes: even if the filehandle has been set to operate
6175 on characters (for example by using the ":encoding(utf8)" I/O
6176 layer), tell() will return byte offsets, not character offsets
6177 (because implementing that would render sysseek() unacceptably
6178 slow).
6179 sysseek() bypasses normal buffered IO, so mixing this with reads
6181 (other than "sysread", for example "<>" or read()) "print",
6182 "write", "seek", "tell", or "eof" may cause confusion.
6183 For WHENCE, you may also use the constants "SEEK_SET", "SEEK_CUR",
6185 and "SEEK_END" (start of the file, current position, end of the
6186 file) from the Fcntl module. Use of the constants is also more
6187 portable than relying on 0, 1, and 2. For example to define a
6188 "systell" function:
6189 use Fcntl 'SEEK_CUR';
6191 sub systell { sysseek($_[0], 0, SEEK_CUR) }
6192 Returns the new position, or the undefined value on failure. A
6194 position of zero is returned as the string "0 but true"; thus
6195 "sysseek" returns true on success and false on failure, yet you can
6196 still easily determine the new position.
6197 system LIST
6199 system PROGRAM LIST
6200 Does exactly the same thing as "exec LIST", except that a fork is
6201 done first, and the parent process waits for the child process to
6202 exit. Note that argument processing varies depending on the number
6203 of arguments. If there is more than one argument in LIST, or if
6204 LIST is an array with more than one value, starts the program given
6205 by the first element of the list with arguments given by the rest
6206 of the list. If there is only one scalar argument, the argument is
6207 checked for shell metacharacters, and if there are any, the entire
6208 argument is passed to the system's command shell for parsing (this
6209 is "/bin/sh -c" on Unix platforms, but varies on other platforms).
6210 If there are no shell metacharacters in the argument, it is split
6211 into words and passed directly to "execvp", which is more
6212 efficient.
6213 Beginning with v5.6.0, Perl will attempt to flush all files opened
6215 for output before any operation that may do a fork, but this may
6216 not be supported on some platforms (see perlport). To be safe, you
6217 may need to set $| ($AUTOFLUSH in English) or call the
6218 "autoflush()" method of "IO::Handle" on any open handles.
6219 The return value is the exit status of the program as returned by
6221 the "wait" call. To get the actual exit value, shift right by
6222 eight (see below). See also "exec". This is not what you want to
6223 use to capture the output from a command, for that you should use
6224 merely backticks or "qx//", as described in "`STRING`" in perlop.
6225 Return value of -1 indicates a failure to start the program or an
6226 error of the wait(2) system call (inspect $! for the reason).
6227 If you'd like to make "system" (and many other bits of Perl) die on
6229 error, have a look at the autodie pragma.
6230 Like "exec", "system" allows you to lie to a program about its name
6232 if you use the "system PROGRAM LIST" syntax. Again, see "exec".
6233 Since "SIGINT" and "SIGQUIT" are ignored during the execution of
6235 "system", if you expect your program to terminate on receipt of
6236 these signals you will need to arrange to do so yourself based on
6237 the return value.
6238 @args = ("command", "arg1", "arg2");
6240 system(@args) == 0
6241 or die "system @args failed: $?"
6242 If you'd like to manually inspect "system"'s failure, you can check
6244 all possible failure modes by inspecting $? like this:
6245 if ($? == -1) {
6247 print "failed to execute: $!\n";
6248 }
6249 elsif ($? & 127) {
6250 printf "child died with signal %d, %s coredump\n",
6251 ($? & 127), ($? & 128) ? 'with' : 'without';
6252 }
6253 else {
6254 printf "child exited with value %d\n", $? >> 8;
6255 }
6256 Alternatively, you may inspect the value of
6258 "${^CHILD_ERROR_NATIVE}" with the "W*()" calls from the POSIX
6259 module.
6260 When "system"'s arguments are executed indirectly by the shell,
6262 results and return codes are subject to its quirks. See "`STRING`"
6263 in perlop and "exec" for details.
6264 Since "system" does a "fork" and "wait" it may affect a "SIGCHLD"
6266 handler. See perlipc for details.
6267 syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
6269 syswrite FILEHANDLE,SCALAR,LENGTH
6270 syswrite FILEHANDLE,SCALAR
6271 Attempts to write LENGTH bytes of data from variable SCALAR to the
6272 specified FILEHANDLE, using write(2). If LENGTH is not specified,
6273 writes whole SCALAR. It bypasses buffered IO, so mixing this with
6274 reads (other than sysread()), "print", "write", "seek", "tell", or
6275 "eof" may cause confusion because the perlio and stdio layers
6276 usually buffers data. Returns the number of bytes actually
6277 written, or "undef" if there was an error (in this case the errno
6278 variable $! is also set). If the LENGTH is greater than the data
6279 available in the SCALAR after the OFFSET, only as much data as is
6280 available will be written.
6281 An OFFSET may be specified to write the data from some part of the
6283 string other than the beginning. A negative OFFSET specifies
6284 writing that many characters counting backwards from the end of the
6285 string. If SCALAR is of length zero, you can only use an OFFSET of
6286 0.
6287 Warning: If the filehandle is marked ":utf8", Unicode characters
6289 encoded in UTF-8 are written instead of bytes, and the LENGTH,
6290 OFFSET, and return value of syswrite() are in (UTF-8 encoded
6291 Unicode) characters. The ":encoding(...)" layer implicitly
6292 introduces the ":utf8" layer. See "binmode", "open", and the
6293 "open" pragma, open.
6294 tell FILEHANDLE
6296 tell
6297 Returns the current position in bytes for FILEHANDLE, or -1 on
6298 error. FILEHANDLE may be an expression whose value gives the name
6299 of the actual filehandle. If FILEHANDLE is omitted, assumes the
6300 file last read.
6301 Note the in bytes: even if the filehandle has been set to operate
6303 on characters (for example by using the ":encoding(utf8)" open
6304 layer), tell() will return byte offsets, not character offsets
6305 (because that would render seek() and tell() rather slow).
6306 The return value of tell() for the standard streams like the STDIN
6308 depends on the operating system: it may return -1 or something
6309 else. tell() on pipes, fifos, and sockets usually returns -1.
6310 There is no "systell" function. Use "sysseek(FH, 0, 1)" for that.
6312 Do not use tell() (or other buffered I/O operations) on a
6314 filehandle that has been manipulated by sysread(), syswrite() or
6315 sysseek(). Those functions ignore the buffering, while tell() does
6316 not.
6317 telldir DIRHANDLE
6319 Returns the current position of the "readdir" routines on
6320 DIRHANDLE. Value may be given to "seekdir" to access a particular
6321 location in a directory. "telldir" has the same caveats about
6322 possible directory compaction as the corresponding system library
6323 routine.
6324 tie VARIABLE,CLASSNAME,LIST
6326 This function binds a variable to a package class that will provide
6327 the implementation for the variable. VARIABLE is the name of the
6328 variable to be enchanted. CLASSNAME is the name of a class
6329 implementing objects of correct type. Any additional arguments are
6330 passed to the "new" method of the class (meaning "TIESCALAR",
6331 "TIEHANDLE", "TIEARRAY", or "TIEHASH"). Typically these are
6332 arguments such as might be passed to the "dbm_open()" function of
6333 C. The object returned by the "new" method is also returned by the
6334 "tie" function, which would be useful if you want to access other
6335 methods in CLASSNAME.
6336 Note that functions such as "keys" and "values" may return huge
6338 lists when used on large objects, like DBM files. You may prefer
6339 to use the "each" function to iterate over such. Example:
6340 # print out history file offsets
6342 use NDBM_File;
6343 tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
6344 while (($key,$val) = each %HIST) {
6345 print $key, ' = ', unpack('L',$val), "\n";
6346 }
6347 untie(%HIST);
6348 A class implementing a hash should have the following methods:
6350 TIEHASH classname, LIST
6352 FETCH this, key
6353 STORE this, key, value
6354 DELETE this, key
6355 CLEAR this
6356 EXISTS this, key
6357 FIRSTKEY this
6358 NEXTKEY this, lastkey
6359 SCALAR this
6360 DESTROY this
6361 UNTIE this
6362 A class implementing an ordinary array should have the following
6364 methods:
6365 TIEARRAY classname, LIST
6367 FETCH this, key
6368 STORE this, key, value
6369 FETCHSIZE this
6370 STORESIZE this, count
6371 CLEAR this
6372 PUSH this, LIST
6373 POP this
6374 SHIFT this
6375 UNSHIFT this, LIST
6376 SPLICE this, offset, length, LIST
6377 EXTEND this, count
6378 DESTROY this
6379 UNTIE this
6380 A class implementing a filehandle should have the following
6382 methods:
6383 TIEHANDLE classname, LIST
6385 READ this, scalar, length, offset
6386 READLINE this
6387 GETC this
6388 WRITE this, scalar, length, offset
6389 PRINT this, LIST
6390 PRINTF this, format, LIST
6391 BINMODE this
6392 EOF this
6393 FILENO this
6394 SEEK this, position, whence
6395 TELL this
6396 OPEN this, mode, LIST
6397 CLOSE this
6398 DESTROY this
6399 UNTIE this
6400 A class implementing a scalar should have the following methods:
6402 TIESCALAR classname, LIST
6404 FETCH this,
6405 STORE this, value
6406 DESTROY this
6407 UNTIE this
6408 Not all methods indicated above need be implemented. See perltie,
6410 Tie::Hash, Tie::Array, Tie::Scalar, and Tie::Handle.
6411 Unlike "dbmopen", the "tie" function will not "use" or "require" a
6413 module for you; you need to do that explicitly yourself. See
6414 DB_File or the Config module for interesting "tie" implementations.
6415 For further details see perltie, "tied VARIABLE".
6417 tied VARIABLE
6419 Returns a reference to the object underlying VARIABLE (the same
6420 value that was originally returned by the "tie" call that bound the
6421 variable to a package.) Returns the undefined value if VARIABLE
6422 isn't tied to a package.
6423 time
6425 Returns the number of non-leap seconds since whatever time the
6426 system considers to be the epoch, suitable for feeding to "gmtime"
6427 and "localtime". On most systems the epoch is 00:00:00 UTC, January
6428 1, 1970; a prominent exception being Mac OS Classic which uses
6429 00:00:00, January 1, 1904 in the current local time zone for its
6430 epoch.
6431 For measuring time in better granularity than one second, you may
6433 use either the Time::HiRes module (from CPAN, and starting from
6434 Perl 5.8 part of the standard distribution), or if you have
6435 gettimeofday(2), you may be able to use the "syscall" interface of
6436 Perl. See perlfaq8 for details.
6437 For date and time processing look at the many related modules on
6439 CPAN. For a comprehensive date and time representation look at the
6440 DateTime module.
6441 times
6443 Returns a four-element list giving the user and system times, in
6444 seconds, for this process and the children of this process.
6445 ($user,$system,$cuser,$csystem) = times;
6447 In scalar context, "times" returns $user.
6449 Children's times are only included for terminated children.
6451 tr///
6453 The transliteration operator. Same as "y///". See "Quote and
6454 Quote-like Operators" in perlop.
6455 truncate FILEHANDLE,LENGTH
6457 truncate EXPR,LENGTH
6458 Truncates the file opened on FILEHANDLE, or named by EXPR, to the
6459 specified length. Raises an exception if truncate isn't
6460 implemented on your system. Returns true if successful, the
6461 undefined value otherwise.
6462 The behavior is undefined if LENGTH is greater than the length of
6464 the file.
6465 The position in the file of FILEHANDLE is left unchanged. You may
6467 want to call seek before writing to the file.
6468 uc EXPR
6470 uc Returns an uppercased version of EXPR. This is the internal
6471 function implementing the "\U" escape in double-quoted strings. It
6472 does not attempt to do titlecase mapping on initial letters. See
6473 "ucfirst" for that.
6474 If EXPR is omitted, uses $_.
6476 This function behaves the same way under various pragma, such as in
6478 a locale, as "lc" does.
6479 ucfirst EXPR
6481 ucfirst
6482 Returns the value of EXPR with the first character in uppercase
6483 (titlecase in Unicode). This is the internal function implementing
6484 the "\u" escape in double-quoted strings.
6485 If EXPR is omitted, uses $_.
6487 This function behaves the same way under various pragma, such as in
6489 a locale, as "lc" does.
6490 umask EXPR
6492 umask
6493 Sets the umask for the process to EXPR and returns the previous
6494 value. If EXPR is omitted, merely returns the current umask.
6495 The Unix permission "rwxr-x---" is represented as three sets of
6497 three bits, or three octal digits: 0750 (the leading 0 indicates
6498 octal and isn't one of the digits). The "umask" value is such a
6499 number representing disabled permissions bits. The permission (or
6500 "mode") values you pass "mkdir" or "sysopen" are modified by your
6501 umask, so even if you tell "sysopen" to create a file with
6502 permissions 0777, if your umask is 0022 then the file will actually
6503 be created with permissions 0755. If your "umask" were 0027 (group
6504 can't write; others can't read, write, or execute), then passing
6505 "sysopen" 0666 would create a file with mode 0640 ("0666 &~ 027" is
6506 0640).
6507 Here's some advice: supply a creation mode of 0666 for regular
6509 files (in "sysopen") and one of 0777 for directories (in "mkdir")
6510 and executable files. This gives users the freedom of choice: if
6511 they want protected files, they might choose process umasks of 022,
6512 027, or even the particularly antisocial mask of 077. Programs
6513 should rarely if ever make policy decisions better left to the
6514 user. The exception to this is when writing files that should be
6515 kept private: mail files, web browser cookies, .rhosts files, and
6516 so on.
6517 If umask(2) is not implemented on your system and you are trying to
6519 restrict access for yourself (i.e., "(EXPR & 0700) > 0"), raises an
6520 exception. If umask(2) is not implemented and you are not trying
6521 to restrict access for yourself, returns "undef".
6522 Remember that a umask is a number, usually given in octal; it is
6524 not a string of octal digits. See also "oct", if all you have is a
6525 string.
6526 undef EXPR
6528 undef
6529 Undefines the value of EXPR, which must be an lvalue. Use only on
6530 a scalar value, an array (using "@"), a hash (using "%"), a
6531 subroutine (using "&"), or a typeglob (using "*"). Saying "undef
6532 $hash{$key}" will probably not do what you expect on most
6533 predefined variables or DBM list values, so don't do that; see
6534 delete. Always returns the undefined value. You can omit the
6535 EXPR, in which case nothing is undefined, but you still get an
6536 undefined value that you could, for instance, return from a
6537 subroutine, assign to a variable, or pass as a parameter.
6538 Examples:
6539 undef $foo;
6541 undef $bar{'blurfl'}; # Compare to: delete $bar{'blurfl'};
6542 undef @ary;
6543 undef %hash;
6544 undef &mysub;
6545 undef *xyz; # destroys $xyz, @xyz, %xyz, &xyz, etc.
6546 return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
6547 select undef, undef, undef, 0.25;
6548 ($a, $b, undef, $c) = &foo; # Ignore third value returned
6549 Note that this is a unary operator, not a list operator.
6551 unlink LIST
6553 unlink
6554 Deletes a list of files. On success, it returns the number of files
6555 it successfully deleted. On failure, it returns false and sets $!
6556 (errno):
6557 my $unlinked = unlink 'a', 'b', 'c';
6559 unlink @goners;
6560 unlink glob "*.bak";
6561 On error, "unlink" will not tell you which files it could not
6563 remove. If you want to know which files you could not remove, try
6564 them one at a time:
6565 foreach my $file ( @goners ) {
6567 unlink $file or warn "Could not unlink $file: $!";
6568 }
6569 Note: "unlink" will not attempt to delete directories unless you
6571 are superuser and the -U flag is supplied to Perl. Even if these
6572 conditions are met, be warned that unlinking a directory can
6573 inflict damage on your filesystem. Finally, using "unlink" on
6574 directories is not supported on many operating systems. Use
6575 "rmdir" instead.
6576 If LIST is omitted, "unlink" uses $_.
6578 unpack TEMPLATE,EXPR
6580 unpack TEMPLATE
6581 "unpack" does the reverse of "pack": it takes a string and expands
6582 it out into a list of values. (In scalar context, it returns
6583 merely the first value produced.)
6584 If EXPR is omitted, unpacks the $_ string. See perlpacktut for an
6586 introduction to this function.
6587 The string is broken into chunks described by the TEMPLATE. Each
6589 chunk is converted separately to a value. Typically, either the
6590 string is a result of "pack", or the characters of the string
6591 represent a C structure of some kind.
6592 The TEMPLATE has the same format as in the "pack" function. Here's
6594 a subroutine that does substring:
6595 sub substr {
6597 my($what,$where,$howmuch) = @_;
6598 unpack("x$where a$howmuch", $what);
6599 }
6600 and then there's
6602 sub ordinal { unpack("W",$_[0]); } # same as ord()
6604 In addition to fields allowed in pack(), you may prefix a field
6606 with a %<number> to indicate that you want a <number>-bit checksum
6607 of the items instead of the items themselves. Default is a 16-bit
6608 checksum. Checksum is calculated by summing numeric values of
6609 expanded values (for string fields the sum of "ord($char)" is
6610 taken, for bit fields the sum of zeroes and ones).
6611 For example, the following computes the same number as the System V
6613 sum program:
6614 $checksum = do {
6616 local $/; # slurp!
6617 unpack("%32W*",<>) % 65535;
6618 };
6619 The following efficiently counts the number of set bits in a bit
6621 vector:
6622 $setbits = unpack("%32b*", $selectmask);
6624 The "p" and "P" formats should be used with care. Since Perl has
6626 no way of checking whether the value passed to "unpack()"
6627 corresponds to a valid memory location, passing a pointer value
6628 that's not known to be valid is likely to have disastrous
6629 consequences.
6630 If there are more pack codes or if the repeat count of a field or a
6632 group is larger than what the remainder of the input string allows,
6633 the result is not well defined: the repeat count may be decreased,
6634 or "unpack()" may produce empty strings or zeros, or it may raise
6635 an exception. If the input string is longer than one described by
6636 the TEMPLATE, the remainder of that input string is ignored.
6637 See "pack" for more examples and notes.
6639 untie VARIABLE
6641 Breaks the binding between a variable and a package. (See "tie".)
6642 Has no effect if the variable is not tied.
6643 unshift ARRAY,LIST
6645 Does the opposite of a "shift". Or the opposite of a "push",
6646 depending on how you look at it. Prepends list to the front of the
6647 array, and returns the new number of elements in the array.
6648 unshift(@ARGV, '-e') unless $ARGV[0] =~ /^-/;
6650 Note the LIST is prepended whole, not one element at a time, so the
6652 prepended elements stay in the same order. Use "reverse" to do the
6653 reverse.
6654 use Module VERSION LIST
6656 use Module VERSION
6657 use Module LIST
6658 use Module
6659 use VERSION
6660 Imports some semantics into the current package from the named
6661 module, generally by aliasing certain subroutine or variable names
6662 into your package. It is exactly equivalent to
6663 BEGIN { require Module; Module->import( LIST ); }
6665 except that Module must be a bareword.
6667 In the peculiar "use VERSION" form, VERSION may be either a
6669 positive decimal fraction such as 5.006, which will be compared to
6670 $], or a v-string of the form v5.6.1, which will be compared to $^V
6671 (aka $PERL_VERSION). An exception is raised if VERSION is greater
6672 than the version of the current Perl interpreter; Perl will not
6673 attempt to parse the rest of the file. Compare with "require",
6674 which can do a similar check at run time. Symmetrically, "no
6675 VERSION" allows you to specify that you want a version of Perl
6676 older than the specified one.
6677 Specifying VERSION as a literal of the form v5.6.1 should generally
6679 be avoided, because it leads to misleading error messages under
6680 earlier versions of Perl (that is, prior to 5.6.0) that do not
6681 support this syntax. The equivalent numeric version should be used
6682 instead.
6683 use v5.6.1; # compile time version check
6685 use 5.6.1; # ditto
6686 use 5.006_001; # ditto; preferred for backwards compatibility
6687 This is often useful if you need to check the current Perl version
6689 before "use"ing library modules that won't work with older versions
6690 of Perl. (We try not to do this more than we have to.)
6691 Also, if the specified Perl version is greater than or equal to
6693 5.9.5, "use VERSION" will also load the "feature" pragma and enable
6694 all features available in the requested version. See feature.
6695 Similarly, if the specified Perl version is greater than or equal
6696 to 5.11.0, strictures are enabled lexically as with "use strict"
6697 (except that the strict.pm file is not actually loaded).
6698 The "BEGIN" forces the "require" and "import" to happen at compile
6700 time. The "require" makes sure the module is loaded into memory if
6701 it hasn't been yet. The "import" is not a builtin; it's just an
6702 ordinary static method call into the "Module" package to tell the
6703 module to import the list of features back into the current
6704 package. The module can implement its "import" method any way it
6705 likes, though most modules just choose to derive their "import"
6706 method via inheritance from the "Exporter" class that is defined in
6707 the "Exporter" module. See Exporter. If no "import" method can be
6708 found then the call is skipped, even if there is an AUTOLOAD
6709 method.
6710 If you do not want to call the package's "import" method (for
6712 instance, to stop your namespace from being altered), explicitly
6713 supply the empty list:
6714 use Module ();
6716 That is exactly equivalent to
6718 BEGIN { require Module }
6720 If the VERSION argument is present between Module and LIST, then
6722 the "use" will call the VERSION method in class Module with the
6723 given version as an argument. The default VERSION method,
6724 inherited from the UNIVERSAL class, croaks if the given version is
6725 larger than the value of the variable $Module::VERSION.
6726 Again, there is a distinction between omitting LIST ("import"
6728 called with no arguments) and an explicit empty LIST "()" ("import"
6729 not called). Note that there is no comma after VERSION!
6730 Because this is a wide-open interface, pragmas (compiler
6732 directives) are also implemented this way. Currently implemented
6733 pragmas are:
6734 use constant;
6736 use diagnostics;
6737 use integer;
6738 use sigtrap qw(SEGV BUS);
6739 use strict qw(subs vars refs);
6740 use subs qw(afunc blurfl);
6741 use warnings qw(all);
6742 use sort qw(stable _quicksort _mergesort);
6743 Some of these pseudo-modules import semantics into the current
6745 block scope (like "strict" or "integer", unlike ordinary modules,
6746 which import symbols into the current package (which are effective
6747 through the end of the file).
6748 Because "use" takes effect at compile time, it doesn't respect the
6750 ordinary flow control of the code being compiled. In particular,
6751 putting a "use" inside the false branch of a conditional doesn't
6752 prevent it from being processed. If a module or pragma only needs
6753 to be loaded conditionally, this can be done using the if pragma:
6754 use if $] < 5.008, "utf8";
6756 use if WANT_WARNINGS, warnings => qw(all);
6757 There's a corresponding "no" command that unimports meanings
6759 imported by "use", i.e., it calls "unimport Module LIST" instead of
6760 "import". It behaves just as "import" does with VERSION, an
6761 omitted or empty LIST, or no unimport method being found.
6762 no integer;
6764 no strict 'refs';
6765 no warnings;
6766 Care should be taken when using the "no VERSION" form of "no". It
6768 is only meant to be used to assert that the running perl is of a
6769 earlier version than its argument and not to undo the feature-
6770 enabling side effects of "use VERSION".
6771 See perlmodlib for a list of standard modules and pragmas. See
6773 perlrun for the "-M" and "-m" command-line options to Perl that
6774 give "use" functionality from the command-line.
6775 utime LIST
6777 Changes the access and modification times on each file of a list of
6778 files. The first two elements of the list must be the NUMERICAL
6779 access and modification times, in that order. Returns the number
6780 of files successfully changed. The inode change time of each file
6781 is set to the current time. For example, this code has the same
6782 effect as the Unix touch(1) command when the files already exist
6783 and belong to the user running the program:
6784 #!/usr/bin/perl
6786 $atime = $mtime = time;
6787 utime $atime, $mtime, @ARGV;
6788 Since Perl 5.7.2, if the first two elements of the list are
6790 "undef", the utime(2) syscall from your C library is called with a
6791 null second argument. On most systems, this will set the file's
6792 access and modification times to the current time (i.e., equivalent
6793 to the example above) and will work even on files you don't own
6794 provided you have write permission:
6795 for $file (@ARGV) {
6797 utime(undef, undef, $file)
6798 || warn "couldn't touch $file: $!";
6799 }
6800 Under NFS this will use the time of the NFS server, not the time of
6802 the local machine. If there is a time synchronization problem, the
6803 NFS server and local machine will have different times. The Unix
6804 touch(1) command will in fact normally use this form instead of the
6805 one shown in the first example.
6806 Passing only one of the first two elements as "undef" is equivalent
6808 to passing a 0 and will not have the effect described when both are
6809 "undef". This also triggers an uninitialized warning.
6810 On systems that support futimes(2), you may pass filehandles among
6812 the files. On systems that don't support futimes(2), passing
6813 filehandles raises an exception. Filehandles must be passed as
6814 globs or glob references to be recognized; barewords are considered
6815 filenames.
6816 values HASH
6818 values ARRAY
6819 Returns a list consisting of all the values of the named hash, or
6820 the values of an array. (In a scalar context, returns the number of
6821 values.)
6822 The values are returned in an apparently random order. The actual
6824 random order is subject to change in future versions of Perl, but
6825 it is guaranteed to be the same order as either the "keys" or
6826 "each" function would produce on the same (unmodified) hash. Since
6827 Perl 5.8.1 the ordering is different even between different runs of
6828 Perl for security reasons (see "Algorithmic Complexity Attacks" in
6829 perlsec).
6830 As a side effect, calling values() resets the HASH or ARRAY's
6832 internal iterator, see "each". (In particular, calling values() in
6833 void context resets the iterator with no other overhead. Apart from
6834 resetting the iterator, "values @array" in list context is the same
6835 as plain @array. We recommend that you use void context "keys
6836 @array" for this, but reasoned that it taking "values @array" out
6837 would require more documentation than leaving it in.)
6838 Note that the values are not copied, which means modifying them
6840 will modify the contents of the hash:
6841 for (values %hash) { s/foo/bar/g } # modifies %hash values
6843 for (@hash{keys %hash}) { s/foo/bar/g } # same
6844 See also "keys", "each", and "sort".
6846 vec EXPR,OFFSET,BITS
6848 Treats the string in EXPR as a bit vector made up of elements of
6849 width BITS, and returns the value of the element specified by
6850 OFFSET as an unsigned integer. BITS therefore specifies the number
6851 of bits that are reserved for each element in the bit vector. This
6852 must be a power of two from 1 to 32 (or 64, if your platform
6853 supports that).
6854 If BITS is 8, "elements" coincide with bytes of the input string.
6856 If BITS is 16 or more, bytes of the input string are grouped into
6858 chunks of size BITS/8, and each group is converted to a number as
6859 with pack()/unpack() with big-endian formats "n"/"N" (and
6860 analogously for BITS==64). See "pack" for details.
6861 If bits is 4 or less, the string is broken into bytes, then the
6863 bits of each byte are broken into 8/BITS groups. Bits of a byte
6864 are numbered in a little-endian-ish way, as in 0x01, 0x02, 0x04,
6865 0x08, 0x10, 0x20, 0x40, 0x80. For example, breaking the single
6866 input byte "chr(0x36)" into two groups gives a list "(0x6, 0x3)";
6867 breaking it into 4 groups gives "(0x2, 0x1, 0x3, 0x0)".
6868 "vec" may also be assigned to, in which case parentheses are needed
6870 to give the expression the correct precedence as in
6871 vec($image, $max_x * $x + $y, 8) = 3;
6873 If the selected element is outside the string, the value 0 is
6875 returned. If an element off the end of the string is written to,
6876 Perl will first extend the string with sufficiently many zero
6877 bytes. It is an error to try to write off the beginning of the
6878 string (i.e., negative OFFSET).
6879 If the string happens to be encoded as UTF-8 internally (and thus
6881 has the UTF8 flag set), this is ignored by "vec", and it operates
6882 on the internal byte string, not the conceptual character string,
6883 even if you only have characters with values less than 256.
6884 Strings created with "vec" can also be manipulated with the logical
6886 operators "|", "&", "^", and "~". These operators will assume a
6887 bit vector operation is desired when both operands are strings.
6888 See "Bitwise String Operators" in perlop.
6889 The following code will build up an ASCII string saying
6891 'PerlPerlPerl'. The comments show the string after each step.
6892 Note that this code works in the same way on big-endian or little-
6893 endian machines.
6894 my $foo = '';
6896 vec($foo, 0, 32) = 0x5065726C; # 'Perl'
6897 # $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits
6899 print vec($foo, 0, 8); # prints 80 == 0x50 == ord('P')
6900 vec($foo, 2, 16) = 0x5065; # 'PerlPe'
6902 vec($foo, 3, 16) = 0x726C; # 'PerlPerl'
6903 vec($foo, 8, 8) = 0x50; # 'PerlPerlP'
6904 vec($foo, 9, 8) = 0x65; # 'PerlPerlPe'
6905 vec($foo, 20, 4) = 2; # 'PerlPerlPe' . "\x02"
6906 vec($foo, 21, 4) = 7; # 'PerlPerlPer'
6907 # 'r' is "\x72"
6908 vec($foo, 45, 2) = 3; # 'PerlPerlPer' . "\x0c"
6909 vec($foo, 93, 1) = 1; # 'PerlPerlPer' . "\x2c"
6910 vec($foo, 94, 1) = 1; # 'PerlPerlPerl'
6911 # 'l' is "\x6c"
6912 To transform a bit vector into a string or list of 0's and 1's, use
6914 these:
6915 $bits = unpack("b*", $vector);
6917 @bits = split(//, unpack("b*", $vector));
6918 If you know the exact length in bits, it can be used in place of
6920 the "*".
6921 Here is an example to illustrate how the bits actually fall in
6923 place:
6924 #!/usr/bin/perl -wl
6926 print <<'EOT';
6928 0 1 2 3
6929 unpack("V",$_) 01234567890123456789012345678901
6930 ------------------------------------------------------------------
6931 EOT
6932 for $w (0..3) {
6934 $width = 2**$w;
6935 for ($shift=0; $shift < $width; ++$shift) {
6936 for ($off=0; $off < 32/$width; ++$off) {
6937 $str = pack("B*", "0"x32);
6938 $bits = (1<<$shift);
6939 vec($str, $off, $width) = $bits;
6940 $res = unpack("b*",$str);
6941 $val = unpack("V", $str);
6942 write;
6943 }
6944 }
6945 }
6946 format STDOUT =
6948 vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
6949 $off, $width, $bits, $val, $res
6950 .
6951 __END__
6952 Regardless of the machine architecture on which it runs, the
6954 example above should print the following table:
6955 0 1 2 3
6957 unpack("V",$_) 01234567890123456789012345678901
6958 ------------------------------------------------------------------
6959 vec($_, 0, 1) = 1 == 1 10000000000000000000000000000000
6960 vec($_, 1, 1) = 1 == 2 01000000000000000000000000000000
6961 vec($_, 2, 1) = 1 == 4 00100000000000000000000000000000
6962 vec($_, 3, 1) = 1 == 8 00010000000000000000000000000000
6963 vec($_, 4, 1) = 1 == 16 00001000000000000000000000000000
6964 vec($_, 5, 1) = 1 == 32 00000100000000000000000000000000
6965 vec($_, 6, 1) = 1 == 64 00000010000000000000000000000000
6966 vec($_, 7, 1) = 1 == 128 00000001000000000000000000000000
6967 vec($_, 8, 1) = 1 == 256 00000000100000000000000000000000
6968 vec($_, 9, 1) = 1 == 512 00000000010000000000000000000000
6969 vec($_,10, 1) = 1 == 1024 00000000001000000000000000000000
6970 vec($_,11, 1) = 1 == 2048 00000000000100000000000000000000
6971 vec($_,12, 1) = 1 == 4096 00000000000010000000000000000000
6972 vec($_,13, 1) = 1 == 8192 00000000000001000000000000000000
6973 vec($_,14, 1) = 1 == 16384 00000000000000100000000000000000
6974 vec($_,15, 1) = 1 == 32768 00000000000000010000000000000000
6975 vec($_,16, 1) = 1 == 65536 00000000000000001000000000000000
6976 vec($_,17, 1) = 1 == 131072 00000000000000000100000000000000
6977 vec($_,18, 1) = 1 == 262144 00000000000000000010000000000000
6978 vec($_,19, 1) = 1 == 524288 00000000000000000001000000000000
6979 vec($_,20, 1) = 1 == 1048576 00000000000000000000100000000000
6980 vec($_,21, 1) = 1 == 2097152 00000000000000000000010000000000
6981 vec($_,22, 1) = 1 == 4194304 00000000000000000000001000000000
6982 vec($_,23, 1) = 1 == 8388608 00000000000000000000000100000000
6983 vec($_,24, 1) = 1 == 16777216 00000000000000000000000010000000
6984 vec($_,25, 1) = 1 == 33554432 00000000000000000000000001000000
6985 vec($_,26, 1) = 1 == 67108864 00000000000000000000000000100000
6986 vec($_,27, 1) = 1 == 134217728 00000000000000000000000000010000
6987 vec($_,28, 1) = 1 == 268435456 00000000000000000000000000001000
6988 vec($_,29, 1) = 1 == 536870912 00000000000000000000000000000100
6989 vec($_,30, 1) = 1 == 1073741824 00000000000000000000000000000010
6990 vec($_,31, 1) = 1 == 2147483648 00000000000000000000000000000001
6991 vec($_, 0, 2) = 1 == 1 10000000000000000000000000000000
6992 vec($_, 1, 2) = 1 == 4 00100000000000000000000000000000
6993 vec($_, 2, 2) = 1 == 16 00001000000000000000000000000000
6994 vec($_, 3, 2) = 1 == 64 00000010000000000000000000000000
6995 vec($_, 4, 2) = 1 == 256 00000000100000000000000000000000
6996 vec($_, 5, 2) = 1 == 1024 00000000001000000000000000000000
6997 vec($_, 6, 2) = 1 == 4096 00000000000010000000000000000000
6998 vec($_, 7, 2) = 1 == 16384 00000000000000100000000000000000
6999 vec($_, 8, 2) = 1 == 65536 00000000000000001000000000000000
7000 vec($_, 9, 2) = 1 == 262144 00000000000000000010000000000000
7001 vec($_,10, 2) = 1 == 1048576 00000000000000000000100000000000
7002 vec($_,11, 2) = 1 == 4194304 00000000000000000000001000000000
7003 vec($_,12, 2) = 1 == 16777216 00000000000000000000000010000000
7004 vec($_,13, 2) = 1 == 67108864 00000000000000000000000000100000
7005 vec($_,14, 2) = 1 == 268435456 00000000000000000000000000001000
7006 vec($_,15, 2) = 1 == 1073741824 00000000000000000000000000000010
7007 vec($_, 0, 2) = 2 == 2 01000000000000000000000000000000
7008 vec($_, 1, 2) = 2 == 8 00010000000000000000000000000000
7009 vec($_, 2, 2) = 2 == 32 00000100000000000000000000000000
7010 vec($_, 3, 2) = 2 == 128 00000001000000000000000000000000
7011 vec($_, 4, 2) = 2 == 512 00000000010000000000000000000000
7012 vec($_, 5, 2) = 2 == 2048 00000000000100000000000000000000
7013 vec($_, 6, 2) = 2 == 8192 00000000000001000000000000000000
7014 vec($_, 7, 2) = 2 == 32768 00000000000000010000000000000000
7015 vec($_, 8, 2) = 2 == 131072 00000000000000000100000000000000
7016 vec($_, 9, 2) = 2 == 524288 00000000000000000001000000000000
7017 vec($_,10, 2) = 2 == 2097152 00000000000000000000010000000000
7018 vec($_,11, 2) = 2 == 8388608 00000000000000000000000100000000
7019 vec($_,12, 2) = 2 == 33554432 00000000000000000000000001000000
7020 vec($_,13, 2) = 2 == 134217728 00000000000000000000000000010000
7021 vec($_,14, 2) = 2 == 536870912 00000000000000000000000000000100
7022 vec($_,15, 2) = 2 == 2147483648 00000000000000000000000000000001
7023 vec($_, 0, 4) = 1 == 1 10000000000000000000000000000000
7024 vec($_, 1, 4) = 1 == 16 00001000000000000000000000000000
7025 vec($_, 2, 4) = 1 == 256 00000000100000000000000000000000
7026 vec($_, 3, 4) = 1 == 4096 00000000000010000000000000000000
7027 vec($_, 4, 4) = 1 == 65536 00000000000000001000000000000000
7028 vec($_, 5, 4) = 1 == 1048576 00000000000000000000100000000000
7029 vec($_, 6, 4) = 1 == 16777216 00000000000000000000000010000000
7030 vec($_, 7, 4) = 1 == 268435456 00000000000000000000000000001000
7031 vec($_, 0, 4) = 2 == 2 01000000000000000000000000000000
7032 vec($_, 1, 4) = 2 == 32 00000100000000000000000000000000
7033 vec($_, 2, 4) = 2 == 512 00000000010000000000000000000000
7034 vec($_, 3, 4) = 2 == 8192 00000000000001000000000000000000
7035 vec($_, 4, 4) = 2 == 131072 00000000000000000100000000000000
7036 vec($_, 5, 4) = 2 == 2097152 00000000000000000000010000000000
7037 vec($_, 6, 4) = 2 == 33554432 00000000000000000000000001000000
7038 vec($_, 7, 4) = 2 == 536870912 00000000000000000000000000000100
7039 vec($_, 0, 4) = 4 == 4 00100000000000000000000000000000
7040 vec($_, 1, 4) = 4 == 64 00000010000000000000000000000000
7041 vec($_, 2, 4) = 4 == 1024 00000000001000000000000000000000
7042 vec($_, 3, 4) = 4 == 16384 00000000000000100000000000000000
7043 vec($_, 4, 4) = 4 == 262144 00000000000000000010000000000000
7044 vec($_, 5, 4) = 4 == 4194304 00000000000000000000001000000000
7045 vec($_, 6, 4) = 4 == 67108864 00000000000000000000000000100000
7046 vec($_, 7, 4) = 4 == 1073741824 00000000000000000000000000000010
7047 vec($_, 0, 4) = 8 == 8 00010000000000000000000000000000
7048 vec($_, 1, 4) = 8 == 128 00000001000000000000000000000000
7049 vec($_, 2, 4) = 8 == 2048 00000000000100000000000000000000
7050 vec($_, 3, 4) = 8 == 32768 00000000000000010000000000000000
7051 vec($_, 4, 4) = 8 == 524288 00000000000000000001000000000000
7052 vec($_, 5, 4) = 8 == 8388608 00000000000000000000000100000000
7053 vec($_, 6, 4) = 8 == 134217728 00000000000000000000000000010000
7054 vec($_, 7, 4) = 8 == 2147483648 00000000000000000000000000000001
7055 vec($_, 0, 8) = 1 == 1 10000000000000000000000000000000
7056 vec($_, 1, 8) = 1 == 256 00000000100000000000000000000000
7057 vec($_, 2, 8) = 1 == 65536 00000000000000001000000000000000
7058 vec($_, 3, 8) = 1 == 16777216 00000000000000000000000010000000
7059 vec($_, 0, 8) = 2 == 2 01000000000000000000000000000000
7060 vec($_, 1, 8) = 2 == 512 00000000010000000000000000000000
7061 vec($_, 2, 8) = 2 == 131072 00000000000000000100000000000000
7062 vec($_, 3, 8) = 2 == 33554432 00000000000000000000000001000000
7063 vec($_, 0, 8) = 4 == 4 00100000000000000000000000000000
7064 vec($_, 1, 8) = 4 == 1024 00000000001000000000000000000000
7065 vec($_, 2, 8) = 4 == 262144 00000000000000000010000000000000
7066 vec($_, 3, 8) = 4 == 67108864 00000000000000000000000000100000
7067 vec($_, 0, 8) = 8 == 8 00010000000000000000000000000000
7068 vec($_, 1, 8) = 8 == 2048 00000000000100000000000000000000
7069 vec($_, 2, 8) = 8 == 524288 00000000000000000001000000000000
7070 vec($_, 3, 8) = 8 == 134217728 00000000000000000000000000010000
7071 vec($_, 0, 8) = 16 == 16 00001000000000000000000000000000
7072 vec($_, 1, 8) = 16 == 4096 00000000000010000000000000000000
7073 vec($_, 2, 8) = 16 == 1048576 00000000000000000000100000000000
7074 vec($_, 3, 8) = 16 == 268435456 00000000000000000000000000001000
7075 vec($_, 0, 8) = 32 == 32 00000100000000000000000000000000
7076 vec($_, 1, 8) = 32 == 8192 00000000000001000000000000000000
7077 vec($_, 2, 8) = 32 == 2097152 00000000000000000000010000000000
7078 vec($_, 3, 8) = 32 == 536870912 00000000000000000000000000000100
7079 vec($_, 0, 8) = 64 == 64 00000010000000000000000000000000
7080 vec($_, 1, 8) = 64 == 16384 00000000000000100000000000000000
7081 vec($_, 2, 8) = 64 == 4194304 00000000000000000000001000000000
7082 vec($_, 3, 8) = 64 == 1073741824 00000000000000000000000000000010
7083 vec($_, 0, 8) = 128 == 128 00000001000000000000000000000000
7084 vec($_, 1, 8) = 128 == 32768 00000000000000010000000000000000
7085 vec($_, 2, 8) = 128 == 8388608 00000000000000000000000100000000
7086 vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
7087 wait
7089 Behaves like wait(2) on your system: it waits for a child process
7090 to terminate and returns the pid of the deceased process, or "-1"
7091 if there are no child processes. The status is returned in $? and
7092 "${^CHILD_ERROR_NATIVE}". Note that a return value of "-1" could
7093 mean that child processes are being automatically reaped, as
7094 described in perlipc.
7095 If you use wait in your handler for $SIG{CHLD} it may accidently
7097 wait for the child created by qx() or system(). See perlipc for
7098 details.
7099 waitpid PID,FLAGS
7101 Waits for a particular child process to terminate and returns the
7102 pid of the deceased process, or "-1" if there is no such child
7103 process. On some systems, a value of 0 indicates that there are
7104 processes still running. The status is returned in $? and
7105 "${^CHILD_ERROR_NATIVE}". If you say
7106 use POSIX ":sys_wait_h";
7108 #...
7109 do {
7110 $kid = waitpid(-1, WNOHANG);
7111 } while $kid > 0;
7112 then you can do a non-blocking wait for all pending zombie
7114 processes. Non-blocking wait is available on machines supporting
7115 either the waitpid(2) or wait4(2) syscalls. However, waiting for a
7116 particular pid with FLAGS of 0 is implemented everywhere. (Perl
7117 emulates the system call by remembering the status values of
7118 processes that have exited but have not been harvested by the Perl
7119 script yet.)
7120 Note that on some systems, a return value of "-1" could mean that
7122 child processes are being automatically reaped. See perlipc for
7123 details, and for other examples.
7124 wantarray
7126 Returns true if the context of the currently executing subroutine
7127 or "eval" is looking for a list value. Returns false if the
7128 context is looking for a scalar. Returns the undefined value if
7129 the context is looking for no value (void context).
7130 return unless defined wantarray; # don't bother doing more
7132 my @a = complex_calculation();
7133 return wantarray ? @a : "@a";
7134 "wantarray()"'s result is unspecified in the top level of a file,
7136 in a "BEGIN", "UNITCHECK", "CHECK", "INIT" or "END" block, or in a
7137 "DESTROY" method.
7138 This function should have been named wantlist() instead.
7140 warn LIST
7142 Prints the value of LIST to STDERR. If the last element of LIST
7143 does not end in a newline, it appends the same file/line number
7144 text as "die" does.
7145 If the output is empty and $@ already contains a value (typically
7147 from a previous eval) that value is used after appending
7148 "\t...caught" to $@. This is useful for staying almost, but not
7149 entirely similar to "die".
7150 If $@ is empty then the string "Warning: Something's wrong" is
7152 used.
7153 No message is printed if there is a $SIG{__WARN__} handler
7155 installed. It is the handler's responsibility to deal with the
7156 message as it sees fit (like, for instance, converting it into a
7157 "die"). Most handlers must therefore arrange to actually display
7158 the warnings that they are not prepared to deal with, by calling
7159 "warn" again in the handler. Note that this is quite safe and will
7160 not produce an endless loop, since "__WARN__" hooks are not called
7161 from inside one.
7162 You will find this behavior is slightly different from that of
7164 $SIG{__DIE__} handlers (which don't suppress the error text, but
7165 can instead call "die" again to change it).
7166 Using a "__WARN__" handler provides a powerful way to silence all
7168 warnings (even the so-called mandatory ones). An example:
7169 # wipe out *all* compile-time warnings
7171 BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
7172 my $foo = 10;
7173 my $foo = 20; # no warning about duplicate my $foo,
7174 # but hey, you asked for it!
7175 # no compile-time or run-time warnings before here
7176 $DOWARN = 1;
7177 # run-time warnings enabled after here
7179 warn "\$foo is alive and $foo!"; # does show up
7180 See perlvar for details on setting %SIG entries, and for more
7182 examples. See the Carp module for other kinds of warnings using
7183 its carp() and cluck() functions.
7184 write FILEHANDLE
7186 write EXPR
7187 write
7188 Writes a formatted record (possibly multi-line) to the specified
7189 FILEHANDLE, using the format associated with that file. By default
7190 the format for a file is the one having the same name as the
7191 filehandle, but the format for the current output channel (see the
7192 "select" function) may be set explicitly by assigning the name of
7193 the format to the $~ variable.
7194 Top of form processing is handled automatically: if there is
7196 insufficient room on the current page for the formatted record, the
7197 page is advanced by writing a form feed, a special top-of-page
7198 format is used to format the new page header, and then the record
7199 is written. By default the top-of-page format is the name of the
7200 filehandle with "_TOP" appended, but it may be dynamically set to
7201 the format of your choice by assigning the name to the $^ variable
7202 while the filehandle is selected. The number of lines remaining on
7203 the current page is in variable "$-", which can be set to 0 to
7204 force a new page.
7205 If FILEHANDLE is unspecified, output goes to the current default
7207 output channel, which starts out as STDOUT but may be changed by
7208 the "select" operator. If the FILEHANDLE is an EXPR, then the
7209 expression is evaluated and the resulting string is used to look up
7210 the name of the FILEHANDLE at run time. For more on formats, see
7211 perlform.
7212 Note that write is not the opposite of "read". Unfortunately.
7214 y///
7216 The transliteration operator. Same as "tr///". See "Quote and
7217 Quote-like Operators" in perlop.
7218perl v5.12.4 2011-06-07 PERLFUNC(1)