1N/Aperlfunc - Perl builtin functions
1N/AThe functions in this section can serve as terms in an expression.
1N/AThey fall into two major categories: list operators and named unary
1N/Aoperators. These differ in their precedence relationship with a
1N/Afollowing comma. (See the precedence table in L<perlop>.) List
1N/Aoperators take more than one argument, while unary operators can never
1N/Atake more than one argument. Thus, a comma terminates the argument of
1N/Aa unary operator, but merely separates the arguments of a list
1N/Aoperator. A unary operator generally provides a scalar context to its
1N/Aargument, while a list operator may provide either scalar or list
1N/Acontexts for its arguments. If it does both, the scalar arguments will
1N/Abe first, and the list argument will follow. (Note that there can ever
1N/Abe only one such list argument.) For instance, splice() has three scalar
1N/Aarguments followed by a list, whereas gethostbyname() has four scalar
1N/AIn the syntax descriptions that follow, list operators that expect a
1N/Alist (and provide list context for the elements of the list) are shown
1N/Awith LIST as an argument. Such a list may consist of any combination
1N/Aof scalar arguments or list values; the list values will be included
1N/Ain the list as if each individual element were interpolated at that
1N/Apoint in the list, forming a longer single-dimensional list value.
1N/AElements of the LIST should be separated by commas.
1N/AAny function in the list below may be used either with or without
1N/Aparentheses around its arguments. (The syntax descriptions omit the
1N/Aparentheses.) If you use the parentheses, the simple (but occasionally
1N/Asurprising) rule is this: It I<looks> like a function, therefore it I<is> a
1N/Afunction, and precedence doesn't matter. Otherwise it's a list
1N/Aoperator or unary operator, and precedence does matter. And whitespace
1N/Abetween the function and left parenthesis doesn't count--so you need to
1N/Abe careful sometimes:
1N/A print 1+2+4; # Prints 7.
1N/A print(1+2) + 4; # Prints 3.
1N/A print (1+2)+4; # Also prints 3!
1N/A print +(1+2)+4; # Prints 7.
1N/A print ((1+2)+4); # Prints 7.
1N/AIf you run Perl with the B<-w> switch it can warn you about this. For
1N/Aexample, the third line above produces:
1N/A print (...) interpreted as function at - line 1.
1N/A Useless use of integer addition in void context at - line 1.
1N/AA few functions take no arguments at all, and therefore work as neither
1N/Aunary nor list operators. These include such functions as C<time>
1N/Aand C<endpwent>. For example, C<time+86_400> always means
1N/AFor functions that can be used in either a scalar or list context,
1N/Anonabortive failure is generally indicated in a scalar context by
1N/Areturning the undefined value, and in a list context by returning the
1N/ARemember the following important rule: There is B<no rule> that relates
1N/Athe behavior of an expression in list context to its behavior in scalar
1N/Acontext, or vice versa. It might do two totally different things.
1N/AEach operator and function decides which sort of value it would be most
1N/Aappropriate to return in scalar context. Some operators return the
1N/Alength of the list that would have been returned in list context. Some
1N/Aoperators return the first value in the list. Some operators return the
1N/Alast value in the list. Some operators return a count of successful
1N/Aoperations. In general, they do what you want, unless you want
1N/AA named array in scalar context is quite different from what would at
1N/Afirst glance appear to be a list in scalar context. You can't get a list
1N/Alike C<(1,2,3)> into being in scalar context, because the compiler knows
1N/Athe context at compile time. It would generate the scalar comma operator
1N/Athere, not the list construction version of the comma. That means it
1N/Awas never a list to start with.
1N/AIn general, functions in Perl that serve as wrappers for system calls
1N/Aof the same name (like chown(2), fork(2), closedir(2), etc.) all return
1N/Atrue when they succeed and C<undef> otherwise, as is usually mentioned
1N/Ain the descriptions below. This is different from the C interfaces,
1N/Awhich return C<-1> on failure. Exceptions to this rule are C<wait>,
1N/AC<waitpid>, and C<syscall>. System calls also set the special C<$!>
1N/Avariable on failure. Other functions do not, except accidentally.
1N/A=head2 Perl Functions by Category
1N/AHere are Perl's functions (including things that look like
1N/Afunctions, like some keywords and named operators)
1N/Aarranged by category. Some functions appear in more
1N/A=item Functions for SCALARs or strings
1N/AC<chomp>, C<chop>, C<chr>, C<crypt>, C<hex>, C<index>, C<lc>, C<lcfirst>,
1N/AC<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y///>
1N/A=item Regular expressions and pattern matching
1N/AC<m//>, C<pos>, C<quotemeta>, C<s///>, C<split>, C<study>, C<qr//>
1N/A=item Numeric functions
1N/AC<abs>, C<atan2>, C<cos>, C<exp>, C<hex>, C<int>, C<log>, C<oct>, C<rand>,
1N/AC<sin>, C<sqrt>, C<srand>
1N/A=item Functions for real @ARRAYs
1N/AC<pop>, C<push>, C<shift>, C<splice>, C<unshift>
1N/A=item Functions for list data
1N/AC<grep>, C<join>, C<map>, C<
qw/STRING/>, C<reverse>, C<sort>, C<unpack>
1N/A=item Functions for real %HASHes
1N/AC<delete>, C<each>, C<exists>, C<keys>, C<values>
1N/A=item Input and output functions
1N/AC<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>,
1N/AC<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>,
1N/AC<readdir>, C<rewinddir>, C<seek>, C<seekdir>, C<select>, C<syscall>,
1N/AC<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>, C<truncate>,
1N/A=item Functions for fixed length data or records
1N/AC<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec>
1N/A=item Functions for filehandles, files, or directories
1N/AC<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
1N/AC<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
1N/AC<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<sysopen>,
1N/AC<umask>, C<unlink>, C<utime>
1N/A=item Keywords related to the control flow of your perl program
1N/AC<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
1N/AC<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
1N/A=item Keywords related to scoping
1N/AC<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<use>
1N/A=item Miscellaneous functions
1N/AC<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>, C<reset>,
1N/AC<scalar>, C<undef>, C<wantarray>
1N/A=item Functions for processes and process groups
1N/AC<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>,
1N/AC<pipe>, C<
qx/STRING/>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>,
1N/AC<times>, C<wait>, C<waitpid>
1N/A=item Keywords related to perl modules
1N/AC<do>, C<import>, C<no>, C<package>, C<require>, C<use>
1N/A=item Keywords related to classes and object-orientedness
1N/AC<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>,
1N/A=item Low-level socket functions
1N/AC<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
1N/AC<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
1N/AC<socket>, C<socketpair>
1N/A=item System V interprocess communication functions
1N/AC<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>,
1N/AC<shmctl>, C<shmget>, C<shmread>, C<shmwrite>
1N/A=item Fetching user and group info
1N/AC<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>,
1N/AC<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>,
1N/AC<getpwuid>, C<setgrent>, C<setpwent>
1N/A=item Fetching network info
1N/AC<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>,
1N/AC<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
1N/AC<getprotobyname>, C<getprotobynumber>, C<getprotoent>,
1N/AC<getservbyname>, C<getservbyport>, C<getservent>, C<sethostent>,
1N/AC<setnetent>, C<setprotoent>, C<setservent>
1N/A=item Time-related functions
1N/AC<gmtime>, C<localtime>, C<time>, C<times>
1N/A=item Functions new in perl5
1N/AC<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>,
1N/AC<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<our>, C<prototype>,
1N/AC<qx>, C<qw>, C<readline>, C<readpipe>, C<ref>, C<sub*>, C<sysopen>, C<tie>,
1N/AC<tied>, C<uc>, C<ucfirst>, C<untie>, C<use>
1N/A* - C<sub> was a keyword in perl4, but in perl5 it is an
1N/Aoperator, which can be used in expressions.
1N/A=item Functions obsoleted in perl5
1N/AC<dbmclose>, C<dbmopen>
1N/APerl was born in Unix and can therefore access all common Unix
1N/Asystem calls. In non-Unix environments, the functionality of some
1N/AUnix system calls may not be available, or details of the available
1N/Afunctionality may differ slightly. The Perl functions affected
1N/AC<-X>, C<binmode>, C<chmod>, C<chown>, C<chroot>, C<crypt>,
1N/AC<dbmclose>, C<dbmopen>, C<dump>, C<endgrent>, C<endhostent>,
1N/AC<endnetent>, C<endprotoent>, C<endpwent>, C<endservent>, C<exec>,
1N/AC<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostbyname>,
1N/AC<gethostent>, C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
1N/AC<getppid>, C<getprgp>, C<getpriority>, C<getprotobynumber>,
1N/AC<getprotoent>, C<getpwent>, C<getpwnam>, C<getpwuid>,
1N/AC<getservbyport>, C<getservent>, C<getsockopt>, C<glob>, C<ioctl>,
1N/AC<kill>, C<link>, C<lstat>, C<msgctl>, C<msgget>, C<msgrcv>,
1N/AC<msgsnd>, C<open>, C<pipe>, C<readlink>, C<rename>, C<select>, C<semctl>,
1N/AC<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>,
1N/AC<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>,
1N/AC<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>,
1N/AC<shmwrite>, C<socket>, C<socketpair>,
1N/AC<stat>, C<symlink>, C<syscall>, C<sysopen>, C<system>,
1N/AC<times>, C<truncate>, C<umask>, C<unlink>,
1N/AC<utime>, C<wait>, C<waitpid>
1N/AFor more information about the portability of these functions, see
1N/AL<perlport> and other available platform-specific documentation.
1N/A=head2 Alphabetical Listing of Perl Functions
1N/AA file test, where X is one of the letters listed below. This unary
1N/Aoperator takes one argument, either a filename or a filehandle, and
1N/Atests the associated file to see if something is true about it. If the
1N/Aargument is omitted, tests C<$_>, except for C<-t>, which tests STDIN.
1N/AUnless otherwise documented, it returns C<1> for true and C<''> for false, or
1N/Athe undefined value if the file doesn't exist. Despite the funny
1N/Anames, precedence is the same as any other named unary operator, and
1N/Athe argument may be parenthesized like any other unary operator. The
1N/Aoperator may be any of:
1N/AX<-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>
1N/AX<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
1N/A -o File is owned by effective uid.
1N/A -O File is owned by real uid.
1N/A -z File has zero size (is empty).
1N/A -s File has nonzero size (returns size in bytes).
1N/A -f File is a plain file.
1N/A -d File is a directory.
1N/A -l File is a symbolic link.
1N/A -p File is a named pipe (FIFO), or Filehandle is a pipe.
1N/A -S File is a socket.
1N/A -b File is a block special file.
1N/A -c File is a character special file.
1N/A -t Filehandle is opened to a tty.
1N/A -u File has setuid bit set.
1N/A -g File has setgid bit set.
1N/A -k File has sticky bit set.
1N/A -T File is an ASCII text file (heuristic guess).
1N/A -B File is a "binary" file (opposite of -T).
1N/A -M Script start time minus file modification time, in days.
1N/A -A Same for access time.
1N/A -C Same for inode change time (Unix, may differ for other platforms)
1N/A next unless -f $_; # ignore specials
1N/AThe interpretation of the file permission operators C<-r>, C<-R>,
1N/AC<-w>, C<-W>, C<-x>, and C<-X> is by default based solely on the mode
1N/Aof the file and the uids and gids of the user. There may be other
1N/Areasons you can't actually read, write, or execute the file. Such
1N/Areasons may be for example network filesystem access controls, ACLs
1N/A(access control lists), read-only filesystems, and unrecognized
1N/AAlso note that, for the superuser on the local filesystems, the C<-r>,
1N/AC<-R>, C<-w>, and C<-W> tests always return 1, and C<-x> and C<-X> return 1
1N/Aif any execute bit is set in the mode. Scripts run by the superuser
1N/Amay thus need to do a stat() to determine the actual mode of the file,
1N/Aor temporarily set their effective uid to something else.
1N/AIf you are using ACLs, there is a pragma called C<filetest> that may
1N/Aproduce more accurate results than the bare stat() mode bits.
1N/AWhen under the C<use filetest 'access'> the above-mentioned filetests
1N/Awill test whether the permission can (not) be granted using the
1N/Aaccess() family of system calls. Also note that the C<-x> and C<-X> may
1N/Aunder this pragma return true even if there are no execute permission
1N/Abits set (nor any extra execute permission ACLs). This strangeness is
1N/Adue to the underlying system calls' definitions. Read the
1N/Adocumentation for the C<filetest> pragma for more information.
1N/ANote that C<-s/a/b/> does not do a negated substitution. Saying
1N/AC<-exp($foo)> still works as expected, however--only single letters
1N/Afollowing a minus are interpreted as file tests.
1N/AThe C<-T> and C<-B> switches work as follows. The first block or so of the
1N/Afile is examined for odd characters such as strange control codes or
1N/Acharacters with the high bit set. If too many strange characters (>30%)
1N/Aare found, it's a C<-B> file, otherwise it's a C<-T> file. Also, any file
1N/Acontaining null in the first block is considered a binary file. If C<-T>
1N/Aor C<-B> is used on a filehandle, the current IO buffer is examined
1N/Arather than the first block. Both C<-T> and C<-B> return true on a null
1N/Afile, or a file at EOF when testing a filehandle. Because you have to
1N/Aread a file to do the C<-T> test, on most occasions you want to use a C<-f>
1N/Aagainst the file first, as in C<next unless -f $file && -T $file>.
1N/AIf any of the file tests (or either the C<stat> or C<lstat> operators) are given
1N/Athe special filehandle consisting of a solitary underline, then the stat
1N/Astructure of the previous file test (or stat operator) is used, saving
1N/Aa system call. (This doesn't work with C<-t>, and you need to remember
1N/Athat lstat() and C<-l> will leave values in the stat structure for the
1N/Asymbolic link, not the real file.) (Also, if the stat buffer was filled by
1N/Aa C<lstat> call, C<-T> and C<-B> will reset it with the results of C<stat _>).
1N/A print "Can do.\n" if -r $a || -w _ || -x _;
1N/A print "Readable\n" if -r _;
1N/A print "Writable\n" if -w _;
1N/A print "Executable\n" if -x _;
1N/A print "Setuid\n" if -u _;
1N/A print "Setgid\n" if -g _;
1N/A print "Sticky\n" if -k _;
1N/A print "Text\n" if -T _;
1N/A print "Binary\n" if -B _;
1N/AReturns the absolute value of its argument.
1N/AIf VALUE is omitted, uses C<$_>.
1N/A=item accept NEWSOCKET,GENERICSOCKET
1N/AAccepts an incoming socket connect, just as the accept(2) system call
1N/Adoes. Returns the packed address if it succeeded, false otherwise.
1N/AOn systems that support a close-on-exec flag on files, the flag will
1N/Abe set for the newly opened file descriptor, as determined by the
1N/Avalue of $^F. See L<perlvar/$^F>.
1N/AArranges to have a SIGALRM delivered to this process after the
1N/Aspecified number of wallclock seconds have elapsed. If SECONDS is not
1N/Aspecified, the value stored in C<$_> is used. (On some machines,
1N/Aunfortunately, the elapsed time may be up to one second less or more
1N/Athan you specified because of how seconds are counted, and process
1N/Ascheduling may delay the delivery of the signal even further.)
1N/AOnly one timer may be counting at once. Each call disables the
1N/Aprevious timer, and an argument of C<0> may be supplied to cancel the
1N/Aprevious timer without starting a new one. The returned value is the
1N/Aamount of time remaining on the previous timer.
1N/AFor delays of finer granularity than one second, you may use Perl's
1N/Afour-argument version of select() leaving the first three arguments
1N/Aundefined, or you might be able to use the C<syscall> interface to
1N/Aaccess setitimer(2) if your system supports it. The Time::HiRes
1N/Amodule (from CPAN, and starting from Perl 5.8 part of the standard
1N/Adistribution) may also prove useful.
1N/AIt is usually a mistake to intermix C<alarm> and C<sleep> calls.
1N/A(C<sleep> may be internally implemented in your system with C<alarm>)
1N/AIf you want to use C<alarm> to time out a system call you need to use an
1N/AC<eval>/C<die> pair. You can't rely on the alarm causing the system call to
1N/Afail with C<$!> set to C<EINTR> because Perl sets up signal handlers to
1N/Arestart system calls on some systems. Using C<eval>/C<die> always works,
1N/Amodulo the caveats given in L<perlipc/"Signals">.
1N/A local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
1N/A $nread = sysread SOCKET, $buffer, $size;
1N/A die unless $@ eq "alarm\n"; # propagate unexpected errors
1N/AFor more information see L<perlipc>.
1N/AReturns the arctangent of Y/X in the range -PI to PI.
1N/AFor the tangent operation, you may use the C<Math::Trig::tan>
1N/Afunction, or use the familiar relation:
1N/A sub tan { sin($_[0]) / cos($_[0]) }
1N/A=item bind SOCKET,NAME
1N/ABinds a network address to a socket, just as the bind system call
1N/Adoes. Returns true if it succeeded, false otherwise. NAME should be a
1N/Apacked address of the appropriate type for the socket. See the examples in
1N/A=item binmode FILEHANDLE, LAYER
1N/A=item binmode FILEHANDLE
1N/AArranges for FILEHANDLE to be read or written in "binary" or "text"
1N/Amode on systems where the run-time libraries distinguish between
1N/Abinary and text files. If FILEHANDLE is an expression, the value is
1N/Ataken as the name of the filehandle. Returns true on success,
1N/Aotherwise it returns C<undef> and sets C<$!> (errno).
1N/AOn some systems (in general, DOS and Windows-based systems) binmode()
1N/Ais necessary when you're not working with a text file. For the sake
1N/Aof portability it is a good idea to always use it when appropriate,
1N/Aand to never use it when it isn't appropriate. Also, people can
1N/Aset their I/O to be by default UTF-8 encoded Unicode, not bytes.
1N/AIn other words: regardless of platform, use binmode() on binary data,
1N/Alike for example images.
1N/AIf LAYER is present it is a single string, but may contain multiple
1N/Adirectives. The directives alter the behaviour of the file handle.
1N/AWhen LAYER is present using binmode on text file makes sense.
1N/AIf LAYER is omitted or specified as C<:raw> the filehandle is made
1N/Asuitable for passing binary data. This includes turning off possible CRLF
1N/Atranslation and marking it as bytes (as opposed to Unicode characters).
1N/ANote that, despite what may be implied in I<"Programming Perl"> (the
1N/ACamel) or elsewhere, C<:raw> is I<not> the simply inverse of C<:crlf>
1N/A-- other layers which would affect binary nature of the stream are
1N/AI<also> disabled. See L<PerlIO>, L<perlrun> and the discussion about the
1N/APERLIO environment variable.
1N/AThe C<:bytes>, C<:crlf>, and C<:utf8>, and any other directives of the
1N/Aform C<:...>, are called I/O I<layers>. The C<open> pragma can be used to
1N/Aestablish default I/O layers. See L<open>.
1N/AI<The LAYER parameter of the binmode() function is described as "DISCIPLINE"
1N/Ain "Programming Perl, 3rd Edition". However, since the publishing of this
1N/Abook, by many known as "Camel III", the consensus of the naming of this
1N/Afunctionality has moved from "discipline" to "layer". All documentation
1N/Aof this version of Perl therefore refers to "layers" rather than to
1N/A"disciplines". Now back to the regularly scheduled documentation...>
1N/ATo mark FILEHANDLE as UTF-8, use C<:utf8>.
1N/AIn general, binmode() should be called after open() but before any I/O
1N/Ais done on the filehandle. Calling binmode() will normally flush any
1N/Apending buffered output data (and perhaps pending input data) on the
1N/Ahandle. An exception to this is the C<:encoding> layer that
1N/Achanges the default character encoding of the handle, see L<open>.
1N/AThe C<:encoding> layer sometimes needs to be called in
1N/Amid-stream, and it doesn't flush the stream. The C<:encoding>
1N/Aalso implicitly pushes on top of itself the C<:utf8> layer because
1N/Ainternally Perl will operate on UTF-8 encoded Unicode characters.
1N/AThe operating system, device drivers, C libraries, and Perl run-time
1N/Asystem all work together to let the programmer treat a single
1N/Acharacter (C<\n>) as the line terminator, irrespective of the external
1N/Arepresentation. On many operating systems, the native text file
1N/Arepresentation matches the internal representation, but on some
1N/Aplatforms the external representation of C<\n> is made up of more than
1N/AMac OS, all variants of Unix, and Stream_LF files on VMS use a single
1N/Acharacter to end each line in the external representation of text (even
1N/Athough that single character is CARRIAGE RETURN on Mac OS and LINE FEED
1N/Aon Unix and most VMS files). In other systems like OS/2, DOS and the
1N/Avarious flavors of MS-Windows your program sees a C<\n> as a simple C<\cJ>,
1N/Abut what's stored in text files are the two characters C<\cM\cJ>. That
1N/Ameans that, if you don't use binmode() on these systems, C<\cM\cJ>
1N/Asequences on disk will be converted to C<\n> on input, and any C<\n> in
1N/Ayour program will be converted back to C<\cM\cJ> on output. This is what
1N/Ayou want for text files, but it can be disastrous for binary files.
1N/AAnother consequence of using binmode() (on some systems) is that
1N/Aspecial end-of-file markers will be seen as part of the data stream.
1N/AFor systems from the Microsoft family this means that if your binary
1N/Adata contains C<\cZ>, the I/O subsystem will regard it as the end of
1N/Athe file, unless you use binmode().
1N/Abinmode() is not only important for readline() and print() operations,
1N/Abut also when using read(), seek(), sysread(), syswrite() and tell()
1N/A(see L<perlport> for more details). See the C<$/> and C<$\> variables
1N/Ain L<perlvar> for how to manually set your input and output
1N/Aline-termination sequences.
1N/A=item bless REF,CLASSNAME
1N/AThis function tells the thingy referenced by REF that it is now an object
1N/Ain the CLASSNAME package. If CLASSNAME is omitted, the current package
1N/Ais used. Because a C<bless> is often the last thing in a constructor,
1N/Ait returns the reference for convenience. Always use the two-argument
1N/Aversion if the function doing the blessing might be inherited by a
1N/Aderived class. See L<perltoot> and L<perlobj> for more about the blessing
1N/A(and blessings) of objects.
1N/AConsider always blessing objects in CLASSNAMEs that are mixed case.
1N/ANamespaces with all lowercase names are considered reserved for
1N/APerl pragmata. Builtin types have all uppercase names, so to prevent
1N/Aconfusion, you may wish to avoid such package names as well. Make sure
1N/Athat CLASSNAME is a true value.
1N/ASee L<perlmod/"Perl Modules">.
1N/AReturns the context of the current subroutine call. In scalar context,
1N/Areturns the caller's package name if there is a caller, that is, if
1N/Awe're in a subroutine or C<eval> or C<require>, and the undefined value
1N/Aotherwise. In list context, returns
1N/A ($package, $filename, $line) = caller;
1N/AWith EXPR, it returns some extra information that the debugger uses to
1N/Aprint a stack trace. The value of EXPR indicates how many call frames
1N/Ato go back before the current one.
1N/A ($package, $filename, $line, $subroutine, $hasargs,
1N/A $wantarray, $evaltext, $is_require, $hints, $bitmask) = caller($i);
1N/AHere $subroutine may be C<(eval)> if the frame is not a subroutine
1N/Acall, but an C<eval>. In such a case additional elements $evaltext and
1N/AC<$is_require> are set: C<$is_require> is true if the frame is created by a
1N/AC<require> or C<use> statement, $evaltext contains the text of the
1N/AC<eval EXPR> statement. In particular, for an C<eval BLOCK> statement,
1N/A$filename is C<(eval)>, but $evaltext is undefined. (Note also that
1N/Aeach C<use> statement creates a C<require> frame inside an C<eval EXPR>
1N/Aframe.) $subroutine may also be C<(unknown)> if this particular
1N/Asubroutine happens to have been deleted from the symbol table.
1N/AC<$hasargs> is true if a new instance of C<@_> was set up for the frame.
1N/AC<$hints> and C<$bitmask> contain pragmatic hints that the caller was
1N/Acompiled with. The C<$hints> and C<$bitmask> values are subject to change
1N/Abetween versions of Perl, and are not meant for external use.
1N/AFurthermore, when called from within the DB package, caller returns more
1N/Adetailed information: it sets the list variable C<@DB::args> to be the
1N/Aarguments with which the subroutine was invoked.
1N/ABe aware that the optimizer might have optimized call frames away before
1N/AC<caller> had a chance to get the information. That means that C<caller(N)>
1N/Amight not return information about the call frame you expect it do, for
1N/AC<< N > 1 >>. In particular, C<@DB::args> might have information from the
1N/Aprevious time C<caller> was called.
1N/AChanges the working directory to EXPR, if possible. If EXPR is omitted,
1N/Achanges to the directory specified by C<$ENV{HOME}>, if set; if not,
1N/Achanges to the directory specified by C<$ENV{LOGDIR}>. (Under VMS, the
1N/Avariable C<$ENV{SYS$LOGIN}> is also checked, and used if it is set.) If
1N/Aneither is set, C<chdir> does nothing. It returns true upon success,
1N/Afalse otherwise. See the example under C<die>.
1N/AChanges the permissions of a list of files. The first element of the
1N/Alist must be the numerical mode, which should probably be an octal
1N/Anumber, and which definitely should I<not> a string of octal digits:
1N/AC<0644> is okay, C<'0644'> is not. Returns the number of files
1N/Asuccessfully changed. See also L</oct>, if all you have is a string.
1N/A $cnt = chmod 0755, 'foo', 'bar';
1N/A chmod 0755, @executables;
1N/A $mode = '0644'; chmod $mode, 'foo'; # !!! sets mode to
1N/A $mode = '0644'; chmod oct($mode), 'foo'; # this is better
1N/A $mode = 0644; chmod $mode, 'foo'; # this is best
1N/AYou can also import the symbolic C<S_I*> constants from the Fcntl
1N/A chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
1N/A # This is identical to the chmod 0755 of the above example.
1N/AThis safer version of L</chop> removes any trailing string
1N/Athat corresponds to the current value of C<$/> (also known as
1N/A$INPUT_RECORD_SEPARATOR in the C<English> module). It returns the total
1N/Anumber of characters removed from all its arguments. It's often used to
1N/Aremove the newline from the end of an input record when you're worried
1N/Athat the final record may be missing its newline. When in paragraph
1N/Amode (C<$/ = "">), it removes all trailing newlines from the string.
1N/AWhen in slurp mode (C<$/ = undef>) or fixed-length record mode (C<$/> is
1N/Aa reference to an integer or the like, see L<perlvar>) chomp() won't
1N/AIf VARIABLE is omitted, it chomps C<$_>. Example:
1N/A chomp; # avoid \n on last field
1N/A @array = split(/:/);
1N/AIf VARIABLE is a hash, it chomps the hash's values, but not its keys.
1N/AYou can actually chomp anything that's an lvalue, including an assignment:
1N/A chomp($cwd = `pwd`);
1N/A chomp($answer = <STDIN>);
1N/AIf you chomp a list, each element is chomped, and the total number of
1N/Acharacters removed is returned.
1N/AIf the C<encoding> pragma is in scope then the lengths returned are
1N/Acalculated from the length of C<$/> in Unicode characters, which is not
1N/Aalways the same as the length of C<$/> in the native encoding.
1N/ANote that parentheses are necessary when you're chomping anything
1N/Athat is not a simple variable. This is because C<chomp $cwd = `pwd`;>
1N/Ais interpreted as C<(chomp $cwd) = `pwd`;>, rather than as
1N/AC<chomp( $cwd = `pwd` )> which you might expect. Similarly,
1N/AC<chomp $a, $b> is interpreted as C<chomp($a), $b> rather than
1N/AChops off the last character of a string and returns the character
1N/Achopped. It is much more efficient than C<s/.$//s> because it neither
1N/Ascans nor copies the string. If VARIABLE is omitted, chops C<$_>.
1N/AIf VARIABLE is a hash, it chops the hash's values, but not its keys.
1N/AYou can actually chop anything that's an lvalue, including an assignment.
1N/AIf you chop a list, each element is chopped. Only the value of the
1N/Alast C<chop> is returned.
1N/ANote that C<chop> returns the last character. To return all but the last
1N/Acharacter, use C<substr($string, 0, -1)>.
1N/AChanges the owner (and group) of a list of files. The first two
1N/Aelements of the list must be the I<numeric> uid and gid, in that
1N/Aorder. A value of -1 in either position is interpreted by most
1N/Asystems to leave that value unchanged. Returns the number of files
1N/Asuccessfully changed.
1N/A $cnt = chown $uid, $gid, 'foo', 'bar';
1N/A chown $uid, $gid, @filenames;
1N/AHere's an example that looks up nonnumeric uids in the passwd file:
1N/A chomp($user = <STDIN>);
1N/A chomp($pattern = <STDIN>);
1N/A ($login,$pass,$uid,$gid) = getpwnam($user)
1N/A or die "$user not in passwd file";
1N/A @ary = glob($pattern); # expand filenames
1N/A chown $uid, $gid, @ary;
1N/AOn most systems, you are not allowed to change the ownership of the
1N/Afile unless you're the superuser, although you should be able to change
1N/Athe group to any of your secondary groups. On insecure systems, these
1N/Arestrictions may be relaxed, but this is not a portable assumption.
1N/AOn POSIX systems, you can detect this condition this way:
1N/A use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
1N/A $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
1N/AReturns the character represented by that NUMBER in the character set.
1N/AFor example, C<chr(65)> is C<"A"> in either ASCII or Unicode, and
1N/Achr(0x263a) is a Unicode smiley face. Note that characters from 128
1N/Ato 255 (inclusive) are by default not encoded in UTF-8 Unicode for
1N/Abackward compatibility reasons (but see L<encoding>).
1N/AIf NUMBER is omitted, uses C<$_>.
1N/AFor the reverse, use L</ord>.
1N/ANote that under the C<bytes> pragma the NUMBER is masked to
1N/ASee L<perlunicode> and L<encoding> for more about Unicode.
1N/A=item chroot FILENAME
1N/AThis function works like the system call by the same name: it makes the
1N/Anamed directory the new root directory for all further pathnames that
1N/Abegin with a C</> by your process and all its children. (It doesn't
1N/Achange your current working directory, which is unaffected.) For security
1N/Areasons, this call is restricted to the superuser. If FILENAME is
1N/Aomitted, does a C<chroot> to C<$_>.
1N/A=item close FILEHANDLE
1N/ACloses the file or pipe associated with the file handle, returning
1N/Atrue only if IO buffers are successfully flushed and closes the system
1N/Afile descriptor. Closes the currently selected filehandle if the
1N/AYou don't have to close FILEHANDLE if you are immediately going to do
1N/Aanother C<open> on it, because C<open> will close it for you. (See
1N/AC<open>.) However, an explicit C<close> on an input file resets the line
1N/Acounter (C<$.>), while the implicit close done by C<open> does not.
1N/AIf the file handle came from a piped open, C<close> will additionally
1N/Areturn false if one of the other system calls involved fails, or if the
1N/Aprogram exits with non-zero status. (If the only problem was that the
1N/Aprogram exited non-zero, C<$!> will be set to C<0>.) Closing a pipe
1N/Aalso waits for the process executing on the pipe to complete, in case you
1N/Awant to look at the output of the pipe afterwards, and
1N/Aimplicitly puts the exit status value of that command into C<$?>.
1N/APrematurely closing the read end of a pipe (
i.e. before the process
1N/Awriting to it at the other end has closed it) will result in a
1N/ASIGPIPE being delivered to the writer. If the other end can't
1N/Ahandle that, be sure to read all the data before closing the pipe.
1N/A open(OUTPUT, '|sort >foo') # pipe to sort
1N/A or die "Can't start sort: $!";
1N/A #... # print stuff to output
1N/A close OUTPUT # wait for sort to finish
1N/A or warn $! ? "Error closing sort pipe: $!"
1N/A : "Exit status $? from sort";
1N/A open(INPUT, 'foo') # get sort's results
1N/A or die "Can't open 'foo' for input: $!";
1N/AFILEHANDLE may be an expression whose value can be used as an indirect
1N/Afilehandle, usually the real filehandle name.
1N/A=item closedir DIRHANDLE
1N/ACloses a directory opened by C<opendir> and returns the success of that
1N/A=item connect SOCKET,NAME
1N/AAttempts to connect to a remote socket, just as the connect system call
1N/Adoes. Returns true if it succeeded, false otherwise. NAME should be a
1N/Apacked address of the appropriate type for the socket. See the examples in
1N/AActually a flow control statement rather than a function. If there is a
1N/AC<continue> BLOCK attached to a BLOCK (typically in a C<while> or
1N/AC<foreach>), it is always executed just before the conditional is about to
1N/Abe evaluated again, just like the third part of a C<for> loop in C. Thus
1N/Ait can be used to increment a loop variable, even when the loop has been
1N/Acontinued via the C<next> statement (which is similar to the C C<continue>
1N/AC<last>, C<next>, or C<redo> may appear within a C<continue>
1N/Ablock. C<last> and C<redo> will behave as if they had been executed within
1N/Athe main block. So will C<next>, but since it will execute a C<continue>
1N/Ablock, it may be more entertaining.
1N/A ### redo always comes here
1N/A ### next always comes here
1N/A # then back the top to re-check EXPR
1N/A ### last always comes here
1N/AOmitting the C<continue> section is semantically equivalent to using an
1N/Aempty one, logically enough. In that case, C<next> goes directly back
1N/Ato check the condition at the top of the loop.
1N/AReturns the cosine of EXPR (expressed in radians). If EXPR is omitted,
1N/Atakes cosine of C<$_>.
1N/AFor the inverse cosine operation, you may use the C<Math::Trig::acos()>
1N/Afunction, or use this relation:
1N/A sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
1N/A=item crypt PLAINTEXT,SALT
1N/AEncrypts a string exactly like the crypt(3) function in the C library
1N/A(assuming that you actually have a version there that has not been
1N/Aextirpated as a potential munition). This can prove useful for checking
1N/Athe password file for lousy passwords, amongst other things. Only the
1N/Aguys wearing white hats should do this.
1N/ANote that L<crypt|/crypt> is intended to be a one-way function, much like
1N/Abreaking eggs to make an omelette. There is no (known) corresponding
1N/Adecrypt function (in other words, the crypt() is a one-way hash
1N/Afunction). As a result, this function isn't all that useful for
1N/Acryptography. (For that, see your nearby CPAN mirror.)
1N/AWhen verifying an existing encrypted string you should use the
1N/Aencrypted text as the salt (like C<crypt($plain, $crypted) eq
1N/A$crypted>). This allows your code to work with the standard L<crypt|/crypt>
1N/Aand with more exotic implementations. In other words, do not assume
1N/Aanything about the returned string itself, or how many bytes in
1N/Athe encrypted string matter.
1N/ATraditionally the result is a string of 13 bytes: two first bytes of
1N/Athe salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only
1N/Athe first eight bytes of the encrypted string mattered, but
1N/Aalternative hashing schemes (like MD5), higher level security schemes
1N/A(like C2), and implementations on non-UNIX platforms may produce
1N/AWhen choosing a new salt create a random two character string whose
1N/Acharacters come from the set C<[./0-9A-Za-z]> (like C<join '', ('.',
1N/A'/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>). This set of
1N/Acharacters is just a recommendation; the characters allowed in
1N/Athe salt depend solely on your system's crypt library, and Perl can't
1N/Arestrict what salts C<crypt()> accepts.
1N/AHere's an example that makes sure that whoever runs this program knows
1N/A $pwd = (getpwuid($<))[1];
1N/A system "stty -echo";
1N/A chomp($word = <STDIN>);
1N/A if (crypt($word, $pwd) ne $pwd) {
1N/AOf course, typing in your own password to whoever asks you
1N/AThe L<crypt|/crypt> function is unsuitable for encrypting large quantities
1N/Aof data, not least of all because you can't get the information
1N/Aon your favorite CPAN mirror for a slew of potentially useful
1N/AIf using crypt() on a Unicode string (which I<potentially> has
1N/Acharacters with codepoints above 255), Perl tries to make sense
1N/Aof the situation by trying to downgrade (a copy of the string)
1N/Athe string back to an eight-bit byte string before calling crypt()
1N/A(on that copy). If that works, good. If not, crypt() dies with
1N/AC<Wide character in crypt>.
1N/A[This function has been largely superseded by the C<untie> function.]
1N/ABreaks the binding between a DBM file and a hash.
1N/A=item dbmopen HASH,DBNAME,MASK
1N/A[This function has been largely superseded by the C<tie> function.]
1N/AThis binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a
1N/Ahash. HASH is the name of the hash. (Unlike normal C<open>, the first
1N/Aargument is I<not> a filehandle, even though it looks like one). DBNAME
1N/Ais the name of the database (without the F<.dir> or F<.pag> extension if
1N/Aany). If the database does not exist, it is created with protection
1N/Aspecified by MASK (as modified by the C<umask>). If your system supports
1N/Aonly the older DBM functions, you may perform only one C<dbmopen> in your
1N/Aprogram. In older versions of Perl, if your system had neither DBM nor
1N/Andbm, calling C<dbmopen> produced a fatal error; it now falls back to
1N/AIf you don't have write access to the DBM file, you can only read hash
1N/Avariables, not set them. If you want to test whether you can write,
1N/Aeither use file tests or try setting a dummy hash entry inside an C<eval>,
1N/Awhich will trap the error.
1N/ANote that functions such as C<keys> and C<values> may return huge lists
1N/Awhen used on large DBM files. You may prefer to use the C<each>
1N/Afunction to iterate over large DBM files. Example:
1N/A # print out history file offsets
1N/A while (($key,$val) = each %HIST) {
1N/A print $key, ' = ', unpack('L',$val), "\n";
1N/ASee also L<AnyDBM_File> for a more general description of the pros and
1N/Acons of the various dbm approaches, as well as L<DB_File> for a particularly
1N/AYou can control which DBM library you use by loading that library
1N/Abefore you call dbmopen():
1N/A or die "Can't open netscape history file: $!";
1N/AReturns a Boolean value telling whether EXPR has a value other than
1N/Athe undefined value C<undef>. If EXPR is not present, C<$_> will be
1N/AMany operations return C<undef> to indicate failure, end of file,
1N/Asystem error, uninitialized variable, and other exceptional
1N/Aconditions. This function allows you to distinguish C<undef> from
1N/Aother values. (A simple Boolean test will not distinguish among
1N/AC<undef>, zero, the empty string, and C<"0">, which are all equally
1N/Afalse.) Note that since C<undef> is a valid scalar, its presence
1N/Adoesn't I<necessarily> indicate an exceptional condition: C<pop>
1N/Areturns C<undef> when its argument is an empty array, I<or> when the
1N/Aelement to return happens to be C<undef>.
1N/AYou may also use C<defined(&func)> to check whether subroutine C<&func>
1N/Ahas ever been defined. The return value is unaffected by any forward
1N/Adeclarations of C<&func>. Note that a subroutine which is not defined
1N/Amay still be callable: its package may have an C<AUTOLOAD> method that
1N/Amakes it spring into existence the first time that it is called -- see
1N/AUse of C<defined> on aggregates (hashes and arrays) is deprecated. It
1N/Aused to report whether memory for that aggregate has ever been
1N/Aallocated. This behavior may disappear in future versions of Perl.
1N/AYou should instead use a simple test for size:
1N/A if (@an_array) { print "has array elements\n" }
1N/A if (%a_hash) { print "has hash members\n" }
1N/AWhen used on a hash element, it tells you whether the value is defined,
1N/Anot whether the key exists in the hash. Use L</exists> for the latter
1N/A print if defined $switch{'D'};
1N/A print "$val\n" while defined($val = pop(@ary));
1N/A die "Can't readlink $sym: $!"
1N/A unless defined($value = readlink $sym);
1N/A sub foo { defined &$bar ? &$bar(@_) : die "No bar"; }
1N/A $debugging = 0 unless defined $debugging;
1N/ANote: Many folks tend to overuse C<defined>, and then are surprised to
1N/Adiscover that the number C<0> and C<""> (the zero-length string) are, in fact,
1N/Adefined values. For example, if you say
1N/AThe pattern match succeeds, and C<$1> is defined, despite the fact that it
1N/Amatched "nothing". But it didn't really match nothing--rather, it
1N/Amatched something that happened to be zero characters long. This is all
1N/Avery above-board and honest. When a function returns an undefined value,
1N/Ait's an admission that it couldn't give you an honest answer. So you
1N/Ashould use C<defined> only when you're questioning the integrity of what
1N/Ayou're trying to do. At other times, a simple comparison to C<0> or C<""> is
1N/ASee also L</undef>, L</exists>, L</ref>.
1N/AGiven an expression that specifies a hash element, array element, hash slice,
1N/Aor array slice, deletes the specified element(s) from the hash or array.
1N/AIn the case of an array, if the array elements happen to be at the end,
1N/Athe size of the array will shrink to the highest element that tests
1N/Atrue for exists() (or 0 if no such element exists).
1N/AReturns a list with the same number of elements as the number of elements
1N/Afor which deletion was attempted. Each element of that list consists of
1N/Aeither the value of the element deleted, or the undefined value. In scalar
1N/Acontext, this means that you get the value of the last element deleted (or
1N/Athe undefined value if that element did not exist).
1N/A %hash = (foo => 11, bar => 22, baz => 33);
1N/A $scalar = delete $hash{foo}; # $scalar is 11
1N/A $scalar = delete @hash{qw(foo bar)}; # $scalar is 22
1N/A @array = delete @hash{qw(foo bar baz)}; # @array is (undef,undef,33)
1N/ADeleting from C<%ENV> modifies the environment. Deleting from
1N/Aa hash tied to a DBM file deletes the entry from the DBM file. Deleting
1N/Afrom a C<tie>d hash or array may not necessarily return anything.
1N/ADeleting an array element effectively returns that position of the array
1N/Ato its initial, uninitialized state. Subsequently testing for the same
1N/Aelement with exists() will return false. Note that deleting array
1N/Aelements in the middle of an array will not shift the index of the ones
1N/Aafter them down--use splice() for that. See L</exists>.
1N/AThe following (inefficiently) deletes all the values of %HASH and @ARRAY:
1N/A foreach $key (keys %HASH) {
1N/A foreach $index (0 .. $#ARRAY) {
1N/A delete $ARRAY[$index];
1N/A delete @HASH{keys %HASH};
1N/A delete @ARRAY[0 .. $#ARRAY];
1N/ABut both of these are slower than just assigning the empty list
1N/Aor undefining %HASH or @ARRAY:
1N/A %HASH = (); # completely empty %HASH
1N/A undef %HASH; # forget %HASH ever existed
1N/A @ARRAY = (); # completely empty @ARRAY
1N/A undef @ARRAY; # forget @ARRAY ever existed
1N/ANote that the EXPR can be arbitrarily complicated as long as the final
1N/Aoperation is a hash element, array element, hash slice, or array slice
1N/A delete $ref->[$x][$y]{$key};
1N/A delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};
1N/A delete $ref->[$x][$y][$index];
1N/A delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
1N/AOutside an C<eval>, prints the value of LIST to C<STDERR> and
1N/Aexits with the current value of C<$!> (errno). If C<$!> is C<0>,
1N/Aexits with the value of C<<< ($? >> 8) >>> (backtick `command`
1N/Astatus). If C<<< ($? >> 8) >>> is C<0>, exits with C<255>. Inside
1N/Aan C<eval(),> the error message is stuffed into C<$@> and the
1N/AC<eval> is terminated with the undefined value. This makes
1N/AC<die> the way to raise an exception.
1N/AIf the last element of LIST does not end in a newline, the current
1N/Ascript line number and input line number (if any) are also printed,
1N/Aand a newline is supplied. Note that the "input line number" (also
1N/Aknown as "chunk") is subject to whatever notion of "line" happens to
1N/Abe currently in effect, and is also available as the special variable
1N/AC<$.>. See L<perlvar/"$/"> and L<perlvar/"$.">.
1N/AHint: sometimes appending C<", stopped"> to your message will cause it
1N/Ato make better sense when the string C<"at foo line 123"> is appended.
1N/ASuppose you are running script "canasta".
1N/Aproduce, respectively
1N/ASee also exit(), warn(), and the Carp module.
1N/AIf LIST is empty and C<$@> already contains a value (typically from a
1N/AThis is useful for propagating exceptions:
1N/A die unless $@ =~ /Expected exception/;
1N/AIf LIST is empty and C<$@> contains an object reference that has a
1N/AC<PROPAGATE> method, that method will be called with additional file
1N/Aand line number parameters. The return value replaces the value in
1N/AC<$@>. ie. as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >>
1N/AIf C<$@> is empty then the string C<"Died"> is used.
1N/Adie() can also be called with a reference argument. If this happens to be
1N/Atrapped within an eval(), $@ contains the reference. This behavior permits
1N/Aa more elaborate exception handling implementation using objects that
1N/Amaintain arbitrary state about the nature of the exception. Such a scheme
1N/Ais sometimes preferable to matching particular string values of $@ using
1N/Aregular expressions. Here's an example:
1N/A eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
1N/A if (ref($@) && UNIVERSAL::isa($@,"Some::Module::Exception")) {
1N/A # handle Some::Module::Exception
1N/A # handle all other possible exceptions
1N/ABecause perl will stringify uncaught exception messages before displaying
1N/Athem, you may want to overload stringification operations on such custom
1N/Aexception objects. See L<overload> for details about that.
1N/AYou can arrange for a callback to be run just before the C<die>
1N/Adoes its deed, by setting the C<$SIG{__DIE__}> hook. The associated
1N/Ahandler will be called with the error text and can change the error
1N/Amessage, if it sees fit, by calling C<die> again. See
1N/AL<perlvar/$SIG{expr}> for details on setting C<%SIG> entries, and
1N/AL<"eval BLOCK"> for some examples. Although this feature was meant
1N/Ato be run only right before your program was to exit, this is not
1N/Acurrently the case--the C<$SIG{__DIE__}> hook is currently called
1N/Anothing in such situations, put
1N/Aas the first line of the handler (see L<perlvar/$^S>). Because
1N/Athis promotes strange action at a distance, this counterintuitive
1N/Abehavior may be fixed in a future release.
1N/ANot really a function. Returns the value of the last command in the
1N/Asequence of commands indicated by BLOCK. When modified by a loop
1N/Amodifier, executes the BLOCK once before testing the loop condition.
1N/A(On other statements the loop modifiers test the conditional first.)
1N/AC<do BLOCK> does I<not> count as a loop, so the loop control statements
1N/AC<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
1N/ASee L<perlsyn> for alternative strategies.
1N/A=item do SUBROUTINE(LIST)
1N/AA deprecated form of subroutine call. See L<perlsub>.
1N/AUses the value of EXPR as a filename and executes the contents of the
1N/Afile as a Perl script. Its primary use is to include subroutines
1N/Afrom a Perl subroutine library.
1N/Aexcept that it's more efficient and concise, keeps track of the current
1N/Afilename for error messages, searches the @INC libraries, and updates
1N/Avariables. It also differs in that code evaluated with C<do FILENAME>
1N/Acannot see lexicals in the enclosing scope; C<eval STRING> does. It's the
1N/Asame, however, in that it does reparse the file every time you call it,
1N/Aso you probably don't want to do this inside a loop.
1N/AIf C<do> cannot read the file, it returns undef and sets C<$!> to the
1N/Aerror. If C<do> can read the file but cannot compile it, it
1N/Areturns undef and sets an error message in C<$@>. If the file is
1N/Asuccessfully compiled, C<do> returns the value of the last expression
1N/ANote that inclusion of library modules is better done with the
1N/AC<use> and C<require> operators, which also do automatic error checking
1N/Aand raise an exception if there's a problem.
1N/AYou might like to use C<do> to read in a program configuration
1N/Afile. Manual error checking can be done this way:
1N/A # read in config files: system first, then user
1N/A "$ENV{HOME}/.someprogrc")
1N/A unless ($return = do $file) {
1N/A warn "couldn't parse $file: $@" if $@;
1N/A warn "couldn't do $file: $!" unless defined $return;
1N/A warn "couldn't run $file" unless $return;
1N/AThis function causes an immediate core dump. See also the B<-u>
1N/Acommand-line switch in L<perlrun>, which does the same thing.
1N/APrimarily this is so that you can use the B<undump> program (not
1N/Asupplied) to turn your core dump into an executable binary after
1N/Ahaving initialized all your variables at the beginning of the
1N/Aprogram. When the new binary is executed it will begin by executing
1N/Aa C<goto LABEL> (with all the restrictions that C<goto> suffers).
1N/AThink of it as a goto with an intervening core dump and reincarnation.
1N/AIf C<LABEL> is omitted, restarts the program from the top.
1N/AB<WARNING>: Any files opened at the time of the dump will I<not>
1N/Abe open any more when the program is reincarnated, with possible
1N/Aresulting confusion on the part of Perl.
1N/AThis function is now largely obsolete, partly because it's very
1N/Ahard to convert a core file into an executable, and because the
1N/Areal compiler backends for generating portable bytecode and compilable
1N/AC code have superseded it. That's why you should now invoke it as
1N/AC<CORE::dump()>, if you don't want to be warned against a possible
1N/AIf you're looking to use L<dump> to speed up your program, consider
1N/Agenerating bytecode or native C code as described in L<perlcc>. If
1N/Ayou're just trying to accelerate a CGI script, consider using the
1N/AC<mod_perl> extension to B<Apache>, or the CPAN module, CGI::Fast.
1N/AYou might also consider autoloading or selfloading, which at least
1N/Amake your program I<appear> to run faster.
1N/AWhen called in list context, returns a 2-element list consisting of the
1N/Akey and value for the next element of a hash, so that you can iterate over
1N/Ait. When called in scalar context, returns only the key for the next
1N/AEntries are returned in an apparently random order. The actual random
1N/Aorder is subject to change in future versions of perl, but it is
1N/Aguaranteed to be in the same order as either the C<keys> or C<values>
1N/Afunction would produce on the same (unmodified) hash. Since Perl
1N/A5.8.1 the ordering is different even between different runs of Perl
1N/Afor security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
1N/AWhen the hash is entirely read, a null array is returned in list context
1N/A(which when assigned produces a false (C<0>) value), and C<undef> in
1N/Ascalar context. The next call to C<each> after that will start iterating
1N/Aagain. There is a single iterator for each hash, shared by all C<each>,
1N/AC<keys>, and C<values> function calls in the program; it can be reset by
1N/Areading all the elements from the hash, or by evaluating C<keys HASH> or
1N/AC<values HASH>. If you add or delete elements of a hash while you're
1N/Aiterating over it, you may get entries skipped or duplicated, so
1N/Adon't. Exception: It is always safe to delete the item most recently
1N/Areturned by C<each()>, which means that the following code will work:
1N/A while (($key, $value) = each %hash) {
1N/A delete $hash{$key}; # This is safe
1N/AThe following prints out your environment like the printenv(1) program,
1N/Aonly in a different order:
1N/A while (($key,$value) = each %ENV) {
1N/A print "$key=$value\n";
1N/ASee also C<keys>, C<values> and C<sort>.
1N/AReturns 1 if the next read on FILEHANDLE will return end of file, or if
1N/AFILEHANDLE is not open. FILEHANDLE may be an expression whose value
1N/Agives the real filehandle. (Note that this function actually
1N/Areads a character and then C<ungetc>s it, so isn't very useful in an
1N/Ainteractive context.) Do not read from a terminal file (or call
1N/AC<eof(FILEHANDLE)> on it) after end-of-file is reached. File types such
1N/Aas terminals may lose the end-of-file condition if you do.
1N/AAn C<eof> without an argument uses the last file read. Using C<eof()>
1N/Awith empty parentheses is very different. It refers to the pseudo file
1N/Aformed from the files listed on the command line and accessed via the
1N/AC<< <> >> operator. Since C<< <> >> isn't explicitly opened,
1N/Aas a normal filehandle is, an C<eof()> before C<< <> >> has been
1N/Aused will cause C<@ARGV> to be examined to determine if input is
1N/Aavailable. Similarly, an C<eof()> after C<< <> >> has returned
1N/Aend-of-file will assume you are processing another C<@ARGV> list,
1N/Aand if you haven't set C<@ARGV>, will read input from C<STDIN>;
1N/Asee L<perlop/"I/O Operators">.
1N/AIn a C<< while (<>) >> loop, C<eof> or C<eof(ARGV)> can be used to
1N/Adetect the end of each file, C<eof()> will only detect the end of the
1N/A # reset line numbering on each input file
1N/A next if /^\s*#/; # skip comments
1N/A close ARGV if eof; # Not eof()!
1N/A # insert dashes just before last line of last file
1N/A if (eof()) { # check for end of last file
1N/A print "--------------\n";
1N/A last if eof(); # needed if we're reading from a terminal
1N/APractical hint: you almost never need to use C<eof> in Perl, because the
1N/Ainput operators typically return C<undef> when they run out of data, or if
1N/AIn the first form, the return value of EXPR is parsed and executed as if it
1N/Awere a little Perl program. The value of the expression (which is itself
1N/Adetermined within scalar context) is first parsed, and if there weren't any
1N/Aerrors, executed in the lexical context of the current Perl program, so
1N/Athat any variable settings or subroutine and format definitions remain
1N/Aafterwards. Note that the value is parsed every time the eval executes.
1N/AIf EXPR is omitted, evaluates C<$_>. This form is typically used to
1N/Adelay parsing and subsequent execution of the text of EXPR until run time.
1N/AIn the second form, the code within the BLOCK is parsed only once--at the
1N/Asame time the code surrounding the eval itself was parsed--and executed
1N/Awithin the context of the current Perl program. This form is typically
1N/Aused to trap exceptions more efficiently than the first (see below), while
1N/Aalso providing the benefit of checking the code within BLOCK at compile
1N/AThe final semicolon, if any, may be omitted from the value of EXPR or within
1N/AIn both forms, the value returned is the value of the last expression
1N/Aevaluated inside the mini-program; a return statement may be also used, just
1N/Aas with subroutines. The expression providing the return value is evaluated
1N/Ain void, scalar, or list context, depending on the context of the eval itself.
1N/ASee L</wantarray> for more on how the evaluation context can be determined.
1N/AIf there is a syntax error or runtime error, or a C<die> statement is
1N/Aexecuted, an undefined value is returned by C<eval>, and C<$@> is set to the
1N/Aerror message. If there was no error, C<$@> is guaranteed to be a null
1N/Astring. Beware that using C<eval> neither silences perl from printing
1N/Awarnings to STDERR, nor does it stuff the text of warning messages into C<$@>.
1N/ATo do either of those, you have to use the C<$SIG{__WARN__}> facility, or
1N/Aturn off warnings inside the BLOCK or EXPR using S<C<no warnings 'all'>>.
1N/ASee L</warn>, L<perlvar>, L<warnings> and L<perllexwarn>.
1N/ANote that, because C<eval> traps otherwise-fatal errors, it is useful for
1N/Adetermining whether a particular feature (such as C<socket> or C<symlink>)
1N/Ais implemented. It is also Perl's exception trapping mechanism, where
1N/Athe die operator is used to raise exceptions.
1N/AIf the code to be executed doesn't vary, you may use the eval-BLOCK
1N/Aform to trap run-time errors without incurring the penalty of
1N/Arecompiling each time. The error, if any, is still returned in C<$@>.
1N/A # make divide-by-zero nonfatal
1N/A eval { $answer = $a / $b; }; warn $@ if $@;
1N/A # same thing, but less efficient
1N/A eval '$answer = $a / $b'; warn $@ if $@;
1N/A # a compile-time error
1N/A eval { $answer = }; # WRONG
1N/A eval '$answer ='; # sets $@
1N/ADue to the current arguably broken state of C<__DIE__> hooks, when using
1N/Athe C<eval{}> form as an exception trap in libraries, you may wish not
1N/Ato trigger any C<__DIE__> hooks that user code may have installed.
1N/AYou can use the C<local $SIG{__DIE__}> construct for this purpose,
1N/Aas shown in this example:
1N/A # a very private exception trap for divide-by-zero
1N/A eval { local $SIG{'__DIE__'}; $answer = $a / $b; };
1N/AThis is especially significant, given that C<__DIE__> hooks can call
1N/AC<die> again, which has the effect of changing their error messages:
1N/A # __DIE__ hooks may modify error messages
1N/A local $SIG{'__DIE__'} =
1N/A eval { die "foo lives here" };
1N/A print $@ if $@; # prints "bar lives here"
1N/ABecause this promotes action at a distance, this counterintuitive behavior
1N/Amay be fixed in a future release.
1N/AWith an C<eval>, you should be especially careful to remember what's
1N/Abeing looked at when:
1N/A eval { $x }; # CASE 4
1N/A eval "\$$x++"; # CASE 5
1N/ACases 1 and 2 above behave identically: they run the code contained in
1N/Athe variable $x. (Although case 2 has misleading double quotes making
1N/Athe reader wonder what else might be happening (nothing is).) Cases 3
1N/Aand 4 likewise behave in the same way: they run the code C<'$x'>, which
1N/Adoes nothing but return the value of $x. (Case 4 is preferred for
1N/Apurely visual reasons, but it also has the advantage of compiling at
1N/Acompile-time instead of at run-time.) Case 5 is a place where
1N/Anormally you I<would> like to use double quotes, except that in this
1N/Aparticular situation, you can just use symbolic references instead, as
1N/AC<eval BLOCK> does I<not> count as a loop, so the loop control statements
1N/AC<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
1N/ANote that as a very special case, an C<eval ''> executed within the C<DB>
1N/Apackage doesn't see the usual surrounding lexical scope, but rather the
1N/Ascope of the first non-DB piece of code that called it. You don't normally
1N/Aneed to worry about this unless you are writing a Perl debugger.
1N/A=item exec PROGRAM LIST
1N/AThe C<exec> function executes a system command I<and never returns>--
1N/Ause C<system> instead of C<exec> if you want it to return. It fails and
1N/Areturns false only if the command does not exist I<and> it is executed
1N/Adirectly instead of via your system's command shell (see below).
1N/ASince it's a common mistake to use C<exec> instead of C<system>, Perl
1N/Awarns you if there is a following statement which isn't C<die>, C<warn>,
1N/Aor C<exit> (if C<-w> is set - but you always do that). If you
1N/AI<really> want to follow an C<exec> with some other statement, you
1N/Acan use one of these styles to avoid the warning:
1N/A exec ('foo') or print STDERR "couldn't exec foo: $!";
1N/A { exec ('foo') }; print STDERR "couldn't exec foo: $!";
1N/AIf there is more than one argument in LIST, or if LIST is an array
1N/Awith more than one value, calls execvp(3) with the arguments in LIST.
1N/AIf there is only one scalar argument or an array with one element in it,
1N/Athe argument is checked for shell metacharacters, and if there are any,
1N/Athe entire argument is passed to the system's command shell for parsing
1N/A(this is C<
/bin/sh -c> on Unix platforms, but varies on other platforms).
1N/AIf there are no shell metacharacters in the argument, it is split into
1N/Awords and passed directly to C<execvp>, which is more efficient.
1N/A exec "sort $outfile | uniq";
1N/AIf you don't really want to execute the first argument, but want to lie
1N/Ato the program you are executing about its own name, you can specify
1N/Athe program you actually want to run as an "indirect object" (without a
1N/Acomma) in front of the LIST. (This always forces interpretation of the
1N/ALIST as a multivalued list, even if there is only a single scalar in
1N/A exec $shell '-sh'; # pretend it's a login shell
1N/AWhen the arguments get executed via the system shell, results will
1N/Abe subject to its quirks and capabilities. See L<perlop/"`STRING`">
1N/AUsing an indirect object with C<exec> or C<system> is also more
1N/Asecure. This usage (which also works fine with system()) forces
1N/Ainterpretation of the arguments as a multivalued list, even if the
1N/Alist had just one argument. That way you're safe from the shell
1N/Aexpanding wildcards or splitting up words with whitespace in them.
1N/A @args = ( "echo surprise" );
1N/A exec @args; # subject to shell escapes
1N/A exec { $args[0] } @args; # safe even with one-arg list
1N/AThe first version, the one without the indirect object, ran the I<echo>
1N/Aprogram, passing it C<"surprise"> an argument. The second version
1N/Adidn't--it tried to run a program literally called I<"echo surprise">,
1N/Adidn't find it, and set C<$?> to a non-zero value indicating failure.
1N/ABeginning with v5.6.0, Perl will attempt to flush all files opened for
1N/Aoutput before the exec, but this may not be supported on some platforms
1N/A(see L<perlport>). To be safe, you may need to set C<$|> ($AUTOFLUSH
1N/Ain English) or call the C<autoflush()> method of C<IO::Handle> on any
1N/Aopen handles in order to avoid lost output.
1N/ANote that C<exec> will not call your C<END> blocks, nor will it call
1N/Aany C<DESTROY> methods in your objects.
1N/AGiven an expression that specifies a hash element or array element,
1N/Areturns true if the specified element in the hash or array has ever
1N/Abeen initialized, even if the corresponding value is undefined. The
1N/Aelement is not autovivified if it doesn't exist.
1N/A print "Exists\n" if exists $hash{$key};
1N/A print "Defined\n" if defined $hash{$key};
1N/A print "True\n" if $hash{$key};
1N/A print "Exists\n" if exists $array[$index];
1N/A print "Defined\n" if defined $array[$index];
1N/A print "True\n" if $array[$index];
1N/AA hash or array element can be true only if it's defined, and defined if
1N/Ait exists, but the reverse doesn't necessarily hold true.
1N/AGiven an expression that specifies the name of a subroutine,
1N/Areturns true if the specified subroutine has ever been declared, even
1N/Aif it is undefined. Mentioning a subroutine name for exists or defined
1N/Adoes not count as declaring it. Note that a subroutine which does not
1N/Aexist may still be callable: its package may have an C<AUTOLOAD>
1N/Amethod that makes it spring into existence the first time that it is
1N/Acalled -- see L<perlsub>.
1N/A print "Exists\n" if exists &subroutine;
1N/A print "Defined\n" if defined &subroutine;
1N/ANote that the EXPR can be arbitrarily complicated as long as the final
1N/Aoperation is a hash or array key lookup or subroutine name:
1N/A if (exists $ref->{A}->{B}->{$key}) { }
1N/A if (exists $hash{A}{B}{$key}) { }
1N/A if (exists $ref->{A}->{B}->[$ix]) { }
1N/A if (exists $hash{A}{B}[$ix]) { }
1N/A if (exists &{$ref->{A}{B}{$key}}) { }
1N/AAlthough the deepest nested array or hash will not spring into existence
1N/Ajust because its existence was tested, any intervening ones will.
1N/AThus C<< $ref->{"A"} >> and C<< $ref->{"A"}->{"B"} >> will spring
1N/Ainto existence due to the existence test for the $key element above.
1N/AThis happens anywhere the arrow operator is used, including even:
1N/A if (exists $ref->{"Some key"}) { }
1N/A print $ref; # prints HASH(0x80d3d5c)
1N/AThis surprising autovivification in what does not at first--or even
1N/Asecond--glance appear to be an lvalue context may be fixed in a future
1N/ASee L<perlref/"Pseudo-hashes: Using an array as a hash"> for specifics
1N/Aon how exists() acts when used on a pseudo-hash.
1N/AUse of a subroutine call, rather than a subroutine name, as an argument
1N/Ato exists() is an error.
1N/A exists &sub(); # Error
1N/AEvaluates EXPR and exits immediately with that value. Example:
1N/A exit 0 if $ans =~ /^[Xx]/;
1N/ASee also C<die>. If EXPR is omitted, exits with C<0> status. The only
1N/Auniversally recognized values for EXPR are C<0> for success and C<1>
1N/Afor error; other values are subject to interpretation depending on the
1N/Aenvironment in which the Perl program is running. For example, exiting
1N/A69 (EX_UNAVAILABLE) from a I<sendmail> incoming-mail filter will cause
1N/Athe mailer to return the item undelivered, but that's not true everywhere.
1N/ADon't use C<exit> to abort a subroutine if there's any chance that
1N/Asomeone might want to trap whatever error happened. Use C<die> instead,
1N/Awhich can be trapped by an C<eval>.
1N/AThe exit() function does not always exit immediately. It calls any
1N/Adefined C<END> routines first, but these C<END> routines may not
1N/Athemselves abort the exit. Likewise any object destructors that need to
1N/Abe called are called before the real exit. If this is a problem, you
1N/Acan call C<POSIX:_exit($status)> to avoid END and destructor processing.
1N/ASee L<perlmod> for details.
1N/AReturns I<e> (the natural logarithm base) to the power of EXPR.
1N/AIf EXPR is omitted, gives C<exp($_)>.
1N/A=item fcntl FILEHANDLE,FUNCTION,SCALAR
1N/AImplements the fcntl(2) function. You'll probably have to say
1N/Afirst to get the correct constant definitions. Argument processing and
1N/Avalue return works just like C<ioctl> below.
1N/A fcntl($filehandle, F_GETFL, $packed_return_buffer)
1N/A or die "can't fcntl F_GETFL: $!";
1N/AYou don't have to check for C<defined> on the return from C<fcntl>.
1N/ALike C<ioctl>, it maps a C<0> return from the system call into
1N/AC<"0 but true"> in Perl. This string is true in boolean context and C<0>
1N/Ain numeric context. It is also exempt from the normal B<-w> warnings
1N/Aon improper numeric conversions.
1N/ANote that C<fcntl> will produce a fatal error if used on a machine that
1N/Adoesn't implement fcntl(2). See the Fcntl module or your fcntl(2)
1N/Amanpage to learn what functions are available on your system.
1N/AHere's an example of setting a filehandle named C<REMOTE> to be
1N/Anon-blocking at the system level. You'll have to negotiate C<$|>
1N/A use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
1N/A $flags = fcntl(REMOTE, F_GETFL, 0)
1N/A or die "Can't get flags for the socket: $!\n";
1N/A $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
1N/A or die "Can't set flags for the socket: $!\n";
1N/A=item fileno FILEHANDLE
1N/AReturns the file descriptor for a filehandle, or undefined if the
1N/Afilehandle is not open. This is mainly useful for constructing
1N/Abitmaps for C<select> and low-level POSIX tty-handling operations.
1N/AIf FILEHANDLE is an expression, the value is taken as an indirect
1N/Afilehandle, generally its name.
1N/AYou can use this to find out whether two handles refer to the
1N/Asame underlying descriptor:
1N/A if (fileno(THIS) == fileno(THAT)) {
1N/A print "THIS and THAT are dups\n";
1N/A(Filehandles connected to memory objects via new features of C<open> may
1N/Areturn undefined even though they are open.)
1N/A=item flock FILEHANDLE,OPERATION
1N/ACalls flock(2), or an emulation of it, on FILEHANDLE. Returns true
1N/Afor success, false on failure. Produces a fatal error if used on a
1N/Amachine that doesn't implement flock(2), fcntl(2) locking, or lockf(3).
1N/AC<flock> is Perl's portable file locking interface, although it locks
1N/Aonly entire files, not records.
1N/ATwo potentially non-obvious but traditional C<flock> semantics are
1N/Athat it waits indefinitely until the lock is granted, and that its locks
1N/AB<merely advisory>. Such discretionary locks are more flexible, but offer
1N/Afewer guarantees. This means that files locked with C<flock> may be
1N/Amodified by programs that do not also use C<flock>. See L<perlport>,
1N/Ayour port's specific documentation, or your system-specific local manpages
1N/Afor details. It's best to assume traditional behavior if you're writing
1N/Aportable programs. (But if you're not, you should as always feel perfectly
1N/Afree to write for your own system's idiosyncrasies (sometimes called
1N/A"features"). Slavish adherence to portability concerns shouldn't get
1N/Ain the way of your getting your job done.)
1N/AOPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with
1N/ALOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but
1N/Ayou can use the symbolic names if you import them from the Fcntl module,
1N/Aeither individually, or as a group using the ':flock' tag. LOCK_SH
1N/Arequests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN
1N/Areleases a previously requested lock. If LOCK_NB is bitwise-or'ed with
1N/ALOCK_SH or LOCK_EX then C<flock> will return immediately rather than blocking
1N/Awaiting for the lock (check the return status to see if you got it).
1N/ATo avoid the possibility of miscoordination, Perl now flushes FILEHANDLE
1N/Abefore locking or unlocking it.
1N/ANote that the emulation built with lockf(3) doesn't provide shared
1N/Alocks, and it requires that FILEHANDLE be open with write intent. These
1N/Aare the semantics that lockf(3) implements. Most if not all systems
1N/Aimplement lockf(3) in terms of fcntl(2) locking, though, so the
1N/Adiffering semantics shouldn't bite too many people.
1N/ANote that the fcntl(2) emulation of flock(3) requires that FILEHANDLE
1N/Abe open with read intent to use LOCK_SH and requires that it be open
1N/Awith write intent to use LOCK_EX.
1N/ANote also that some versions of C<flock> cannot lock things over the
1N/Anetwork; you would need to use the more system-specific C<fcntl> for
1N/Athat. If you like you can force Perl to ignore your system's flock(2)
1N/Afunction, and so provide its own fcntl(2)-based emulation, by passing
1N/Athe switch C<-Ud_flock> to the F<Configure> program when you configure
1N/AHere's a mailbox appender for BSD systems.
1N/A use Fcntl ':flock'; # import LOCK_* constants
1N/A flock(MBOX,LOCK_EX);
1N/A # and, in case someone appended
1N/A # while we were waiting...
1N/A flock(MBOX,LOCK_UN);
1N/A or die "Can't open mailbox: $!";
1N/A print MBOX $msg,"\n\n";
1N/AOn systems that support a real flock(), locks are inherited across fork()
1N/Acalls, whereas those that must resort to the more capricious fcntl()
1N/Afunction lose the locks, making it harder to write servers.
1N/ASee also L<DB_File> for other flock() examples.
1N/ADoes a fork(2) system call to create a new process running the
1N/Asame program at the same point. It returns the child pid to the
1N/Aparent process, C<0> to the child process, or C<undef> if the fork is
1N/Aunsuccessful. File descriptors (and sometimes locks on those descriptors)
1N/Aare shared, while everything else is copied. On most systems supporting
1N/Afork(), great care has gone into making it extremely efficient (for
1N/Aexample, using copy-on-write technology on data pages), making it the
1N/Adominant paradigm for multitasking over the last few decades.
1N/ABeginning with v5.6.0, Perl will attempt to flush all files opened for
1N/Aoutput before forking the child process, but this may not be supported
1N/Aon some platforms (see L<perlport>). To be safe, you may need to set
1N/AC<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
1N/AC<IO::Handle> on any open handles in order to avoid duplicate output.
1N/AIf you C<fork> without ever waiting on your children, you will
1N/Aaccumulate zombies. On some systems, you can avoid this by setting
1N/AC<$SIG{CHLD}> to C<"IGNORE">. See also L<perlipc> for more examples of
1N/Aforking and reaping moribund children.
1N/ANote that if your forked child inherits system file descriptors like
1N/ASTDIN and STDOUT that are actually connected by a pipe or socket, even
1N/Aif you exit, then the remote server (such as, say, a CGI script or a
1N/Abackgrounded job launched from a remote shell) won't think you're done.
1N/ADeclare a picture format for use by the C<write> function. For
1N/A Test: @<<<<<<<< @||||| @>>>>>
1N/A $str, $%, '$' . int($num)
1N/A $num = $cost/$quantity;
1N/ASee L<perlform> for many details and examples.
1N/A=item formline PICTURE,LIST
1N/AThis is an internal function used by C<format>s, though you may call it,
1N/Atoo. It formats (see L<perlform>) a list of values according to the
1N/Acontents of PICTURE, placing the output into the format output
1N/Aaccumulator, C<$^A> (or C<$ACCUMULATOR> in English).
1N/AEventually, when a C<write> is done, the contents of
1N/AC<$^A> are written to some filehandle, but you could also read C<$^A>
1N/Ayourself and then set C<$^A> back to C<"">. Note that a format typically
1N/Adoes one C<formline> per line of form, but the C<formline> function itself
1N/Adoesn't care how many newlines are embedded in the PICTURE. This means
1N/Athat the C<~> and C<~~> tokens will treat the entire PICTURE as a single line.
1N/AYou may therefore need to use multiple formlines to implement a single
1N/Arecord format, just like the format compiler.
1N/ABe careful if you put double quotes around the picture, because an C<@>
1N/Acharacter may be taken to mean the beginning of an array name.
1N/AC<formline> always returns true. See L<perlform> for other examples.
1N/A=item getc FILEHANDLE
1N/AReturns the next character from the input file attached to FILEHANDLE,
1N/Aor the undefined value at end of file, or if there was an error (in
1N/Athe latter case C<$!> is set). If FILEHANDLE is omitted, reads from
1N/ASTDIN. This is not particularly efficient. However, it cannot be
1N/Aused by itself to fetch single characters without waiting for the user
1N/Ato hit enter. For that, try something more like:
1N/A system "stty", '-icanon', 'eol', "\001";
1N/A system "stty", 'icanon', 'eol', '^@'; # ASCII null
1N/ADetermination of whether $BSD_STYLE should be set
1N/Ais left as an exercise to the reader.
1N/AThe C<POSIX::getattr> function can do this more portably on
1N/Asystems purporting POSIX compliance. See also the C<Term::ReadKey>
1N/Amodule from your nearest CPAN site; details on CPAN can be found on
1N/AImplements the C library function of the same name, which on most
1N/Asystems returns the current login from F<
/etc/utmp>, if any. If null,
1N/A $login = getlogin || getpwuid($<) || "Kilroy";
1N/ADo not consider C<getlogin> for authentication: it is not as
1N/Asecure as C<getpwuid>.
1N/A=item getpeername SOCKET
1N/AReturns the packed sockaddr address of other end of the SOCKET connection.
1N/A $hersockaddr = getpeername(SOCK);
1N/A ($port, $iaddr) = sockaddr_in($hersockaddr);
1N/A $herhostname = gethostbyaddr($iaddr, AF_INET);
1N/A $herstraddr = inet_ntoa($iaddr);
1N/AReturns the current process group for the specified PID. Use
1N/Aa PID of C<0> to get the current process group for the
1N/Acurrent process. Will raise an exception if used on a machine that
1N/Adoesn't implement getpgrp(2). If PID is omitted, returns process
1N/Agroup of current process. Note that the POSIX version of C<getpgrp>
1N/Adoes not accept a PID argument, so only C<PID==0> is truly portable.
1N/AReturns the process id of the parent process.
1N/ANote for Linux users: on Linux, the C functions C<getpid()> and
1N/AC<getppid()> return different values from different threads. In order to
1N/Abe portable, this behavior is not reflected by the perl-level function
1N/AC<getppid()>, that returns a consistent value across threads. If you want
1N/Ato call the underlying C<getppid()>, you may use the CPAN module
1N/A=item getpriority WHICH,WHO
1N/AReturns the current priority for a process, a process group, or a user.
1N/A(See L<getpriority(2)>.) Will raise a fatal exception if used on a
1N/Amachine that doesn't implement getpriority(2).
1N/A=item gethostbyname NAME
1N/A=item getnetbyname NAME
1N/A=item getprotobyname NAME
1N/A=item getservbyname NAME,PROTO
1N/A=item gethostbyaddr ADDR,ADDRTYPE
1N/A=item getnetbyaddr ADDR,ADDRTYPE
1N/A=item getprotobynumber NUMBER
1N/A=item getservbyport PORT,PROTO
1N/A=item sethostent STAYOPEN
1N/A=item setnetent STAYOPEN
1N/A=item setprotoent STAYOPEN
1N/A=item setservent STAYOPEN
1N/AThese routines perform the same functions as their counterparts in the
1N/Asystem library. In list context, the return values from the
1N/Avarious get routines are as follows:
1N/A ($name,$passwd,$uid,$gid,
1N/A $quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
1N/A ($name,$passwd,$gid,$members) = getgr*
1N/A ($name,$aliases,$addrtype,$length,@addrs) = gethost*
1N/A ($name,$aliases,$addrtype,$net) = getnet*
1N/A ($name,$aliases,$proto) = getproto*
1N/A ($name,$aliases,$port,$proto) = getserv*
1N/A(If the entry doesn't exist you get a null list.)
1N/AThe exact meaning of the $gcos field varies but it usually contains
1N/Athe real name of the user (as opposed to the login name) and other
1N/Ainformation pertaining to the user. Beware, however, that in many
1N/Asystem users are able to change this information and therefore it
1N/Acannot be trusted and therefore the $gcos is tainted (see
1N/AL<perlsec>). The $passwd and $shell, user's encrypted password and
1N/Alogin shell, are also tainted, because of the same reason.
1N/AIn scalar context, you get the name, unless the function was a
1N/Alookup by name, in which case you get the other thing, whatever it is.
1N/A(If the entry doesn't exist you get the undefined value.) For example:
1N/A $uid = getpwnam($name);
1N/A $name = getpwuid($num);
1N/A $gid = getgrnam($name);
1N/A $name = getgrgid($num);
1N/AIn I<getpw*()> the fields $quota, $comment, and $expire are special
1N/Acases in the sense that in many systems they are unsupported. If the
1N/A$quota is unsupported, it is an empty scalar. If it is supported, it
1N/Ausually encodes the disk quota. If the $comment field is unsupported,
1N/Ait is an empty scalar. If it is supported it usually encodes some
1N/Aadministrative comment about the user. In some systems the $quota
1N/Afield may be $change or $age, fields that have to do with password
1N/Aaging. In some systems the $comment field may be $class. The $expire
1N/Afield, if present, encodes the expiration period of the account or the
1N/Apassword. For the availability and the exact meaning of these fields
1N/Ain your system, please consult your getpwnam(3) documentation and your
1N/AF<
pwd.h> file. You can also find out from within Perl what your
1N/A$quota and $comment fields mean and whether you have the $expire field
1N/Aby using the C<Config> module and the values C<d_pwquota>, C<d_pwage>,
1N/AC<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>. Shadow password
1N/Afiles are only supported if your vendor has implemented them in the
1N/Aintuitive fashion that calling the regular C library routines gets the
1N/Ashadow versions if you're running under privilege or if there exists
1N/Athe shadow(3) functions as found in System V ( this includes Solaris
1N/Aand Linux.) Those systems which implement a proprietary shadow password
1N/Afacility are unlikely to be supported.
1N/AThe $members value returned by I<getgr*()> is a space separated list of
1N/Athe login names of the members of the group.
1N/AFor the I<gethost*()> functions, if the C<h_errno> variable is supported in
1N/AC, it will be returned to you via C<$?> if the function call fails. The
1N/AC<@addrs> value returned by a successful call is a list of the raw
1N/Aaddresses returned by the corresponding system library call. In the
1N/AInternet domain, each address is four bytes long and you can unpack it
1N/Aby saying something like:
1N/A ($a,$b,$c,$d) = unpack('C4',$addr[0]);
1N/AThe Socket library makes this slightly easier:
1N/A $iaddr = inet_aton("127.1"); # or whatever address
1N/A $name = gethostbyaddr($iaddr, AF_INET);
1N/A # or going the other way
1N/A $straddr = inet_ntoa($iaddr);
1N/AIf you get tired of remembering which element of the return list
1N/Acontains which return value, by-name interfaces are provided
1N/Ain standard modules: C<File::stat>, C<Net::hostent>, C<Net::netent>,
1N/AC<Net::protoent>, C<Net::servent>, C<Time::gmtime>, C<Time::localtime>,
1N/Aand C<User::grent>. These override the normal built-ins, supplying
1N/Aversions that return objects with the appropriate names
1N/Afor each field. For example:
1N/A $is_his = (stat($filename)->uid == pwent($whoever)->uid);
1N/AEven though it looks like they're the same method calls (uid),
1N/Athey aren't, because a C<File::stat> object is different from
1N/Aa C<User::pwent> object.
1N/A=item getsockname SOCKET
1N/AReturns the packed sockaddr address of this end of the SOCKET connection,
1N/Ain case you don't know the address because you have several different
1N/AIPs that the connection might have come in on.
1N/A $mysockaddr = getsockname(SOCK);
1N/A ($port, $myaddr) = sockaddr_in($mysockaddr);
1N/A printf "Connect to %s [%s]\n",
1N/A scalar gethostbyaddr($myaddr, AF_INET),
1N/A=item getsockopt SOCKET,LEVEL,OPTNAME
1N/AReturns the socket option requested, or undef if there is an error.
1N/AIn list context, returns a (possibly empty) list of filename expansions on
1N/Athe value of EXPR such as the standard Unix shell F<
/bin/csh> would do. In
1N/Ascalar context, glob iterates through such filename expansions, returning
1N/Aundef when the list is exhausted. This is the internal function
1N/Aimplementing the C<< <*.c> >> operator, but you can use it directly. If
1N/AEXPR is omitted, C<$_> is used. The C<< <*.c> >> operator is discussed in
1N/Amore detail in L<perlop/"I/O Operators">.
1N/ABeginning with v5.6.0, this operator is implemented using the standard
1N/AC<File::Glob> extension. See L<File::Glob> for details.
1N/AConverts a time as returned by the time function to an 8-element list
1N/Awith the time localized for the standard Greenwich time zone.
1N/ATypically used as follows:
1N/A ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday) =
1N/AAll list elements are numeric, and come straight out of the C `struct
1N/Atm'. $sec, $min, and $hour are the seconds, minutes, and hours of the
1N/Aspecified time. $mday is the day of the month, and $mon is the month
1N/Aitself, in the range C<0..11> with 0 indicating January and 11
1N/Aindicating December. $year is the number of years since 1900. That
1N/Ais, $year is C<123> in year 2023. $wday is the day of the week, with
1N/A0 indicating Sunday and 3 indicating Wednesday. $yday is the day of
1N/Athe year, in the range C<0..364> (or C<0..365> in leap years.)
1N/ANote that the $year element is I<not> simply the last two digits of
1N/Athe year. If you assume it is, then you create non-Y2K-compliant
1N/Aprograms--and you wouldn't want to do that, would you?
1N/AThe proper way to get a complete 4-digit year is simply:
1N/AAnd to get the last two digits of the year (
e.g., '01' in 2001) do:
1N/A $year = sprintf("%02d", $year % 100);
1N/AIf EXPR is omitted, C<gmtime()> uses the current time (C<gmtime(time)>).
1N/AIn scalar context, C<gmtime()> returns the ctime(3) value:
1N/A $now_string = gmtime; #
e.g., "Thu Oct 13 04:54:34 1994"
1N/AIf you need local time instead of GMT use the L</localtime> builtin.
1N/ASee also the C<timegm> function provided by the C<Time::Local> module,
1N/Aand the strftime(3) and mktime(3) functions available via the L<POSIX> module.
1N/AThis scalar value is B<not> locale dependent (see L<perllocale>), but is
1N/Ainstead a Perl builtin. To get somewhat similar but locale dependent date
1N/Astrings, see the example in L</localtime>.
1N/AThe C<goto-LABEL> form finds the statement labeled with LABEL and resumes
1N/Aexecution there. It may not be used to go into any construct that
1N/Arequires initialization, such as a subroutine or a C<foreach> loop. It
1N/Aalso can't be used to go into a construct that is optimized away,
1N/Aor to get out of a block or subroutine given to C<sort>.
1N/AIt can be used to go almost anywhere else within the dynamic scope,
1N/Aincluding out of subroutines, but it's usually better to use some other
1N/Aconstruct such as C<last> or C<die>. The author of Perl has never felt the
1N/Aneed to use this form of C<goto> (in Perl, that is--C is another matter).
1N/A(The difference being that C does not offer named loops combined with
1N/Aloop control. Perl does, and this replaces most structured uses of C<goto>
1N/AThe C<goto-EXPR> form expects a label name, whose scope will be resolved
1N/Adynamically. This allows for computed C<goto>s per FORTRAN, but isn't
1N/Anecessarily recommended if you're optimizing for maintainability:
1N/A goto ("FOO", "BAR", "GLARCH")[$i];
1N/AThe C<goto-&NAME> form is quite different from the other forms of
1N/AC<goto>. In fact, it isn't a goto in the normal sense at all, and
1N/Adoesn't have the stigma associated with other gotos. Instead, it
1N/Aexits the current subroutine (losing any changes set by local()) and
1N/Aimmediately calls in its place the named subroutine using the current
1N/Avalue of @_. This is used by C<AUTOLOAD> subroutines that wish to
1N/Aload another subroutine and then pretend that the other subroutine had
1N/Abeen called in the first place (except that any modifications to C<@_>
1N/Ain the current subroutine are propagated to the other subroutine.)
1N/AAfter the C<goto>, not even C<caller> will be able to tell that this
1N/Aroutine was called first.
1N/ANAME needn't be the name of a subroutine; it can be a scalar variable
1N/Acontaining a code reference, or a block which evaluates to a code
1N/A=item grep BLOCK LIST
1N/AThis is similar in spirit to, but not the same as, grep(1) and its
1N/Arelatives. In particular, it is not limited to using regular expressions.
1N/AEvaluates the BLOCK or EXPR for each element of LIST (locally setting
1N/AC<$_> to each element) and returns the list value consisting of those
1N/Aelements for which the expression evaluated to true. In scalar
1N/Acontext, returns the number of times the expression was true.
1N/A @foo = grep(!/^#/, @bar); # weed out comments
1N/A @foo = grep {!/^#/} @bar; # weed out comments
1N/ANote that C<$_> is an alias to the list value, so it can be used to
1N/Amodify the elements of the LIST. While this is useful and supported,
1N/Ait can cause bizarre results if the elements of LIST are not variables.
1N/ASimilarly, grep returns aliases into the original list, much as a for
1N/Aloop's index variable aliases the list elements. That is, modifying an
1N/Aelement of a list returned by grep (for example, in a C<foreach>, C<map>
1N/Aor another C<grep>) actually modifies the element in the original list.
1N/AThis is usually something to be avoided when writing clear code.
1N/ASee also L</map> for a list composed of the results of the BLOCK or EXPR.
1N/AInterprets EXPR as a hex string and returns the corresponding value.
1N/A(To convert strings that might start with either 0, 0x, or 0b, see
1N/AL</oct>.) If EXPR is omitted, uses C<$_>.
1N/A print hex '0xAf'; # prints '175'
1N/A print hex 'aF'; # same
1N/AHex strings may only represent integers. Strings that would cause
1N/Ainteger overflow trigger a warning. Leading whitespace is not stripped,
1N/AThere is no builtin C<import> function. It is just an ordinary
1N/Amethod (subroutine) defined (or inherited) by modules that wish to export
1N/Anames to another module. The C<use> function calls the C<import> method
1N/Afor the package used. See also L</use>, L<perlmod>, and L<Exporter>.
1N/A=item index STR,SUBSTR,POSITION
1N/A=item index STR,SUBSTR
1N/AThe index function searches for one string within another, but without
1N/Athe wildcard-like behavior of a full regular-expression pattern match.
1N/AIt returns the position of the first occurrence of SUBSTR in STR at
1N/Aor after POSITION. If POSITION is omitted, starts searching from the
1N/Abeginning of the string. The return value is based at C<0> (or whatever
1N/Ayou've set the C<$[> variable to--but don't do that). If the substring
1N/Ais not found, returns one less than the base, ordinarily C<-1>.
1N/AReturns the integer portion of EXPR. If EXPR is omitted, uses C<$_>.
1N/AYou should not use this function for rounding: one because it truncates
1N/Atowards C<0>, and two because machine representations of floating point
1N/Anumbers can sometimes produce counterintuitive results. For example,
1N/AC<int(-6.725/0.025)> produces -268 rather than the correct -269; that's
1N/Abecause it's really more like -268.99999999999994315658 instead. Usually,
1N/Athe C<sprintf>, C<printf>, or the C<POSIX::floor> and C<POSIX::ceil>
1N/Afunctions will serve you better than will int().
1N/A=item ioctl FILEHANDLE,FUNCTION,SCALAR
1N/AImplements the ioctl(2) function. You'll probably first have to say
1N/Ato get the correct function definitions. If F<
ioctl.ph> doesn't
1N/Aexist or doesn't have the correct definitions you'll have to roll your
1N/A(There is a Perl script called B<h2ph> that comes with the Perl kit that
1N/Amay help you in this, but it's nontrivial.) SCALAR will be read
and/or 1N/Awritten depending on the FUNCTION--a pointer to the string value of SCALAR
1N/Awill be passed as the third argument of the actual C<ioctl> call. (If SCALAR
1N/Ahas no string value but does have a numeric value, that value will be
1N/Apassed rather than a pointer to the string value. To guarantee this to be
1N/Atrue, add a C<0> to the scalar before using it.) The C<pack> and C<unpack>
1N/Afunctions may be needed to manipulate the values of structures used by
1N/AThe return value of C<ioctl> (and C<fcntl>) is as follows:
1N/A if OS returns: then Perl returns:
1N/A 0 string "0 but true"
1N/A anything else that number
1N/AThus Perl returns true on success and false on failure, yet you can
1N/Astill easily determine the actual value returned by the operating
1N/A $retval = ioctl(...) || -1;
1N/A printf "System returned %d\n", $retval;
1N/AThe special string C<"0 but true"> is exempt from B<-w> complaints
1N/Aabout improper numeric conversions.
1N/AJoins the separate strings of LIST into a single string with fields
1N/Aseparated by the value of EXPR, and returns that new string. Example:
1N/A $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
1N/ABeware that unlike C<split>, C<join> doesn't take a pattern as its
1N/Afirst argument. Compare L</split>.
1N/AReturns a list consisting of all the keys of the named hash.
1N/A(In scalar context, returns the number of keys.)
1N/AThe keys are returned in an apparently random order. The actual
1N/Arandom order is subject to change in future versions of perl, but it
1N/Ais guaranteed to be the same order as either the C<values> or C<each>
1N/Afunction produces (given that the hash has not been modified). Since
1N/APerl 5.8.1 the ordering is different even between different runs of
1N/APerl for security reasons (see L<perlsec/"Algorithmic Complexity
1N/AAs a side effect, calling keys() resets the HASH's internal iterator,
1N/Asee L</each>. (In particular, calling keys() in void context resets
1N/Athe iterator with no other overhead.)
1N/AHere is yet another way to print your environment:
1N/A @values = values %ENV;
1N/A print pop(@keys), '=', pop(@values), "\n";
1N/Aor how about sorted by key:
1N/A foreach $key (sort(keys %ENV)) {
1N/A print $key, '=', $ENV{$key}, "\n";
1N/AThe returned values are copies of the original keys in the hash, so
1N/Amodifying them will not affect the original hash. Compare L</values>.
1N/ATo sort a hash by value, you'll need to use a C<sort> function.
1N/AHere's a descending numeric sort of a hash by its values:
1N/A foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
1N/A printf "%4d %s\n", $hash{$key}, $key;
1N/AAs an lvalue C<keys> allows you to increase the number of hash buckets
1N/Aallocated for the given hash. This can gain you a measure of efficiency if
1N/Ayou know the hash is going to get big. (This is similar to pre-extending
1N/Aan array by assigning a larger number to $#array.) If you say
1N/Athen C<%hash> will have at least 200 buckets allocated for it--256 of them,
1N/Ain fact, since it rounds up to the next power of two. These
1N/Abuckets will be retained even if you do C<%hash = ()>, use C<undef
1N/A%hash> if you want to free the storage while C<%hash> is still in scope.
1N/AYou can't shrink the number of buckets allocated for the hash using
1N/AC<keys> in this way (but you needn't worry about doing this by accident,
1N/Aas trying has no effect).
1N/ASee also C<each>, C<values> and C<sort>.
1N/A=item kill SIGNAL, LIST
1N/ASends a signal to a list of processes. Returns the number of
1N/Aprocesses successfully signaled (which is not necessarily the
1N/Asame as the number actually killed).
1N/A $cnt = kill 1, $child1, $child2;
1N/AIf SIGNAL is zero, no signal is sent to the process. This is a
1N/Auseful way to check that a child process is alive and hasn't changed
1N/Aits UID. See L<perlport> for notes on the portability of this
1N/AUnlike in the shell, if SIGNAL is negative, it kills
1N/Aprocess groups instead of processes. (On System V, a negative I<PROCESS>
1N/Anumber will also kill process groups, but that's not portable.) That
1N/Ameans you usually want to use positive not negative signals. You may also
1N/Ause a signal name in quotes.
1N/ASee L<perlipc/"Signals"> for more details.
1N/AThe C<last> command is like the C<break> statement in C (as used in
1N/Aloops); it immediately exits the loop in question. If the LABEL is
1N/Aomitted, the command refers to the innermost enclosing loop. The
1N/AC<continue> block, if any, is not executed:
1N/A LINE: while (<STDIN>) {
1N/A last LINE if /^$/; # exit when done with header
1N/AC<last> cannot be used to exit a block which returns a value such as
1N/AC<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit
1N/Aa grep() or map() operation.
1N/ANote that a block by itself is semantically identical to a loop
1N/Athat executes once. Thus C<last> can be used to effect an early
1N/Aexit out of such a block.
1N/ASee also L</continue> for an illustration of how C<last>, C<next>, and
1N/AReturns a lowercased version of EXPR. This is the internal function
1N/Aimplementing the C<\L> escape in double-quoted strings. Respects
1N/Acurrent LC_CTYPE locale if C<use locale> in force. See L<perllocale>
1N/Aand L<perlunicode> for more details about locale and Unicode support.
1N/AIf EXPR is omitted, uses C<$_>.
1N/AReturns the value of EXPR with the first character lowercased. This
1N/Ais the internal function implementing the C<\l> escape in
1N/Adouble-quoted strings. Respects current LC_CTYPE locale if C<use
1N/Alocale> in force. See L<perllocale> and L<perlunicode> for more
1N/Adetails about locale and Unicode support.
1N/AIf EXPR is omitted, uses C<$_>.
1N/AReturns the length in I<characters> of the value of EXPR. If EXPR is
1N/Aomitted, returns length of C<$_>. Note that this cannot be used on
1N/Aan entire array or hash to find out how many elements these have.
1N/AFor that, use C<scalar @array> and C<scalar keys %hash> respectively.
1N/ANote the I<characters>: if the EXPR is in Unicode, you will get the
1N/Anumber of characters, not the number of bytes. To get the length
1N/Ain bytes, use C<do { use bytes; length(EXPR) }>, see L<bytes>.
1N/A=item link OLDFILE,NEWFILE
1N/ACreates a new filename linked to the old filename. Returns true for
1N/Asuccess, false otherwise.
1N/A=item listen SOCKET,QUEUESIZE
1N/ADoes the same thing that the listen system call does. Returns true if
1N/Ait succeeded, false otherwise. See the example in
1N/AYou really probably want to be using C<my> instead, because C<local> isn't
1N/Awhat most people think of as "local". See
1N/AL<perlsub/"Private Variables via my()"> for details.
1N/AA local modifies the listed variables to be local to the enclosing
1N/Ablock, file, or eval. If more than one value is listed, the list must
1N/Abe placed in parentheses. See L<perlsub/"Temporary Values via local()">
1N/Afor details, including issues with tied arrays and hashes.
1N/AConverts a time as returned by the time function to a 9-element list
1N/Awith the time analyzed for the local time zone. Typically used as
1N/A ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
1N/AAll list elements are numeric, and come straight out of the C `struct
1N/Atm'. $sec, $min, and $hour are the seconds, minutes, and hours of the
1N/Aspecified time. $mday is the day of the month, and $mon is the month
1N/Aitself, in the range C<0..11> with 0 indicating January and 11
1N/Aindicating December. $year is the number of years since 1900. That
1N/Ais, $year is C<123> in year 2023. $wday is the day of the week, with
1N/A0 indicating Sunday and 3 indicating Wednesday. $yday is the day of
1N/Athe year, in the range C<0..364> (or C<0..365> in leap years.) $isdst
1N/Ais true if the specified time occurs during daylight savings time,
1N/ANote that the $year element is I<not> simply the last two digits of
1N/Athe year. If you assume it is, then you create non-Y2K-compliant
1N/Aprograms--and you wouldn't want to do that, would you?
1N/AThe proper way to get a complete 4-digit year is simply:
1N/AAnd to get the last two digits of the year (
e.g., '01' in 2001) do:
1N/A $year = sprintf("%02d", $year % 100);
1N/AIf EXPR is omitted, C<localtime()> uses the current time (C<localtime(time)>).
1N/AIn scalar context, C<localtime()> returns the ctime(3) value:
1N/A $now_string = localtime; #
e.g., "Thu Oct 13 04:54:34 1994"
1N/AThis scalar value is B<not> locale dependent but is a Perl builtin. For GMT
1N/Ainstead of local time use the L</gmtime> builtin. See also the
1N/AC<Time::Local> module (to convert the second, minutes, hours, ... back to
1N/Athe integer value returned by time()), and the L<POSIX> module's strftime(3)
1N/Aand mktime(3) functions.
1N/ATo get somewhat similar but locale dependent date strings, set up your
1N/Alocale environment variables appropriately (please see L<perllocale>) and
1N/A use POSIX qw(strftime);
1N/A $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
1N/A # or for GMT formatted appropriately for your locale:
1N/A $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
1N/ANote that the C<%a> and C<%b>, the short forms of the day of the week
1N/Aand the month of the year, may not necessarily be three characters wide.
1N/AThis function places an advisory lock on a shared variable, or referenced
1N/Aobject contained in I<THING> until the lock goes out of scope.
1N/Alock() is a "weak keyword" : this means that if you've defined a function
1N/Aby this name (before any calls to it), that function will be called
1N/Ainstead. (However, if you've said C<use threads>, lock() is always a
1N/Akeyword.) See L<threads>.
1N/AReturns the natural logarithm (base I<e>) of EXPR. If EXPR is omitted,
1N/Areturns log of C<$_>. To get the log of another base, use basic algebra:
1N/AThe base-N log of a number is equal to the natural log of that number
1N/Adivided by the natural log of N. For example:
1N/A return log($n)/log(10);
1N/ASee also L</exp> for the inverse operation.
1N/ADoes the same thing as the C<stat> function (including setting the
1N/Aspecial C<_> filehandle) but stats a symbolic link instead of the file
1N/Athe symbolic link points to. If symbolic links are unimplemented on
1N/Ayour system, a normal C<stat> is done. For much more detailed
1N/Ainformation, please see the documentation for L</stat>.
1N/AIf EXPR is omitted, stats C<$_>.
1N/AThe match operator. See L<perlop>.
1N/AEvaluates the BLOCK or EXPR for each element of LIST (locally setting
1N/AC<$_> to each element) and returns the list value composed of the
1N/Aresults of each such evaluation. In scalar context, returns the
1N/Atotal number of elements so generated. Evaluates BLOCK or EXPR in
1N/Alist context, so each element of LIST may produce zero, one, or
1N/Amore elements in the returned value.
1N/A @chars = map(chr, @nums);
1N/Atranslates a list of numbers to the corresponding characters. And
1N/A %hash = map { getkey($_) => $_ } @array;
1N/Ais just a funny way to write
1N/A foreach $_ (@array) {
1N/A $hash{getkey($_)} = $_;
1N/ANote that C<$_> is an alias to the list value, so it can be used to
1N/Amodify the elements of the LIST. While this is useful and supported,
1N/Ait can cause bizarre results if the elements of LIST are not variables.
1N/AUsing a regular C<foreach> loop for this purpose would be clearer in
1N/Amost cases. See also L</grep> for an array composed of those items of
1N/Athe original list for which the BLOCK or EXPR evaluates to true.
1N/AC<{> starts both hash references and blocks, so C<map { ...> could be either
1N/Athe start of map BLOCK LIST or map EXPR, LIST. Because perl doesn't look
1N/Aahead for the closing C<}> it has to take a guess at which its dealing with
1N/Abased what it finds just after the C<{>. Usually it gets it right, but if it
1N/Adoesn't it won't realize something is wrong until it gets to the C<}> and
1N/Aencounters the missing (or unexpected) comma. The syntax error will be
1N/Areported close to the C<}> but you'll need to change something near the C<{>
1N/Asuch as using a unary C<+> to give perl some help:
1N/A %hash = map { "\L$_", 1 } @array # perl guesses EXPR. wrong
1N/A %hash = map { +"\L$_", 1 } @array # perl guesses BLOCK. right
1N/A %hash = map { ("\L$_", 1) } @array # this also works
1N/A %hash = map { lc($_), 1 } @array # as does this.
1N/A %hash = map +( lc($_), 1 ), @array # this is EXPR and works!
1N/A %hash = map ( lc($_), 1 ), @array # evaluates to (1, @array)
1N/Aor to force an anon hash constructor use C<+{>
1N/A @hashes = map +{ lc($_), 1 }, @array # EXPR, so needs , at end
1N/Aand you get list of anonymous hashes each with only 1 entry.
1N/A=item mkdir FILENAME,MASK
1N/ACreates the directory specified by FILENAME, with permissions
1N/Aspecified by MASK (as modified by C<umask>). If it succeeds it
1N/Areturns true, otherwise it returns false and sets C<$!> (errno).
1N/AIf omitted, MASK defaults to 0777.
1N/AIn general, it is better to create directories with permissive MASK,
1N/Aand let the user modify that with their C<umask>, than it is to supply
1N/Aa restrictive MASK and give the user no way to be more permissive.
1N/AThe exceptions to this rule are when the file or directory should be
1N/Akept private (mail files, for instance). The perlfunc(1) entry on
1N/AC<umask> discusses the choice of MASK in more detail.
1N/ANote that according to the POSIX 1003.1-1996 the FILENAME may have any
1N/Anumber of trailing slashes. Some operating and filesystems do not get
1N/Athis right, so Perl automatically removes all trailing slashes to keep
1N/A=item msgctl ID,CMD,ARG
1N/ACalls the System V IPC function msgctl(2). You'll probably have to say
1N/Afirst to get the correct constant definitions. If CMD is C<IPC_STAT>,
1N/Athen ARG must be a variable which will hold the returned C<msqid_ds>
1N/Astructure. Returns like C<ioctl>: the undefined value for error,
1N/AC<"0 but true"> for zero, or the actual return value otherwise. See also
1N/AL<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::Semaphore> documentation.
1N/A=item msgget KEY,FLAGS
1N/ACalls the System V IPC function msgget(2). Returns the message queue
1N/Aid, or the undefined value if there is an error. See also
1N/AL<perlipc/"SysV IPC"> and C<IPC::SysV> and C<IPC::Msg> documentation.
1N/A=item msgrcv ID,VAR,SIZE,TYPE,FLAGS
1N/ACalls the System V IPC function msgrcv to receive a message from
1N/Amessage queue ID into variable VAR with a maximum message size of
1N/ASIZE. Note that when a message is received, the message type as a
1N/Anative long integer will be the first thing in VAR, followed by the
1N/Aactual message. This packing may be opened with C<unpack("l! a*")>.
1N/ATaints the variable. Returns true if successful, or false if there is
1N/Aan error. See also L<perlipc/"SysV IPC">, C<IPC::SysV>, and
1N/AC<IPC::SysV::Msg> documentation.
1N/A=item msgsnd ID,MSG,FLAGS
1N/ACalls the System V IPC function msgsnd to send the message MSG to the
1N/Amessage queue ID. MSG must begin with the native long integer message
1N/Atype, and be followed by the length of the actual message, and finally
1N/Athe message itself. This kind of packing can be achieved with
1N/AC<pack("l! a*", $type, $message)>. Returns true if successful,
1N/Aor false if there is an error. See also C<IPC::SysV>
1N/Aand C<IPC::SysV::Msg> documentation.
1N/A=item my EXPR : ATTRS
1N/A=item my TYPE EXPR : ATTRS
1N/AA C<my> declares the listed variables to be local (lexically) to the
1N/Aenclosing block, file, or C<eval>. If more than one value is listed,
1N/Athe list must be placed in parentheses.
1N/AThe exact semantics and interface of TYPE and ATTRS are still
1N/Aevolving. TYPE is currently bound to the use of C<fields> pragma,
1N/Aand attributes are handled using the C<attributes> pragma, or starting
1N/Afrom Perl 5.8.0 also via the C<Attribute::Handlers> module. See
1N/AL<perlsub/"Private Variables via my()"> for details, and L<fields>,
1N/AL<attributes>, and L<Attribute::Handlers>.
1N/AThe C<next> command is like the C<continue> statement in C; it starts
1N/Athe next iteration of the loop:
1N/A LINE: while (<STDIN>) {
1N/A next LINE if /^#/; # discard comments
1N/ANote that if there were a C<continue> block on the above, it would get
1N/Aexecuted even on discarded lines. If the LABEL is omitted, the command
1N/Arefers to the innermost enclosing loop.
1N/AC<next> cannot be used to exit a block which returns a value such as
1N/AC<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit
1N/Aa grep() or map() operation.
1N/ANote that a block by itself is semantically identical to a loop
1N/Athat executes once. Thus C<next> will exit such a block early.
1N/ASee also L</continue> for an illustration of how C<last>, C<next>, and
1N/A=item no Module VERSION LIST
1N/A=item no Module VERSION
1N/ASee the C<use> function, which C<no> is the opposite of.
1N/AInterprets EXPR as an octal string and returns the corresponding
1N/Avalue. (If EXPR happens to start off with C<0x>, interprets it as a
1N/Ahex string. If EXPR starts off with C<0b>, it is interpreted as a
1N/Abinary string. Leading whitespace is ignored in all three cases.)
1N/AThe following will handle decimal, binary, octal, and hex in the standard
1N/A $val = oct($val) if $val =~ /^0/;
1N/AIf EXPR is omitted, uses C<$_>. To go the other way (produce a number
1N/Ain octal), use sprintf() or printf():
1N/A $perms = (stat("filename"))[2] & 07777;
1N/A $oct_perms = sprintf "%lo", $perms;
1N/AThe oct() function is commonly used when a string such as C<644> needs
1N/Ato be converted into a file mode, for example. (Although perl will
1N/Aautomatically convert strings into numbers as needed, this automatic
1N/Aconversion assumes base 10.)
1N/A=item open FILEHANDLE,EXPR
1N/A=item open FILEHANDLE,MODE,EXPR
1N/A=item open FILEHANDLE,MODE,EXPR,LIST
1N/A=item open FILEHANDLE,MODE,REFERENCE
1N/A=item open FILEHANDLE
1N/AOpens the file whose filename is given by EXPR, and associates it with
1N/A(The following is a comprehensive reference to open(): for a gentler
1N/Aintroduction you may consider L<perlopentut>.)
1N/AIf FILEHANDLE is an undefined scalar variable (or array or hash element)
1N/Athe variable is assigned a reference to a new anonymous filehandle,
1N/Aotherwise if FILEHANDLE is an expression, its value is used as the name of
1N/Athe real filehandle wanted. (This is considered a symbolic reference, so
1N/AC<use strict 'refs'> should I<not> be in effect.)
1N/AIf EXPR is omitted, the scalar variable of the same name as the
1N/AFILEHANDLE contains the filename. (Note that lexical variables--those
1N/Adeclared with C<my>--will not work for this purpose; so if you're
1N/Ausing C<my>, specify EXPR in your call to open.)
1N/AIf three or more arguments are specified then the mode of opening and
1N/Athe file name are separate. If MODE is C<< '<' >> or nothing, the file
1N/Ais opened for input. If MODE is C<< '>' >>, the file is truncated and
1N/Aopened for output, being created if necessary. If MODE is C<<< '>>' >>>,
1N/Athe file is opened for appending, again being created if necessary.
1N/AYou can put a C<'+'> in front of the C<< '>' >> or C<< '<' >> to
1N/Aindicate that you want both read and write access to the file; thus
1N/AC<< '+<' >> is almost always preferred for
read/write updates--the C<<
1N/A'+>' >> mode would clobber the file first. You can't usually use
1N/Aeither read-write mode for updating textfiles, since they have
1N/Avariable length records. See the B<-i> switch in L<perlrun> for a
1N/Abetter approach. The file is created with permissions of C<0666>
1N/Amodified by the process' C<umask> value.
1N/AThese various prefixes correspond to the fopen(3) modes of C<'r'>,
1N/AC<'r+'>, C<'w'>, C<'w+'>, C<'a'>, and C<'a+'>.
1N/AIn the 2-arguments (and 1-argument) form of the call the mode and
1N/Afilename should be concatenated (in this order), possibly separated by
1N/Aspaces. It is possible to omit the mode in these forms if the mode is
1N/AIf the filename begins with C<'|'>, the filename is interpreted as a
1N/Acommand to which output is to be piped, and if the filename ends with a
1N/AC<'|'>, the filename is interpreted as a command which pipes output to
1N/Aus. See L<perlipc/"Using open() for IPC">
1N/Afor more examples of this. (You are not allowed to C<open> to a command
1N/Athat pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>,
1N/Aand L<perlipc/"Bidirectional Communication with Another Process">
1N/AFor three or more arguments if MODE is C<'|-'>, the filename is
1N/Ainterpreted as a command to which output is to be piped, and if MODE
1N/Ais C<'-|'>, the filename is interpreted as a command which pipes
1N/Aoutput to us. In the 2-arguments (and 1-argument) form one should
1N/Areplace dash (C<'-'>) with the command.
1N/ASee L<perlipc/"Using open() for IPC"> for more examples of this.
1N/A(You are not allowed to C<open> to a command that pipes both in I<and>
1N/Aout, but see L<IPC::Open2>, L<IPC::Open3>, and
1N/AL<perlipc/"Bidirectional Communication"> for alternatives.)
1N/AIn the three-or-more argument form of pipe opens, if LIST is specified
1N/A(extra arguments after the command name) then LIST becomes arguments
1N/Ato the command invoked if the platform supports it. The meaning of
1N/AC<open> with more than three arguments for non-pipe modes is not yet
1N/Aspecified. Experimental "layers" may give extra LIST arguments
1N/AIn the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN
1N/Aand opening C<< '>-' >> opens STDOUT.
1N/AYou may use the three-argument form of open to specify IO "layers"
1N/A(sometimes also referred to as "disciplines") to be applied to the handle
1N/Athat affect how the input and output are processed (see L<open> and
1N/AL<PerlIO> for more details). For example
1N/A open(FH, "<:utf8", "file")
1N/Awill open the UTF-8 encoded file containing Unicode characters,
1N/Asee L<perluniintro>. (Note that if layers are specified in the
1N/Athree-arg form then default layers set by the C<open> pragma are
1N/AOpen returns nonzero upon success, the undefined value otherwise. If
1N/Athe C<open> involved a pipe, the return value happens to be the pid of
1N/AIf you're running Perl on a system that distinguishes between text
1N/Afiles and binary files, then you should check out L</binmode> for tips
1N/Afor dealing with this. The key distinction between systems that need
1N/AC<binmode> and those that don't is their text file formats. Systems
1N/Alike Unix, Mac OS, and Plan 9, which delimit lines with a single
1N/Acharacter, and which encode that character in C as C<"\n">, do not
1N/Aneed C<binmode>. The rest need it.
1N/AWhen opening a file, it's usually a bad idea to continue normal execution
1N/Aif the request failed, so C<open> is frequently used in connection with
1N/AC<die>. Even if C<die> won't do what you want (say, in a CGI script,
1N/Awhere you want to make a nicely formatted error message (but there are
1N/Amodules that can help with that problem)) you should always check
1N/Athe return value from opening a file. The infrequent exception is when
1N/Aworking with an unopened filehandle is actually what you want to do.
1N/AAs a special case the 3 arg form with a
read/write mode and the third
1N/Aargument being C<undef>:
1N/A open(TMP, "+>", undef) or die ...
1N/Aopens a filehandle to an anonymous temporary file. Also using "+<"
1N/Aworks for symmetry, but you really should consider writing something
1N/Ato the temporary file first. You will need to seek() to do the
1N/AFile handles can be opened to "in memory" files held in Perl scalars via:
1N/A open($fh, '>', \$variable) || ..
1N/AThough if you try to re-open C<STDOUT> or C<STDERR> as an "in memory"
1N/Afile, you have to close it first:
1N/A open STDOUT, '>', \$variable or die "Can't open STDOUT: $!";
1N/A open ARTICLE or die "Can't find article $ARTICLE: $!\n";
1N/A while (<ARTICLE>) {...
1N/A # if the open fails, output is discarded
1N/A open(ARTICLE, '-|', "caesar <$article") # decrypt article
1N/A or die "Can't start caesar: $!";
1N/A open(ARTICLE, "caesar <$article |") # ditto
1N/A or die "Can't start caesar: $!";
1N/A open(EXTRACT, "|sort >Tmp$$") # $$ is our process id
1N/A or die "Can't start sort: $!";
1N/A open(MEMORY,'>', \$var)
1N/A or die "Can't open memory file: $!";
1N/A print MEMORY "foo!\n"; # output will end up in $var
1N/A # process argument list of files along with any includes
1N/A foreach $file (@ARGV) {
1N/A process($file, 'fh00');
1N/A my($filename, $input) = @_;
1N/A $input++; # this is a string increment
1N/A unless (open($input, $filename)) {
1N/A print STDERR "Can't open $filename: $!\n";
1N/A while (<$input>) { # note use of indirection
1N/A if (/^#include "(.*)"/) {
1N/A process($1, $input);
1N/AYou may also, in the Bourne shell tradition, specify an EXPR beginning
1N/Awith C<< '>&' >>, in which case the rest of the string is interpreted
1N/Aas the name of a filehandle (or file descriptor, if numeric) to be
1N/Aduped (as L<dup(2)>) and opened. You may use C<&> after C<< > >>,
1N/AC<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>.
1N/AThe mode you specify should match the mode of the original filehandle.
1N/A(Duping a filehandle does not take into account any existing contents
1N/Aof IO buffers.) If you use the 3 arg form then you can pass either a
1N/Anumber, the name of a filehandle or the normal "reference to a glob".
1N/AHere is a script that saves, redirects, and restores C<STDOUT> and
1N/AC<STDERR> using various methods:
1N/A open my $oldout, ">&STDOUT" or die "Can't dup STDOUT: $!";
1N/A open OLDERR, ">&", \*STDERR or die "Can't dup STDERR: $!";
1N/A open STDOUT, '>', "
foo.out" or die "Can't redirect STDOUT: $!";
1N/A open STDERR, ">&STDOUT" or die "Can't dup STDOUT: $!";
1N/A select STDERR; $| = 1; # make unbuffered
1N/A select STDOUT; $| = 1; # make unbuffered
1N/A print STDOUT "stdout 1\n"; # this works for
1N/A print STDERR "stderr 1\n"; # subprocesses too
1N/A open STDOUT, ">&", $oldout or die "Can't dup \$oldout: $!";
1N/A open STDERR, ">&OLDERR" or die "Can't dup OLDERR: $!";
1N/A print STDOUT "stdout 2\n";
1N/A print STDERR "stderr 2\n";
1N/AIf you specify C<< '<&=X' >>, where C<X> is a file descriptor number
1N/Aor a filehandle, then Perl will do an equivalent of C's C<fdopen> of
1N/Athat file descriptor (and not call L<dup(2)>); this is more
1N/Aparsimonious of file descriptors. For example:
1N/A # open for input, reusing the fileno of $fd
1N/A open(FILEHANDLE, "<&=$fd")
1N/A open(FILEHANDLE, "<&=", $fd)
1N/A # open for append, using the fileno of OLDFH
1N/A open(FH, ">>&=", OLDFH)
1N/A open(FH, ">>&=OLDFH")
1N/ABeing parsimonious on filehandles is also useful (besides being
1N/Aparsimonious) for example when something is dependent on file
1N/Adescriptors, like for example locking using flock(). If you do just
1N/AC<< open(A, '>>&B') >>, the filehandle A will not have the same file
1N/Adescriptor as B, and therefore flock(A) will not flock(B), and vice
1N/Aversa. But with C<< open(A, '>>&=B') >> the filehandles will share
1N/Athe same file descriptor.
1N/ANote that if you are using Perls older than 5.8.0, Perl will be using
1N/Athe standard C libraries' fdopen() to implement the "=" functionality.
1N/AOn many UNIX systems fdopen() fails when file descriptors exceed a
1N/Acertain value, typically 255. For Perls 5.8.0 and later, PerlIO is
1N/Amost often the default.
1N/AYou can see whether Perl has been compiled with PerlIO or not by
1N/Arunning C<perl -V> and looking for C<useperlio=> line. If C<useperlio>
1N/Ais C<define>, you have PerlIO, otherwise you don't.
1N/AIf you open a pipe on the command C<'-'>,
i.e., either C<'|-'> or C<'-|'>
1N/Awith 2-arguments (or 1-argument) form of open(), then
1N/Athere is an implicit fork done, and the return value of open is the pid
1N/Aof the child within the parent process, and C<0> within the child
1N/Aprocess. (Use C<defined($pid)> to determine whether the open was successful.)
1N/AThe filehandle behaves normally for the parent, but i/o to that
1N/AIn the child process the filehandle isn't opened--i/o happens
from/to 1N/Athe new STDOUT or STDIN. Typically this is used like the normal
1N/Apiped open when you want to exercise more control over just how the
1N/Apipe command gets executed, such as when you are running setuid, and
1N/Adon't want to have to scan shell commands for metacharacters.
1N/AThe following triples are more or less equivalent:
1N/A open(FOO, "|tr '[a-z]' '[A-Z]'");
1N/A open(FOO, '|-', "tr '[a-z]' '[A-Z]'");
1N/A open(FOO, '|-') || exec 'tr', '[a-z]', '[A-Z]';
1N/A open(FOO, '|-', "tr", '[a-z]', '[A-Z]');
1N/A open(FOO, "cat -n '$file'|");
1N/A open(FOO, '-|', "cat -n '$file'");
1N/A open(FOO, '-|') || exec 'cat', '-n', $file;
1N/A open(FOO, '-|', "cat", '-n', $file);
1N/AThe last example in each block shows the pipe as "list form", which is
1N/Anot yet supported on all platforms. A good rule of thumb is that if
1N/Ayour platform has true C<fork()> (in other words, if your platform is
1N/AUNIX) you can use the list form.
1N/ASee L<perlipc/"Safe Pipe Opens"> for more examples of this.
1N/ABeginning with v5.6.0, Perl will attempt to flush all files opened for
1N/Aoutput before any operation that may do a fork, but this may not be
1N/Asupported on some platforms (see L<perlport>). To be safe, you may need
1N/Ato set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
1N/Aof C<IO::Handle> on any open handles.
1N/AOn systems that support a close-on-exec flag on files, the flag will
1N/Abe set for the newly opened file descriptor as determined by the value
1N/Aof $^F. See L<perlvar/$^F>.
1N/AClosing any piped filehandle causes the parent process to wait for the
1N/Achild to finish, and returns the status value in C<$?>.
1N/AThe filename passed to 2-argument (or 1-argument) form of open() will
1N/Ahave leading and trailing whitespace deleted, and the normal
1N/Aredirection characters honored. This property, known as "magic open",
1N/Acan often be used to good effect. A user could specify a filename of
1N/AF<"rsh cat file |">, or you could change certain filenames as needed:
1N/A $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
1N/A open(FH, $filename) or die "Can't open $filename: $!";
1N/AUse 3-argument form to open a file with arbitrary weird characters in it,
1N/A open(FOO, '<', $file);
1N/Aotherwise it's necessary to protect any leading and trailing whitespace:
1N/A $file =~ s#^(\s)#./$1#;
1N/A open(FOO, "< $file\0");
1N/A(this may not work on some bizarre filesystems). One should
1N/Aconscientiously choose between the I<magic> and 3-arguments form
1N/Awill allow the user to specify an argument of the form C<"rsh cat file |">,
1N/Abut will not work on a filename which happens to have a trailing space, while
1N/A open IN, '<', $ARGV[0];
1N/Awill have exactly the opposite restrictions.
1N/AIf you want a "real" C C<open> (see L<open(2)> on your system), then you
1N/Ashould use the C<sysopen> function, which involves no such magic (but
1N/Amay use subtly different filemodes than Perl open(), which is mapped
1N/Ato C fopen()). This is
1N/Aanother way to protect your filenames from interpretation. For example:
1N/A sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL)
1N/A or die "sysopen $path: $!";
1N/A $oldfh = select(HANDLE); $| = 1; select($oldfh);
1N/A print HANDLE "stuff $$\n";
1N/A print "File contains: ", <HANDLE>;
1N/AUsing the constructor from the C<IO::Handle> package (or one of its
1N/Asubclasses, such as C<IO::File> or C<IO::Socket>), you can generate anonymous
1N/Afilehandles that have the scope of whatever variables hold references to
1N/Athem, and automatically close whenever and however you leave that scope:
1N/A sub read_myfile_munged {
1N/A my $handle = new IO::File;
1N/A open($handle, "myfile") or die "myfile: $!";
1N/A or return (); # Automatically closed here.
1N/A mung $first or die "mung failed"; # Or here.
1N/A return $first, <$handle> if $ALL; # Or here.
1N/ASee L</seek> for some details about mixing reading and writing.
1N/A=item opendir DIRHANDLE,EXPR
1N/AOpens a directory named EXPR for processing by C<readdir>, C<telldir>,
1N/AC<seekdir>, C<rewinddir>, and C<closedir>. Returns true if successful.
1N/ADIRHANDLE may be an expression whose value can be used as an indirect
1N/Adirhandle, usually the real dirhandle name. If DIRHANDLE is an undefined
1N/Ascalar variable (or array or hash element), the variable is assigned a
1N/Areference to a new anonymous dirhandle.
1N/ADIRHANDLEs have their own namespace separate from FILEHANDLEs.
1N/AReturns the numeric (the native 8-bit encoding, like ASCII or EBCDIC,
1N/Aor Unicode) value of the first character of EXPR. If EXPR is omitted,
1N/AFor the reverse, see L</chr>.
1N/ASee L<perlunicode> and L<encoding> for more about Unicode.
1N/A=item our EXPR : ATTRS
1N/A=item our TYPE EXPR : ATTRS
1N/AAn C<our> declares the listed variables to be valid globals within
1N/Athe enclosing block, file, or C<eval>. That is, it has the same
1N/Ascoping rules as a "my" declaration, but does not create a local
1N/Avariable. If more than one value is listed, the list must be placed
1N/Ain parentheses. The C<our> declaration has no semantic effect unless
1N/A"use strict vars" is in effect, in which case it lets you use the
1N/Adeclared global variable without qualifying it with a package name.
1N/A(But only within the lexical scope of the C<our> declaration. In this
1N/Ait differs from "use vars", which is package scoped.)
1N/AAn C<our> declaration declares a global variable that will be visible
1N/Aacross its entire lexical scope, even across package boundaries. The
1N/Apackage in which the variable is entered is determined at the point
1N/Aof the declaration, not at the point of use. This means the following
1N/A our $bar; # declares $Foo::bar for rest of lexical scope
1N/A print $bar; # prints 20
1N/AMultiple C<our> declarations in the same lexical scope are allowed
1N/Aif they are in different packages. If they happened to be in the same
1N/Apackage, Perl will emit warnings if you have asked for them.
1N/A our $bar; # declares $Foo::bar for rest of lexical scope
1N/A our $bar = 30; # declares $Bar::bar for rest of lexical scope
1N/A print $bar; # prints 30
1N/A our $bar; # emits warning
1N/AAn C<our> declaration may also have a list of attributes associated
1N/AThe exact semantics and interface of TYPE and ATTRS are still
1N/Aevolving. TYPE is currently bound to the use of C<fields> pragma,
1N/Aand attributes are handled using the C<attributes> pragma, or starting
1N/Afrom Perl 5.8.0 also via the C<Attribute::Handlers> module. See
1N/AL<perlsub/"Private Variables via my()"> for details, and L<fields>,
1N/AL<attributes>, and L<Attribute::Handlers>.
1N/AThe only currently recognized C<our()> attribute is C<unique> which
1N/Aindicates that a single copy of the global is to be used by all
1N/Ainterpreters should the program happen to be running in a
1N/Amulti-interpreter environment. (The default behaviour would be for
1N/Aeach interpreter to have its own copy of the global.) Examples:
1N/A our @EXPORT : unique = qw(foo);
1N/A our %EXPORT_TAGS : unique = (bar => [qw(aa bb cc)]);
1N/A our $VERSION : unique = "1.00";
1N/ANote that this attribute also has the effect of making the global
1N/Areadonly when the first new interpreter is cloned (for example,
1N/Awhen the first new thread is created).
1N/AMulti-interpreter environments can come to being either through the
1N/Afork() emulation on Windows platforms, or by embedding perl in a
1N/Amulti-threaded application. The C<unique> attribute does nothing in
1N/Aall other environments.
1N/AWarning: the current implementation of this attribute operates on the
1N/Atypeglob associated with the variable; this means that C<our $x : unique>
1N/Aalso has the effect of C<our @x : unique; our %x : unique>. This may be
1N/A=item pack TEMPLATE,LIST
1N/ATakes a LIST of values and converts it into a string using the rules
1N/Agiven by the TEMPLATE. The resulting string is the concatenation of
1N/Athe converted values. Typically, each converted value looks
1N/Alike its machine-level representation. For example, on 32-bit machines
1N/Aa converted integer may be represented by a sequence of 4 bytes.
1N/AThe TEMPLATE is a sequence of characters that give the order and type
1N/Aof values, as follows:
1N/A a A string with arbitrary binary data, will be null padded.
1N/A A A text (ASCII) string, will be space padded.
1N/A Z A null terminated (ASCIZ) string, will be null padded.
1N/A b A bit string (ascending bit order inside each byte, like vec()).
1N/A B A bit string (descending bit order inside each byte).
1N/A h A hex string (low nybble first).
1N/A H A hex string (high nybble first).
1N/A c A signed char value.
1N/A C An unsigned char value. Only does bytes. See U for Unicode.
1N/A s A signed short value.
1N/A S An unsigned short value.
1N/A (This 'short' is _exactly_ 16 bits, which may differ from
1N/A what a local C compiler calls 'short'. If you want
1N/A native-length shorts, use the '!' suffix.)
1N/A i A signed integer value.
1N/A I An unsigned integer value.
1N/A (This 'integer' is _at_least_ 32 bits wide. Its exact
1N/A size depends on what a local C compiler calls 'int',
1N/A and may even be larger than the 'long' described in
1N/A l A signed long value.
1N/A L An unsigned long value.
1N/A (This 'long' is _exactly_ 32 bits, which may differ from
1N/A what a local C compiler calls 'long'. If you want
1N/A native-length longs, use the '!' suffix.)
1N/A n An unsigned short in "network" (big-endian) order.
1N/A N An unsigned long in "network" (big-endian) order.
1N/A v An unsigned short in "VAX" (little-endian) order.
1N/A V An unsigned long in "VAX" (little-endian) order.
1N/A (These 'shorts' and 'longs' are _exactly_ 16 bits and
1N/A _exactly_ 32 bits, respectively.)
1N/A q A signed quad (64-bit) value.
1N/A Q An unsigned quad value.
1N/A (Quads are available only if your system supports 64-bit
1N/A integer values _and_ if Perl has been compiled to support those.
1N/A Causes a fatal error otherwise.)
1N/A j A signed integer value (a Perl internal integer, IV).
1N/A J An unsigned integer value (a Perl internal unsigned integer, UV).
1N/A f A single-precision float in the native format.
1N/A d A double-precision float in the native format.
1N/A F A floating point value in the native native format
1N/A (a Perl internal floating point value, NV).
1N/A D A long double-precision float in the native format.
1N/A (Long doubles are available only if your system supports long
1N/A double values _and_ if Perl has been compiled to support those.
1N/A Causes a fatal error otherwise.)
1N/A p A pointer to a null-terminated string.
1N/A P A pointer to a structure (fixed-length string).
1N/A u A uuencoded string.
1N/A U A Unicode character number. Encodes to UTF-8 internally
1N/A (or UTF-EBCDIC in EBCDIC platforms).
1N/A w A BER compressed integer. Its bytes represent an unsigned
1N/A integer in base 128, most significant digit first, with as
1N/A few digits as possible. Bit eight (the high bit) is set
1N/A on each byte except the last.
1N/A @ Null fill to absolute position, counted from the start of
1N/A the innermost ()-group.
1N/A ( Start of a ()-group.
1N/AThe following rules apply:
1N/AEach letter may optionally be followed by a number giving a repeat
1N/Acount. With all types except C<a>, C<A>, C<Z>, C<b>, C<B>, C<h>,
1N/AC<H>, C<@>, C<x>, C<X> and C<P> the pack function will gobble up that
1N/Amany values from the LIST. A C<*> for the repeat count means to use
1N/Ahowever many items are left, except for C<@>, C<x>, C<X>, where it is
1N/Aequivalent to C<0>, and C<u>, where it is equivalent to 1 (or 45, what
1N/Ais the same). A numeric repeat count may optionally be enclosed in
1N/Abrackets, as in C<pack 'C[80]', @arr>.
1N/AOne can replace the numeric repeat count by a template enclosed in brackets;
1N/Athen the packed length of this template in bytes is used as a count.
1N/AFor example, C<x[L]> skips a long (it skips the number of bytes in a long);
1N/Athe template C<$t X[$t] $t> unpack()s twice what $t unpacks.
1N/AIf the template in brackets contains alignment commands (such as C<x![d]>),
1N/Aits packed length is calculated as if the start of the template has the maximal
1N/AWhen used with C<Z>, C<*> results in the addition of a trailing null
1N/Abyte (so the packed result will be one longer than the byte C<length>
1N/AThe repeat count for C<u> is interpreted as the maximal number of bytes
1N/Ato encode per line of output, with 0 and 1 replaced by 45.
1N/AThe C<a>, C<A>, and C<Z> types gobble just one value, but pack it as a
1N/Astring of length count, padding with nulls or spaces as necessary. When
1N/Aunpacking, C<A> strips trailing spaces and nulls, C<Z> strips everything
1N/Aafter the first null, and C<a> returns data verbatim. When packing,
1N/AC<a>, and C<Z> are equivalent.
1N/AIf the value-to-pack is too long, it is truncated. If too long and an
1N/Aexplicit count is provided, C<Z> packs only C<$count-1> bytes, followed
1N/Aby a null byte. Thus C<Z> always packs a trailing null byte under
1N/ALikewise, the C<b> and C<B> fields pack a string that many bits long.
1N/AEach byte of the input field of pack() generates 1 bit of the result.
1N/AEach result bit is based on the least-significant bit of the corresponding
1N/Ainput byte,
i.e., on C<ord($byte)%2>. In particular, bytes C<"0"> and
1N/AC<"1"> generate bits 0 and 1, as do bytes C<"\0"> and C<"\1">.
1N/AStarting from the beginning of the input string of pack(), each 8-tuple
1N/Aof bytes is converted to 1 byte of output. With format C<b>
1N/Athe first byte of the 8-tuple determines the least-significant bit of a
1N/Abyte, and with format C<B> it determines the most-significant bit of
1N/AIf the length of the input string is not exactly divisible by 8, the
1N/Aremainder is packed as if the input string were padded by null bytes
1N/Aat the end. Similarly, during unpack()ing the "extra" bits are ignored.
1N/AIf the input string of pack() is longer than needed, extra bytes are ignored.
1N/AA C<*> for the repeat count of pack() means to use all the bytes of
1N/Athe input field. On unpack()ing the bits are converted to a string
1N/Aof C<"0">s and C<"1">s.
1N/AThe C<h> and C<H> fields pack a string that many nybbles (4-bit groups,
1N/Arepresentable as hexadecimal digits, 0-9a-f) long.
1N/AEach byte of the input field of pack() generates 4 bits of the result.
1N/AFor non-alphabetical bytes the result is based on the 4 least-significant
1N/Abits of the input byte,
i.e., on C<ord($byte)%16>. In particular,
1N/Abytes C<"0"> and C<"1"> generate nybbles 0 and 1, as do bytes
1N/AC<"\0"> and C<"\1">. For bytes C<"a".."f"> and C<"A".."F"> the result
1N/Ais compatible with the usual hexadecimal digits, so that C<"a"> and
1N/AC<"A"> both generate the nybble C<0xa==10>. The result for bytes
1N/AC<"g".."z"> and C<"G".."Z"> is not well-defined.
1N/AStarting from the beginning of the input string of pack(), each pair
1N/Aof bytes is converted to 1 byte of output. With format C<h> the
1N/Afirst byte of the pair determines the least-significant nybble of the
1N/Aoutput byte, and with format C<H> it determines the most-significant
1N/AIf the length of the input string is not even, it behaves as if padded
1N/Aby a null byte at the end. Similarly, during unpack()ing the "extra"
1N/AIf the input string of pack() is longer than needed, extra bytes are ignored.
1N/AA C<*> for the repeat count of pack() means to use all the bytes of
1N/Athe input field. On unpack()ing the bits are converted to a string
1N/Aof hexadecimal digits.
1N/AThe C<p> type packs a pointer to a null-terminated string. You are
1N/Aresponsible for ensuring the string is not a temporary value (which can
1N/Apotentially get deallocated before you get around to using the packed result).
1N/AThe C<P> type packs a pointer to a structure of the size indicated by the
1N/Alength. A NULL pointer is created if the corresponding value for C<p> or
1N/AC<P> is C<undef>, similarly for unpack().
1N/AThe C</> template character allows packing and unpacking of strings where
1N/Athe packed structure contains a byte count followed by the string itself.
1N/AYou write I<length-item>C</>I<string-item>.
1N/AThe I<length-item> can be any C<pack> template letter, and describes
1N/Ahow the length value is packed. The ones likely to be of most use are
1N/Ainteger-packing ones like C<n> (for Java strings), C<w> (for ASN.1 or
1N/ASNMP) and C<N> (for Sun XDR).
1N/AFor C<pack>, the I<string-item> must, at present, be C<"A*">, C<"a*"> or
1N/AC<"Z*">. For C<unpack> the length of the string is obtained from the
1N/AI<length-item>, but if you put in the '*' it will be ignored. For all other
1N/Acodes, C<unpack> applies the length value to the next item, which must not
1N/A unpack 'C/a', "\04Gurusamy"; gives 'Guru'
1N/A unpack 'a3/A* A*', '007 Bond J '; gives (' Bond','J')
1N/A pack 'n/a* w/a*','hello,','world'; gives "\000\006hello,\005world"
1N/AThe I<length-item> is not returned explicitly from C<unpack>.
1N/AAdding a count to the I<length-item> letter is unlikely to do anything
1N/Auseful, unless that letter is C<A>, C<a> or C<Z>. Packing with a
1N/AI<length-item> of C<a> or C<Z> may introduce C<"\000"> characters,
1N/Awhich Perl does not regard as legal in numeric strings.
1N/AThe integer types C<s>, C<S>, C<l>, and C<L> may be
1N/Aimmediately followed by a C<!> suffix to signify native shorts or
1N/Alongs--as you can see from above for example a bare C<l> does mean
1N/Aexactly 32 bits, the native C<long> (as seen by the local C compiler)
1N/Amay be larger. This is an issue mainly in 64-bit platforms. You can
1N/Asee whether using C<!> makes any difference by
1N/A print length(pack("s")), " ", length(pack("s!")), "\n";
1N/A print length(pack("l")), " ", length(pack("l!")), "\n";
1N/AC<i!> and C<I!> also work but only because of completeness;
1N/Athey are identical to C<i> and C<I>.
1N/AThe actual sizes (in bytes) of native shorts, ints, longs, and long
1N/Alongs on the platform where Perl was built are also available via
1N/A print $Config{shortsize}, "\n";
1N/A print $Config{intsize}, "\n";
1N/A print $Config{longsize}, "\n";
1N/A print $Config{longlongsize}, "\n";
1N/A(The C<$Config{longlongsize}> will be undefined if your system does
1N/Anot support long longs.)
1N/AThe integer formats C<s>, C<S>, C<i>, C<I>, C<l>, C<L>, C<j>, and C<J>
1N/Aare inherently non-portable between processors and operating systems
1N/Abecause they obey the native byteorder and endianness. For example a
1N/A4-byte integer 0x12345678 (305419896 decimal) would be ordered natively
1N/A(arranged in and handled by the CPU registers) into bytes as
1N/A 0x12 0x34 0x56 0x78 # big-endian
1N/A 0x78 0x56 0x34 0x12 # little-endian
1N/ABasically, the Intel and VAX CPUs are little-endian, while everybody
1N/Aelse, for example Motorola m68k/88k, PPC, Sparc, HP PA, Power, and
1N/AThe names `big-endian' and `little-endian' are comic references to
1N/Athe classic "Gulliver's Travels" (via the paper "On Holy Wars and a
1N/APlea for Peace" by Danny Cohen,
USC/ISI IEN 137, April 1, 1980) and
1N/Athe egg-eating habits of the Lilliputians.
1N/ASome systems may have even weirder byte orders such as
1N/AYou can see your system's preference with
1N/A print join(" ", map { sprintf "%#02x", $_ }
1N/A unpack("C*",pack("L",0x12345678))), "\n";
1N/AThe byteorder on the platform where Perl was built is also available
1N/A print $Config{byteorder}, "\n";
1N/AByteorders C<'1234'> and C<'12345678'> are little-endian, C<'4321'>
1N/Aand C<'87654321'> are big-endian.
1N/AIf you want portable packed integers use the formats C<n>, C<N>,
1N/AC<v>, and C<V>, their byte endianness and size are known.
1N/ASee also L<perlport>.
1N/AReal numbers (floats and doubles) are in the native machine format only;
1N/Adue to the multiplicity of floating formats around, and the lack of a
1N/Astandard "network" representation, no facility for interchange has been
1N/Amade. This means that packed floating point data written on one machine
1N/Amay not be readable on another - even if both use IEEE floating point
1N/Aarithmetic (as the endian-ness of the memory representation is not part
1N/Aof the IEEE spec). See also L<perlport>.
1N/ANote that Perl uses doubles internally for all numeric calculation, and
1N/Aconverting from double into float and thence back to double again will
1N/Alose precision (
i.e., C<unpack("f", pack("f", $foo)>) will not in general
1N/AIf the pattern begins with a C<U>, the resulting string will be
1N/Atreated as UTF-8-encoded Unicode. You can force UTF-8 encoding on in a
1N/Astring with an initial C<U0>, and the bytes that follow will be
1N/Ainterpreted as Unicode characters. If you don't want this to happen,
1N/Ayou can begin your pattern with C<C0> (or anything else) to force Perl
1N/Anot to UTF-8 encode your string, and then follow this with a C<U*>
1N/Asomewhere in your pattern.
1N/AYou must yourself do any alignment or padding by inserting for example
1N/Aenough C<'x'>es while packing. There is no way to pack() and unpack()
1N/Acould know where the bytes are going to or coming from. Therefore
1N/AC<pack> (and C<unpack>) handle their output and input as flat
1N/AA ()-group is a sub-TEMPLATE enclosed in parentheses. A group may
1N/Atake a repeat count, both as postfix, and for unpack() also via the C</>
1N/Atemplate character. Within each repetition of a group, positioning with
1N/AC<@> starts again at 0. Therefore, the result of
1N/A pack( '@1A((@2A)@3A)', 'a', 'b', 'c' )
1N/Ais the string "\0a\0\0bc".
1N/AC<x> and C<X> accept C<!> modifier. In this case they act as
1N/Aaligned at a multiple of C<count> bytes. For example, to pack() or
1N/Aunpack() C's C<struct {char c; double d; char cc[2]}> one may need to
1N/Ause the template C<C x![d] d C[2]>; this assumes that doubles must be
1N/Aaligned on the double's size.
1N/AFor alignment commands C<count> of 0 is equivalent to C<count> of 1;
1N/Aboth result in no-ops.
1N/AA comment in a TEMPLATE starts with C<#> and goes to the end of line.
1N/AWhite space may be used to separate pack codes from each other, but
1N/Aa C<!> modifier and a repeat count must follow immediately.
1N/AIf TEMPLATE requires more arguments to pack() than actually given, pack()
1N/Aassumes additional C<""> arguments. If TEMPLATE requires less arguments
1N/Ato pack() than actually given, extra arguments are ignored.
1N/A $foo = pack("CCCC",65,66,67,68);
1N/A $foo = pack("C4",65,66,67,68);
1N/A $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9);
1N/A # same thing with Unicode circled letters
1N/A $foo = pack("ccxxcc",65,66,67,68);
1N/A # note: the above examples featuring "C" and "c" are true
1N/A # only on ASCII and ASCII-derived systems such as ISO Latin 1
1N/A # and UTF-8. In EBCDIC the first example would be
1N/A # $foo = pack("CCCC",193,194,195,196);
1N/A $foo = pack("s2",1,2);
1N/A # "\1\0\2\0" on little-endian
1N/A # "\0\1\0\2" on big-endian
1N/A $foo = pack("a4","abcd","x","y","z");
1N/A $foo = pack("aaaa","abcd","x","y","z");
1N/A $foo = pack("a14","abcdefg");
1N/A # "abcdefg\0\0\0\0\0\0\0"
1N/A $foo = pack("i9pl", gmtime);
1N/A # a real struct tm (on my system anyway)
1N/A $utmp_template = "Z8 Z8 Z16 L";
1N/A $utmp = pack($utmp_template, @utmp1);
1N/A # a struct utmp (BSDish)
1N/A @utmp2 = unpack($utmp_template, $utmp);
1N/A # "@utmp1" eq "@utmp2"
1N/A unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
1N/A $foo = pack('sx2l', 12, 34);
1N/A # short 12, two zero bytes padding, long 34
1N/A $bar = pack('s@4l', 12, 34);
1N/A # short 12, zero fill to position 4, long 34
1N/AThe same template may generally also be used in unpack().
1N/A=item package NAMESPACE
1N/ADeclares the compilation unit as being in the given namespace. The scope
1N/Aof the package declaration is from the declaration itself through the end
1N/Aof the enclosing block, file, or eval (the same as the C<my> operator).
1N/AAll further unqualified dynamic identifiers will be in this namespace.
1N/AA package statement affects only dynamic variables--including those
1N/Ayou've used C<local> on--but I<not> lexical variables, which are created
1N/Awith C<my>. Typically it would be the first declaration in a file to
1N/Abe included by the C<require> or C<use> operator. You can switch into a
1N/Apackage in more than one place; it merely influences which symbol table
1N/Ais used by the compiler for the rest of that block. You can refer to
1N/Avariables and filehandles in other packages by prefixing the identifier
1N/Awith the package name and a double colon: C<$Package::Variable>.
1N/AIf the package name is null, the C<main> package as assumed. That is,
1N/AC<$::sail> is equivalent to C<$main::sail> (as well as to C<$main'sail>,
1N/Astill seen in older code).
1N/AIf NAMESPACE is omitted, then there is no current package, and all
1N/Aidentifiers must be fully qualified or lexicals. However, you are
1N/Astrongly advised not to make use of this feature. Its use can cause
1N/Aunexpected behaviour, even crashing some versions of Perl. It is
1N/Adeprecated, and will be removed from a future release.
1N/ASee L<perlmod/"Packages"> for more information about packages, modules,
1N/Aand classes. See L<perlsub> for other scoping issues.
1N/A=item pipe READHANDLE,WRITEHANDLE
1N/AOpens a pair of connected pipes like the corresponding system call.
1N/ANote that if you set up a loop of piped processes, deadlock can occur
1N/Aunless you are very careful. In addition, note that Perl's pipes use
1N/AIO buffering, so you may need to set C<$|> to flush your WRITEHANDLE
1N/Aafter each command, depending on the application.
1N/ASee L<IPC::Open2>, L<IPC::Open3>, and L<perlipc/"Bidirectional Communication">
1N/Afor examples of such things.
1N/AOn systems that support a close-on-exec flag on files, the flag will be set
1N/Afor the newly opened file descriptors as determined by the value of $^F.
1N/APops and returns the last value of the array, shortening the array by
1N/Aone element. Has an effect similar to
1N/AIf there are no elements in the array, returns the undefined value
1N/A(although this may happen at other times as well). If ARRAY is
1N/Aomitted, pops the C<@ARGV> array in the main program, and the C<@_>
1N/Aarray in subroutines, just like C<shift>.
1N/AReturns the offset of where the last C<m//g> search left off for the variable
1N/Ain question (C<$_> is used when the variable is not specified). May be
1N/Amodified to change that offset. Such modification will also influence
1N/Athe C<\G> zero-width assertion in regular expressions. See L<perlre> and
1N/A=item print FILEHANDLE LIST
1N/APrints a string or a list of strings. Returns true if successful.
1N/AFILEHANDLE may be a scalar variable name, in which case the variable
1N/Acontains the name of or a reference to the filehandle, thus introducing
1N/Aone level of indirection. (NOTE: If FILEHANDLE is a variable and
1N/Athe next token is a term, it may be misinterpreted as an operator
1N/Aunless you interpose a C<+> or put parentheses around the arguments.)
1N/AIf FILEHANDLE is omitted, prints by default to standard output (or
1N/Ato the last selected output channel--see L</select>). If LIST is
1N/Aalso omitted, prints C<$_> to the currently selected output channel.
1N/ATo set the default output channel to something other than STDOUT
1N/Ause the select operation. The current value of C<$,> (if any) is
1N/Aprinted between each LIST item. The current value of C<$\> (if
1N/Aany) is printed after the entire LIST has been printed. Because
1N/Aprint takes a LIST, anything in the LIST is evaluated in list
1N/Acontext, and any subroutine that you call will have one or more of
1N/Aits expressions evaluated in list context. Also be careful not to
1N/Afollow the print keyword with a left parenthesis unless you want
1N/Athe corresponding right parenthesis to terminate the arguments to
1N/Athe print--interpose a C<+> or put parentheses around all the
1N/ANote that if you're storing FILEHANDLES in an array or other expression,
1N/Ayou will have to use a block returning its value instead:
1N/A print { $files[$i] } "stuff\n";
1N/A print { $OK ? STDOUT : STDERR } "stuff\n";
1N/A=item printf FILEHANDLE FORMAT, LIST
1N/A=item printf FORMAT, LIST
1N/AEquivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that C<$\>
1N/A(the output record separator) is not appended. The first argument
1N/Aof the list will be interpreted as the C<printf> format. See C<sprintf>
1N/Afor an explanation of the format argument. If C<use locale> is in effect,
1N/Athe character used for the decimal point in formatted real numbers is
1N/Aaffected by the LC_NUMERIC locale. See L<perllocale>.
1N/ADon't fall into the trap of using a C<printf> when a simple
1N/AC<print> would do. The C<print> is more efficient and less
1N/A=item prototype FUNCTION
1N/AReturns the prototype of a function as a string (or C<undef> if the
1N/Afunction has no prototype). FUNCTION is a reference to, or the name of,
1N/Athe function whose prototype you want to retrieve.
1N/AIf FUNCTION is a string starting with C<CORE::>, the rest is taken as a
1N/Aname for Perl builtin. If the builtin is not I<overridable> (such as
1N/AC<qw//>) or its arguments cannot be expressed by a prototype (such as
1N/AC<system>) returns C<undef> because the builtin does not really behave
1N/Alike a Perl function. Otherwise, the string describing the equivalent
1N/Aprototype is returned.
1N/A=item push ARRAY,LIST
1N/ATreats ARRAY as a stack, and pushes the values of LIST
1N/Aonto the end of ARRAY. The length of ARRAY increases by the length of
1N/ALIST. Has the same effect as
1N/A $ARRAY[++$#ARRAY] = $value;
1N/Abut is more efficient. Returns the new number of elements in the array.
1N/AGeneralized quotes. See L<perlop/"Regexp Quote-Like Operators">.
1N/AReturns the value of EXPR with all non-"word"
1N/Acharacters backslashed. (That is, all characters not matching
1N/AC</[A-Za-z_0-9]/> will be preceded by a backslash in the
1N/Areturned string, regardless of any locale settings.)
1N/AThis is the internal function implementing
1N/Athe C<\Q> escape in double-quoted strings.
1N/AIf EXPR is omitted, uses C<$_>.
1N/AReturns a random fractional number greater than or equal to C<0> and less
1N/Athan the value of EXPR. (EXPR should be positive.) If EXPR is
1N/Aomitted, the value C<1> is used. Currently EXPR with the value C<0> is
1N/Aalso special-cased as C<1> - this has not been documented before perl 5.8.0
1N/Aand is subject to change in future versions of perl. Automatically calls
1N/AC<srand> unless C<srand> has already been called. See also C<srand>.
1N/AApply C<int()> to the value returned by C<rand()> if you want random
1N/Aintegers instead of random fractional numbers. For example,
1N/Areturns a random integer between C<0> and C<9>, inclusive.
1N/A(Note: If your rand function consistently returns numbers that are too
1N/Alarge or too small, then your version of Perl was probably compiled
1N/Awith the wrong number of RANDBITS.)
1N/A=item read FILEHANDLE,SCALAR,LENGTH,OFFSET
1N/A=item read FILEHANDLE,SCALAR,LENGTH
1N/AAttempts to read LENGTH I<characters> of data into variable SCALAR
1N/Afrom the specified FILEHANDLE. Returns the number of characters
1N/Aactually read, C<0> at end of file, or undef if there was an error (in
1N/Athe latter case C<$!> is also set). SCALAR will be grown or shrunk
1N/Aso that the last character actually read is the last character of the
1N/Ascalar after the read.
1N/AAn OFFSET may be specified to place the read data at some place in the
1N/Astring other than the beginning. A negative OFFSET specifies
1N/Aplacement at that many characters counting backwards from the end of
1N/Athe string. A positive OFFSET greater than the length of SCALAR
1N/Aresults in the string being padded to the required size with C<"\0">
1N/Abytes before the result of the read is appended.
1N/AThe call is actually implemented in terms of either Perl's or system's
1N/Afread() call. To get a true read(2) system call, see C<sysread>.
1N/ANote the I<characters>: depending on the status of the filehandle,
1N/Aeither (8-bit) bytes or characters are read. By default all
1N/Afilehandles operate on bytes, but for example if the filehandle has
1N/Abeen opened with the C<:utf8> I/O layer (see L</open>, and the C<open>
1N/Apragma, L<open>), the I/O will operate on UTF-8 encoded Unicode
1N/Acharacters, not bytes. Similarly for the C<:encoding> pragma:
1N/Ain that case pretty much any characters can be read.
1N/A=item readdir DIRHANDLE
1N/AReturns the next directory entry for a directory opened by C<opendir>.
1N/AIf used in list context, returns all the rest of the entries in the
1N/Adirectory. If there are no more entries, returns an undefined value in
1N/Ascalar context or a null list in list context.
1N/AIf you're planning to filetest the return values out of a C<readdir>, you'd
1N/Abetter prepend the directory in question. Otherwise, because we didn't
1N/AC<chdir> there, it would have been testing the wrong file.
1N/A opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!";
1N/A @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
1N/AReads from the filehandle whose typeglob is contained in EXPR. In scalar
1N/Acontext, each call reads and returns the next line, until end-of-file is
1N/Areached, whereupon the subsequent call returns undef. In list context,
1N/Areads until end-of-file is reached and returns a list of lines. Note that
1N/Athe notion of "line" used here is however you may have defined it
1N/Awith C<$/> or C<$INPUT_RECORD_SEPARATOR>). See L<perlvar/"$/">.
1N/AWhen C<$/> is set to C<undef>, when readline() is in scalar
1N/Acontext (
i.e. file slurp mode), and when an empty file is read, it
1N/Areturns C<''> the first time, followed by C<undef> subsequently.
1N/AThis is the internal function implementing the C<< <EXPR> >>
1N/Aoperator, but you can use it directly. The C<< <EXPR> >>
1N/Aoperator is discussed in more detail in L<perlop/"I/O Operators">.
1N/A $line = readline(*STDIN); # same thing
1N/AIf readline encounters an operating system error, C<$!> will be set with the
1N/Acorresponding error message. It can be helpful to check C<$!> when you are
1N/Areading from filehandles you don't trust, such as a tty or a socket. The
1N/Afollowing example uses the operator form of C<readline>, and takes the necessary
1N/Asteps to ensure that C<readline> was successful.
1N/A unless (defined( $line = <> )) {
1N/AReturns the value of a symbolic link, if symbolic links are
1N/Aimplemented. If not, gives a fatal error. If there is some system
1N/Aerror, returns the undefined value and sets C<$!> (errno). If EXPR is
1N/AEXPR is executed as a system command.
1N/AThe collected standard output of the command is returned.
1N/AIn scalar context, it comes back as a single (potentially
1N/Amulti-line) string. In list context, returns a list of lines
1N/A(however you've defined lines with C<$/> or C<$INPUT_RECORD_SEPARATOR>).
1N/AThis is the internal function implementing the C<
qx/EXPR/>
1N/Aoperator, but you can use it directly. The C<
qx/EXPR/>
1N/Aoperator is discussed in more detail in L<perlop/"I/O Operators">.
1N/A=item recv SOCKET,SCALAR,LENGTH,FLAGS
1N/AReceives a message on a socket. Attempts to receive LENGTH characters
1N/Aof data into variable SCALAR from the specified SOCKET filehandle.
1N/ASCALAR will be grown or shrunk to the length actually read. Takes the
1N/Asame flags as the system call of the same name. Returns the address
1N/Aof the sender if SOCKET's protocol supports this; returns an empty
1N/Astring otherwise. If there's an error, returns the undefined value.
1N/AThis call is actually implemented in terms of recvfrom(2) system call.
1N/ASee L<perlipc/"UDP: Message Passing"> for examples.
1N/ANote the I<characters>: depending on the status of the socket, either
1N/A(8-bit) bytes or characters are received. By default all sockets
1N/Aoperate on bytes, but for example if the socket has been changed using
1N/Abinmode() to operate with the C<:utf8> I/O layer (see the C<open>
1N/Apragma, L<open>), the I/O will operate on UTF-8 encoded Unicode
1N/Acharacters, not bytes. Similarly for the C<:encoding> pragma:
1N/Ain that case pretty much any characters can be read.
1N/AThe C<redo> command restarts the loop block without evaluating the
1N/Aconditional again. The C<continue> block, if any, is not executed. If
1N/Athe LABEL is omitted, the command refers to the innermost enclosing
1N/Aloop. This command is normally used by programs that want to lie to
1N/Athemselves about what was just input:
1N/A # a simpleminded Pascal comment stripper
1N/A # (warning: assumes no { or } in strings)
1N/A LINE: while (<STDIN>) {
1N/A while (s|({.*}.*){.*}|$1 |) {}
1N/A if (/}/) { # end of comment?
1N/AC<redo> cannot be used to retry a block which returns a value such as
1N/AC<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit
1N/Aa grep() or map() operation.
1N/ANote that a block by itself is semantically identical to a loop
1N/Athat executes once. Thus C<redo> inside such a block will effectively
1N/Aturn it into a looping construct.
1N/ASee also L</continue> for an illustration of how C<last>, C<next>, and
1N/AReturns a non-empty string if EXPR is a reference, the empty
1N/Astring otherwise. If EXPR
1N/Ais not specified, C<$_> will be used. The value returned depends on the
1N/Atype of thing the reference is a reference to.
1N/ABuiltin types include:
1N/AIf the referenced object has been blessed into a package, then that package
1N/Aname is returned instead. You can think of C<ref> as a C<typeof> operator.
1N/A if (ref($r) eq "HASH") {
1N/A print "r is a reference to a hash.\n";
1N/A print "r is not a reference at all.\n";
1N/A if (UNIVERSAL::isa($r, "HASH")) { # for subclassing
1N/A print "r is a reference to something that isa hash.\n";
1N/A=item rename OLDNAME,NEWNAME
1N/AChanges the name of a file; an existing file NEWNAME will be
1N/Aclobbered. Returns true for success, false otherwise.
1N/ABehavior of this function varies wildly depending on your system
1N/Aimplementation. For example, it will usually not work across file system
1N/Aboundaries, even though the system I<mv> command sometimes compensates
1N/Afor this. Other restrictions include whether it works on directories,
1N/Aopen files, or pre-existing files. Check L<perlport> and either the
1N/Arename(2) manpage or equivalent system documentation for details.
1N/A=item require VERSION
1N/ADemands a version of Perl specified by VERSION, or demands some semantics
1N/Aspecified by EXPR or by C<$_> if EXPR is not supplied.
1N/AVERSION may be either a numeric argument such as 5.006, which will be
1N/Acompared to C<$]>, or a literal of the form v5.6.1, which will be compared
1N/Ato C<$^V> (aka $PERL_VERSION). A fatal error is produced at run time if
1N/AVERSION is greater than the version of the current Perl interpreter.
1N/ACompare with L</use>, which can do a similar check at compile time.
1N/ASpecifying VERSION as a literal of the form v5.6.1 should generally be
1N/Aavoided, because it leads to misleading error messages under earlier
1N/Aversions of Perl which do not support this syntax. The equivalent numeric
1N/Aversion should be used instead.
1N/A require v5.6.1; # run time version check
1N/A require 5.6.1; # ditto
1N/A require 5.006_001; # ditto; preferred for backwards compatibility
1N/AOtherwise, demands that a library file be included if it hasn't already
1N/Abeen included. The file is included via the do-FILE mechanism, which is
1N/Aessentially just a variety of C<eval>. Has semantics similar to the
1N/Afollowing subroutine:
1N/A my ($filename) = @_;
1N/A if (exists $INC{$filename}) {
1N/A return 1 if $INC{$filename};
1N/A die "Compilation failed in require";
1N/A my ($realfilename,$result);
1N/A foreach $prefix (@INC) {
1N/A $realfilename = "$prefix/$filename";
1N/A if (-f $realfilename) {
1N/A $INC{$filename} = $realfilename;
1N/A $result = do $realfilename;
1N/A die "Can't find $filename in \@INC";
1N/A $INC{$filename} = undef;
1N/A } elsif (!$result) {
1N/A delete $INC{$filename};
1N/A die "$filename did not return true value";
1N/ANote that the file will not be included twice under the same specified
1N/AThe file must return true as the last statement to indicate
1N/Asuccessful execution of any initialization code, so it's customary to
1N/Aend such a file with C<1;> unless you're sure it'll return true
1N/Aotherwise. But it's better just to put the C<1;>, in case you add more
1N/AIf EXPR is a bareword, the require assumes a "F<.pm>" extension and
1N/Areplaces "F<::>" with "F</>" in the filename for you,
1N/Ato make it easy to load standard modules. This form of loading of
1N/Amodules does not risk altering your namespace.
1N/AIn other words, if you try this:
1N/A require Foo::Bar; # a splendid bareword
1N/AThe require function will actually look for the "F<
Foo/Bar.pm>" file in the
1N/Adirectories specified in the C<@INC> array.
1N/A $class = 'Foo::Bar';
1N/A require $class; # $class is not a bareword
1N/A require "Foo::Bar"; # not a bareword because of the ""
1N/AThe require function will look for the "F<Foo::Bar>" file in the @INC array and
1N/Awill complain about not finding "F<Foo::Bar>" there. In this case you can do:
1N/A eval "require $class";
1N/ANow that you understand how C<require> looks for files in the case of
1N/Aa bareword argument, there is a little extra functionality going on
1N/Abehind the scenes. Before C<require> looks for a "F<.pm>" extension,
1N/Ait will first look for a filename with a "F<.pmc>" extension. A file
1N/Awith this extension is assumed to be Perl bytecode generated by
1N/AL<B::Bytecode|B::Bytecode>. If this file is found, and it's modification
1N/Atime is newer than a coinciding "F<.pm>" non-compiled file, it will be
1N/Aloaded in place of that non-compiled file ending in a "F<.pm>" extension.
1N/AYou can also insert hooks into the import facility, by putting directly
1N/APerl code into the @INC array. There are three forms of hooks: subroutine
1N/Areferences, array references and blessed objects.
1N/ASubroutine references are the simplest case. When the inclusion system
1N/Awalks through @INC and encounters a subroutine, this subroutine gets
1N/Acalled with two parameters, the first being a reference to itself, and the
1N/Asubroutine should return C<undef> or a filehandle, from which the file to
1N/Ainclude will be read. If C<undef> is returned, C<require> will look at
1N/Athe remaining elements of @INC.
1N/AIf the hook is an array reference, its first element must be a subroutine
1N/Areference. This subroutine is called as above, but the first parameter is
1N/Athe array reference. This enables to pass indirectly some arguments to
1N/AIn other words, you can write:
1N/A push @INC, \&my_sub;
1N/A my ($coderef, $filename) = @_; # $coderef is \&my_sub
1N/A push @INC, [ \&my_sub, $x, $y, ... ];
1N/A my ($arrayref, $filename) = @_;
1N/A # Retrieve $x, $y, ...
1N/A my @parameters = @$arrayref[1..$#$arrayref];
1N/AIf the hook is an object, it must provide an INC method, that will be
1N/Acalled as above, the first parameter being the object itself. (Note that
1N/Ayou must fully qualify the sub's name, as it is always forced into package
1N/AC<main>.) Here is a typical code layout:
1N/A my ($self, $filename) = @_;
1N/A # In the main program
1N/A push @INC, new Foo(...);
1N/ANote that these hooks are also permitted to set the %INC entry
1N/Acorresponding to the files they have loaded. See L<perlvar/%INC>.
1N/AFor a yet-more-powerful import facility, see L</use> and L<perlmod>.
1N/AGenerally used in a C<continue> block at the end of a loop to clear
1N/Avariables and reset C<??> searches so that they work again. The
1N/Aexpression is interpreted as a list of single characters (hyphens
1N/Aallowed for ranges). All variables and arrays beginning with one of
1N/Athose letters are reset to their pristine state. If the expression is
1N/Aomitted, one-match searches (C<?pattern?>) are reset to match again. Resets
1N/Aonly variables or searches in the current package. Always returns
1N/A reset 'X'; # reset all X variables
1N/A reset 'a-z'; # reset lower case variables
1N/A reset; # just reset ?one-time? searches
1N/AResetting C<"A-Z"> is not recommended because you'll wipe out your
1N/AC<@ARGV> and C<@INC> arrays and your C<%ENV> hash. Resets only package
1N/Avariables--lexical variables are unaffected, but they clean themselves
1N/Aup on scope exit anyway, so you'll probably want to use them instead.
1N/AReturns from a subroutine, C<eval>, or C<do FILE> with the value
1N/Agiven in EXPR. Evaluation of EXPR may be in list, scalar, or void
1N/Acontext, depending on how the return value will be used, and the context
1N/Amay vary from one execution to the next (see C<wantarray>). If no EXPR
1N/Ais given, returns an empty list in list context, the undefined value in
1N/Ascalar context, and (of course) nothing at all in a void context.
1N/A(Note that in the absence of an explicit C<return>, a subroutine, eval,
1N/Aor do FILE will automatically return the value of the last expression
1N/AIn list context, returns a list value consisting of the elements
1N/Aof LIST in the opposite order. In scalar context, concatenates the
1N/Aelements of LIST and returns a string value with all characters
1N/Ain the opposite order.
1N/A print reverse <>; # line tac, last line first
1N/A undef $/; # for efficiency of <>
1N/A print scalar reverse <>; # character tac, last line tsrif
1N/AUsed without arguments in scalar context, reverse() reverses C<$_>.
1N/AThis operator is also handy for inverting a hash, although there are some
1N/Acaveats. If a value is duplicated in the original hash, only one of those
1N/Acan be represented as a key in the inverted hash. Also, this has to
1N/Aunwind one hash and build a whole new one, which may take some time
1N/Aon a large hash, such as from a DBM file.
1N/A %by_name = reverse %by_address; # Invert the hash
1N/A=item rewinddir DIRHANDLE
1N/ASets the current position to the beginning of the directory for the
1N/AC<readdir> routine on DIRHANDLE.
1N/A=item rindex STR,SUBSTR,POSITION
1N/A=item rindex STR,SUBSTR
1N/AWorks just like index() except that it returns the position of the LAST
1N/Aoccurrence of SUBSTR in STR. If POSITION is specified, returns the
1N/Alast occurrence at or before that position.
1N/ADeletes the directory specified by FILENAME if that directory is
1N/Aempty. If it succeeds it returns true, otherwise it returns false and
1N/Asets C<$!> (errno). If FILENAME is omitted, uses C<$_>.
1N/AThe substitution operator. See L<perlop>.
1N/AForces EXPR to be interpreted in scalar context and returns the value
1N/A @counts = ( scalar @a, scalar @b, scalar @c );
1N/AThere is no equivalent operator to force an expression to
1N/Abe interpolated in list context because in practice, this is never
1N/Aneeded. If you really wanted to do so, however, you could use
1N/Athe construction C<@{[ (some expression) ]}>, but usually a simple
1N/AC<(some expression)> suffices.
1N/ABecause C<scalar> is unary operator, if you accidentally use for EXPR a
1N/Aparenthesized list, this behaves as a scalar comma expression, evaluating
1N/Aall but the last element in void context and returning the final element
1N/Aevaluated in scalar context. This is seldom what you want.
1N/AThe following single statement:
1N/A print uc(scalar(&foo,$bar)),$baz;
1N/Ais the moral equivalent of these two:
1N/A print(uc($bar),$baz);
1N/ASee L<perlop> for more details on unary operators and the comma operator.
1N/A=item seek FILEHANDLE,POSITION,WHENCE
1N/ASets FILEHANDLE's position, just like the C<fseek> call of C<stdio>.
1N/AFILEHANDLE may be an expression whose value gives the name of the
1N/Afilehandle. The values for WHENCE are C<0> to set the new position
1N/AI<in bytes> to POSITION, C<1> to set it to the current position plus
1N/APOSITION, and C<2> to set it to EOF plus POSITION (typically
1N/Anegative). For WHENCE you may use the constants C<SEEK_SET>,
1N/AC<SEEK_CUR>, and C<SEEK_END> (start of the file, current position, end
1N/Aof the file) from the Fcntl module. Returns C<1> upon success, C<0>
1N/ANote the I<in bytes>: even if the filehandle has been set to
1N/Aoperate on characters (for example by using the C<:utf8> open
1N/Alayer), tell() will return byte offsets, not character offsets
1N/A(because implementing that would render seek() and tell() rather slow).
1N/AIf you want to position file for C<sysread> or C<syswrite>, don't use
1N/AC<seek>--buffering makes its effect on the file's system position
1N/Aunpredictable and non-portable. Use C<sysseek> instead.
1N/ADue to the rules and rigors of ANSI C, on some systems you have to do a
1N/Aseek whenever you switch between reading and writing. Amongst other
1N/Athings, this may have the effect of calling stdio's clearerr(3).
1N/AA WHENCE of C<1> (C<SEEK_CUR>) is useful for not moving the file position:
1N/AThis is also useful for applications emulating C<tail -f>. Once you hit
1N/AEOF on your read, and then sleep for a while, you might have to stick in a
1N/Aseek() to reset things. The C<seek> doesn't change the current position,
1N/Abut it I<does> clear the end-of-file condition on the handle, so that the
1N/Anext C<< <FILE> >> makes Perl try again to read something. We hope.
1N/AIf that doesn't work (some IO implementations are particularly
1N/Acantankerous), then you may need something more like this:
1N/A for ($curpos = tell(FILE); $_ = <FILE>;
1N/A $curpos = tell(FILE)) {
1N/A # search for some stuff and put it into files
1N/A sleep($for_a_while);
1N/A seek(FILE, $curpos, 0);
1N/A=item seekdir DIRHANDLE,POS
1N/ASets the current position for the C<readdir> routine on DIRHANDLE. POS
1N/Amust be a value returned by C<telldir>. Has the same caveats about
1N/Apossible directory compaction as the corresponding system library
1N/A=item select FILEHANDLE
1N/AReturns the currently selected filehandle. Sets the current default
1N/Afilehandle for output, if FILEHANDLE is supplied. This has two
1N/Aeffects: first, a C<write> or a C<print> without a filehandle will
1N/Adefault to this FILEHANDLE. Second, references to variables related to
1N/Aoutput will refer to this output channel. For example, if you have to
1N/Aset the top of form format for more than one output channel, you might
1N/AFILEHANDLE may be an expression whose value gives the name of the
1N/Aactual filehandle. Thus:
1N/A $oldfh = select(STDERR); $| = 1; select($oldfh);
1N/ASome programmers may prefer to think of filehandles as objects with
1N/Amethods, preferring to write the last example as:
1N/A STDERR->autoflush(1);
1N/A=item select RBITS,WBITS,EBITS,TIMEOUT
1N/AThis calls the select(2) system call with the bit masks specified, which
1N/Acan be constructed using C<fileno> and C<vec>, along these lines:
1N/A $rin = $win = $ein = '';
1N/A vec($rin,fileno(STDIN),1) = 1;
1N/A vec($win,fileno(STDOUT),1) = 1;
1N/AIf you want to select on many filehandles you might wish to write a
1N/A my(@fhlist) = split(' ',$_[0]);
1N/A vec($bits,fileno($_),1) = 1;
1N/A $rin = fhbits('STDIN TTY SOCK');
1N/A ($nfound,$timeleft) =
1N/A select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
1N/Aor to block until something becomes ready just do this
1N/A $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
1N/AMost systems do not bother to return anything useful in $timeleft, so
1N/Acalling select() in scalar context just returns $nfound.
1N/AAny of the bit masks can also be undef. The timeout, if specified, is
1N/Ain seconds, which may be fractional. Note: not all implementations are
1N/Acapable of returning the $timeleft. If not, they always return
1N/A$timeleft equal to the supplied $timeout.
1N/AYou can effect a sleep of 250 milliseconds this way:
1N/A select(undef, undef, undef, 0.25);
1N/ANote that whether C<select> gets restarted after signals (say, SIGALRM)
1N/Ais implementation-dependent.
1N/AB<WARNING>: One should not attempt to mix buffered I/O (like C<read>
1N/Aor <FH>) with C<select>, except as permitted by POSIX, and even
1N/Athen only on POSIX systems. You have to use C<sysread> instead.
1N/A=item semctl ID,SEMNUM,CMD,ARG
1N/ACalls the System V IPC function C<semctl>. You'll probably have to say
1N/Afirst to get the correct constant definitions. If CMD is IPC_STAT or
1N/AGETALL, then ARG must be a variable which will hold the returned
1N/Asemid_ds structure or semaphore value array. Returns like C<ioctl>:
1N/Athe undefined value for error, "C<0 but true>" for zero, or the actual
1N/Areturn value otherwise. The ARG must consist of a vector of native
1N/Ashort integers, which may be created with C<pack("s!",(0)x$nsem)>.
1N/ASee also L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::Semaphore>
1N/A=item semget KEY,NSEMS,FLAGS
1N/ACalls the System V IPC function semget. Returns the semaphore id, or
1N/Athe undefined value if there is an error. See also
1N/AL<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::SysV::Semaphore>
1N/A=item semop KEY,OPSTRING
1N/ACalls the System V IPC function semop to perform semaphore operations
1N/Asuch as signalling and waiting. OPSTRING must be a packed array of
1N/Asemop structures. Each semop structure can be generated with
1N/AC<pack("s!3", $semnum, $semop, $semflag)>. The number of semaphore
1N/Aoperations is implied by the length of OPSTRING. Returns true if
1N/Asuccessful, or false if there is an error. As an example, the
1N/Afollowing code waits on semaphore $semnum of semaphore id $semid:
1N/A $semop = pack("s!3", $semnum, -1, 0);
1N/A die "Semaphore trouble: $!\n" unless semop($semid, $semop);
1N/ATo signal the semaphore, replace C<-1> with C<1>. See also
1N/AL<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::SysV::Semaphore>
1N/A=item send SOCKET,MSG,FLAGS,TO
1N/A=item send SOCKET,MSG,FLAGS
1N/ASends a message on a socket. Attempts to send the scalar MSG to the
1N/ASOCKET filehandle. Takes the same flags as the system call of the
1N/Asame name. On unconnected sockets you must specify a destination to
1N/Asend TO, in which case it does a C C<sendto>. Returns the number of
1N/Acharacters sent, or the undefined value if there is an error. The C
1N/Asystem call sendmsg(2) is currently unimplemented. See
1N/AL<perlipc/"UDP: Message Passing"> for examples.
1N/ANote the I<characters>: depending on the status of the socket, either
1N/A(8-bit) bytes or characters are sent. By default all sockets operate
1N/Aon bytes, but for example if the socket has been changed using
1N/Abinmode() to operate with the C<:utf8> I/O layer (see L</open>, or the
1N/AC<open> pragma, L<open>), the I/O will operate on UTF-8 encoded
1N/AUnicode characters, not bytes. Similarly for the C<:encoding> pragma:
1N/Ain that case pretty much any characters can be sent.
1N/A=item setpgrp PID,PGRP
1N/ASets the current process group for the specified PID, C<0> for the current
1N/Aprocess. Will produce a fatal error if used on a machine that doesn't
1N/Aimplement POSIX setpgid(2) or BSD setpgrp(2). If the arguments are omitted,
1N/Ait defaults to C<0,0>. Note that the BSD 4.2 version of C<setpgrp> does not
1N/Aaccept any arguments, so only C<setpgrp(0,0)> is portable. See also
1N/A=item setpriority WHICH,WHO,PRIORITY
1N/ASets the current priority for a process, a process group, or a user.
1N/A(See setpriority(2).) Will produce a fatal error if used on a machine
1N/Athat doesn't implement setpriority(2).
1N/A=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
1N/ASets the socket option requested. Returns undefined if there is an
1N/Aerror. OPTVAL may be specified as C<undef> if you don't want to pass an
1N/AShifts the first value of the array off and returns it, shortening the
1N/Aarray by 1 and moving everything down. If there are no elements in the
1N/Aarray, returns the undefined value. If ARRAY is omitted, shifts the
1N/AC<@_> array within the lexical scope of subroutines and formats, and the
1N/AC<@ARGV> array at file scopes or within the lexical scopes established by
1N/Athe C<eval ''>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>, and C<END {}>
1N/ASee also C<unshift>, C<push>, and C<pop>. C<shift> and C<unshift> do the
1N/Asame thing to the left end of an array that C<pop> and C<push> do to the
1N/A=item shmctl ID,CMD,ARG
1N/ACalls the System V IPC function shmctl. You'll probably have to say
1N/Afirst to get the correct constant definitions. If CMD is C<IPC_STAT>,
1N/Athen ARG must be a variable which will hold the returned C<shmid_ds>
1N/Astructure. Returns like ioctl: the undefined value for error, "C<0> but
1N/Atrue" for zero, or the actual return value otherwise.
1N/ASee also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
1N/A=item shmget KEY,SIZE,FLAGS
1N/ACalls the System V IPC function shmget. Returns the shared memory
1N/Asegment id, or the undefined value if there is an error.
1N/ASee also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
1N/A=item shmread ID,VAR,POS,SIZE
1N/A=item shmwrite ID,STRING,POS,SIZE
1N/AReads or writes the System V shared memory segment ID starting at
1N/Aposition POS for size SIZE by attaching to it, copying
in/out, and
1N/Adetaching from it. When reading, VAR must be a variable that will
1N/Ahold the data read. When writing, if STRING is too long, only SIZE
1N/Abytes are used; if STRING is too short, nulls are written to fill out
1N/ASIZE bytes. Return true if successful, or false if there is an error.
1N/Ashmread() taints the variable. See also L<perlipc/"SysV IPC">,
1N/AC<IPC::SysV> documentation, and the C<IPC::Shareable> module from CPAN.
1N/A=item shutdown SOCKET,HOW
1N/AShuts down a socket connection in the manner indicated by HOW, which
1N/Ahas the same interpretation as in the system call of the same name.
1N/A shutdown(SOCKET, 0); #
I/we have stopped reading data
1N/A shutdown(SOCKET, 1); #
I/we have stopped writing data
1N/A shutdown(SOCKET, 2); #
I/we have stopped using this socket
1N/AThis is useful with sockets when you want to tell the other
1N/Aside you're done writing but not done reading, or vice versa.
1N/AIt's also a more insistent form of close because it also
1N/Adisables the file descriptor in any forked copies in other
1N/AReturns the sine of EXPR (expressed in radians). If EXPR is omitted,
1N/Areturns sine of C<$_>.
1N/AFor the inverse sine operation, you may use the C<Math::Trig::asin>
1N/Afunction, or use this relation:
1N/A sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
1N/ACauses the script to sleep for EXPR seconds, or forever if no EXPR.
1N/AMay be interrupted if the process receives a signal such as C<SIGALRM>.
1N/AReturns the number of seconds actually slept. You probably cannot
1N/Amix C<alarm> and C<sleep> calls, because C<sleep> is often implemented
1N/AOn some older systems, it may sleep up to a full second less than what
1N/Ayou requested, depending on how it counts seconds. Most modern systems
1N/Aalways sleep the full amount. They may appear to sleep longer than that,
1N/Ahowever, because your process might not be scheduled right away in a
1N/Abusy multitasking system.
1N/AFor delays of finer granularity than one second, you may use Perl's
1N/AC<syscall> interface to access setitimer(2) if your system supports
1N/Ait, or else see L</select> above. The Time::HiRes module (from CPAN,
1N/Aand starting from Perl 5.8 part of the standard distribution) may also
1N/ASee also the POSIX module's C<pause> function.
1N/A=item socket SOCKET,DOMAIN,TYPE,PROTOCOL
1N/AOpens a socket of the specified kind and attaches it to filehandle
1N/ASOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for
1N/Athe system call of the same name. You should C<use Socket> first
1N/Ato get the proper definitions imported. See the examples in
1N/AOn systems that support a close-on-exec flag on files, the flag will
1N/Abe set for the newly opened file descriptor, as determined by the
1N/Avalue of $^F. See L<perlvar/$^F>.
1N/A=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
1N/ACreates an unnamed pair of sockets in the specified domain, of the
1N/Aspecified type. DOMAIN, TYPE, and PROTOCOL are specified the same as
1N/Afor the system call of the same name. If unimplemented, yields a fatal
1N/Aerror. Returns true if successful.
1N/AOn systems that support a close-on-exec flag on files, the flag will
1N/Abe set for the newly opened file descriptors, as determined by the value
1N/Aof $^F. See L<perlvar/$^F>.
1N/ASome systems defined C<pipe> in terms of C<socketpair>, in which a call
1N/Ato C<pipe(Rdr, Wtr)> is essentially:
1N/A socketpair(Rdr, Wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC);
1N/A shutdown(Rdr, 1); # no more writing for reader
1N/A shutdown(Wtr, 0); # no more reading for writer
1N/ASee L<perlipc> for an example of socketpair use. Perl 5.8 and later will
1N/Aemulate socketpair using IP sockets to localhost if your system implements
1N/Asockets but not socketpair.
1N/A=item sort SUBNAME LIST
1N/A=item sort BLOCK LIST
1N/AIn list context, this sorts the LIST and returns the sorted list value.
1N/AIn scalar context, the behaviour of C<sort()> is undefined.
1N/AIf SUBNAME or BLOCK is omitted, C<sort>s in standard string comparison
1N/Aorder. If SUBNAME is specified, it gives the name of a subroutine
1N/Athat returns an integer less than, equal to, or greater than C<0>,
1N/Adepending on how the elements of the list are to be ordered. (The C<<
1N/A<=> >> and C<cmp> operators are extremely useful in such routines.)
1N/ASUBNAME may be a scalar variable name (unsubscripted), in which case
1N/Athe value provides the name of (or a reference to) the actual
1N/Asubroutine to use. In place of a SUBNAME, you can provide a BLOCK as
1N/Aan anonymous, in-line sort subroutine.
1N/AIf the subroutine's prototype is C<($$)>, the elements to be compared
1N/Aare passed by reference in C<@_>, as for a normal subroutine. This is
1N/Aslower than unprototyped subroutines, where the elements to be
1N/Acompared are passed into the subroutine
1N/Aas the package global variables $a and $b (see example below). Note that
1N/Ain the latter case, it is usually counter-productive to declare $a and
1N/AIn either case, the subroutine may not be recursive. The values to be
1N/Acompared are always passed by reference, so don't modify them.
1N/AYou also cannot exit out of the sort block or subroutine using any of the
1N/Aloop control operators described in L<perlsyn> or with C<goto>.
1N/AWhen C<use locale> is in effect, C<sort LIST> sorts LIST according to the
1N/Acurrent collation locale. See L<perllocale>.
1N/APerl 5.6 and earlier used a quicksort algorithm to implement sort.
1N/AThat algorithm was not stable, and I<could> go quadratic. (A I<stable> sort
1N/Apreserves the input order of elements that compare equal. Although
1N/Aquicksort's run time is O(NlogN) when averaged over all arrays of
1N/Alength N, the time can be O(N**2), I<quadratic> behavior, for some
1N/Ainputs.) In 5.7, the quicksort implementation was replaced with
1N/Aa stable mergesort algorithm whose worst case behavior is O(NlogN).
1N/ABut benchmarks indicated that for some inputs, on some platforms,
1N/Athe original quicksort was faster. 5.8 has a sort pragma for
1N/Alimited control of the sort. Its rather blunt control of the
1N/Aunderlying algorithm may not persist into future perls, but the
1N/Aability to characterize the input or output in implementation
1N/Aindependent ways quite probably will. See L<sort>.
1N/A @articles = sort @files;
1N/A # same thing, but with explicit sort routine
1N/A @articles = sort {$a cmp $b} @files;
1N/A # now case-insensitively
1N/A @articles = sort {uc($a) cmp uc($b)} @files;
1N/A # same thing in reversed order
1N/A @articles = sort {$b cmp $a} @files;
1N/A # sort numerically ascending
1N/A @articles = sort {$a <=> $b} @files;
1N/A # sort numerically descending
1N/A @articles = sort {$b <=> $a} @files;
1N/A # this sorts the %age hash by value instead of key
1N/A # using an in-line function
1N/A @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
1N/A # sort using explicit subroutine name
1N/A $age{$a} <=> $age{$b}; # presuming numeric
1N/A @sortedclass = sort byage @class;
1N/A sub backwards { $b cmp $a }
1N/A @harry = qw(dog cat x Cain Abel);
1N/A @george = qw(gone chased yz Punished Axed);
1N/A # prints AbelCaincatdogx
1N/A print sort backwards @harry;
1N/A # prints xdogcatCainAbel
1N/A print sort @george, 'to', @harry;
1N/A # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
1N/A # inefficiently sort by descending numeric compare using
1N/A # the first integer after the first = sign, or the
1N/A # whole record case-insensitively otherwise
1N/A ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
1N/A # same thing, but much more efficiently;
1N/A # we'll build auxiliary indices instead
1N/A push @nums, /=(\d+)/;
1N/A $nums[$b] <=> $nums[$a]
1N/A $caps[$a] cmp $caps[$b]
1N/A # same thing, but without any temps
1N/A @new = map { $_->[0] }
1N/A sort { $b->[1] <=> $a->[1]
1N/A } map { [$_, /=(\d+)/, uc($_)] } @old;
1N/A # using a prototype allows you to use any comparison subroutine
1N/A # as a sort subroutine (including other package's subroutines)
1N/A sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are not set here
1N/A @new = sort other::backwards @old;
1N/A # guarantee stability, regardless of algorithm
1N/A @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
1N/A # force use of mergesort (not portable outside Perl 5.8)
1N/A use sort '_mergesort'; # note discouraging _
1N/A @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
1N/AIf you're using strict, you I<must not> declare $a
1N/Aand $b as lexicals. They are package globals. That means
1N/Aif you're in the C<main> package and type
1N/A @articles = sort {$b <=> $a} @files;
1N/Athen C<$a> and C<$b> are C<$main::a> and C<$main::b> (or C<$::a> and C<$::b>),
1N/Abut if you're in the C<FooPack> package, it's the same as typing
1N/A @articles = sort {$FooPack::b <=> $FooPack::a} @files;
1N/AThe comparison function is required to behave. If it returns
1N/Ainconsistent results (sometimes saying C<$x[1]> is less than C<$x[2]> and
1N/Asometimes saying the opposite, for example) the results are not
1N/ABecause C<< <=> >> returns C<undef> when either operand is C<NaN>
1N/A(not-a-number), and because C<sort> will trigger a fatal error unless the
1N/Aresult of a comparison is defined, when sorting with a comparison function
1N/Alike C<< $a <=> $b >>, be careful about lists that might contain a C<NaN>.
1N/AThe following example takes advantage of the fact that C<NaN != NaN> to
1N/Aeliminate any C<NaN>s from the input.
1N/A @result = sort { $a <=> $b } grep { $_ == $_ } @input;
1N/A=item splice ARRAY,OFFSET,LENGTH,LIST
1N/A=item splice ARRAY,OFFSET,LENGTH
1N/A=item splice ARRAY,OFFSET
1N/ARemoves the elements designated by OFFSET and LENGTH from an array, and
1N/Areplaces them with the elements of LIST, if any. In list context,
1N/Areturns the elements removed from the array. In scalar context,
1N/Areturns the last element removed, or C<undef> if no elements are
1N/Aremoved. The array grows or shrinks as necessary.
1N/AIf OFFSET is negative then it starts that far from the end of the array.
1N/AIf LENGTH is omitted, removes everything from OFFSET onward.
1N/AIf LENGTH is negative, removes the elements from OFFSET onward
1N/Aexcept for -LENGTH elements at the end of the array.
1N/AIf both OFFSET and LENGTH are omitted, removes everything. If OFFSET is
1N/Apast the end of the array, perl issues a warning, and splices at the
1N/AThe following equivalences hold (assuming C<< $[ == 0 and $#a >= $i >> )
1N/A push(@a,$x,$y) splice(@a,@a,0,$x,$y)
1N/A pop(@a) splice(@a,-1)
1N/A shift(@a) splice(@a,0,1)
1N/A unshift(@a,$x,$y) splice(@a,0,0,$x,$y)
1N/A $a[$i] = $y splice(@a,$i,1,$y)
1N/AExample, assuming array lengths are passed before arrays:
1N/A sub aeq { # compare two list values
1N/A my(@a) = splice(@_,0,shift);
1N/A my(@b) = splice(@_,0,shift);
1N/A return 0 unless @a == @b; # same len?
1N/A return 0 if pop(@a) ne pop(@b);
1N/A if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
1N/A=item split /PATTERN/,EXPR,LIMIT
1N/A=item split /PATTERN/,EXPR
1N/A=item split /PATTERN/
1N/ASplits the string EXPR into a list of strings and returns that list. By
1N/Adefault, empty leading fields are preserved, and empty trailing ones are
1N/AIn scalar context, returns the number of fields found and splits into
1N/Athe C<@_> array. Use of split in scalar context is deprecated, however,
1N/Abecause it clobbers your subroutine arguments.
1N/AIf EXPR is omitted, splits the C<$_> string. If PATTERN is also omitted,
1N/Asplits on whitespace (after skipping any leading whitespace). Anything
1N/Amatching PATTERN is taken to be a delimiter separating the fields. (Note
1N/Athat the delimiter may be longer than one character.)
1N/AIf LIMIT is specified and positive, it represents the maximum number
1N/Aof fields the EXPR will be split into, though the actual number of
1N/Afields returned depends on the number of times PATTERN matches within
1N/AEXPR. If LIMIT is unspecified or zero, trailing null fields are
1N/Astripped (which potential users of C<pop> would do well to remember).
1N/AIf LIMIT is negative, it is treated as if an arbitrarily large LIMIT
1N/Ahad been specified. Note that splitting an EXPR that evaluates to the
1N/Aempty string always returns the empty list, regardless of the LIMIT
1N/AA pattern matching the null string (not to be confused with
1N/Aa null pattern C<//>, which is just one member of the set of patterns
1N/Amatching a null string) will split the value of EXPR into separate
1N/Acharacters at each point it matches that way. For example:
1N/A print join(':', split(/ */, 'hi there'));
1N/Aproduces the output 'h:i:t:h:e:r:e'.
1N/AUsing the empty pattern C<//> specifically matches the null string, and is
1N/Anot be confused with the use of C<//> to mean "the last successful pattern
1N/AEmpty leading (or trailing) fields are produced when there are positive width
1N/Amatches at the beginning (or end) of the string; a zero-width match at the
1N/Abeginning (or end) of the string does not produce an empty field. For
1N/A print join(':', split(/(?=\w)/, 'hi there!'));
1N/Aproduces the output 'h:i :t:h:e:r:e!'.
1N/AThe LIMIT parameter can be used to split a line partially
1N/A ($login, $passwd, $remainder) = split(/:/, $_, 3);
1N/AWhen assigning to a list, if LIMIT is omitted, or zero, Perl supplies
1N/Aa LIMIT one larger than the number of variables in the list, to avoid
1N/Aunnecessary work. For the list above LIMIT would have been 4 by
1N/Adefault. In time critical applications it behooves you not to split
1N/Ainto more fields than you really need.
1N/AIf the PATTERN contains parentheses, additional list elements are
1N/Acreated from each matching substring in the delimiter.
1N/A split(/([,-])/, "1-10,20", 3);
1N/Aproduces the list value
1N/A (1, '-', 10, ',', 20)
1N/AIf you had the entire header of a normal Unix email message in $header,
1N/Ayou could split it up into fields and their values this way:
1N/A $header =~ s/\n\s+/ /g; # fix continuation lines
1N/A %hdrs = (UNIX_FROM => split /^(\S*?):\s*/m, $header);
1N/AThe pattern C</PATTERN/> may be replaced with an expression to specify
1N/Apatterns that vary at runtime. (To do runtime compilation only once,
1N/Ause C</$variable/o>.)
1N/AAs a special case, specifying a PATTERN of space (S<C<' '>>) will split on
1N/Awhite space just as C<split> with no arguments does. Thus, S<C<split(' ')>> can
1N/Abe used to emulate B<awk>'s default behavior, whereas S<C<split(/ /)>>
1N/Awill give you as many null initial fields as there are leading spaces.
1N/AA C<split> on C</\s+/> is like a S<C<split(' ')>> except that any leading
1N/Awhitespace produces a null first field. A C<split> with no arguments
1N/Areally does a S<C<split(' ', $_)>> internally.
1N/AA PATTERN of C</^/> is treated as if it were C</^/m>, since it isn't
1N/A ($login, $passwd, $uid, $gid,
1N/A $gcos, $home, $shell) = split(/:/);
1N/AAs with regular pattern matching, any capturing parentheses that are not
1N/Amatched in a C<split()> will be set to C<undef> when returned:
1N/A @fields = split /(A)|B/, "1A2B3";
1N/A # @fields is (1, 'A', 2, undef, 3)
1N/A=item sprintf FORMAT, LIST
1N/AReturns a string formatted by the usual C<printf> conventions of the C
1N/Alibrary function C<sprintf>. See below for more details
1N/Aand see L<sprintf(3)> or L<printf(3)> on your system for an explanation of
1N/Athe general principles.
1N/A # Format number with up to 8 leading zeroes
1N/A $result = sprintf("%08d", $number);
1N/A # Round number to 3 digits after decimal point
1N/A $rounded = sprintf("%.3f", $number);
1N/APerl does its own C<sprintf> formatting--it emulates the C
1N/Afunction C<sprintf>, but it doesn't use it (except for floating-point
1N/Anumbers, and even then only the standard modifiers are allowed). As a
1N/Aresult, any non-standard extensions in your local C<sprintf> are not
1N/AUnlike C<printf>, C<sprintf> does not do what you probably mean when you
1N/Apass it an array as your first argument. The array is given scalar context,
1N/Aand instead of using the 0th element of the array as the format, Perl will
1N/Ause the count of elements in the array as the format, which is almost never
1N/APerl's C<sprintf> permits the following universally-known conversions:
1N/A %c a character with the given number
1N/A %d a signed integer, in decimal
1N/A %u an unsigned integer, in decimal
1N/A %o an unsigned integer, in octal
1N/A %x an unsigned integer, in hexadecimal
1N/A %e a floating-point number, in scientific notation
1N/A %f a floating-point number, in fixed decimal notation
1N/A %g a floating-point number, in %e or %f notation
1N/AIn addition, Perl permits the following widely-supported conversions:
1N/A %X like %x, but using upper-case letters
1N/A %E like %e, but using an upper-case "E"
1N/A %G like %g, but with an upper-case "E" (if applicable)
1N/A %b an unsigned integer, in binary
1N/A %p a pointer (outputs the Perl value's address in hexadecimal)
1N/A %n special: *stores* the number of characters output so far
1N/A into the next variable in the parameter list
1N/AFinally, for backward (and we do mean "backward") compatibility, Perl
1N/Apermits these unnecessary but widely-supported conversions:
1N/A %D a synonym for %ld
1N/A %U a synonym for %lu
1N/A %O a synonym for %lo
1N/ANote that the number of exponent digits in the scientific notation produced
1N/Aby C<%e>, C<%E>, C<%g> and C<%G> for numbers with the modulus of the
1N/Aexponent less than 100 is system-dependent: it may be three or less
1N/A(zero-padded as necessary). In other words, 1.23 times ten to the
1N/A99th may be either "1.23e99" or "1.23e099".
1N/ABetween the C<%> and the format letter, you may specify a number of
1N/Aadditional attributes controlling the interpretation of the format.
1N/A=item format parameter index
1N/AAn explicit format parameter index, such as C<2$>. By default sprintf
1N/Awill format the next unused argument in the list, but this allows you
1N/Ato take the arguments out of order. Eg:
1N/A printf '%2$d %1$d', 12, 34; # prints "34 12"
1N/A printf '%3$d %d %1$d', 1, 2, 3; # prints "3 1 1"
1N/A space prefix positive number with a space
1N/A + prefix positive number with a plus sign
1N/A - left-justify within the field
1N/A 0 use zeros, not spaces, to right-justify
1N/A # prefix non-zero octal with "0", non-zero hex with "0x",
1N/A non-zero binary with "0b"
1N/A printf '<% d>', 12; # prints "< 12>"
1N/A printf '<%+d>', 12; # prints "<+12>"
1N/A printf '<%6s>', 12; # prints "< 12>"
1N/A printf '<%-6s>', 12; # prints "<12 >"
1N/A printf '<%06s>', 12; # prints "<000012>"
1N/A printf '<%#x>', 12; # prints "<0xc>"
1N/AThe vector flag C<v>, optionally specifying the join string to use.
1N/AThis flag tells perl to interpret the supplied string as a vector
1N/Aof integers, one for each character in the string, separated by
1N/Aa given string (a dot C<.> by default). This can be useful for
1N/Adisplaying ordinal values of characters in arbitrary strings:
1N/A printf "version is v%vd\n", $^V; # Perl's version
1N/APut an asterisk C<*> before the C<v> to override the string to
1N/Ause to separate the numbers:
1N/A printf "address is %*vX\n", ":", $addr; # IPv6 address
1N/A printf "bits are %0*v8b\n", " ", $bits; # random bitstring
1N/AYou can also explicitly specify the argument number to use for
1N/Athe join string using eg C<*2$v>:
1N/A printf '%*4$vX %*4$vX %*4$vX', @addr[1..3], ":"; # 3 IPv6 addresses
1N/A=item (minimum) width
1N/AArguments are usually formatted to be only as wide as required to
1N/Adisplay the given value. You can override the width by putting
1N/Aa number here, or get the width from the next argument (with C<*>)
1N/Aor from a specified argument (with eg C<*2$>):
1N/A printf '<%s>', "a"; # prints "<a>"
1N/A printf '<%6s>', "a"; # prints "< a>"
1N/A printf '<%*s>', 6, "a"; # prints "< a>"
1N/A printf '<%*2$s>', "a", 6; # prints "< a>"
1N/A printf '<%2s>', "long"; # prints "<long>" (does not truncate)
1N/AIf a field width obtained through C<*> is negative, it has the same
1N/Aeffect as the C<-> flag: left-justification.
1N/A=item precision, or maximum width
1N/AYou can specify a precision (for numeric conversions) or a maximum
1N/Awidth (for string conversions) by specifying a C<.> followed by a number.
1N/AFor floating point formats, with the exception of 'g' and 'G', this specifies
1N/Athe number of decimal places to show (the default being 6), eg:
1N/A # these examples are subject to system-specific variation
1N/A printf '<%f>', 1; # prints "<1.000000>"
1N/A printf '<%.1f>', 1; # prints "<1.0>"
1N/A printf '<%.0f>', 1; # prints "<1>"
1N/A printf '<%e>', 10; # prints "<1.000000e+01>"
1N/A printf '<%.1e>', 10; # prints "<1.0e+01>"
1N/AFor 'g' and 'G', this specifies the maximum number of digits to show,
1N/Aincluding prior to the decimal point as well as after it, eg:
1N/A # these examples are subject to system-specific variation
1N/A printf '<%g>', 1; # prints "<1>"
1N/A printf '<%.10g>', 1; # prints "<1>"
1N/A printf '<%g>', 100; # prints "<100>"
1N/A printf '<%.1g>', 100; # prints "<1e+02>"
1N/A printf '<%.2g>', 100.01; # prints "<1e+02>"
1N/A printf '<%.5g>', 100.01; # prints "<100.01>"
1N/A printf '<%.4g>', 100.01; # prints "<100>"
1N/AFor integer conversions, specifying a precision implies that the
1N/Aoutput of the number itself should be zero-padded to this width:
1N/A printf '<%.6x>', 1; # prints "<000001>"
1N/A printf '<%#.6x>', 1; # prints "<0x000001>"
1N/A printf '<%-10.6x>', 1; # prints "<000001 >"
1N/AFor string conversions, specifying a precision truncates the string
1N/Ato fit in the specified width:
1N/A printf '<%.5s>', "truncated"; # prints "<trunc>"
1N/A printf '<%10.5s>', "truncated"; # prints "< trunc>"
1N/AYou can also get the precision from the next argument using C<.*>:
1N/A printf '<%.6x>', 1; # prints "<000001>"
1N/A printf '<%.*x>', 6, 1; # prints "<000001>"
1N/AYou cannot currently get the precision from a specified number,
1N/Abut it is intended that this will be possible in the future using
1N/A printf '<%.*2$x>', 1, 6; # INVALID, but in future will print "<000001>"
1N/AFor numeric conversions, you can specify the size to interpret the
1N/Anumber as using C<l>, C<h>, C<V>, C<q>, C<L>, or C<ll>. For integer
1N/Aconversions (C<d u o x X b i D U O>), numbers are usually assumed to be
1N/Awhatever the default integer size is on your platform (usually 32 or 64
1N/Abits), but you can override this to use instead one of the standard C types,
1N/Aas supported by the compiler used to build Perl:
1N/A l interpret integer as C type "long" or "unsigned long"
1N/A h interpret integer as C type "short" or "unsigned short"
1N/A q, L or ll interpret integer as C type "long long", "unsigned long long".
1N/A or "quads" (typically 64-bit integers)
1N/AThe last will produce errors if Perl does not understand "quads" in your
1N/Ainstallation. (This requires that either the platform natively supports quads
1N/Aor Perl was specifically compiled to support quads.) You can find out
1N/Awhether your Perl supports quads via L<Config>:
1N/A ($Config{use64bitint} eq 'define' || $Config{longsize} >= 8) &&
1N/AFor floating point conversions (C<e f g E F G>), numbers are usually assumed
1N/Ato be the default floating point size on your platform (double or long double),
1N/Abut you can force 'long double' with C<q>, C<L>, or C<ll> if your
1N/Aplatform supports them. You can find out whether your Perl supports long
1N/Adoubles via L<Config>:
1N/A $Config{d_longdbl} eq 'define' && print "long doubles\n";
1N/AYou can find out whether Perl considers 'long double' to be the default
1N/Afloating point size to use on your platform via L<Config>:
1N/A ($Config{uselongdouble} eq 'define') &&
1N/A print "long doubles by default\n";
1N/AIt can also be the case that long doubles and doubles are the same thing:
1N/A ($Config{doublesize} == $Config{longdblsize}) &&
1N/A print "doubles are long doubles\n";
1N/AThe size specifier C<V> has no effect for Perl code, but it is supported
1N/Afor compatibility with XS code; it means 'use the standard size for
1N/Aa Perl integer (or floating-point number)', which is already the
1N/Adefault for Perl code.
1N/A=item order of arguments
1N/ANormally, sprintf takes the next unused argument as the value to
1N/Aformat for each format specification. If the format specification
1N/Auses C<*> to require additional arguments, these are consumed from
1N/Athe argument list in the order in which they appear in the format
1N/Aspecification I<before> the value to format. Where an argument is
1N/Aspecified using an explicit index, this does not affect the normal
1N/Aorder for the arguments (even when the explicitly specified index
1N/Awould have been the next argument in any case).
1N/A printf '<%*.*s>', $a, $b, $c;
1N/Awould use C<$a> for the width, C<$b> for the precision and C<$c>
1N/Aas the value to format, while:
1N/A print '<%*1$.*s>', $a, $b;
1N/Awould use C<$a> for the width and the precision, and C<$b> as the
1N/AHere are some more examples - beware that when using an explicit
1N/Aindex, the C<$> may need to be escaped:
1N/A printf "%2\$d %d\n", 12, 34; # will print "34 12\n"
1N/A printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n"
1N/A printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n"
1N/A printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n"
1N/AIf C<use locale> is in effect, the character used for the decimal
1N/Apoint in formatted real numbers is affected by the LC_NUMERIC locale.
1N/AReturn the square root of EXPR. If EXPR is omitted, returns square
1N/Aroot of C<$_>. Only works on non-negative operands, unless you've
1N/Aloaded the standard Math::Complex module.
1N/A print sqrt(-2); # prints 1.4142135623731i
1N/ASets the random number seed for the C<rand> operator.
1N/AThe point of the function is to "seed" the C<rand> function so that
1N/AC<rand> can produce a different sequence each time you run your
1N/AIf srand() is not called explicitly, it is called implicitly at the
1N/Afirst use of the C<rand> operator. However, this was not the case in
1N/Aversions of Perl before 5.004, so if your script will run under older
1N/APerl versions, it should call C<srand>.
1N/AMost programs won't even call srand() at all, except those that
1N/Aneed a cryptographically-strong starting point rather than the
1N/Agenerally acceptable default, which is based on time of day,
1N/AYou can call srand($seed) with the same $seed to reproduce the
1N/AI<same> sequence from rand(), but this is usually reserved for
1N/Agenerating predictable results for testing or debugging.
1N/AOtherwise, don't call srand() more than once in your program.
1N/ADo B<not> call srand() (
i.e. without an argument) more than once in
1N/Aa script. The internal state of the random number generator should
1N/Acontain more entropy than can be provided by any seed, so calling
1N/Asrand() again actually I<loses> randomness.
1N/AMost implementations of C<srand> take an integer and will silently
1N/Atruncate decimal numbers. This means C<srand(42)> will usually
1N/Aproduce the same results as C<srand(42.1)>. To be safe, always pass
1N/AIn versions of Perl prior to 5.004 the default seed was just the
1N/Acurrent C<time>. This isn't a particularly good seed, so many old
1N/Aprograms supply their own seed value (often C<time ^ $$> or C<time ^
1N/A($$ + ($$ << 15))>), but that isn't necessary any more.
1N/ANote that you need something much more random than the default seed for
1N/Acryptographic purposes. Checksumming the compressed output of one or more
1N/Arapidly changing operating system status programs is the usual method. For
1N/A srand (time ^ $$ ^ unpack "%L*", `ps axww | gzip`);
1N/AIf you're particularly concerned with this, see the C<Math::TrulyRandom>
1N/AFrequently called programs (like CGI scripts) that simply use
1N/Afor a seed can fall prey to the mathematical property that
1N/Aone-third of the time. So don't do that.
1N/A=item stat FILEHANDLE
1N/AReturns a 13-element list giving the status info for a file, either
1N/Athe file opened via FILEHANDLE, or named by EXPR. If EXPR is omitted,
1N/Ait stats C<$_>. Returns a null list if the stat fails. Typically used
1N/A ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
1N/A $atime,$mtime,$ctime,$blksize,$blocks)
1N/ANot all fields are supported on all filesystem types. Here are the
1N/Ameanings of the fields:
1N/A 0 dev device number of filesystem
1N/A 2 mode file mode (type and permissions)
1N/A 3 nlink number of (hard) links to the file
1N/A 4 uid numeric user ID of file's owner
1N/A 5 gid numeric group ID of file's owner
1N/A 6 rdev the device identifier (special files only)
1N/A 7 size total size of file, in bytes
1N/A 8 atime last access time in seconds since the epoch
1N/A 9 mtime last modify time in seconds since the epoch
1N/A 10 ctime inode change time in seconds since the epoch (*)
1N/A 11 blksize preferred block size for file system I/O
1N/A 12 blocks actual number of blocks allocated
1N/A(The epoch was at 00:00 January 1, 1970 GMT.)
1N/A(*) The ctime field is non-portable. In particular, you cannot expect
1N/Ait to be a "creation time", see L<perlport/"Files and Filesystems">
1N/AIf C<stat> is passed the special filehandle consisting of an underline, no
1N/Astat is done, but the current contents of the stat structure from the
1N/Alast C<stat>, C<lstat>, or filetest are returned. Example:
1N/A if (-x $file && (($d) = stat(_)) && $d < 0) {
1N/A print "$file is executable NFS file\n";
1N/A(This works on machines only for which the device number is negative
1N/ABecause the mode contains both the file type and its permissions, you
1N/Ashould mask off the file type portion and (s)printf using a C<"%o">
1N/Aif you want to see the real permissions.
1N/A $mode = (stat($filename))[2];
1N/A printf "Permissions are %04o\n", $mode & 07777;
1N/AIn scalar context, C<stat> returns a boolean value indicating success
1N/Aor failure, and, if successful, sets the information associated with
1N/Athe special filehandle C<_>.
1N/AThe File::stat module provides a convenient, by-name access mechanism:
1N/A $sb = stat($filename);
1N/A printf "File is %s, size is %s, perm %04o, mtime %s\n",
1N/A $filename, $sb->size, $sb->mode & 07777,
1N/A scalar localtime $sb->mtime;
1N/AYou can import symbolic mode constants (C<S_IF*>) and functions
1N/A(C<S_IS*>) from the Fcntl module:
1N/A $mode = (stat($filename))[2];
1N/A $user_rwx = ($mode & S_IRWXU) >> 6;
1N/A $group_read = ($mode & S_IRGRP) >> 3;
1N/A $other_execute = $mode & S_IXOTH;
1N/A printf "Permissions are %04o\n", S_IMODE($mode), "\n";
1N/A $is_setuid = $mode & S_ISUID;
1N/A $is_setgid = S_ISDIR($mode);
1N/AYou could write the last two using the C<-u> and C<-d> operators.
1N/AThe commonly available C<S_IF*> constants are
1N/A # Permissions: read, write, execute, for user, group, others.
1N/A S_IRWXU S_IRUSR S_IWUSR S_IXUSR
1N/A S_IRWXG S_IRGRP S_IWGRP S_IXGRP
1N/A S_IRWXO S_IROTH S_IWOTH S_IXOTH
1N/A # Note that the exact meaning of these is system dependent.
1N/A S_ISUID S_ISGID S_ISVTX S_ISTXT
1N/A # File types. Not necessarily all are available on your system.
1N/A S_IFREG S_IFDIR S_IFLNK S_IFBLK S_ISCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
1N/A # The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.
1N/A S_IREAD S_IWRITE S_IEXEC
1N/Aand the C<S_IF*> functions are
1N/A S_IMODE($mode) the part of $mode containing the permission bits
1N/A S_IFMT($mode) the part of $mode containing the file type
1N/A which can be bit-anded with
e.g. S_IFREG
1N/A or with the following functions
1N/A # The operators -f, -d, -l, -b, -c, -p, and -S.
1N/A S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
1N/A S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
1N/A # No direct -X operator counterpart, but for the first one
1N/A # the -g operator is often equivalent. The ENFMT stands for
1N/A # record flocking enforcement, a platform-dependent feature.
1N/A S_ISENFMT($mode) S_ISWHT($mode)
1N/ASee your native chmod(2) and stat(2) documentation for more details
1N/Aabout the C<S_*> constants. To get status info for a symbolic link
1N/Ainstead of the target file behind the link, use the C<lstat> function.
1N/ATakes extra time to study SCALAR (C<$_> if unspecified) in anticipation of
1N/Adoing many pattern matches on the string before it is next modified.
1N/AThis may or may not save time, depending on the nature and number of
1N/Apatterns you are searching on, and on the distribution of character
1N/Afrequencies in the string to be searched--you probably want to compare
1N/Arun times with and without it to see which runs faster. Those loops
1N/Awhich scan for many short constant strings (including the constant
1N/Aparts of more complex patterns) will benefit most. You may have only
1N/Aone C<study> active at a time--if you study a different scalar the first
1N/Ais "unstudied". (The way C<study> works is this: a linked list of every
1N/Acharacter in the string to be searched is made, so we know, for
1N/Aexample, where all the C<'k'> characters are. From each search string,
1N/Athe rarest character is selected, based on some static frequency tables
1N/Aconstructed from some C programs and English text. Only those places
1N/Athat contain this "rarest" character are examined.)
1N/AFor example, here is a loop that inserts index producing entries
1N/Abefore any line containing a certain pattern:
1N/A print ".IX foo\n" if /\bfoo\b/;
1N/A print ".IX bar\n" if /\bbar\b/;
1N/A print ".IX blurfl\n" if /\bblurfl\b/;
1N/AIn searching for C</\bfoo\b/>, only those locations in C<$_> that contain C<f>
1N/Awill be looked at, because C<f> is rarer than C<o>. In general, this is
1N/Aa big win except in pathological cases. The only question is whether
1N/Ait saves you more time than it took to build the linked list in the
1N/ANote that if you have to look for strings that you don't know till
1N/Aruntime, you can build an entire loop as a string and C<eval> that to
1N/Aavoid recompiling all your patterns all the time. Together with
1N/Aundefining C<$/> to input entire files as one record, this can be very
1N/Afast, often faster than specialized programs like fgrep(1). The following
1N/Ascans a list of files (C<@files>) for a list of words (C<@words>), and prints
1N/Aout the names of those files that contain a match:
1N/A $search = 'while (<>) { study;';
1N/A foreach $word (@words) {
1N/A $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n";
1N/A eval $search; # this screams
1N/A $/ = "\n"; # put back to normal input delimiter
1N/A foreach $file (sort keys(%seen)) {
1N/A=item sub NAME (PROTO) BLOCK
1N/A=item sub NAME : ATTRS BLOCK
1N/A=item sub NAME (PROTO) : ATTRS BLOCK
1N/AThis is subroutine definition, not a real function I<per se>.
1N/AWithout a BLOCK it's just a forward declaration. Without a NAME,
1N/Ait's an anonymous function declaration, and does actually return
1N/Aa value: the CODE ref of the closure you just created.
1N/ASee L<perlsub> and L<perlref> for details about subroutines and
1N/Areferences, and L<attributes> and L<Attribute::Handlers> for more
1N/Ainformation about attributes.
1N/A=item substr EXPR,OFFSET,LENGTH,REPLACEMENT
1N/A=item substr EXPR,OFFSET,LENGTH
1N/A=item substr EXPR,OFFSET
1N/AExtracts a substring out of EXPR and returns it. First character is at
1N/Aoffset C<0>, or whatever you've set C<$[> to (but don't do that).
1N/AIf OFFSET is negative (or more precisely, less than C<$[>), starts
1N/Athat far from the end of the string. If LENGTH is omitted, returns
1N/Aeverything to the end of the string. If LENGTH is negative, leaves that
1N/Amany characters off the end of the string.
1N/AYou can use the substr() function as an lvalue, in which case EXPR
1N/Amust itself be an lvalue. If you assign something shorter than LENGTH,
1N/Athe string will shrink, and if you assign something longer than LENGTH,
1N/Athe string will grow to accommodate it. To keep the string the same
1N/Alength you may need to pad or chop your value using C<sprintf>.
1N/AIf OFFSET and LENGTH specify a substring that is partly outside the
1N/Astring, only the part within the string is returned. If the substring
1N/Ais beyond either end of the string, substr() returns the undefined
1N/Avalue and produces a warning. When used as an lvalue, specifying a
1N/Asubstring that is entirely outside the string is a fatal error.
1N/AHere's an example showing the behavior for boundary cases:
1N/A substr($name, 4) = 'dy'; # $name is now 'freddy'
1N/A my $null = substr $name, 6, 2; # returns '' (no warning)
1N/A my $oops = substr $name, 7; # returns undef, with warning
1N/A substr($name, 7) = 'gap'; # fatal error
1N/AAn alternative to using substr() as an lvalue is to specify the
1N/Areplacement string as the 4th argument. This allows you to replace
1N/Aparts of the EXPR and return what was there before in one operation,
1N/Ajust as you can with splice().
1N/AIf the lvalue returned by substr is used after the EXPR is changed in
1N/Aany way, the behaviour may not be as expected and is subject to change.
1N/AThis caveat includes code such as C<print(substr($foo,$a,$b)=$bar)> or
1N/AC<(substr($foo,$a,$b)=$bar)=$fud> (where $foo is changed via the
1N/Asubstring assignment, and then the substr is used again), or where a
1N/Asubstr() is aliased via a C<foreach> loop or passed as a parameter or
1N/Aa reference to it is taken and then the alias, parameter, or deref'd
1N/Areference either is used after the original EXPR has been changed or
1N/Ais assigned to and then used a second time.
1N/A=item symlink OLDFILE,NEWFILE
1N/ACreates a new filename symbolically linked to the old filename.
1N/AReturns C<1> for success, C<0> otherwise. On systems that don't support
1N/Asymbolic links, produces a fatal error at run time. To check for that,
1N/A $symlink_exists = eval { symlink("",""); 1 };
1N/A=item syscall NUMBER, LIST
1N/ACalls the system call specified as the first element of the list,
1N/Apassing the remaining elements as arguments to the system call. If
1N/Aunimplemented, produces a fatal error. The arguments are interpreted
1N/Aas follows: if a given argument is numeric, the argument is passed as
1N/Aan int. If not, the pointer to the string value is passed. You are
1N/Aresponsible to make sure a string is pre-extended long enough to
1N/Areceive any result that might be written into a string. You can't use a
1N/Astring literal (or other read-only string) as an argument to C<syscall>
1N/Abecause Perl has to assume that any string pointer might be written
1N/Ainteger arguments are not literals and have never been interpreted in a
1N/Anumeric context, you may need to add C<0> to them to force them to look
1N/Alike numbers. This emulates the C<syswrite> function (or vice versa):
1N/A syscall(&SYS_write, fileno(STDOUT), $s, length $s);
1N/ANote that Perl supports passing of up to only 14 arguments to your system call,
1N/Awhich in practice should usually suffice.
1N/ASyscall returns whatever value returned by the system call it calls.
1N/AIf the system call fails, C<syscall> returns C<-1> and sets C<$!> (errno).
1N/ANote that some system calls can legitimately return C<-1>. The proper
1N/Away to handle such calls is to assign C<$!=0;> before the call and
1N/Acheck the value of C<$!> if syscall returns C<-1>.
1N/AThere's a problem with C<syscall(&SYS_pipe)>: it returns the file
1N/Anumber of the read end of the pipe it creates. There is no way
1N/Ato retrieve the file number of the other end. You can avoid this
1N/Aproblem by using C<pipe> instead.
1N/A=item sysopen FILEHANDLE,FILENAME,MODE
1N/A=item sysopen FILEHANDLE,FILENAME,MODE,PERMS
1N/AOpens the file whose filename is given by FILENAME, and associates it
1N/Awith FILEHANDLE. If FILEHANDLE is an expression, its value is used as
1N/Athe name of the real filehandle wanted. This function calls the
1N/Aunderlying operating system's C<open> function with the parameters
1N/AFILENAME, MODE, PERMS.
1N/AThe possible values and flag bits of the MODE parameter are
1N/Asystem-dependent; they are available via the standard module C<Fcntl>.
1N/ASee the documentation of your operating system's C<open> to see which
1N/Avalues and flag bits are available. You may combine several flags
1N/Ausing the C<|>-operator.
1N/ASome of the most common values are C<O_RDONLY> for opening the file in
1N/Aread-only mode, C<O_WRONLY> for opening the file in write-only mode,
1N/Aand C<O_RDWR> for opening the file in read-write mode, and.
1N/AFor historical reasons, some values work on almost every system
1N/Asupported by perl: zero means read-only, one means write-only, and two
1N/AOS/390 &
VM/ESA Unix and on the Macintosh; you probably don't want to
1N/Ause them in new code.
1N/AIf the file named by FILENAME does not exist and the C<open> call creates
1N/Ait (typically because MODE includes the C<O_CREAT> flag), then the value of
1N/APERMS specifies the permissions of the newly created file. If you omit
1N/Athe PERMS argument to C<sysopen>, Perl uses the octal value C<0666>.
1N/AThese permission values need to be in octal, and are modified by your
1N/Aprocess's current C<umask>.
1N/AIn many systems the C<O_EXCL> flag is available for opening files in
1N/Aexclusive mode. This is B<not> locking: exclusiveness means here that
1N/Aif the file already exists, sysopen() fails. The C<O_EXCL> wins
1N/ASometimes you may want to truncate an already-existing file: C<O_TRUNC>.
1N/AYou should seldom if ever use C<0644> as argument to C<sysopen>, because
1N/Athat takes away the user's option to have a more permissive umask.
1N/ABetter to omit it. See the perlfunc(1) entry on C<umask> for more
1N/ANote that C<sysopen> depends on the fdopen() C library function.
1N/AOn many UNIX systems, fdopen() is known to fail when file descriptors
1N/Aexceed a certain value, typically 255. If you need more file
1N/Adescriptors than that, consider rebuilding Perl to use the C<sfio>
1N/Alibrary, or perhaps using the POSIX::open() function.
1N/ASee L<perlopentut> for a kinder, gentler explanation of opening files.
1N/A=item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
1N/A=item sysread FILEHANDLE,SCALAR,LENGTH
1N/AAttempts to read LENGTH bytes of data into variable SCALAR from the
1N/Aspecified FILEHANDLE, using the system call read(2). It bypasses
1N/Abuffered IO, so mixing this with other kinds of reads, C<print>,
1N/AC<write>, C<seek>, C<tell>, or C<eof> can cause confusion because the
1N/Aperlio or stdio layers usually buffers data. Returns the number of
1N/Abytes actually read, C<0> at end of file, or undef if there was an
1N/Aerror (in the latter case C<$!> is also set). SCALAR will be grown or
1N/Ashrunk so that the last byte actually read is the last byte of the
1N/Ascalar after the read.
1N/AAn OFFSET may be specified to place the read data at some place in the
1N/Astring other than the beginning. A negative OFFSET specifies
1N/Aplacement at that many characters counting backwards from the end of
1N/Athe string. A positive OFFSET greater than the length of SCALAR
1N/Aresults in the string being padded to the required size with C<"\0">
1N/Abytes before the result of the read is appended.
1N/AThere is no syseof() function, which is ok, since eof() doesn't work
1N/Avery well on device files (like ttys) anyway. Use sysread() and check
1N/Afor a return value for 0 to decide whether you're done.
1N/ANote that if the filehandle has been marked as C<:utf8> Unicode
1N/Acharacters are read instead of bytes (the LENGTH, OFFSET, and the
1N/Areturn value of sysread() are in Unicode characters).
1N/AThe C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
1N/ASee L</binmode>, L</open>, and the C<open> pragma, L<open>.
1N/A=item sysseek FILEHANDLE,POSITION,WHENCE
1N/ASets FILEHANDLE's system position in bytes using the system call
1N/Alseek(2). FILEHANDLE may be an expression whose value gives the name
1N/Aof the filehandle. The values for WHENCE are C<0> to set the new
1N/Aposition to POSITION, C<1> to set the it to the current position plus
1N/APOSITION, and C<2> to set it to EOF plus POSITION (typically
1N/ANote the I<in bytes>: even if the filehandle has been set to operate
1N/Aon characters (for example by using the C<:utf8> I/O layer), tell()
1N/Awill return byte offsets, not character offsets (because implementing
1N/Athat would render sysseek() very slow).
1N/Asysseek() bypasses normal buffered IO, so mixing this with reads (other
1N/Athan C<sysread>, for example >< or read()) C<print>, C<write>,
1N/AC<seek>, C<tell>, or C<eof> may cause confusion.
1N/AFor WHENCE, you may also use the constants C<SEEK_SET>, C<SEEK_CUR>,
1N/Aand C<SEEK_END> (start of the file, current position, end of the file)
1N/Afrom the Fcntl module. Use of the constants is also more portable
1N/Athan relying on 0, 1, and 2. For example to define a "systell" function:
1N/A use Fcntl 'SEEK_CUR';
1N/A sub systell { sysseek($_[0], 0, SEEK_CUR) }
1N/AReturns the new position, or the undefined value on failure. A position
1N/Aof zero is returned as the string C<"0 but true">; thus C<sysseek> returns
1N/Atrue on success and false on failure, yet you can still easily determine
1N/A=item system PROGRAM LIST
1N/ADoes exactly the same thing as C<exec LIST>, except that a fork is
1N/Adone first, and the parent process waits for the child process to
1N/Acomplete. Note that argument processing varies depending on the
1N/Anumber of arguments. If there is more than one argument in LIST,
1N/Aor if LIST is an array with more than one value, starts the program
1N/Agiven by the first element of the list with arguments given by the
1N/Arest of the list. If there is only one scalar argument, the argument
1N/Ais checked for shell metacharacters, and if there are any, the
1N/Aentire argument is passed to the system's command shell for parsing
1N/A(this is C<
/bin/sh -c> on Unix platforms, but varies on other
1N/Aplatforms). If there are no shell metacharacters in the argument,
1N/Ait is split into words and passed directly to C<execvp>, which is
1N/ABeginning with v5.6.0, Perl will attempt to flush all files opened for
1N/Aoutput before any operation that may do a fork, but this may not be
1N/Asupported on some platforms (see L<perlport>). To be safe, you may need
1N/Ato set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
1N/Aof C<IO::Handle> on any open handles.
1N/AThe return value is the exit status of the program as returned by the
1N/AC<wait> call. To get the actual exit value shift right by eight (see below).
1N/ASee also L</exec>. This is I<not> what you want to use to capture
1N/Athe output from a command, for that you should use merely backticks or
1N/AC<qx//>, as described in L<perlop/"`STRING`">. Return value of -1
1N/Aindicates a failure to start the program (inspect $! for the reason).
1N/ALike C<exec>, C<system> allows you to lie to a program about its name if
1N/Ayou use the C<system PROGRAM LIST> syntax. Again, see L</exec>.
1N/ASince C<SIGINT> and C<SIGQUIT> are ignored during the execution of
1N/AC<system>, if you expect your program to terminate on receipt of these
1N/Asignals you will need to arrange to do so yourself based on the return
1N/A @args = ("command", "arg1", "arg2");
1N/A or die "system @args failed: $?"
1N/AYou can check all the failure possibilities by inspecting
1N/A print "failed to execute: $!\n";
1N/A printf "child died with signal %d, %s coredump\n",
1N/A ($? & 127), ($? & 128) ? 'with' : 'without';
1N/A printf "child exited with value %d\n", $? >> 8;
1N/Aor more portably by using the W*() calls of the POSIX extension;
1N/Asee L<perlport> for more information.
1N/AWhen the arguments get executed via the system shell, results
1N/Aand return codes will be subject to its quirks and capabilities.
1N/ASee L<perlop/"`STRING`"> and L</exec> for details.
1N/A=item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
1N/A=item syswrite FILEHANDLE,SCALAR,LENGTH
1N/A=item syswrite FILEHANDLE,SCALAR
1N/AAttempts to write LENGTH bytes of data from variable SCALAR to the
1N/Aspecified FILEHANDLE, using the system call write(2). If LENGTH is
1N/Anot specified, writes whole SCALAR. It bypasses buffered IO, so
1N/Amixing this with reads (other than C<sysread())>, C<print>, C<write>,
1N/AC<seek>, C<tell>, or C<eof> may cause confusion because the perlio and
1N/Astdio layers usually buffers data. Returns the number of bytes
1N/Aactually written, or C<undef> if there was an error (in this case the
1N/Aerrno variable C<$!> is also set). If the LENGTH is greater than the
1N/Aavailable data in the SCALAR after the OFFSET, only as much data as is
1N/Aavailable will be written.
1N/AAn OFFSET may be specified to write the data from some part of the
1N/Astring other than the beginning. A negative OFFSET specifies writing
1N/Athat many characters counting backwards from the end of the string.
1N/AIn the case the SCALAR is empty you can use OFFSET but only zero offset.
1N/ANote that if the filehandle has been marked as C<:utf8>, Unicode
1N/Acharacters are written instead of bytes (the LENGTH, OFFSET, and the
1N/Areturn value of syswrite() are in UTF-8 encoded Unicode characters).
1N/AThe C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
1N/ASee L</binmode>, L</open>, and the C<open> pragma, L<open>.
1N/A=item tell FILEHANDLE
1N/AReturns the current position I<in bytes> for FILEHANDLE, or -1 on
1N/Aerror. FILEHANDLE may be an expression whose value gives the name of
1N/Athe actual filehandle. If FILEHANDLE is omitted, assumes the file
1N/ANote the I<in bytes>: even if the filehandle has been set to
1N/Aoperate on characters (for example by using the C<:utf8> open
1N/Alayer), tell() will return byte offsets, not character offsets
1N/A(because that would render seek() and tell() rather slow).
1N/AThe return value of tell() for the standard streams like the STDIN
1N/Adepends on the operating system: it may return -1 or something else.
1N/Atell() on pipes, fifos, and sockets usually returns -1.
1N/AThere is no C<systell> function. Use C<sysseek(FH, 0, 1)> for that.
1N/ADo not use tell() on a filehandle that has been opened using
1N/Asysopen(), use sysseek() for that as described above. Why? Because
1N/Asysopen() creates unbuffered, "raw", filehandles, while open() creates
1N/Abuffered filehandles. sysseek() make sense only on the first kind,
1N/Atell() only makes sense on the second kind.
1N/A=item telldir DIRHANDLE
1N/AReturns the current position of the C<readdir> routines on DIRHANDLE.
1N/AValue may be given to C<seekdir> to access a particular location in a
1N/Adirectory. Has the same caveats about possible directory compaction as
1N/Athe corresponding system library routine.
1N/A=item tie VARIABLE,CLASSNAME,LIST
1N/AThis function binds a variable to a package class that will provide the
1N/Aimplementation for the variable. VARIABLE is the name of the variable
1N/Ato be enchanted. CLASSNAME is the name of a class implementing objects
1N/Aof correct type. Any additional arguments are passed to the C<new>
1N/Amethod of the class (meaning C<TIESCALAR>, C<TIEHANDLE>, C<TIEARRAY>,
1N/Aor C<TIEHASH>). Typically these are arguments such as might be passed
1N/Ato the C<dbm_open()> function of C. The object returned by the C<new>
1N/Amethod is also returned by the C<tie> function, which would be useful
1N/Aif you want to access other methods in CLASSNAME.
1N/ANote that functions such as C<keys> and C<values> may return huge lists
1N/Awhen used on large objects, like DBM files. You may prefer to use the
1N/AC<each> function to iterate over such. Example:
1N/A # print out history file offsets
1N/A while (($key,$val) = each %HIST) {
1N/A print $key, ' = ', unpack('L',$val), "\n";
1N/AA class implementing a hash should have the following methods:
1N/A TIEHASH classname, LIST
1N/A STORE this, key, value
1N/A NEXTKEY this, lastkey
1N/AA class implementing an ordinary array should have the following methods:
1N/A TIEARRAY classname, LIST
1N/A STORE this, key, value
1N/A STORESIZE this, count
1N/A SPLICE this, offset, length, LIST
1N/AA class implementing a file handle should have the following methods:
1N/A TIEHANDLE classname, LIST
1N/A READ this, scalar, length, offset
1N/A WRITE this, scalar, length, offset
1N/A PRINTF this, format, LIST
1N/A SEEK this, position, whence
1N/A OPEN this, mode, LIST
1N/AA class implementing a scalar should have the following methods:
1N/A TIESCALAR classname, LIST
1N/ANot all methods indicated above need be implemented. See L<perltie>,
1N/AL<Tie::Hash>, L<Tie::Array>, L<Tie::Scalar>, and L<Tie::Handle>.
1N/AUnlike C<dbmopen>, the C<tie> function will not use or require a module
1N/Afor you--you need to do that explicitly yourself. See L<DB_File>
1N/Aor the F<Config> module for interesting C<tie> implementations.
1N/AFor further details see L<perltie>, L<"tied VARIABLE">.
1N/AReturns a reference to the object underlying VARIABLE (the same value
1N/Athat was originally returned by the C<tie> call that bound the variable
1N/Ato a package.) Returns the undefined value if VARIABLE isn't tied to a
1N/AReturns the number of non-leap seconds since whatever time the system
1N/Aconsiders to be the epoch (that's 00:00:00, January 1, 1904 for Mac OS,
1N/Aand 00:00:00 UTC, January 1, 1970 for most other systems).
1N/ASuitable for feeding to C<gmtime> and C<localtime>.
1N/AFor measuring time in better granularity than one second,
1N/Ayou may use either the Time::HiRes module (from CPAN, and starting from
1N/APerl 5.8 part of the standard distribution), or if you have
1N/Agettimeofday(2), you may be able to use the C<syscall> interface of Perl.
1N/ASee L<perlfaq8> for details.
1N/AReturns a four-element list giving the user and system times, in
1N/Aseconds, for this process and the children of this process.
1N/A ($user,$system,$cuser,$csystem) = times;
1N/AIn scalar context, C<times> returns C<$user>.
1N/AThe transliteration operator. Same as C<y///>. See L<perlop>.
1N/A=item truncate FILEHANDLE,LENGTH
1N/A=item truncate EXPR,LENGTH
1N/ATruncates the file opened on FILEHANDLE, or named by EXPR, to the
1N/Aspecified length. Produces a fatal error if truncate isn't implemented
1N/Aon your system. Returns true if successful, the undefined value
1N/AThe behavior is undefined if LENGTH is greater than the length of the
1N/AReturns an uppercased version of EXPR. This is the internal function
1N/Aimplementing the C<\U> escape in double-quoted strings. Respects
1N/Acurrent LC_CTYPE locale if C<use locale> in force. See L<perllocale>
1N/Aand L<perlunicode> for more details about locale and Unicode support.
1N/AIt does not attempt to do titlecase mapping on initial letters. See
1N/AIf EXPR is omitted, uses C<$_>.
1N/AReturns the value of EXPR with the first character in uppercase
1N/A(titlecase in Unicode). This is the internal function implementing
1N/Athe C<\u> escape in double-quoted strings. Respects current LC_CTYPE
1N/Alocale if C<use locale> in force. See L<perllocale> and L<perlunicode>
1N/Afor more details about locale and Unicode support.
1N/AIf EXPR is omitted, uses C<$_>.
1N/ASets the umask for the process to EXPR and returns the previous value.
1N/AIf EXPR is omitted, merely returns the current umask.
1N/AThe Unix permission C<rwxr-x---> is represented as three sets of three
1N/Abits, or three octal digits: C<0750> (the leading 0 indicates octal
1N/Aand isn't one of the digits). The C<umask> value is such a number
1N/Arepresenting disabled permissions bits. The permission (or "mode")
1N/Avalues you pass C<mkdir> or C<sysopen> are modified by your umask, so
1N/Aeven if you tell C<sysopen> to create a file with permissions C<0777>,
1N/Aif your umask is C<0022> then the file will actually be created with
1N/Apermissions C<0755>. If your C<umask> were C<0027> (group can't
1N/Awrite; others can't read, write, or execute), then passing
1N/AC<sysopen> C<0666> would create a file with mode C<0640> (C<0666 &~
1N/AHere's some advice: supply a creation mode of C<0666> for regular
1N/Afiles (in C<sysopen>) and one of C<0777> for directories (in
1N/AC<mkdir>) and executable files. This gives users the freedom of
1N/Achoice: if they want protected files, they might choose process umasks
1N/Aof C<022>, C<027>, or even the particularly antisocial mask of C<077>.
1N/APrograms should rarely if ever make policy decisions better left to
1N/Athe user. The exception to this is when writing files that should be
1N/Akept private: mail files, web browser cookies, I<.rhosts> files, and
1N/AIf umask(2) is not implemented on your system and you are trying to
1N/Arestrict access for I<yourself> (
i.e., (EXPR & 0700) > 0), produces a
1N/Afatal error at run time. If umask(2) is not implemented and you are
1N/Anot trying to restrict access for yourself, returns C<undef>.
1N/ARemember that a umask is a number, usually given in octal; it is I<not> a
1N/Astring of octal digits. See also L</oct>, if all you have is a string.
1N/AUndefines the value of EXPR, which must be an lvalue. Use only on a
1N/Ascalar value, an array (using C<@>), a hash (using C<%>), a subroutine
1N/A(using C<&>), or a typeglob (using C<*>). (Saying C<undef $hash{$key}>
1N/Awill probably not do what you expect on most predefined variables or
1N/ADBM list values, so don't do that; see L<delete>.) Always returns the
1N/Aundefined value. You can omit the EXPR, in which case nothing is
1N/Aundefined, but you still get an undefined value that you could, for
1N/Ainstance, return from a subroutine, assign to a variable or pass as a
1N/A undef $bar{'blurfl'}; # Compare to: delete $bar{'blurfl'};
1N/A undef *xyz; # destroys $xyz, @xyz, %xyz, &xyz, etc.
1N/A return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
1N/A select undef, undef, undef, 0.25;
1N/A ($a, $b, undef, $c) = &foo; # Ignore third value returned
1N/ANote that this is a unary operator, not a list operator.
1N/ADeletes a list of files. Returns the number of files successfully
1N/A $cnt = unlink 'a', 'b', 'c';
1N/ANote: C<unlink> will not delete directories unless you are superuser and
1N/Athe B<-U> flag is supplied to Perl. Even if these conditions are
1N/Amet, be warned that unlinking a directory can inflict damage on your
1N/Afilesystem. Use C<rmdir> instead.
1N/AIf LIST is omitted, uses C<$_>.
1N/A=item unpack TEMPLATE,EXPR
1N/AC<unpack> does the reverse of C<pack>: it takes a string
1N/Aand expands it out into a list of values.
1N/A(In scalar context, it returns merely the first value produced.)
1N/AThe string is broken into chunks described by the TEMPLATE. Each chunk
1N/Ais converted separately to a value. Typically, either the string is a result
1N/Aof C<pack>, or the bytes of the string represent a C structure of some
1N/AThe TEMPLATE has the same format as in the C<pack> function.
1N/AHere's a subroutine that does substring:
1N/A my($what,$where,$howmuch) = @_;
1N/A unpack("x$where a$howmuch", $what);
1N/A sub ordinal { unpack("c",$_[0]); } # same as ord()
1N/AIn addition to fields allowed in pack(), you may prefix a field with
1N/Aa %<number> to indicate that
1N/Ayou want a <number>-bit checksum of the items instead of the items
1N/Athemselves. Default is a 16-bit checksum. Checksum is calculated by
1N/Asumming numeric values of expanded values (for string fields the sum of
1N/AC<ord($char)> is taken, for bit fields the sum of zeroes and ones).
1N/AFor example, the following
1N/Acomputes the same number as the System V sum program:
1N/A unpack("%32C*",<>) % 65535;
1N/AThe following efficiently counts the number of set bits in a bit vector:
1N/A $setbits = unpack("%32b*", $selectmask);
1N/AThe C<p> and C<P> formats should be used with care. Since Perl
1N/Ahas no way of checking whether the value passed to C<unpack()>
1N/Acorresponds to a valid memory location, passing a pointer value that's
1N/Anot known to be valid is likely to have disastrous consequences.
1N/AIf there are more pack codes or if the repeat count of a field or a group
1N/Ais larger than what the remainder of the input string allows, the result
1N/Ais not well defined: in some cases, the repeat count is decreased, or
1N/AC<unpack()> will produce null strings or zeroes, or terminate with an
1N/Aerror. If the input string is longer than one described by the TEMPLATE,
1N/ASee L</pack> for more examples and notes.
1N/ABreaks the binding between a variable and a package. (See C<tie>.)
1N/AHas no effect if the variable is not tied.
1N/A=item unshift ARRAY,LIST
1N/ADoes the opposite of a C<shift>. Or the opposite of a C<push>,
1N/Adepending on how you look at it. Prepends list to the front of the
1N/Aarray, and returns the new number of elements in the array.
1N/A unshift(@ARGV, '-e') unless $ARGV[0] =~ /^-/;
1N/ANote the LIST is prepended whole, not one element at a time, so the
1N/Aprepended elements stay in the same order. Use C<reverse> to do the
1N/A=item use Module VERSION LIST
1N/A=item use Module VERSION
1N/A=item use Module LIST
1N/AImports some semantics into the current package from the named module,
1N/Agenerally by aliasing certain subroutine or variable names into your
1N/Apackage. It is exactly equivalent to
1N/A BEGIN { require Module; import Module LIST; }
1N/Aexcept that Module I<must> be a bareword.
1N/AVERSION may be either a numeric argument such as 5.006, which will be
1N/Acompared to C<$]>, or a literal of the form v5.6.1, which will be compared
1N/Ato C<$^V> (aka $PERL_VERSION. A fatal error is produced if VERSION is
1N/Agreater than the version of the current Perl interpreter; Perl will not
1N/Aattempt to parse the rest of the file. Compare with L</require>, which can
1N/Ado a similar check at run time.
1N/ASpecifying VERSION as a literal of the form v5.6.1 should generally be
1N/Aavoided, because it leads to misleading error messages under earlier
1N/Aversions of Perl which do not support this syntax. The equivalent numeric
1N/Aversion should be used instead.
1N/A use v5.6.1; # compile time version check
1N/A use 5.006_001; # ditto; preferred for backwards compatibility
1N/AThis is often useful if you need to check the current Perl version before
1N/AC<use>ing library modules that have changed in incompatible ways from
1N/Aolder versions of Perl. (We try not to do this more than we have to.)
1N/AThe C<BEGIN> forces the C<require> and C<import> to happen at compile time. The
1N/AC<require> makes sure the module is loaded into memory if it hasn't been
1N/Ayet. The C<import> is not a builtin--it's just an ordinary static method
1N/Acall into the C<Module> package to tell the module to import the list of
1N/Afeatures back into the current package. The module can implement its
1N/AC<import> method any way it likes, though most modules just choose to
1N/Aderive their C<import> method via inheritance from the C<Exporter> class that
1N/Ais defined in the C<Exporter> module. See L<Exporter>. If no C<import>
1N/Amethod can be found then the call is skipped.
1N/AIf you do not want to call the package's C<import> method (for instance,
1N/Ato stop your namespace from being altered), explicitly supply the empty list:
1N/AThat is exactly equivalent to
1N/A BEGIN { require Module }
1N/AIf the VERSION argument is present between Module and LIST, then the
1N/AC<use> will call the VERSION method in class Module with the given
1N/Aversion as an argument. The default VERSION method, inherited from
1N/Athe UNIVERSAL class, croaks if the given version is larger than the
1N/Avalue of the variable C<$Module::VERSION>.
1N/AAgain, there is a distinction between omitting LIST (C<import> called
1N/Awith no arguments) and an explicit empty LIST C<()> (C<import> not
1N/Acalled). Note that there is no comma after VERSION!
1N/ABecause this is a wide-open interface, pragmas (compiler directives)
1N/Aare also implemented this way. Currently implemented pragmas are:
1N/A use sigtrap qw(SEGV BUS);
1N/A use strict qw(subs vars refs);
1N/A use subs qw(afunc blurfl);
1N/A use warnings qw(all);
1N/A use sort qw(stable _quicksort _mergesort);
1N/ASome of these pseudo-modules import semantics into the current
1N/Ablock scope (like C<strict> or C<integer>, unlike ordinary modules,
1N/Awhich import symbols into the current package (which are effective
1N/Athrough the end of the file).
1N/AThere's a corresponding C<no> command that unimports meanings imported
1N/Aby C<use>,
i.e., it calls C<unimport Module LIST> instead of C<import>.
1N/ASee L<perlmodlib> for a list of standard modules and pragmas. See L<perlrun>
1N/Afor the C<-M> and C<-m> command-line options to perl that give C<use>
1N/Afunctionality from the command-line.
1N/AChanges the access and modification times on each file of a list of
1N/Afiles. The first two elements of the list must be the NUMERICAL access
1N/Aand modification times, in that order. Returns the number of files
1N/Asuccessfully changed. The inode change time of each file is set
1N/Ato the current time. For example, this code has the same effect as the
1N/AUnix touch(1) command when the files I<already exist>.
1N/A $atime = $mtime = time;
1N/A utime $atime, $mtime, @ARGV;
1N/ASince perl 5.7.2, if the first two elements of the list are C<undef>, then
1N/Athe utime(2) function in the C library will be called with a null second
1N/Aargument. On most systems, this will set the file's access and
1N/Amodification times to the current time (
i.e. equivalent to the example
1N/A utime undef, undef, @ARGV;
1N/AUnder NFS this will use the time of the NFS server, not the time of
1N/Athe local machine. If there is a time synchronization problem, the
1N/ANFS server and local machine will have different times. The Unix
1N/Atouch(1) command will in fact normally use this form instead of the
1N/Aone shown in the first example.
1N/ANote that only passing one of the first two elements as C<undef> will
1N/Abe equivalent of passing it as 0 and will not have the same effect as
1N/Adescribed when they are both C<undef>. This case will also trigger an
1N/Auninitialized warning.
1N/AReturns a list consisting of all the values of the named hash.
1N/A(In a scalar context, returns the number of values.)
1N/AThe values are returned in an apparently random order. The actual
1N/Arandom order is subject to change in future versions of perl, but it
1N/Ais guaranteed to be the same order as either the C<keys> or C<each>
1N/Afunction would produce on the same (unmodified) hash. Since Perl
1N/A5.8.1 the ordering is different even between different runs of Perl
1N/Afor security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
1N/AAs a side effect, calling values() resets the HASH's internal iterator,
1N/Asee L</each>. (In particular, calling values() in void context resets
1N/Athe iterator with no other overhead.)
1N/ANote that the values are not copied, which means modifying them will
1N/Amodify the contents of the hash:
1N/ASee also C<keys>, C<each>, and C<sort>.
1N/A=item vec EXPR,OFFSET,BITS
1N/ATreats the string in EXPR as a bit vector made up of elements of
1N/Awidth BITS, and returns the value of the element specified by OFFSET
1N/Aas an unsigned integer. BITS therefore specifies the number of bits
1N/Athat are reserved for each element in the bit vector. This must
1N/Abe a power of two from 1 to 32 (or 64, if your platform supports
1N/AIf BITS is 8, "elements" coincide with bytes of the input string.
1N/AIf BITS is 16 or more, bytes of the input string are grouped into chunks
1N/Aof size BITS/8, and each group is converted to a number as with
1N/Apack()/unpack() with big-endian formats C<n>/C<N> (and analogously
1N/Afor BITS==64). See L<"pack"> for details.
1N/AIf bits is 4 or less, the string is broken into bytes, then the bits
1N/Aof each byte are broken into 8/BITS groups. Bits of a byte are
1N/Anumbered in a little-endian-ish way, as in C<0x01>, C<0x02>,
1N/AC<0x04>, C<0x08>, C<0x10>, C<0x20>, C<0x40>, C<0x80>. For example,
1N/Abreaking the single input byte C<chr(0x36)> into two groups gives a list
1N/AC<(0x6, 0x3)>; breaking it into 4 groups gives C<(0x2, 0x1, 0x3, 0x0)>.
1N/AC<vec> may also be assigned to, in which case parentheses are needed
1N/Ato give the expression the correct precedence as in
1N/A vec($image, $max_x * $x + $y, 8) = 3;
1N/AIf the selected element is outside the string, the value 0 is returned.
1N/AIf an element off the end of the string is written to, Perl will first
1N/Aextend the string with sufficiently many zero bytes. It is an error
1N/Ato try to write off the beginning of the string (
i.e. negative OFFSET).
1N/AThe string should not contain any character with the value > 255 (which
1N/Acan only happen if you're using UTF-8 encoding). If it does, it will be
1N/Atreated as something which is not UTF-8 encoded. When the C<vec> was
1N/Aassigned to, other parts of your program will also no longer consider the
1N/Astring to be UTF-8 encoded. In other words, if you do have such characters
1N/Ain your string, vec() will operate on the actual byte string, and not the
1N/Aconceptual character string.
1N/AStrings created with C<vec> can also be manipulated with the logical
1N/Aoperators C<|>, C<&>, C<^>, and C<~>. These operators will assume a bit
1N/Avector operation is desired when both operands are strings.
1N/ASee L<perlop/"Bitwise String Operators">.
1N/AThe following code will build up an ASCII string saying C<'PerlPerlPerl'>.
1N/AThe comments show the string after each step. Note that this code works
1N/Ain the same way on big-endian or little-endian machines.
1N/A vec($foo, 0, 32) = 0x5065726C; # 'Perl'
1N/A # $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits
1N/A print vec($foo, 0, 8); # prints 80 == 0x50 == ord('P')
1N/A vec($foo, 2, 16) = 0x5065; # 'PerlPe'
1N/A vec($foo, 3, 16) = 0x726C; # 'PerlPerl'
1N/A vec($foo, 8, 8) = 0x50; # 'PerlPerlP'
1N/A vec($foo, 9, 8) = 0x65; # 'PerlPerlPe'
1N/A vec($foo, 20, 4) = 2; # 'PerlPerlPe' . "\x02"
1N/A vec($foo, 21, 4) = 7; # 'PerlPerlPer'
1N/A vec($foo, 45, 2) = 3; # 'PerlPerlPer' . "\x0c"
1N/A vec($foo, 93, 1) = 1; # 'PerlPerlPer' . "\x2c"
1N/A vec($foo, 94, 1) = 1; # 'PerlPerlPerl'
1N/ATo transform a bit vector into a string or list of 0's and 1's, use these:
1N/A $bits = unpack("b*", $vector);
1N/A @bits = split(//, unpack("b*", $vector));
1N/AIf you know the exact length in bits, it can be used in place of the C<*>.
1N/AHere is an example to illustrate how the bits actually fall in place:
1N/A unpack("V",$_) 01234567890123456789012345678901
1N/A ------------------------------------------------------------------
1N/A for ($shift=0; $shift < $width; ++$shift) {
1N/A for ($off=0; $off < 32/$width; ++$off) {
1N/A $str = pack("B*", "0"x32);
1N/A $bits = (1<<$shift);
1N/A vec($str, $off, $width) = $bits;
1N/A $res = unpack("b*",$str);
1N/A $val = unpack("V", $str);
1N/A vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
1N/A $off, $width, $bits, $val, $res
1N/ARegardless of the machine architecture on which it is run, the above
1N/Aexample should print the following table:
1N/A unpack("V",$_) 01234567890123456789012345678901
1N/A ------------------------------------------------------------------
1N/A vec($_, 0, 1) = 1 == 1 10000000000000000000000000000000
1N/A vec($_, 1, 1) = 1 == 2 01000000000000000000000000000000
1N/A vec($_, 2, 1) = 1 == 4 00100000000000000000000000000000
1N/A vec($_, 3, 1) = 1 == 8 00010000000000000000000000000000
1N/A vec($_, 4, 1) = 1 == 16 00001000000000000000000000000000
1N/A vec($_, 5, 1) = 1 == 32 00000100000000000000000000000000
1N/A vec($_, 6, 1) = 1 == 64 00000010000000000000000000000000
1N/A vec($_, 7, 1) = 1 == 128 00000001000000000000000000000000
1N/A vec($_, 8, 1) = 1 == 256 00000000100000000000000000000000
1N/A vec($_, 9, 1) = 1 == 512 00000000010000000000000000000000
1N/A vec($_,10, 1) = 1 == 1024 00000000001000000000000000000000
1N/A vec($_,11, 1) = 1 == 2048 00000000000100000000000000000000
1N/A vec($_,12, 1) = 1 == 4096 00000000000010000000000000000000
1N/A vec($_,13, 1) = 1 == 8192 00000000000001000000000000000000
1N/A vec($_,14, 1) = 1 == 16384 00000000000000100000000000000000
1N/A vec($_,15, 1) = 1 == 32768 00000000000000010000000000000000
1N/A vec($_,16, 1) = 1 == 65536 00000000000000001000000000000000
1N/A vec($_,17, 1) = 1 == 131072 00000000000000000100000000000000
1N/A vec($_,18, 1) = 1 == 262144 00000000000000000010000000000000
1N/A vec($_,19, 1) = 1 == 524288 00000000000000000001000000000000
1N/A vec($_,20, 1) = 1 == 1048576 00000000000000000000100000000000
1N/A vec($_,21, 1) = 1 == 2097152 00000000000000000000010000000000
1N/A vec($_,22, 1) = 1 == 4194304 00000000000000000000001000000000
1N/A vec($_,23, 1) = 1 == 8388608 00000000000000000000000100000000
1N/A vec($_,24, 1) = 1 == 16777216 00000000000000000000000010000000
1N/A vec($_,25, 1) = 1 == 33554432 00000000000000000000000001000000
1N/A vec($_,26, 1) = 1 == 67108864 00000000000000000000000000100000
1N/A vec($_,27, 1) = 1 == 134217728 00000000000000000000000000010000
1N/A vec($_,28, 1) = 1 == 268435456 00000000000000000000000000001000
1N/A vec($_,29, 1) = 1 == 536870912 00000000000000000000000000000100
1N/A vec($_,30, 1) = 1 == 1073741824 00000000000000000000000000000010
1N/A vec($_,31, 1) = 1 == 2147483648 00000000000000000000000000000001
1N/A vec($_, 0, 2) = 1 == 1 10000000000000000000000000000000
1N/A vec($_, 1, 2) = 1 == 4 00100000000000000000000000000000
1N/A vec($_, 2, 2) = 1 == 16 00001000000000000000000000000000
1N/A vec($_, 3, 2) = 1 == 64 00000010000000000000000000000000
1N/A vec($_, 4, 2) = 1 == 256 00000000100000000000000000000000
1N/A vec($_, 5, 2) = 1 == 1024 00000000001000000000000000000000
1N/A vec($_, 6, 2) = 1 == 4096 00000000000010000000000000000000
1N/A vec($_, 7, 2) = 1 == 16384 00000000000000100000000000000000
1N/A vec($_, 8, 2) = 1 == 65536 00000000000000001000000000000000
1N/A vec($_, 9, 2) = 1 == 262144 00000000000000000010000000000000
1N/A vec($_,10, 2) = 1 == 1048576 00000000000000000000100000000000
1N/A vec($_,11, 2) = 1 == 4194304 00000000000000000000001000000000
1N/A vec($_,12, 2) = 1 == 16777216 00000000000000000000000010000000
1N/A vec($_,13, 2) = 1 == 67108864 00000000000000000000000000100000
1N/A vec($_,14, 2) = 1 == 268435456 00000000000000000000000000001000
1N/A vec($_,15, 2) = 1 == 1073741824 00000000000000000000000000000010
1N/A vec($_, 0, 2) = 2 == 2 01000000000000000000000000000000
1N/A vec($_, 1, 2) = 2 == 8 00010000000000000000000000000000
1N/A vec($_, 2, 2) = 2 == 32 00000100000000000000000000000000
1N/A vec($_, 3, 2) = 2 == 128 00000001000000000000000000000000
1N/A vec($_, 4, 2) = 2 == 512 00000000010000000000000000000000
1N/A vec($_, 5, 2) = 2 == 2048 00000000000100000000000000000000
1N/A vec($_, 6, 2) = 2 == 8192 00000000000001000000000000000000
1N/A vec($_, 7, 2) = 2 == 32768 00000000000000010000000000000000
1N/A vec($_, 8, 2) = 2 == 131072 00000000000000000100000000000000
1N/A vec($_, 9, 2) = 2 == 524288 00000000000000000001000000000000
1N/A vec($_,10, 2) = 2 == 2097152 00000000000000000000010000000000
1N/A vec($_,11, 2) = 2 == 8388608 00000000000000000000000100000000
1N/A vec($_,12, 2) = 2 == 33554432 00000000000000000000000001000000
1N/A vec($_,13, 2) = 2 == 134217728 00000000000000000000000000010000
1N/A vec($_,14, 2) = 2 == 536870912 00000000000000000000000000000100
1N/A vec($_,15, 2) = 2 == 2147483648 00000000000000000000000000000001
1N/A vec($_, 0, 4) = 1 == 1 10000000000000000000000000000000
1N/A vec($_, 1, 4) = 1 == 16 00001000000000000000000000000000
1N/A vec($_, 2, 4) = 1 == 256 00000000100000000000000000000000
1N/A vec($_, 3, 4) = 1 == 4096 00000000000010000000000000000000
1N/A vec($_, 4, 4) = 1 == 65536 00000000000000001000000000000000
1N/A vec($_, 5, 4) = 1 == 1048576 00000000000000000000100000000000
1N/A vec($_, 6, 4) = 1 == 16777216 00000000000000000000000010000000
1N/A vec($_, 7, 4) = 1 == 268435456 00000000000000000000000000001000
1N/A vec($_, 0, 4) = 2 == 2 01000000000000000000000000000000
1N/A vec($_, 1, 4) = 2 == 32 00000100000000000000000000000000
1N/A vec($_, 2, 4) = 2 == 512 00000000010000000000000000000000
1N/A vec($_, 3, 4) = 2 == 8192 00000000000001000000000000000000
1N/A vec($_, 4, 4) = 2 == 131072 00000000000000000100000000000000
1N/A vec($_, 5, 4) = 2 == 2097152 00000000000000000000010000000000
1N/A vec($_, 6, 4) = 2 == 33554432 00000000000000000000000001000000
1N/A vec($_, 7, 4) = 2 == 536870912 00000000000000000000000000000100
1N/A vec($_, 0, 4) = 4 == 4 00100000000000000000000000000000
1N/A vec($_, 1, 4) = 4 == 64 00000010000000000000000000000000
1N/A vec($_, 2, 4) = 4 == 1024 00000000001000000000000000000000
1N/A vec($_, 3, 4) = 4 == 16384 00000000000000100000000000000000
1N/A vec($_, 4, 4) = 4 == 262144 00000000000000000010000000000000
1N/A vec($_, 5, 4) = 4 == 4194304 00000000000000000000001000000000
1N/A vec($_, 6, 4) = 4 == 67108864 00000000000000000000000000100000
1N/A vec($_, 7, 4) = 4 == 1073741824 00000000000000000000000000000010
1N/A vec($_, 0, 4) = 8 == 8 00010000000000000000000000000000
1N/A vec($_, 1, 4) = 8 == 128 00000001000000000000000000000000
1N/A vec($_, 2, 4) = 8 == 2048 00000000000100000000000000000000
1N/A vec($_, 3, 4) = 8 == 32768 00000000000000010000000000000000
1N/A vec($_, 4, 4) = 8 == 524288 00000000000000000001000000000000
1N/A vec($_, 5, 4) = 8 == 8388608 00000000000000000000000100000000
1N/A vec($_, 6, 4) = 8 == 134217728 00000000000000000000000000010000
1N/A vec($_, 7, 4) = 8 == 2147483648 00000000000000000000000000000001
1N/A vec($_, 0, 8) = 1 == 1 10000000000000000000000000000000
1N/A vec($_, 1, 8) = 1 == 256 00000000100000000000000000000000
1N/A vec($_, 2, 8) = 1 == 65536 00000000000000001000000000000000
1N/A vec($_, 3, 8) = 1 == 16777216 00000000000000000000000010000000
1N/A vec($_, 0, 8) = 2 == 2 01000000000000000000000000000000
1N/A vec($_, 1, 8) = 2 == 512 00000000010000000000000000000000
1N/A vec($_, 2, 8) = 2 == 131072 00000000000000000100000000000000
1N/A vec($_, 3, 8) = 2 == 33554432 00000000000000000000000001000000
1N/A vec($_, 0, 8) = 4 == 4 00100000000000000000000000000000
1N/A vec($_, 1, 8) = 4 == 1024 00000000001000000000000000000000
1N/A vec($_, 2, 8) = 4 == 262144 00000000000000000010000000000000
1N/A vec($_, 3, 8) = 4 == 67108864 00000000000000000000000000100000
1N/A vec($_, 0, 8) = 8 == 8 00010000000000000000000000000000
1N/A vec($_, 1, 8) = 8 == 2048 00000000000100000000000000000000
1N/A vec($_, 2, 8) = 8 == 524288 00000000000000000001000000000000
1N/A vec($_, 3, 8) = 8 == 134217728 00000000000000000000000000010000
1N/A vec($_, 0, 8) = 16 == 16 00001000000000000000000000000000
1N/A vec($_, 1, 8) = 16 == 4096 00000000000010000000000000000000
1N/A vec($_, 2, 8) = 16 == 1048576 00000000000000000000100000000000
1N/A vec($_, 3, 8) = 16 == 268435456 00000000000000000000000000001000
1N/A vec($_, 0, 8) = 32 == 32 00000100000000000000000000000000
1N/A vec($_, 1, 8) = 32 == 8192 00000000000001000000000000000000
1N/A vec($_, 2, 8) = 32 == 2097152 00000000000000000000010000000000
1N/A vec($_, 3, 8) = 32 == 536870912 00000000000000000000000000000100
1N/A vec($_, 0, 8) = 64 == 64 00000010000000000000000000000000
1N/A vec($_, 1, 8) = 64 == 16384 00000000000000100000000000000000
1N/A vec($_, 2, 8) = 64 == 4194304 00000000000000000000001000000000
1N/A vec($_, 3, 8) = 64 == 1073741824 00000000000000000000000000000010
1N/A vec($_, 0, 8) = 128 == 128 00000001000000000000000000000000
1N/A vec($_, 1, 8) = 128 == 32768 00000000000000010000000000000000
1N/A vec($_, 2, 8) = 128 == 8388608 00000000000000000000000100000000
1N/A vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
1N/ABehaves like the wait(2) system call on your system: it waits for a child
1N/Aprocess to terminate and returns the pid of the deceased process, or
1N/AC<-1> if there are no child processes. The status is returned in C<$?>.
1N/ANote that a return value of C<-1> could mean that child processes are
1N/Abeing automatically reaped, as described in L<perlipc>.
1N/A=item waitpid PID,FLAGS
1N/AWaits for a particular child process to terminate and returns the pid of
1N/Athe deceased process, or C<-1> if there is no such child process. On some
1N/Asystems, a value of 0 indicates that there are processes still running.
1N/AThe status is returned in C<$?>. If you say
1N/A use POSIX ":sys_wait_h";
1N/A $kid = waitpid(-1, WNOHANG);
1N/Athen you can do a non-blocking wait for all pending zombie processes.
1N/ANon-blocking wait is available on machines supporting either the
1N/Awaitpid(2) or wait4(2) system calls. However, waiting for a particular
1N/Apid with FLAGS of C<0> is implemented everywhere. (Perl emulates the
1N/Asystem call by remembering the status values of processes that have
1N/Aexited but have not been harvested by the Perl script yet.)
1N/ANote that on some systems, a return value of C<-1> could mean that child
1N/Aprocesses are being automatically reaped. See L<perlipc> for details,
1N/Aand for other examples.
1N/AReturns true if the context of the currently executing subroutine or
1N/Aeval() block is looking for a list value. Returns false if the context is
1N/Alooking for a scalar. Returns the undefined value if the context is
1N/Alooking for no value (void context).
1N/A return unless defined wantarray; # don't bother doing more
1N/A my @a = complex_calculation();
1N/A return wantarray ? @a : "@a";
1N/AThis function should have been named wantlist() instead.
1N/AProduces a message on STDERR just like C<die>, but doesn't exit or throw
1N/AIf LIST is empty and C<$@> already contains a value (typically from a
1N/Aprevious eval) that value is used after appending C<"\
t...caught">
1N/Ato C<$@>. This is useful for staying almost, but not entirely similar to
1N/AIf C<$@> is empty then the string C<"Warning: Something's wrong"> is used.
1N/ANo message is printed if there is a C<$SIG{__WARN__}> handler
1N/Ainstalled. It is the handler's responsibility to deal with the message
1N/Aas it sees fit (like, for instance, converting it into a C<die>). Most
1N/Ahandlers must therefore make arrangements to actually display the
1N/Awarnings that they are not prepared to deal with, by calling C<warn>
1N/Aagain in the handler. Note that this is quite safe and will not
1N/Aproduce an endless loop, since C<__WARN__> hooks are not called from
1N/AYou will find this behavior is slightly different from that of
1N/AC<$SIG{__DIE__}> handlers (which don't suppress the error text, but can
1N/Ainstead call C<die> again to change it).
1N/AUsing a C<__WARN__> handler provides a powerful way to silence all
1N/Awarnings (even the so-called mandatory ones). An example:
1N/A # wipe out *all* compile-time warnings
1N/A BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
1N/A my $foo = 20; # no warning about duplicate my $foo,
1N/A # but hey, you asked for it!
1N/A # no compile-time or run-time warnings before here
1N/A # run-time warnings enabled after here
1N/A warn "\$foo is alive and $foo!"; # does show up
1N/ASee L<perlvar> for details on setting C<%SIG> entries, and for more
1N/Aexamples. See the Carp module for other kinds of warnings using its
1N/Acarp() and cluck() functions.
1N/A=item write FILEHANDLE
1N/AWrites a formatted record (possibly multi-line) to the specified FILEHANDLE,
1N/Ausing the format associated with that file. By default the format for
1N/Aa file is the one having the same name as the filehandle, but the
1N/Aformat for the current output channel (see the C<select> function) may be set
1N/Aexplicitly by assigning the name of the format to the C<$~> variable.
1N/ATop of form processing is handled automatically: if there is
1N/Ainsufficient room on the current page for the formatted record, the
1N/Apage is advanced by writing a form feed, a special top-of-page format
1N/Ais used to format the new page header, and then the record is written.
1N/ABy default the top-of-page format is the name of the filehandle with
1N/A"_TOP" appended, but it may be dynamically set to the format of your
1N/Achoice by assigning the name to the C<$^> variable while the filehandle is
1N/Aselected. The number of lines remaining on the current page is in
1N/Avariable C<$->, which can be set to C<0> to force a new page.
1N/AIf FILEHANDLE is unspecified, output goes to the current default output
1N/Achannel, which starts out as STDOUT but may be changed by the
1N/AC<select> operator. If the FILEHANDLE is an EXPR, then the expression
1N/Ais evaluated and the resulting string is used to look up the name of
1N/Athe FILEHANDLE at run time. For more on formats, see L<perlform>.
1N/ANote that write is I<not> the opposite of C<read>. Unfortunately.
1N/AThe transliteration operator. Same as C<tr///>. See L<perlop>.