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