table of contents
other versions
- wheezy 5.14.2-21+deb7u3
- jessie 5.20.2-3+deb8u6
- testing 5.24.1-3
- unstable 5.24.1-3
- experimental 5.26.0-1
PERLFUNC(1) | Perl Programmers Reference Guide | PERLFUNC(1) |
NAME¶
perlfunc - Perl builtin functionsDESCRIPTION¶
The functions in this section can serve as terms in an expression. They fall into two major categories: list operators and named unary operators. These differ in their precedence relationship with a following comma. (See the precedence table in perlop.) List operators take more than one argument, while unary operators can never take more than one argument. Thus, a comma terminates the argument of a unary operator, but merely separates the arguments of a list operator. A unary operator generally provides scalar context to its argument, while a list operator may provide either scalar or list contexts for its arguments. If it does both, scalar arguments come first and list argument follow, and there can only ever be one such list argument. For instance, splice() has three scalar arguments followed by a list, whereas gethostbyname() has four scalar arguments. In the syntax descriptions that follow, list operators that expect a list (and provide list context for elements of the list) are shown with LIST as an argument. Such a list may consist of any combination of scalar arguments or list values; the list values will be included in the list as if each individual element were interpolated at that point in the list, forming a longer single-dimensional list value. Commas should separate literal elements of the LIST. Any function in the list below may be used either with or without parentheses around its arguments. (The syntax descriptions omit the parentheses.) If you use parentheses, the simple but occasionally surprising rule is this: It looks like a function, therefore it is a function, and precedence doesn't matter. Otherwise it's a list operator or unary operator, and precedence does matter. Whitespace between the function and left parenthesis doesn't count, so sometimes you need to be careful:print 1+2+4; # Prints 7. print(1+2) + 4; # Prints 3. print (1+2)+4; # Also prints 3! print +(1+2)+4; # Prints 7. print ((1+2)+4); # Prints 7.If you run Perl with the -w switch it can warn you about this. For example, the third line above produces:
print (...) interpreted as function at - line 1. Useless use of integer addition in void context at - line 1.A few functions take no arguments at all, and therefore work as neither unary nor list operators. These include such functions as "time" and "endpwent". For example, "time+86_400" always means "time() + 86_400". For functions that can be used in either a scalar or list context, nonabortive failure is generally indicated in scalar context by returning the undefined value, and in list context by returning the empty list. Remember the following important rule: There is no rule that relates the behavior of an expression in list context to its behavior in scalar context, or vice versa. It might do two totally different things. Each operator and function decides which sort of value would be most appropriate to return in scalar context. Some operators return the length of the list that would have been returned in list context. Some operators return the first value in the list. Some operators return the last value in the list. Some operators return a count of successful operations. In general, they do what you want, unless you want consistency. A named array in scalar context is quite different from what would at first glance appear to be a list in scalar context. You can't get a list like "(1,2,3)" into being in scalar context, because the compiler knows the context at compile time. It would generate the scalar comma operator there, not the list construction version of the comma. That means it was never a list to start with. In general, functions in Perl that serve as wrappers for system calls ("syscalls") of the same name (like chown(2), fork(2), closedir(2), etc.) return true when they succeed and "undef" otherwise, as is usually mentioned in the descriptions below. This is different from the C interfaces, which return "-1" on failure. Exceptions to this rule include "wait", "waitpid", and "syscall". System calls also set the special $! variable on failure. Other functions do not, except accidentally. Extension modules can also hook into the Perl parser to define new kinds of keyword-headed expression. These may look like functions, but may also look completely different. The syntax following the keyword is defined entirely by the extension. If you are an implementor, see "PL_keyword_plugin" in perlapi for the mechanism. If you are using such a module, see the module's documentation for details of the syntax that it defines.
Perl Functions by Category¶
Here are Perl's functions (including things that look like functions, like some keywords and named operators) arranged by category. Some functions appear in more than one place.- Functions for SCALARs or strings
- "chomp", "chop", "chr", "crypt", "hex", "index", "lc", "lcfirst", "length", "oct", "ord", "pack", "q//", "qq//", "reverse", "rindex", "sprintf", "substr", "tr///", "uc", "ucfirst", "y///"
- Regular expressions and pattern matching
- "m//", "pos", "quotemeta", "s///", "split", "study", "qr//"
- Numeric functions
- "abs", "atan2", "cos", "exp", "hex", "int", "log", "oct", "rand", "sin", "sqrt", "srand"
- Functions for real @ARRAYs
- "each", "keys", "pop", "push", "shift", "splice", "unshift", "values"
- Functions for list data
- "grep", "join", "map", "qw//", "reverse", "sort", "unpack"
- Functions for real %HASHes
- "delete", "each", "exists", "keys", "values"
- Input and output functions
- "binmode", "close", "closedir", "dbmclose", "dbmopen", "die", "eof", "fileno", "flock", "format", "getc", "print", "printf", "read", "readdir", "rewinddir", "say", "seek", "seekdir", "select", "syscall", "sysread", "sysseek", "syswrite", "tell", "telldir", "truncate", "warn", "write"
- Functions for fixed-length data or records
- "pack", "read", "syscall", "sysread", "syswrite", "unpack", "vec"
- Functions for filehandles, files, or directories
- "-X", "chdir", "chmod", "chown", "chroot", "fcntl", "glob", "ioctl", "link", "lstat", "mkdir", "open", "opendir", "readlink", "rename", "rmdir", "stat", "symlink", "sysopen", "umask", "unlink", "utime"
- Keywords related to the control flow of your Perl program
- "caller", "continue", "die", "do", "dump", "eval", "exit", "goto", "last", "next", "redo", "return", "sub", "wantarray"
- Keywords related to the switch feature
- "break", "continue", "default,
""given", "when"
- Keywords related to scoping
- "caller", "import", "local",
"my", "our", "package", "state",
"use"
- Miscellaneous functions
- "defined", "dump", "eval", "formline", "local", "my", "our", "reset", "scalar", "state", "undef", "wantarray"
- Functions for processes and process groups
- "alarm", "exec", "fork", "getpgrp", "getppid", "getpriority", "kill", "pipe", "qx//", "setpgrp", "setpriority", "sleep", "system", "times", "wait", "waitpid"
- Keywords related to Perl modules
- "do", "import", "no", "package", "require", "use"
- Keywords related to classes and object-orientation
- "bless", "dbmclose", "dbmopen", "package", "ref", "tie", "tied", "untie", "use"
- Low-level socket functions
- "accept", "bind", "connect", "getpeername", "getsockname", "getsockopt", "listen", "recv", "send", "setsockopt", "shutdown", "socket", "socketpair"
- System V interprocess communication functions
- "msgctl", "msgget", "msgrcv", "msgsnd", "semctl", "semget", "semop", "shmctl", "shmget", "shmread", "shmwrite"
- Fetching user and group info
- "endgrent", "endhostent", "endnetent", "endpwent", "getgrent", "getgrgid", "getgrnam", "getlogin", "getpwent", "getpwnam", "getpwuid", "setgrent", "setpwent"
- Fetching network info
- "endprotoent", "endservent", "gethostbyaddr", "gethostbyname", "gethostent", "getnetbyaddr", "getnetbyname", "getnetent", "getprotobyname", "getprotobynumber", "getprotoent", "getservbyname", "getservbyport", "getservent", "sethostent", "setnetent", "setprotoent", "setservent"
- Time-related functions
- "gmtime", "localtime", "time", "times"
- Functions new in perl5
- "abs", "bless", "break",
"chomp", "chr", "continue",
"default", "exists", "formline",
"given", "glob", "import", "lc",
"lcfirst", "lock", "map", "my",
"no", "our", "prototype", "qr//",
"qw//", "qx//", "readline",
"readpipe", "ref", "sub"*,
"sysopen", "tie", "tied", "uc",
"ucfirst", "untie", "use", "when"
- Functions obsoleted in perl5
- "dbmclose", "dbmopen"
Portability¶
Perl was born in Unix and can therefore access all common Unix system calls. In non-Unix environments, the functionality of some Unix system calls may not be available or details of the available functionality may differ slightly. The Perl functions affected by this are: "-X", "binmode", "chmod", "chown", "chroot", "crypt", "dbmclose", "dbmopen", "dump", "endgrent", "endhostent", "endnetent", "endprotoent", "endpwent", "endservent", "exec", "fcntl", "flock", "fork", "getgrent", "getgrgid", "gethostbyname", "gethostent", "getlogin", "getnetbyaddr", "getnetbyname", "getnetent", "getppid", "getpgrp", "getpriority", "getprotobynumber", "getprotoent", "getpwent", "getpwnam", "getpwuid", "getservbyport", "getservent", "getsockopt", "glob", "ioctl", "kill", "link", "lstat", "msgctl", "msgget", "msgrcv", "msgsnd", "open", "pipe", "readlink", "rename", "select", "semctl", "semget", "semop", "setgrent", "sethostent", "setnetent", "setpgrp", "setpriority", "setprotoent", "setpwent", "setservent", "setsockopt", "shmctl", "shmget", "shmread", "shmwrite", "socket", "socketpair", "stat", "symlink", "syscall", "sysopen", "system", "times", "truncate", "umask", "unlink", "utime", "wait", "waitpid" For more information about the portability of these functions, see perlport and other available platform-specific documentation.Alphabetical Listing of Perl Functions¶
- -X FILEHANDLE
- -X EXPR
- -X DIRHANDLE
- -X
- A file test, where X is one of the letters listed below.
This unary operator takes one argument, either a filename, a filehandle,
or a dirhandle, and tests the associated file to see if something is true
about it. If the argument is omitted, tests $_, except for "-t",
which tests STDIN. Unless otherwise documented, it returns 1 for true and
'' for false, or the undefined value if the file doesn't exist. Despite
the funny names, precedence is the same as any other named unary operator.
The operator may be any of:
-r File is readable by effective uid/gid. -w File is writable by effective uid/gid. -x File is executable by effective uid/gid. -o File is owned by effective uid. -R File is readable by real uid/gid. -W File is writable by real uid/gid. -X File is executable by real uid/gid. -O File is owned by real uid. -e File exists. -z File has zero size (is empty). -s File has nonzero size (returns size in bytes). -f File is a plain file. -d File is a directory. -l File is a symbolic link. -p File is a named pipe (FIFO), or Filehandle is a pipe. -S File is a socket. -b File is a block special file. -c File is a character special file. -t Filehandle is opened to a tty. -u File has setuid bit set. -g File has setgid bit set. -k File has sticky bit set. -T File is an ASCII text file (heuristic guess). -B File is a "binary" file (opposite of -T). -M Script start time minus file modification time, in days. -A Same for access time. -C Same for inode change time (Unix, may differ for other platforms)
while (<>) { chomp; next unless -f $_; # ignore specials #... }
-s($file) + 1024 # probably wrong; same as -s($file + 1024) (-s $file) + 1024 # correct
print "Can do.\n" if -r $a || -w _ || -x _; stat($filename); print "Readable\n" if -r _; print "Writable\n" if -w _; print "Executable\n" if -x _; print "Setuid\n" if -u _; print "Setgid\n" if -g _; print "Sticky\n" if -k _; print "Text\n" if -T _; print "Binary\n" if -B _;
- abs VALUE
- abs
- Returns the absolute value of its argument. If VALUE is omitted, uses $_.
- accept NEWSOCKET,GENERICSOCKET
- Accepts an incoming socket connect, just as
accept(2) does. Returns the packed address if it succeeded, false
otherwise. See the example in "Sockets: Client/Server
Communication" in perlipc.
- alarm SECONDS
- alarm
- Arranges to have a SIGALRM delivered to this process after
the specified number of wallclock seconds has elapsed. If SECONDS is not
specified, the value stored in $_ is used. (On some machines,
unfortunately, the elapsed time may be up to one second less or more than
you specified because of how seconds are counted, and process scheduling
may delay the delivery of the signal even further.)
eval { local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required alarm $timeout; $nread = sysread SOCKET, $buffer, $size; alarm 0; }; if ($@) { die unless $@ eq "alarm\n"; # propagate unexpected errors # timed out } else { # didn't }
- atan2 Y,X
- Returns the arctangent of Y/X in the range -PI to PI.
sub tan { sin($_[0]) / cos($_[0]) }
- bind SOCKET,NAME
- Binds a network address to a socket, just as bind(2) does. Returns true if it succeeded, false otherwise. NAME should be a packed address of the appropriate type for the socket. See the examples in "Sockets: Client/Server Communication" in perlipc.
- binmode FILEHANDLE, LAYER
- binmode FILEHANDLE
- Arranges for FILEHANDLE to be read or written in
"binary" or "text" mode on systems where the run-time
libraries distinguish between binary and text files. If FILEHANDLE is an
expression, the value is taken as the name of the filehandle. Returns true
on success, otherwise it returns "undef" and sets $! (errno).
- bless REF,CLASSNAME
- bless REF
- This function tells the thingy referenced by REF that it is
now an object in the CLASSNAME package. If CLASSNAME is omitted, the
current package is used. Because a "bless" is often the last
thing in a constructor, it returns the reference for convenience. Always
use the two-argument version if a derived class might inherit the function
doing the blessing. See perltoot and perlobj for more about the blessing
(and blessings) of objects.
- break
- Break out of a "given()" block.
- caller EXPR
- caller
- Returns the context of the current subroutine call. In
scalar context, returns the caller's package name if there is a
caller (that is, if we're in a subroutine or "eval" or
"require") and the undefined value otherwise. In list context,
returns
# 0 1 2 ($package, $filename, $line) = caller;
# 0 1 2 3 4 ($package, $filename, $line, $subroutine, $hasargs, # 5 6 7 8 9 10 $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash) = caller($i);
- chdir EXPR
- chdir FILEHANDLE
- chdir DIRHANDLE
- chdir
- Changes the working directory to EXPR, if possible. If EXPR
is omitted, changes to the directory specified by $ENV{HOME}, if set; if
not, changes to the directory specified by $ENV{LOGDIR}. (Under VMS, the
variable $ENV{SYS$LOGIN} is also checked, and used if it is set.) If
neither is set, "chdir" does nothing. It returns true on
success, false otherwise. See the example under "die".
- chmod LIST
- Changes the permissions of a list of files. The first
element of the list must be the numeric mode, which should probably be an
octal number, and which definitely should not be a string of octal
digits: 0644 is okay, but "0644" is not. Returns the number of
files successfully changed. See also "oct" if all you have is a
string.
$cnt = chmod 0755, "foo", "bar"; chmod 0755, @executables; $mode = "0644"; chmod $mode, "foo"; # !!! sets mode to # --w----r-T $mode = "0644"; chmod oct($mode), "foo"; # this is better $mode = 0644; chmod $mode, "foo"; # this is best
open(my $fh, "<", "foo"); my $perm = (stat $fh)[2] & 07777; chmod($perm | 0600, $fh);
use Fcntl qw( :mode ); chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables; # Identical to the chmod 0755 of the example above.
- chomp VARIABLE
- chomp( LIST )
- chomp
- This safer version of "chop" removes any trailing
string that corresponds to the current value of $/ (also known as
$INPUT_RECORD_SEPARATOR in the "English" module). It returns the
total number of characters removed from all its arguments. It's often used
to remove the newline from the end of an input record when you're worried
that the final record may be missing its newline. When in paragraph mode
("$/ = """), it removes all trailing newlines from the
string. When in slurp mode ("$/ = undef") or fixed-length record
mode ($/ is a reference to an integer or the like; see perlvar)
chomp() won't remove anything. If VARIABLE is omitted, it chomps
$_. Example:
while (<>) { chomp; # avoid \n on last field @array = split(/:/); # ... }
chomp($cwd = `pwd`); chomp($answer = <STDIN>);
- chop VARIABLE
- chop( LIST )
- chop
- Chops off the last character of a string and returns the
character chopped. It is much more efficient than "s/.$//s"
because it neither scans nor copies the string. If VARIABLE is omitted,
chops $_. If VARIABLE is a hash, it chops the hash's values, but not its
keys.
- chown LIST
- Changes the owner (and group) of a list of files. The first
two elements of the list must be the numeric uid and gid, in that
order. A value of -1 in either position is interpreted by most systems to
leave that value unchanged. Returns the number of files successfully
changed.
$cnt = chown $uid, $gid, 'foo', 'bar'; chown $uid, $gid, @filenames;
print "User: "; chomp($user = <STDIN>); print "Files: "; chomp($pattern = <STDIN>); ($login,$pass,$uid,$gid) = getpwnam($user) or die "$user not in passwd file"; @ary = glob($pattern); # expand filenames chown $uid, $gid, @ary;
use POSIX qw(sysconf _PC_CHOWN_RESTRICTED); $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
- chr NUMBER
- chr
- Returns the character represented by that NUMBER in the
character set. For example, "chr(65)" is "A" in either
ASCII or Unicode, and chr(0x263a) is a Unicode smiley face.
- chroot FILENAME
- chroot
- This function works like the system call by the same name: it makes the named directory the new root directory for all further pathnames that begin with a "/" by your process and all its children. (It doesn't change your current working directory, which is unaffected.) For security reasons, this call is restricted to the superuser. If FILENAME is omitted, does a "chroot" to $_.
- close FILEHANDLE
- close
- Closes the file or pipe associated with the filehandle,
flushes the IO buffers, and closes the system file descriptor. Returns
true if those operations succeed and if no error was reported by any
PerlIO layer. Closes the currently selected filehandle if the argument is
omitted.
open(OUTPUT, '|sort >foo') # pipe to sort or die "Can't start sort: $!"; #... # print stuff to output close OUTPUT # wait for sort to finish or warn $! ? "Error closing sort pipe: $!" : "Exit status $? from sort"; open(INPUT, 'foo') # get sort's results or die "Can't open 'foo' for input: $!";
- closedir DIRHANDLE
- Closes a directory opened by "opendir" and returns the success of that system call.
- connect SOCKET,NAME
- Attempts to connect to a remote socket, just like connect(2). Returns true if it succeeded, false otherwise. NAME should be a packed address of the appropriate type for the socket. See the examples in "Sockets: Client/Server Communication" in perlipc.
- continue BLOCK
- continue
- "continue" is actually a flow control statement
rather than a function. If there is a "continue" BLOCK attached
to a BLOCK (typically in a "while" or "foreach"), it
is always executed just before the conditional is about to be evaluated
again, just like the third part of a "for" loop in C. Thus it
can be used to increment a loop variable, even when the loop has been
continued via the "next" statement (which is similar to the C
"continue" statement).
while (EXPR) { ### redo always comes here do_something; } continue { ### next always comes here do_something_else; # then back the top to re-check EXPR } ### last always comes here
- cos EXPR
- cos
- Returns the cosine of EXPR (expressed in radians). If EXPR
is omitted, takes the cosine of $_.
sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
- crypt PLAINTEXT,SALT
- Creates a digest string exactly like the crypt(3)
function in the C library (assuming that you actually have a version there
that has not been extirpated as a potential munition).
$pwd = (getpwuid($<))[1]; system "stty -echo"; print "Password: "; chomp($word = <STDIN>); print "\n"; system "stty echo"; if (crypt($word, $pwd) ne $pwd) { die "Sorry...\n"; } else { print "ok\n"; }
- dbmclose HASH
- [This function has been largely superseded by the
"untie" function.]
- dbmopen HASH,DBNAME,MASK
- [This function has been largely superseded by the
"tie" function.]
# print out history file offsets dbmopen(%HIST,'/usr/lib/news/history',0666); while (($key,$val) = each %HIST) { print $key, ' = ', unpack('L',$val), "\n"; } dbmclose(%HIST);
use DB_File; dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db") or die "Can't open netscape history file: $!";
- default BLOCK
- Within a "foreach" or a "given", a "default" BLOCK acts like a "when" that's always true. Only available after Perl 5.10, and only if the "switch" feature has been requested. See "when".
- defined EXPR
- defined
- Returns a Boolean value telling whether EXPR has a value
other than the undefined value "undef". If EXPR is not present,
$_ is checked.
if (@an_array) { print "has array elements\n" } if (%a_hash) { print "has hash members\n" }
print if defined $switch{D}; print "$val\n" while defined($val = pop(@ary)); die "Can't readlink $sym: $!" unless defined($value = readlink $sym); sub foo { defined &$bar ? &$bar(@_) : die "No bar"; } $debugging = 0 unless defined $debugging;
"ab" =~ /a(.*)b/;
- delete EXPR
- Given an expression that specifies an element or slice of a
hash, "delete" deletes the specified elements from that hash so
that exists() on that element no longer returns true. Setting a
hash element to the undefined value does not remove its key, but deleting
it does; see "exists".
%hash = (foo => 11, bar => 22, baz => 33); $scalar = delete $hash{foo}; # $scalar is 11 $scalar = delete @hash{qw(foo bar)}; # $scalar is 22 @array = delete @hash{qw(foo bar baz)}; # @array is (undef,undef,33)
foreach $key (keys %HASH) { delete $HASH{$key}; } foreach $index (0 .. $#ARRAY) { delete $ARRAY[$index]; }
delete @HASH{keys %HASH}; delete @ARRAY[0 .. $#ARRAY];
%HASH = (); # completely empty %HASH undef %HASH; # forget %HASH ever existed @ARRAY = (); # completely empty @ARRAY undef @ARRAY; # forget @ARRAY ever existed
delete $ref->[$x][$y]{$key}; delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys}; delete $ref->[$x][$y][$index]; delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
- die LIST
- "die" raises an exception. Inside an
"eval" the error message is stuffed into $@ and the
"eval" is terminated with the undefined value. If the exception
is outside of all enclosing "eval"s, then the uncaught exception
prints LIST to "STDERR" and exits with a non-zero value. If you
need to exit the process with a specific exit code, see "exit".
die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news'; chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
die "/etc/games is no good"; die "/etc/games is no good, stopped";
/etc/games is no good at canasta line 123. /etc/games is no good, stopped at canasta line 123.
eval { ... }; die unless $@ =~ /Expected exception/;
exit $! if $!; # errno exit $? >> 8 if $? >> 8; # child exit status exit 255; # last resort
use Scalar::Util "blessed"; eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) }; if (my $ev_err = $@) { if (blessed($ev_err) && $ev_err->isa("Some::Module::Exception")) { # handle Some::Module::Exception } else { # handle all other possible exceptions } }
die @_ if $^S;
- do BLOCK
- Not really a function. Returns the value of the last
command in the sequence of commands indicated by BLOCK. When modified by
the "while" or "until" loop modifier, executes the
BLOCK once before testing the loop condition. (On other statements the
loop modifiers test the conditional first.)
- do SUBROUTINE(LIST)
- This form of subroutine call is deprecated. SUBROUTINE can be a bareword, a scalar variable or a subroutine beginning with "&".
- do EXPR
- Uses the value of EXPR as a filename and executes the
contents of the file as a Perl script.
do 'stat.pl';
eval `cat stat.pl`;
# read in config files: system first, then user for $file ("/share/prog/defaults.rc", "$ENV{HOME}/.someprogrc") { unless ($return = do $file) { warn "couldn't parse $file: $@" if $@; warn "couldn't do $file: $!" unless defined $return; warn "couldn't run $file" unless $return; } }
- dump LABEL
- dump
- This function causes an immediate core dump. See also the
-u command-line switch in perlrun, which does the same thing.
Primarily this is so that you can use the undump program (not
supplied) to turn your core dump into an executable binary after having
initialized all your variables at the beginning of the program. When the
new binary is executed it will begin by executing a "goto LABEL"
(with all the restrictions that "goto" suffers). Think of it as
a goto with an intervening core dump and reincarnation. If
"LABEL" is omitted, restarts the program from the top.
- each HASH
- each ARRAY
- each EXPR
- When called in list context, returns a 2-element list
consisting of the key and value for the next element of a hash, or the
index and value for the next element of an array, so that you can iterate
over it. When called in scalar context, returns only the key (not the
value) in a hash, or the index in an array.
while (($key, $value) = each %hash) { print $key, "\n"; delete $hash{$key}; # This is safe }
while (($key,$value) = each %ENV) { print "$key=$value\n"; }
while (($key,$value) = each $hashref) { ... }
- eof FILEHANDLE
- eof ()
- eof
- Returns 1 if the next read on FILEHANDLE will return end of
file or if FILEHANDLE is not open. FILEHANDLE may be an expression
whose value gives the real filehandle. (Note that this function actually
reads a character and then "ungetc"s it, so isn't useful in an
interactive context.) Do not read from a terminal file (or call
"eof(FILEHANDLE)" on it) after end-of-file is reached. File
types such as terminals may lose the end-of-file condition if you do.
# reset line numbering on each input file while (<>) { next if /^\s*#/; # skip comments print "$.\t$_"; } continue { close ARGV if eof; # Not eof()! } # insert dashes just before last line of last file while (<>) { if (eof()) { # check for end of last file print "--------------\n"; } print; last if eof(); # needed if we're reading from a terminal }
- eval EXPR
- eval BLOCK
- eval
- In the first form, the return value of EXPR is parsed and
executed as if it were a little Perl program. The value of the expression
(which is itself determined within scalar context) is first parsed, and if
there were no errors, executed in the lexical context of the current Perl
program, so that any variable settings or subroutine and format
definitions remain afterwards. Note that the value is parsed every time
the "eval" executes. If EXPR is omitted, evaluates $_. This form
is typically used to delay parsing and subsequent execution of the text of
EXPR until run time.
# make divide-by-zero nonfatal eval { $answer = $a / $b; }; warn $@ if $@; # same thing, but less efficient eval '$answer = $a / $b'; warn $@ if $@; # a compile-time error eval { $answer = }; # WRONG # a run-time error eval '$answer ='; # sets $@
# a private exception trap for divide-by-zero eval { local $SIG{'__DIE__'}; $answer = $a / $b; }; warn $@ if $@;
# __DIE__ hooks may modify error messages { local $SIG{'__DIE__'} = sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x }; eval { die "foo lives here" }; print $@ if $@; # prints "bar lives here" }
eval $x; # CASE 1 eval "$x"; # CASE 2 eval '$x'; # CASE 3 eval { $x }; # CASE 4 eval "\$$x++"; # CASE 5 $$x++; # CASE 6
# alter $@ on nefarious repugnancy only { my $e; { local $@; # protect existing $@ eval { test_repugnancy() }; # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only $@ =~ /nefarious/ and $e = $@; } die $e if defined $e }
- exec LIST
- exec PROGRAM LIST
- The "exec" function executes a system command
and never returns; use "system" instead of
"exec" if you want it to return. It fails and returns false only
if the command does not exist and it is executed directly instead
of via your system's command shell (see below).
exec ('foo') or print STDERR "couldn't exec foo: $!"; { exec ('foo') }; print STDERR "couldn't exec foo: $!";
exec '/bin/echo', 'Your arguments are: ', @ARGV; exec "sort $outfile | uniq";
$shell = '/bin/csh'; exec $shell '-sh'; # pretend it's a login shell
exec {'/bin/csh'} '-sh'; # pretend it's a login shell
@args = ( "echo surprise" ); exec @args; # subject to shell escapes # if @args == 1 exec { $args[0] } @args; # safe even with one-arg list
- exists EXPR
- Given an expression that specifies an element of a hash,
returns true if the specified element in the hash has ever been
initialized, even if the corresponding value is undefined.
print "Exists\n" if exists $hash{$key}; print "Defined\n" if defined $hash{$key}; print "True\n" if $hash{$key};
print "Exists\n" if exists $array[$index]; print "Defined\n" if defined $array[$index]; print "True\n" if $array[$index];
print "Exists\n" if exists &subroutine; print "Defined\n" if defined &subroutine;
if (exists $ref->{A}->{B}->{$key}) { } if (exists $hash{A}{B}{$key}) { } if (exists $ref->{A}->{B}->[$ix]) { } if (exists $hash{A}{B}[$ix]) { } if (exists &{$ref->{A}{B}{$key}}) { }
undef $ref; if (exists $ref->{"Some key"}) { } print $ref; # prints HASH(0x80d3d5c)
exists ⊂ # OK exists &sub(); # Error
- exit EXPR
- exit
- Evaluates EXPR and exits immediately with that value.
Example:
$ans = <STDIN>; exit 0 if $ans =~ /^[Xx]/;
- exp EXPR
- exp
- Returns e (the natural logarithm base) to the power of EXPR. If EXPR is omitted, gives "exp($_)".
- fcntl FILEHANDLE,FUNCTION,SCALAR
- Implements the fcntl(2) function. You'll probably
have to say
use Fcntl;
use Fcntl; fcntl($filehandle, F_GETFL, $packed_return_buffer) or die "can't fcntl F_GETFL: $!";
use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK); $flags = fcntl(REMOTE, F_GETFL, 0) or die "Can't get flags for the socket: $!\n"; $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK) or die "Can't set flags for the socket: $!\n";
- fileno FILEHANDLE
- Returns the file descriptor for a filehandle, or undefined
if the filehandle is not open. If there is no real file descriptor at the
OS level, as can happen with filehandles connected to memory objects via
"open" with a reference for the third argument, -1 is returned.
if (fileno(THIS) == fileno(THAT)) { print "THIS and THAT are dups\n"; }
- flock FILEHANDLE,OPERATION
- Calls flock(2), or an emulation of it, on
FILEHANDLE. Returns true for success, false on failure. Produces a fatal
error if used on a machine that doesn't implement flock(2),
fcntl(2) locking, or lockf(3). "flock" is Perl's
portable file-locking interface, although it locks entire files only, not
records.
use Fcntl qw(:flock SEEK_END); # import LOCK_* and SEEK_END constants sub lock { my ($fh) = @_; flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n"; # and, in case someone appended while we were waiting... seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n"; } sub unlock { my ($fh) = @_; flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n"; } open(my $mbox, ">>", "/usr/spool/mail/$ENV{'USER'}") or die "Can't open mailbox: $!"; lock($mbox); print $mbox $msg,"\n\n"; unlock($mbox);
- fork
- Does a fork(2) system call to create a new process
running the same program at the same point. It returns the child pid to
the parent process, 0 to the child process, or "undef" if the
fork is unsuccessful. File descriptors (and sometimes locks on those
descriptors) are shared, while everything else is copied. On most systems
supporting fork(), great care has gone into making it extremely
efficient (for example, using copy-on-write technology on data pages),
making it the dominant paradigm for multitasking over the last few
decades.
- format
- Declare a picture format for use by the "write"
function. For example:
format Something = Test: @<<<<<<<< @||||| @>>>>> $str, $%, '$' . int($num) . $str = "widget"; $num = $cost/$quantity; $~ = 'Something'; write;
- formline PICTURE,LIST
- This is an internal function used by "format"s,
though you may call it, too. It formats (see perlform) a list of values
according to the contents of PICTURE, placing the output into the format
output accumulator, $^A (or $ACCUMULATOR in English). Eventually, when a
"write" is done, the contents of $^A are written to some
filehandle. You could also read $^A and then set $^A back to "".
Note that a format typically does one "formline" per line of
form, but the "formline" function itself doesn't care how many
newlines are embedded in the PICTURE. This means that the "~"
and "~~" tokens treat the entire PICTURE as a single line. You
may therefore need to use multiple formlines to implement a single record
format, just like the "format" compiler.
- getc FILEHANDLE
- getc
- Returns the next character from the input file attached to
FILEHANDLE, or the undefined value at end of file or if there was an error
(in the latter case $! is set). If FILEHANDLE is omitted, reads from
STDIN. This is not particularly efficient. However, it cannot be used by
itself to fetch single characters without waiting for the user to hit
enter. For that, try something more like:
if ($BSD_STYLE) { system "stty cbreak </dev/tty >/dev/tty 2>&1"; } else { system "stty", '-icanon', 'eol', "\001"; } $key = getc(STDIN); if ($BSD_STYLE) { system "stty -cbreak </dev/tty >/dev/tty 2>&1"; } else { system 'stty', 'icanon', 'eol', '^@'; # ASCII NUL } print "\n";
- getlogin
- This implements the C library function of the same name,
which on most systems returns the current login from /etc/utmp, if
any. If it returns the empty string, use "getpwuid".
$login = getlogin || getpwuid($<) || "Kilroy";
- getpeername SOCKET
- Returns the packed sockaddr address of the other end of the
SOCKET connection.
use Socket; $hersockaddr = getpeername(SOCK); ($port, $iaddr) = sockaddr_in($hersockaddr); $herhostname = gethostbyaddr($iaddr, AF_INET); $herstraddr = inet_ntoa($iaddr);
- getpgrp PID
- Returns the current process group for the specified PID. Use a PID of 0 to get the current process group for the current process. Will raise an exception if used on a machine that doesn't implement getpgrp(2). If PID is omitted, returns the process group of the current process. Note that the POSIX version of "getpgrp" does not accept a PID argument, so only "PID==0" is truly portable.
- getppid
- Returns the process id of the parent process.
- getpriority WHICH,WHO
- Returns the current priority for a process, a process group, or a user. (See getpriority(2).) Will raise a fatal exception if used on a machine that doesn't implement getpriority(2).
- getpwnam NAME
- getgrnam NAME
- gethostbyname NAME
- getnetbyname NAME
- getprotobyname NAME
- getpwuid UID
- getgrgid GID
- getservbyname NAME,PROTO
- gethostbyaddr ADDR,ADDRTYPE
- getnetbyaddr ADDR,ADDRTYPE
- getprotobynumber NUMBER
- getservbyport PORT,PROTO
- getpwent
- getgrent
- gethostent
- getnetent
- getprotoent
- getservent
- setpwent
- setgrent
- sethostent STAYOPEN
- setnetent STAYOPEN
- setprotoent STAYOPEN
- setservent STAYOPEN
- endpwent
- endgrent
- endhostent
- endnetent
- endprotoent
- endservent
- These routines are the same as their counterparts in the
system C library. In list context, the return values from the various get
routines are as follows:
($name,$passwd,$uid,$gid, $quota,$comment,$gcos,$dir,$shell,$expire) = getpw* ($name,$passwd,$gid,$members) = getgr* ($name,$aliases,$addrtype,$length,@addrs) = gethost* ($name,$aliases,$addrtype,$net) = getnet* ($name,$aliases,$proto) = getproto* ($name,$aliases,$port,$proto) = getserv*
$uid = getpwnam($name); $name = getpwuid($num); $name = getpwent(); $gid = getgrnam($name); $name = getgrgid($num); $name = getgrent(); #etc.
($a,$b,$c,$d) = unpack('W4',$addr[0]);
use Socket; $iaddr = inet_aton("127.1"); # or whatever address $name = gethostbyaddr($iaddr, AF_INET); # or going the other way $straddr = inet_ntoa($iaddr);
use Socket; $packed_ip = gethostbyname("www.perl.org"); if (defined $packed_ip) { $ip_address = inet_ntoa($packed_ip); }
use File::stat; use User::pwent; $is_his = (stat($filename)->uid == pwent($whoever)->uid);
- getsockname SOCKET
- Returns the packed sockaddr address of this end of the
SOCKET connection, in case you don't know the address because you have
several different IPs that the connection might have come in on.
use Socket; $mysockaddr = getsockname(SOCK); ($port, $myaddr) = sockaddr_in($mysockaddr); printf "Connect to %s [%s]\n", scalar gethostbyaddr($myaddr, AF_INET), inet_ntoa($myaddr);
- getsockopt SOCKET,LEVEL,OPTNAME
- Queries the option named OPTNAME associated with SOCKET at
a given LEVEL. Options may exist at multiple protocol levels depending on
the socket type, but at least the uppermost socket level SOL_SOCKET
(defined in the "Socket" module) will exist. To query options at
another level the protocol number of the appropriate protocol controlling
the option should be supplied. For example, to indicate that an option is
to be interpreted by the TCP protocol, LEVEL should be set to the protocol
number of TCP, which you can get using "getprotobyname".
use Socket qw(:all); defined(my $tcp = getprotobyname("tcp")) or die "Could not determine the protocol number for tcp"; # my $tcp = IPPROTO_TCP; # Alternative my $packed = getsockopt($socket, $tcp, TCP_NODELAY) or die "getsockopt TCP_NODELAY: $!"; my $nodelay = unpack("I", $packed); print "Nagle's algorithm is turned ", $nodelay ? "off\n" : "on\n";
- given EXPR BLOCK
- given BLOCK
- "given" is analogous to the "switch"
keyword in other languages. "given" and "when" are
used in Perl to implement "switch"/"case" like
statements. Only available after Perl 5.10. For example:
use v5.10; given ($fruit) { when (/apples?/) { print "I like apples." } when (/oranges?/) { print "I don't like oranges." } default { print "I don't like anything" } }
- glob EXPR
- glob
- In list context, returns a (possibly empty) list of
filename expansions on the value of EXPR such as the standard Unix shell
/bin/csh would do. In scalar context, glob iterates through such
filename expansions, returning undef when the list is exhausted. This is
the internal function implementing the "<*.c>" operator,
but you can use it directly. If EXPR is omitted, $_ is used. The
"<*.c>" operator is discussed in more detail in "I/O
Operators" in perlop.
@many = glob "{apple,tomato,cherry}={green,yellow,red}";
- gmtime EXPR
- gmtime
- Works just like localtime but the returned values are
localized for the standard Greenwich time zone.
- goto LABEL
- goto EXPR
- goto &NAME
- The "goto-LABEL" form finds the statement labeled
with LABEL and resumes execution there. It can't be used to get out of a
block or subroutine given to "sort". It can be used to go almost
anywhere else within the dynamic scope, including out of subroutines, but
it's usually better to use some other construct such as "last"
or "die". The author of Perl has never felt the need to use this
form of "goto" (in Perl, that is; C is another matter). (The
difference is that C does not offer named loops combined with loop
control. Perl does, and this replaces most structured uses of
"goto" in other languages.)
goto ("FOO", "BAR", "GLARCH")[$i];
- grep BLOCK LIST
- grep EXPR,LIST
- This is similar in spirit to, but not the same as,
grep(1) and its relatives. In particular, it is not limited to
using regular expressions.
@foo = grep(!/^#/, @bar); # weed out comments
@foo = grep {!/^#/} @bar; # weed out comments
- hex EXPR
- hex
- Interprets EXPR as a hex string and returns the
corresponding value. (To convert strings that might start with either 0,
"0x", or "0b", see "oct".) If EXPR is
omitted, uses $_.
print hex '0xAf'; # prints '175' print hex 'aF'; # same
- import LIST
- There is no builtin "import" function. It is just an ordinary method (subroutine) defined (or inherited) by modules that wish to export names to another module. The "use" function calls the "import" method for the package used. See also "use", perlmod, and Exporter.
- index STR,SUBSTR,POSITION
- index STR,SUBSTR
- The index function searches for one string within another, but without the wildcard-like behavior of a full regular-expression pattern match. It returns the position of the first occurrence of SUBSTR in STR at or after POSITION. If POSITION is omitted, starts searching from the beginning of the string. POSITION before the beginning of the string or after its end is treated as if it were the beginning or the end, respectively. POSITION and the return value are based at 0 (or whatever you've set the $[ variable to--but don't do that). If the substring is not found, "index" returns one less than the base, ordinarily "-1".
- int EXPR
- int
- Returns the integer portion of EXPR. If EXPR is omitted, uses $_. You should not use this function for rounding: one because it truncates towards 0, and two because machine representations of floating-point numbers can sometimes produce counterintuitive results. For example, "int(-6.725/0.025)" produces -268 rather than the correct -269; that's because it's really more like -268.99999999999994315658 instead. Usually, the "sprintf", "printf", or the "POSIX::floor" and "POSIX::ceil" functions will serve you better than will int().
- ioctl FILEHANDLE,FUNCTION,SCALAR
- Implements the ioctl(2) function. You'll probably
first have to say
require "sys/ioctl.ph"; # probably in $Config{archlib}/sys/ioctl.ph
if OS returns: then Perl returns: -1 undefined value 0 string "0 but true" anything else that number
$retval = ioctl(...) || -1; printf "System returned %d\n", $retval;
- join EXPR,LIST
- Joins the separate strings of LIST into a single string
with fields separated by the value of EXPR, and returns that new string.
Example:
$rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
- keys HASH
- keys ARRAY
- keys EXPR
- Returns a list consisting of all the keys of the named
hash, or the indices of an array. (In scalar context, returns the number
of keys or indices.)
@keys = keys %ENV; @values = values %ENV; while (@keys) { print pop(@keys), '=', pop(@values), "\n"; }
foreach $key (sort(keys %ENV)) { print $key, '=', $ENV{$key}, "\n"; }
foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) { printf "%4d %s\n", $hash{$key}, $key; }
keys %hash = 200;
for (keys $hashref) { ... } for (keys $obj->get_arrayref) { ... }
- kill SIGNAL, LIST
- Sends a signal to a list of processes. Returns the number
of processes successfully signaled (which is not necessarily the same as
the number actually killed).
$cnt = kill 1, $child1, $child2; kill 9, @goners;
- last LABEL
- last
- The "last" command is like the "break"
statement in C (as used in loops); it immediately exits the loop in
question. If the LABEL is omitted, the command refers to the innermost
enclosing loop. The "continue" block, if any, is not executed:
LINE: while (<STDIN>) { last LINE if /^$/; # exit when done with header #... }
- lc EXPR
- lc
- Returns a lowercased version of EXPR. This is the internal
function implementing the "\L" escape in double-quoted strings.
- If "use bytes" is in effect:
- On EBCDIC platforms
- The results are what the C language system call "tolower()" returns.
- On ASCII platforms
- The results follow ASCII semantics. Only characters "A-Z" change, to "a-z" respectively.
- Otherwise, If EXPR has the UTF8 flag set
- If the current package has a subroutine named "ToLower", it will be used to change the case (See "User-Defined Case Mappings (for serious hackers only)" in perlunicode.) Otherwise Unicode semantics are used for the case change.
- Otherwise, if "use locale" is in effect
- Respects current LC_CTYPE locale. See perllocale.
- Otherwise, if "use feature 'unicode_strings'" is in effect:
- Unicode semantics are used for the case change. Any subroutine named "ToLower" will be ignored.
- Otherwise:
- On EBCDIC platforms
- The results are what the C language system call "tolower()" returns.
- On ASCII platforms
- ASCII semantics are used for the case change. The lowercase of any character outside the ASCII range is the character itself.
- lcfirst EXPR
- lcfirst
- Returns the value of EXPR with the first character
lowercased. This is the internal function implementing the "\l"
escape in double-quoted strings.
- length EXPR
- length
- Returns the length in characters of the value of
EXPR. If EXPR is omitted, returns the length of $_. If EXPR is undefined,
returns "undef".
- link OLDFILE,NEWFILE
- Creates a new filename linked to the old filename. Returns true for success, false otherwise.
- listen SOCKET,QUEUESIZE
- Does the same thing that the listen(2) system call does. Returns true if it succeeded, false otherwise. See the example in "Sockets: Client/Server Communication" in perlipc.
- local EXPR
- You really probably want to be using "my"
instead, because "local" isn't what most people think of as
"local". See "Private Variables via my()" in
perlsub for details.
- localtime EXPR
- localtime
- Converts a time as returned by the time function to a
9-element list with the time analyzed for the local time zone. Typically
used as follows:
# 0 1 2 3 4 5 6 7 8 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time);
my @abbr = qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ); print "$abbr[$mon] $mday"; # $mon=9, $mday=18 gives "Oct 18"
$year += 1900;
$year = sprintf("%02d", $year % 100);
$now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
use POSIX qw(strftime); $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime; # or for GMT formatted appropriately for your locale: $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
- lock THING
- This function places an advisory lock on a shared variable
or referenced object contained in THING until the lock goes out of
scope.
- log EXPR
- log
- Returns the natural logarithm (base e) of EXPR. If
EXPR is omitted, returns the log of $_. To get the log of another base,
use basic algebra: The base-N log of a number is equal to the natural log
of that number divided by the natural log of N. For example:
sub log10 { my $n = shift; return log($n)/log(10); }
- lstat EXPR
- lstat
- Does the same thing as the "stat" function
(including setting the special "_" filehandle) but stats a
symbolic link instead of the file the symbolic link points to. If symbolic
links are unimplemented on your system, a normal "stat" is done.
For much more detailed information, please see the documentation for
"stat".
- m//
- The match operator. See "Regexp Quote-Like Operators" in perlop.
- map BLOCK LIST
- map EXPR,LIST
- Evaluates the BLOCK or EXPR for each element of LIST
(locally setting $_ to each element) and returns the list value composed
of the results of each such evaluation. In scalar context, returns the
total number of elements so generated. Evaluates BLOCK or EXPR in list
context, so each element of LIST may produce zero, one, or more elements
in the returned value.
@chars = map(chr, @numbers);
my @squares = map { $_ * $_ } @numbers;
my @squares = map { $_ > 5 ? ($_ * $_) : () } @numbers;
my @squares = map { $_ * $_ } grep { $_ > 5 } @numbers;
%hash = map { get_a_key_for($_) => $_ } @array;
%hash = (); foreach (@array) { $hash{get_a_key_for($_)} = $_; }
%hash = map { "\L$_" => 1 } @array # perl guesses EXPR. wrong %hash = map { +"\L$_" => 1 } @array # perl guesses BLOCK. right %hash = map { ("\L$_" => 1) } @array # this also works %hash = map { lc($_) => 1 } @array # as does this. %hash = map +( lc($_) => 1 ), @array # this is EXPR and works! %hash = map ( lc($_), 1 ), @array # evaluates to (1, @array)
@hashes = map +{ lc($_) => 1 }, @array # EXPR, so needs comma at end
- mkdir FILENAME,MASK
- mkdir FILENAME
- mkdir
- Creates the directory specified by FILENAME, with
permissions specified by MASK (as modified by "umask"). If it
succeeds it returns true; otherwise it returns false and sets $! (errno).
MASK defaults to 0777 if omitted, and FILENAME defaults to $_ if omitted.
- msgctl ID,CMD,ARG
- Calls the System V IPC function msgctl(2). You'll
probably have to say
use IPC::SysV;
- msgget KEY,FLAGS
- Calls the System V IPC function msgget(2). Returns the message queue id, or "undef" on error. See also "SysV IPC" in perlipc and the documentation for "IPC::SysV" and "IPC::Msg".
- msgrcv ID,VAR,SIZE,TYPE,FLAGS
- Calls the System V IPC function msgrcv to receive a message from message queue ID into variable VAR with a maximum message size of SIZE. Note that when a message is received, the message type as a native long integer will be the first thing in VAR, followed by the actual message. This packing may be opened with "unpack("l! a*")". Taints the variable. Returns true if successful, false on error. See also "SysV IPC" in perlipc and the documentation for "IPC::SysV" and "IPC::SysV::Msg".
- msgsnd ID,MSG,FLAGS
- Calls the System V IPC function msgsnd to send the message MSG to the message queue ID. MSG must begin with the native long integer message type, be followed by the length of the actual message, and then finally the message itself. This kind of packing can be achieved with "pack("l! a*", $type, $message)". Returns true if successful, false on error. See also the "IPC::SysV" and "IPC::SysV::Msg" documentation.
- my EXPR
- my TYPE EXPR
- my EXPR : ATTRS
- my TYPE EXPR : ATTRS
- A "my" declares the listed variables to be local
(lexically) to the enclosing block, file, or "eval". If more
than one value is listed, the list must be placed in parentheses.
- next LABEL
- next
- The "next" command is like the
"continue" statement in C; it starts the next iteration of the
loop:
LINE: while (<STDIN>) { next LINE if /^#/; # discard comments #... }
- no MODULE VERSION LIST
- no MODULE VERSION
- no MODULE LIST
- no MODULE
- no VERSION
- See the "use" function, of which "no" is the opposite.
- oct EXPR
- oct
- Interprets EXPR as an octal string and returns the
corresponding value. (If EXPR happens to start off with "0x",
interprets it as a hex string. If EXPR starts off with "0b", it
is interpreted as a binary string. Leading whitespace is ignored in all
three cases.) The following will handle decimal, binary, octal, and hex in
standard Perl notation:
$val = oct($val) if $val =~ /^0/;
$dec_perms = (stat("filename"))[2] & 07777; $oct_perm_str = sprintf "%o", $perms;
- open FILEHANDLE,EXPR
- open FILEHANDLE,MODE,EXPR
- open FILEHANDLE,MODE,EXPR,LIST
- open FILEHANDLE,MODE,REFERENCE
- open FILEHANDLE
- Opens the file whose filename is given by EXPR, and
associates it with FILEHANDLE.
open(my $fh, "<", "input.txt") or die "cannot open < input.txt: $!";
open(my $fh, ">", "output.txt") or die "cannot open > output.txt: $!";
open(my $fh, "<:encoding(UTF-8)", "filename") || die "can't open UTF-8 encoded filename: $!";
open(my $tmp, "+>", undef) or die ...
open($fh, ">", \$variable) || ..
close STDOUT; open(STDOUT, ">", \$variable) or die "Can't open STDOUT: $!";
$ARTICLE = 100; open(ARTICLE) or die "Can't find article $ARTICLE: $!\n"; while (<ARTICLE>) {... open(LOG, ">>/usr/spool/news/twitlog"); # (log is reserved) # if the open fails, output is discarded open(my $dbase, "+<", "dbase.mine") # open for update or die "Can't open 'dbase.mine' for update: $!"; open(my $dbase, "+<dbase.mine") # ditto or die "Can't open 'dbase.mine' for update: $!"; open(ARTICLE, "-|", "caesar <$article") # decrypt article or die "Can't start caesar: $!"; open(ARTICLE, "caesar <$article |") # ditto or die "Can't start caesar: $!"; open(EXTRACT, "|sort >Tmp$$") # $$ is our process id or die "Can't start sort: $!"; # in-memory files open(MEMORY, ">", \$var) or die "Can't open memory file: $!"; print MEMORY "foo!\n"; # output will appear in $var # process argument list of files along with any includes foreach $file (@ARGV) { process($file, "fh00"); } sub process { my($filename, $input) = @_; $input++; # this is a string increment unless (open($input, "<", $filename)) { print STDERR "Can't open $filename: $!\n"; return; } local $_; while (<$input>) { # note use of indirection if (/^#include "(.*)"/) { process($1, $input); next; } #... # whatever } }
#!/usr/bin/perl open(my $oldout, ">&STDOUT") or die "Can't dup STDOUT: $!"; open(OLDERR, ">&", \*STDERR) or die "Can't dup STDERR: $!"; open(STDOUT, '>', "foo.out") or die "Can't redirect STDOUT: $!"; open(STDERR, ">&STDOUT") or die "Can't dup STDOUT: $!"; select STDERR; $| = 1; # make unbuffered select STDOUT; $| = 1; # make unbuffered print STDOUT "stdout 1\n"; # this works for print STDERR "stderr 1\n"; # subprocesses too open(STDOUT, ">&", $oldout) or die "Can't dup \$oldout: $!"; open(STDERR, ">&OLDERR") or die "Can't dup OLDERR: $!"; print STDOUT "stdout 2\n"; print STDERR "stderr 2\n";
# open for input, reusing the fileno of $fd open(FILEHANDLE, "<&=$fd")
open(FILEHANDLE, "<&=", $fd)
# open for append, using the fileno of OLDFH open(FH, ">>&=", OLDFH)
open(FH, ">>&=OLDFH")
$child_pid = open(FROM_KID, "|-") // die "can't fork: $!";
$child_pid = open(TO_KID, "|-") // die "can't fork: $!";if ($child_pid) { # am the parent: # either write TO_KID or else read FROM_KID ... wait $child_pid; } else { # am the child; use STDIN/STDOUT normally ... exit; }
open(FOO, "|tr '[a-z]' '[A-Z]'"); open(FOO, "|-", "tr '[a-z]' '[A-Z]'"); open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]'; open(FOO, "|-", "tr", '[a-z]', '[A-Z]'); open(FOO, "cat -n '$file'|"); open(FOO, "-|", "cat -n '$file'"); open(FOO, "-|") || exec "cat", "-n", $file; open(FOO, "-|", "cat", "-n", $file);
open(FOO, "|cat -n | expand -4 | lpr") // die "Can't open pipeline to lpr: $!";
$filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/; open(FH, $filename) or die "Can't open $filename: $!";
open(FOO, "<", $file) || die "can't open < $file: $!";
$file =~ s#^(\s)#./$1#; open(FOO, "< $file\0") || die "open failed: $!";
open(IN, $ARGV[0]) || die "can't open $ARGV[0]: $!";
open(IN, "<", $ARGV[0]) || die "can't open < $ARGV[0]: $!";
use IO::Handle; sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL) or die "sysopen $path: $!"; $oldfh = select(HANDLE); $| = 1; select($oldfh); print HANDLE "stuff $$\n"; seek(HANDLE, 0, 0); print "File contains: ", <HANDLE>;
use IO::File; #... sub read_myfile_munged { my $ALL = shift; # or just leave it undef to autoviv my $handle = IO::File->new; open($handle, "<", "myfile") or die "myfile: $!"; $first = <$handle> or return (); # Automatically closed here. mung($first) or die "mung failed"; # Or here. return (first, <$handle>) if $ALL; # Or here. return $first; # Or here. }
close($handle) || warn "close failed: $!";
- opendir DIRHANDLE,EXPR
- Opens a directory named EXPR for processing by
"readdir", "telldir", "seekdir",
"rewinddir", and "closedir". Returns true if
successful. DIRHANDLE may be an expression whose value can be used as an
indirect dirhandle, usually the real dirhandle name. If DIRHANDLE is an
undefined scalar variable (or array or hash element), the variable is
assigned a reference to a new anonymous dirhandle; that is, it's
autovivified. DIRHANDLEs have their own namespace separate from
FILEHANDLEs.
- ord EXPR
- ord
- Returns the numeric (the native 8-bit encoding, like ASCII
or EBCDIC, or Unicode) value of the first character of EXPR. If EXPR is an
empty string, returns 0. If EXPR is omitted, uses $_. (Note
character, not byte.)
- our EXPR
- our TYPE EXPR
- our EXPR : ATTRS
- our TYPE EXPR : ATTRS
- "our" associates a simple name with a package
variable in the current package for use within the current scope. When
"use strict 'vars'" is in effect, "our" lets you use
declared global variables without qualifying them with package names,
within the lexical scope of the "our" declaration. In this way
"our" differs from "use vars", which is
package-scoped.
our $foo; our($bar, $baz);
package Foo; our $bar; # declares $Foo::bar for rest of lexical scope $bar = 20; package Bar; print $bar; # prints 20, as it refers to $Foo::bar
use warnings; package Foo; our $bar; # declares $Foo::bar for rest of lexical scope $bar = 20; package Bar; our $bar = 30; # declares $Bar::bar for rest of lexical scope print $bar; # prints 30 our $bar; # emits warning but has no other effect print $bar; # still prints 30
- pack TEMPLATE,LIST
- Takes a LIST of values and converts it into a string using
the rules given by the TEMPLATE. The resulting string is the concatenation
of the converted values. Typically, each converted value looks like its
machine-level representation. For example, on 32-bit machines an integer
may be represented by a sequence of 4 bytes, which will in Perl be
presented as a string that's 4 characters long.
a A string with arbitrary binary data, will be null padded. A A text (ASCII) string, will be space padded. Z A null-terminated (ASCIZ) string, will be null padded. b A bit string (ascending bit order inside each byte, like vec()). B A bit string (descending bit order inside each byte). h A hex string (low nybble first). H A hex string (high nybble first). c A signed char (8-bit) value. C An unsigned char (octet) value. W An unsigned char value (can be greater than 255). s A signed short (16-bit) value. S An unsigned short value. l A signed long (32-bit) value. L An unsigned long value. q A signed quad (64-bit) value. Q An unsigned quad value. (Quads are available only if your system supports 64-bit integer values _and_ if Perl has been compiled to support those. Raises an exception otherwise.) i A signed integer value. I A unsigned integer value. (This 'integer' is _at_least_ 32 bits wide. Its exact size depends on what a local C compiler calls 'int'.) n An unsigned short (16-bit) in "network" (big-endian) order. N An unsigned long (32-bit) in "network" (big-endian) order. v An unsigned short (16-bit) in "VAX" (little-endian) order. V An unsigned long (32-bit) in "VAX" (little-endian) order. j A Perl internal signed integer value (IV). J A Perl internal unsigned integer value (UV). f A single-precision float in native format. d A double-precision float in native format. F A Perl internal floating-point value (NV) in native format D A float of long-double precision in native format. (Long doubles are available only if your system supports long double values _and_ if Perl has been compiled to support those. Raises an exception otherwise.) p A pointer to a null-terminated string. P A pointer to a structure (fixed-length string). u A uuencoded string. U A Unicode character number. Encodes to a character in character mode and UTF-8 (or UTF-EBCDIC in EBCDIC platforms) in byte mode. w A BER compressed integer (not an ASN.1 BER, see perlpacktut for details). Its bytes represent an unsigned integer in base 128, most significant digit first, with as few digits as possible. Bit eight (the high bit) is set on each byte except the last. x A null byte (a.k.a ASCII NUL, "\000", chr(0)) X Back up a byte. @ Null-fill or truncate to absolute position, counted from the start of the innermost ()-group. . Null-fill or truncate to absolute position specified by the value. ( Start of a ()-group.
! sSlLiI Forces native (short, long, int) sizes instead of fixed (16-/32-bit) sizes. xX Make x and X act as alignment commands. nNvV Treat integers as signed instead of unsigned. @. Specify position as byte offset in the internal representation of the packed string. Efficient but dangerous. > sSiIlLqQ Force big-endian byte-order on the type. jJfFdDpP (The "big end" touches the construct.) < sSiIlLqQ Force little-endian byte-order on the type. jJfFdDpP (The "little end" touches the construct.)
- •
- Each letter may optionally be followed by a number indicating the repeat count. A numeric repeat count may optionally be enclosed in brackets, as in "pack("C[80]", @arr)". The repeat count gobbles that many values from the LIST when used with all format types other than "a", "A", "Z", "b", "B", "h", "H", "@", ".", "x", "X", and "P", where it means something else, described below. Supplying a "*" for the repeat count instead of a number means to use however many items are left, except for:
- •
- "@", "x", and "X", where it is equivalent to 0.
- •
- <.>, where it means relative to the start of the string.
- •
- "u", where it is equivalent to 1 (or 45, which here is equivalent).
- •
- If the repeat count is 0, it's relative to the current position.
- •
- If the repeat count is "*", the offset is relative to the start of the packed string.
- •
- And if it's an integer n, the offset is relative to the start of the nth innermost "( )" group, or to the start of the string if n is bigger then the group level.
- •
- The "a", "A", and "Z" types
gobble just one value, but pack it as a string of length count, padding
with nulls or spaces as needed. When unpacking, "A" strips
trailing whitespace and nulls, "Z" strips everything after the
first null, and "a" returns data with no stripping at all.
- •
- Likewise, the "b" and "B" formats pack
a string that's that many bits long. Each such format generates 1 bit of
the result. These are typically followed by a repeat count like
"B8" or "B64".
- •
- The "h" and "H" formats pack a string
that many nybbles (4-bit groups, representable as hexadecimal digits,
"0".."9" "a".."f") long.
- •
- The "p" format packs a pointer to a
null-terminated string. You are responsible for ensuring that the string
is not a temporary value, as that could potentially get deallocated before
you got around to using the packed result. The "P" format packs
a pointer to a structure of the size indicated by the length. A null
pointer is created if the corresponding value for "p" or
"P" is "undef"; similarly with unpack(), where
a null pointer unpacks into "undef".
- •
- The "/" template character allows packing and
unpacking of a sequence of items where the packed structure contains a
packed item count followed by the packed items themselves. This is useful
when the structure you're unpacking has encoded the sizes or repeat counts
for some of its fields within the structure itself as separate fields.
unpack("W/a", "\004Gurusamy") gives ("Guru") unpack("a3/A A*", "007 Bond J ") gives (" Bond", "J") unpack("a3 x2 /A A*", "007: Bond, J.") gives ("Bond, J", ".") pack("n/a* w/a","hello,","world") gives "\000\006hello,\005world" pack("a/W2", ord("a") .. ord("z")) gives "2ab"
- •
- The integer types "s", "S",
"l", and "L" may be followed by a "!"
modifier to specify native shorts or longs. As shown in the example above,
a bare "l" means exactly 32 bits, although the native
"long" as seen by the local C compiler may be larger. This is
mainly an issue on 64-bit platforms. You can see whether using
"!" makes any difference this way:
printf "format s is %d, s! is %d\n", length pack("s"), length pack("s!"); printf "format l is %d, l! is %d\n", length pack("l"), length pack("l!");
$ perl -V:{short,int,long{,long}}size shortsize='2'; intsize='4'; longsize='4'; longlongsize='8';
use Config; print $Config{shortsize}, "\n"; print $Config{intsize}, "\n"; print $Config{longsize}, "\n"; print $Config{longlongsize}, "\n";
- •
- The integer formats "s", "S",
"i", "I", "l", "L", "j",
and "J" are inherently non-portable between processors and
operating systems because they obey native byteorder and endianness. For
example, a 4-byte integer 0x12345678 (305419896 decimal) would be ordered
natively (arranged in and handled by the CPU registers) into bytes as
0x12 0x34 0x56 0x78 # big-endian 0x78 0x56 0x34 0x12 # little-endian
0x56 0x78 0x12 0x34 0x34 0x12 0x78 0x56
printf("%#02x ", $_) for unpack("W*", pack L=>0x12345678);
use Config; print "$Config{byteorder}\n";
$ perl -V:byteorder
- •
- Starting with Perl 5.9.2, integer and floating-point
formats, along with the "p" and "P" formats and
"()" groups, may all be followed by the ">" or
"<" endianness modifiers to respectively enforce big- or
little-endian byte-order. These modifiers are especially useful given how
"n", "N", "v", and "V" don't cover
signed integers, 64-bit integers, or floating-point values.
- •
- Exchanging signed integers between different platforms works only when all platforms store them in the same format. Most platforms store signed integers in two's-complement notation, so usually this is not an issue.
- •
- The ">" or "<" modifiers can only be used on floating-point formats on big- or little-endian machines. Otherwise, attempting to use them raises an exception.
- •
- Forcing big- or little-endian byte-order on floating-point values for data exchange can work only if all platforms use the same binary representation such as IEEE floating-point. Even if all platforms are using IEEE, there may still be subtle differences. Being able to use ">" or "<" on floating-point values can be useful, but also dangerous if you don't know exactly what you're doing. It is not a general way to portably store floating-point values.
- •
- When using ">" or "<" on a "()" group, this affects all types inside the group that accept byte-order modifiers, including all subgroups. It is silently ignored for all other types. You are not allowed to override the byte-order within a group that already has a byte-order modifier suffix.
- •
- Real numbers (floats and doubles) are in native machine
format only. Due to the multiplicity of floating-point formats and the
lack of a standard "network" representation for them, no
facility for interchange has been made. This means that packed
floating-point data written on one machine may not be readable on another,
even if both use IEEE floating-point arithmetic (because the endianness of
the memory representation is not part of the IEEE spec). See also
perlport.
- •
- Pack and unpack can operate in two modes: character mode
("C0" mode) where the packed string is processed per character,
and UTF-8 mode ("U0" mode) where the packed string is processed
in its UTF-8-encoded Unicode form on a byte-by-byte basis. Character mode
is the default unless the format string starts with "U". You can
always switch mode mid-format with an explicit "C0" or
"U0" in the format. This mode remains in effect until the next
mode change, or until the end of the "()" group it (directly)
applies to.
$ perl -CS -E 'say "\x{3B1}\x{3C9}"' | perl -CS -ne 'printf "%v04X\n", $_ for unpack("C0A*", $_)' 03B1.03C9 $ perl -CS -E 'say "\x{3B1}\x{3C9}"' | perl -CS -ne 'printf "%v02X\n", $_ for unpack("U0A*", $_)' CE.B1.CF.89 $ perl -CS -E 'say "\x{3B1}\x{3C9}"' | perl -C0 -ne 'printf "%v02X\n", $_ for unpack("C0A*", $_)' CE.B1.CF.89 $ perl -CS -E 'say "\x{3B1}\x{3C9}"' | perl -C0 -ne 'printf "%v02X\n", $_ for unpack("U0A*", $_)' C3.8E.C2.B1.C3.8F.C2.89
- •
- You must yourself do any alignment or padding by inserting, for example, enough "x"es while packing. There is no way for pack() and unpack() to know where characters are going to or coming from, so they handle their output and input as flat sequences of characters.
- •
- A "()" group is a sub-TEMPLATE enclosed in
parentheses. A group may take a repeat count either as postfix, or for
unpack(), also via the "/" template character. Within
each repetition of a group, positioning with "@" starts over at
0. Therefore, the result of
pack("@1A((@2A)@3A)", qw[X Y Z])
- •
- "x" and "X" accept the "!"
modifier to act as alignment commands: they jump forward or back to the
closest position aligned at a multiple of "count" characters.
For example, to pack() or unpack() a C structure like
struct { char c; /* one signed, 8-bit character */ double d; char cc[2]; }
- •
- "n", "N", "v" and "V" accept the "!" modifier to represent signed 16-/32-bit integers in big-/little-endian order. This is portable only when all platforms sharing packed data use the same binary representation for signed integers; for example, when all platforms use two's-complement representation.
- •
- Comments can be embedded in a TEMPLATE using "#" through the end of line. White space can separate pack codes from each other, but modifiers and repeat counts must follow immediately. Breaking complex templates into individual line-by-line components, suitably annotated, can do as much to improve legibility and maintainability of pack/unpack formats as "/x" can for complicated pattern matches.
- •
- If TEMPLATE requires more arguments than pack() is given, pack() assumes additional "" arguments. If TEMPLATE requires fewer arguments than given, extra arguments are ignored.
$foo = pack("WWWW",65,66,67,68); # foo eq "ABCD" $foo = pack("W4",65,66,67,68); # same thing $foo = pack("W4",0x24b6,0x24b7,0x24b8,0x24b9); # same thing with Unicode circled letters. $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9); # same thing with Unicode circled letters. You don't get the UTF-8 # bytes because the U at the start of the format caused a switch to # U0-mode, so the UTF-8 bytes get joined into characters $foo = pack("C0U4",0x24b6,0x24b7,0x24b8,0x24b9); # foo eq "\xe2\x92\xb6\xe2\x92\xb7\xe2\x92\xb8\xe2\x92\xb9" # This is the UTF-8 encoding of the string in the previous example $foo = pack("ccxxcc",65,66,67,68); # foo eq "AB\0\0CD" # NOTE: The examples above featuring "W" and "c" are true # only on ASCII and ASCII-derived systems such as ISO Latin 1 # and UTF-8. On EBCDIC systems, the first example would be # $foo = pack("WWWW",193,194,195,196); $foo = pack("s2",1,2); # "\001\000\002\000" on little-endian # "\000\001\000\002" on big-endian $foo = pack("a4","abcd","x","y","z"); # "abcd" $foo = pack("aaaa","abcd","x","y","z"); # "axyz" $foo = pack("a14","abcdefg"); # "abcdefg\0\0\0\0\0\0\0" $foo = pack("i9pl", gmtime); # a real struct tm (on my system anyway) $utmp_template = "Z8 Z8 Z16 L"; $utmp = pack($utmp_template, @utmp1); # a struct utmp (BSDish) @utmp2 = unpack($utmp_template, $utmp); # "@utmp1" eq "@utmp2" sub bintodec { unpack("N", pack("B32", substr("0" x 32 . shift, -32))); } $foo = pack('sx2l', 12, 34); # short 12, two zero bytes padding, long 34 $bar = pack('s@4l', 12, 34); # short 12, zero fill to position 4, long 34 # $foo eq $bar $baz = pack('s.l', 12, 4, 34); # short 12, zero fill to position 4, long 34 $foo = pack('nN', 42, 4711); # pack big-endian 16- and 32-bit unsigned integers $foo = pack('S>L>', 42, 4711); # exactly the same $foo = pack('s<l<', -42, 4711); # pack little-endian 16- and 32-bit signed integers $foo = pack('(sl)<', -42, 4711); # exactly the same
- package NAMESPACE
- package NAMESPACE VERSION
- package NAMESPACE BLOCK
- package NAMESPACE VERSION BLOCK
- Declares the BLOCK or the rest of the compilation unit as
being in the given namespace. The scope of the package declaration is
either the supplied code BLOCK or, in the absence of a BLOCK, from the
declaration itself through the end of current scope (the enclosing block,
file, or "eval"). That is, the forms without a BLOCK are
operative through the end of the current scope, just like the
"my", "state", and "our" operators. All
unqualified dynamic identifiers in this scope will be in the given
namespace, except where overridden by another "package"
declaration or when they're one of the special identifiers that qualify
into "main::", like "STDOUT", "ARGV",
"ENV", and the punctuation variables.
- pipe READHANDLE,WRITEHANDLE
- Opens a pair of connected pipes like the corresponding
system call. Note that if you set up a loop of piped processes, deadlock
can occur unless you are very careful. In addition, note that Perl's pipes
use IO buffering, so you may need to set $| to flush your WRITEHANDLE
after each command, depending on the application.
- pop ARRAY
- pop EXPR
- pop
- Pops and returns the last value of the array, shortening
the array by one element.
- pos SCALAR
- pos
- Returns the offset of where the last "m//g"
search left off for the variable in question ($_ is used when the variable
is not specified). Note that 0 is a valid match offset. "undef"
indicates that the search position is reset (usually due to match failure,
but can also be because no match has yet been run on the scalar).
- print FILEHANDLE LIST
- print FILEHANDLE
- print LIST
- Prints a string or a list of strings. Returns true if
successful. FILEHANDLE may be a scalar variable containing the name of or
a reference to the filehandle, thus introducing one level of indirection.
(NOTE: If FILEHANDLE is a variable and the next token is a term, it may be
misinterpreted as an operator unless you interpose a "+" or put
parentheses around the arguments.) If FILEHANDLE is omitted, prints to the
last selected (see "select") output handle. If LIST is omitted,
prints $_ to the currently selected output handle. To use FILEHANDLE alone
to print the content of $_ to it, you must use a real filehandle like
"FH", not an indirect one like $fh. To set the default output
handle to something other than STDOUT, use the select operation.
print { $files[$i] } "stuff\n"; print { $OK ? STDOUT : STDERR } "stuff\n";
- printf FILEHANDLE FORMAT, LIST
- printf FILEHANDLE
- printf FORMAT, LIST
- printf
- Equivalent to "print FILEHANDLE sprintf(FORMAT,
LIST)", except that "$\" (the output record separator) is
not appended. The first argument of the list will be interpreted as the
"printf" format. See "sprintf" for an explanation of
the format argument. If you omit the LIST, $_ is used; to use FILEHANDLE
without a LIST, you must use a real filehandle like "FH", not an
indirect one like $fh. If "use locale" is in effect and
POSIX::setlocale() has been called, the character used for the
decimal separator in formatted floating-point numbers is affected by the
LC_NUMERIC locale setting. See perllocale and POSIX.
- prototype FUNCTION
- Returns the prototype of a function as a string (or
"undef" if the function has no prototype). FUNCTION is a
reference to, or the name of, the function whose prototype you want to
retrieve.
- push ARRAY,LIST
- push EXPR,LIST
- Treats ARRAY as a stack by appending the values of LIST to
the end of ARRAY. The length of ARRAY increases by the length of LIST. Has
the same effect as
for $value (LIST) { $ARRAY[++$#ARRAY] = $value; }
- q/STRING/
- qq/STRING/
- qx/STRING/
- qw/STRING/
- Generalized quotes. See "Quote-Like Operators" in perlop.
- qr/STRING/
- Regexp-like quote. See "Regexp Quote-Like Operators" in perlop.
- quotemeta EXPR
- quotemeta
- Returns the value of EXPR with all non-"word"
characters backslashed. (That is, all characters not matching
"/[A-Za-z_0-9]/" will be preceded by a backslash in the returned
string, regardless of any locale settings.) This is the internal function
implementing the "\Q" escape in double-quoted strings.
my $sentence = 'The quick brown fox jumped over the lazy dog'; my $substring = 'quick.*?fox'; $sentence =~ s{$substring}{big bad wolf};
my $sentence = 'The quick brown fox jumped over the lazy dog'; my $substring = 'quick.*?fox'; $sentence =~ s{\Q$substring\E}{big bad wolf};
my $sentence = 'The quick brown fox jumped over the lazy dog'; my $substring = 'quick.*?fox'; my $quoted_substring = quotemeta($substring); $sentence =~ s{$quoted_substring}{big bad wolf};
- rand EXPR
- rand
- Returns a random fractional number greater than or equal to
0 and less than the value of EXPR. (EXPR should be positive.) If EXPR is
omitted, the value 1 is used. Currently EXPR with the value 0 is also
special-cased as 1 (this was undocumented before Perl 5.8.0 and is subject
to change in future versions of Perl). Automatically calls
"srand" unless "srand" has already been called. See
also "srand".
int(rand(10))
- read FILEHANDLE,SCALAR,LENGTH,OFFSET
- read FILEHANDLE,SCALAR,LENGTH
- Attempts to read LENGTH characters of data into
variable SCALAR from the specified FILEHANDLE. Returns the number of
characters actually read, 0 at end of file, or undef if there was an error
(in the latter case $! is also set). SCALAR will be grown or shrunk so
that the last character actually read is the last character of the scalar
after the read.
- readdir DIRHANDLE
- Returns the next directory entry for a directory opened by
"opendir". If used in list context, returns all the rest of the
entries in the directory. If there are no more entries, returns the
undefined value in scalar context and the empty list in list context.
opendir(my $dh, $some_dir) || die "can't opendir $some_dir: $!"; @dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh); closedir $dh;
opendir(my $dh, $some_dir) || die; while(readdir $dh) { print "$some_dir/$_\n"; } closedir $dh;
- readline EXPR
- readline
- Reads from the filehandle whose typeglob is contained in
EXPR (or from *ARGV if EXPR is not provided). In scalar context, each call
reads and returns the next line until end-of-file is reached, whereupon
the subsequent call returns "undef". In list context, reads
until end-of-file is reached and returns a list of lines. Note that the
notion of "line" used here is whatever you may have defined with
$/ or $INPUT_RECORD_SEPARATOR). See "$/" in perlvar.
$line = <STDIN>; $line = readline(*STDIN); # same thing
while ( ! eof($fh) ) { defined( $_ = <$fh> ) or die "readline failed: $!"; ... }
foreach my $arg (@ARGV) { open(my $fh, $arg) or warn "Can't open $arg: $!"; while ( ! eof($fh) ) { defined( $_ = <$fh> ) or die "readline failed for $arg: $!"; ... } }
- readlink EXPR
- readlink
- Returns the value of a symbolic link, if symbolic links are implemented. If not, raises an exception. If there is a system error, returns the undefined value and sets $! (errno). If EXPR is omitted, uses $_.
- readpipe EXPR
- readpipe
- EXPR is executed as a system command. The collected standard output of the command is returned. In scalar context, it comes back as a single (potentially multi-line) string. In list context, returns a list of lines (however you've defined lines with $/ or $INPUT_RECORD_SEPARATOR). This is the internal function implementing the "qx/EXPR/" operator, but you can use it directly. The "qx/EXPR/" operator is discussed in more detail in "I/O Operators" in perlop. If EXPR is omitted, uses $_.
- recv SOCKET,SCALAR,LENGTH,FLAGS
- Receives a message on a socket. Attempts to receive LENGTH
characters of data into variable SCALAR from the specified SOCKET
filehandle. SCALAR will be grown or shrunk to the length actually read.
Takes the same flags as the system call of the same name. Returns the
address of the sender if SOCKET's protocol supports this; returns an empty
string otherwise. If there's an error, returns the undefined value. This
call is actually implemented in terms of recvfrom(2) system call.
See "UDP: Message Passing" in perlipc for examples.
- redo LABEL
- redo
- The "redo" command restarts the loop block
without evaluating the conditional again. The "continue" block,
if any, is not executed. If the LABEL is omitted, the command refers to
the innermost enclosing loop. Programs that want to lie to themselves
about what was just input normally use this command:
# a simpleminded Pascal comment stripper # (warning: assumes no { or } in strings) LINE: while (<STDIN>) { while (s|({.*}.*){.*}|$1 |) {} s|{.*}| |; if (s|{.*| |) { $front = $_; while (<STDIN>) { if (/}/) { # end of comment? s|^|$front\{|; redo LINE; } } } print; }
- ref EXPR
- ref
- Returns a non-empty string if EXPR is a reference, the
empty string otherwise. If EXPR is not specified, $_ will be used. The
value returned depends on the type of thing the reference is a reference
to. Builtin types include:
SCALAR ARRAY HASH CODE REF GLOB LVALUE FORMAT IO VSTRING Regexp
if (ref($r) eq "HASH") { print "r is a reference to a hash.\n"; } unless (ref($r)) { print "r is not a reference at all.\n"; }
- rename OLDNAME,NEWNAME
- Changes the name of a file; an existing file NEWNAME will
be clobbered. Returns true for success, false otherwise.
- require VERSION
- require EXPR
- require
- Demands a version of Perl specified by VERSION, or demands
some semantics specified by EXPR or by $_ if EXPR is not supplied.
require v5.6.1; # run time version check require 5.6.1; # ditto require 5.006_001; # ditto; preferred for backwards compatibility
sub require { my ($filename) = @_; if (exists $INC{$filename}) { return 1 if $INC{$filename}; die "Compilation failed in require"; } my ($realfilename,$result); ITER: { foreach $prefix (@INC) { $realfilename = "$prefix/$filename"; if (-f $realfilename) { $INC{$filename} = $realfilename; $result = do $realfilename; last ITER; } } die "Can't find $filename in \@INC"; } if ($@) { $INC{$filename} = undef; die $@; } elsif (!$result) { delete $INC{$filename}; die "$filename did not return true value"; } else { return $result; } }
require Foo::Bar; # a splendid bareword
$class = 'Foo::Bar'; require $class; # $class is not a bareword #or require "Foo::Bar"; # not a bareword because of the ""
eval "require $class";
- 1.
- A filehandle, from which the file will be read.
- 2.
- A reference to a subroutine. If there is no filehandle (previous item), then this subroutine is expected to generate one line of source code per call, writing the line into $_ and returning 1, then finally at end of file returning 0. If there is a filehandle, then the subroutine will be called to act as a simple source filter, with the line as read in $_. Again, return 1 for each valid line, and 0 after all lines have been returned.
- 3.
- Optional state for the subroutine. The state is passed in as $_[1]. A reference to the subroutine itself is passed in as $_[0].
push @INC, \&my_sub; sub my_sub { my ($coderef, $filename) = @_; # $coderef is \&my_sub ... }
push @INC, [ \&my_sub, $x, $y, ... ]; sub my_sub { my ($arrayref, $filename) = @_; # Retrieve $x, $y, ... my @parameters = @$arrayref[1..$#$arrayref]; ... }
# In Foo.pm package Foo; sub new { ... } sub Foo::INC { my ($self, $filename) = @_; ... } # In the main program push @INC, Foo->new(...);
- reset EXPR
- reset
- Generally used in a "continue" block at the end
of a loop to clear variables and reset "??" searches so that
they work again. The expression is interpreted as a list of single
characters (hyphens allowed for ranges). All variables and arrays
beginning with one of those letters are reset to their pristine state. If
the expression is omitted, one-match searches ("?pattern?") are
reset to match again. Only resets variables or searches in the current
package. Always returns 1. Examples:
reset 'X'; # reset all X variables reset 'a-z'; # reset lower case variables reset; # just reset ?one-time? searches
- return EXPR
- return
- Returns from a subroutine, "eval", or "do
FILE" with the value given in EXPR. Evaluation of EXPR may be in
list, scalar, or void context, depending on how the return value will be
used, and the context may vary from one execution to the next (see
"wantarray"). If no EXPR is given, returns an empty list in list
context, the undefined value in scalar context, and (of course) nothing at
all in void context.
- reverse LIST
- In list context, returns a list value consisting of the
elements of LIST in the opposite order. In scalar context, concatenates
the elements of LIST and returns a string value with all characters in the
opposite order.
print join(", ", reverse "world", "Hello"); # Hello, world print scalar reverse "dlrow ,", "olleH"; # Hello, world
$_ = "dlrow ,olleH"; print reverse; # No output, list context print scalar reverse; # Hello, world
%by_name = reverse %by_address; # Invert the hash
- rewinddir DIRHANDLE
- Sets the current position to the beginning of the directory for the "readdir" routine on DIRHANDLE.
- rindex STR,SUBSTR,POSITION
- rindex STR,SUBSTR
- Works just like index() except that it returns the position of the last occurrence of SUBSTR in STR. If POSITION is specified, returns the last occurrence beginning at or before that position.
- rmdir FILENAME
- rmdir
- Deletes the directory specified by FILENAME if that
directory is empty. If it succeeds it returns true; otherwise it returns
false and sets $! (errno). If FILENAME is omitted, uses $_.
- s///
- The substitution operator. See "Regexp Quote-Like Operators" in perlop.
- say FILEHANDLE LIST
- say FILEHANDLE
- say LIST
- say
- Just like "print", but implicitly appends a
newline. "say LIST" is simply an abbreviation for "{ local
$\ = "\n"; print LIST }". To use FILEHANDLE without a LIST
to print the contents of $_ to it, you must use a real filehandle like
"FH", not an indirect one like $fh.
- scalar EXPR
- Forces EXPR to be interpreted in scalar context and returns
the value of EXPR.
@counts = ( scalar @a, scalar @b, scalar @c );
print uc(scalar(&foo,$bar)),$baz;
&foo; print(uc($bar),$baz);
- seek FILEHANDLE,POSITION,WHENCE
- Sets FILEHANDLE's position, just like the "fseek"
call of "stdio". FILEHANDLE may be an expression whose value
gives the name of the filehandle. The values for WHENCE are 0 to set the
new position in bytes to POSITION; 1 to set it to the current
position plus POSITION; and 2 to set it to EOF plus POSITION, typically
negative. For WHENCE you may use the constants "SEEK_SET",
"SEEK_CUR", and "SEEK_END" (start of the file, current
position, end of the file) from the Fcntl module. Returns 1 on success,
false otherwise.
seek(TEST,0,1);
for (;;) { for ($curpos = tell(FILE); $_ = <FILE>; $curpos = tell(FILE)) { # search for some stuff and put it into files } sleep($for_a_while); seek(FILE, $curpos, 0); }
- seekdir DIRHANDLE,POS
- Sets the current position for the "readdir" routine on DIRHANDLE. POS must be a value returned by "telldir". "seekdir" also has the same caveats about possible directory compaction as the corresponding system library routine.
- select FILEHANDLE
- select
- Returns the currently selected filehandle. If FILEHANDLE is
supplied, sets the new current default filehandle for output. This has two
effects: first, a "write" or a "print" without a
filehandle default to this FILEHANDLE. Second, references to variables
related to output will refer to this output channel.
select(REPORT1); $^ = 'report1_top'; select(REPORT2); $^ = 'report2_top';
$oldfh = select(STDERR); $| = 1; select($oldfh);
use IO::Handle; STDERR->autoflush(1);
- select RBITS,WBITS,EBITS,TIMEOUT
- This calls the select(2) syscall with the bit masks
specified, which can be constructed using "fileno" and
"vec", along these lines:
$rin = $win = $ein = ''; vec($rin,fileno(STDIN),1) = 1; vec($win,fileno(STDOUT),1) = 1; $ein = $rin | $win;
sub fhbits { my(@fhlist) = split(' ',$_[0]); my($bits); for (@fhlist) { vec($bits,fileno($_),1) = 1; } $bits; } $rin = fhbits('STDIN TTY SOCK');
($nfound,$timeleft) = select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
$nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);
select(undef, undef, undef, 0.25);
- semctl ID,SEMNUM,CMD,ARG
- Calls the System V IPC function semctl(2). You'll
probably have to say
use IPC::SysV;
- semget KEY,NSEMS,FLAGS
- Calls the System V IPC function semget(2). Returns the semaphore id, or the undefined value on error. See also "SysV IPC" in perlipc, "IPC::SysV", "IPC::SysV::Semaphore" documentation.
- semop KEY,OPSTRING
- Calls the System V IPC function semop(2) for
semaphore operations such as signalling and waiting. OPSTRING must be a
packed array of semop structures. Each semop structure can be generated
with "pack("s!3", $semnum, $semop, $semflag)". The
length of OPSTRING implies the number of semaphore operations. Returns
true if successful, false on error. As an example, the following code
waits on semaphore $semnum of semaphore id $semid:
$semop = pack("s!3", $semnum, -1, 0); die "Semaphore trouble: $!\n" unless semop($semid, $semop);
- send SOCKET,MSG,FLAGS,TO
- send SOCKET,MSG,FLAGS
- Sends a message on a socket. Attempts to send the scalar
MSG to the SOCKET filehandle. Takes the same flags as the system call of
the same name. On unconnected sockets, you must specify a destination to
send to, in which case it does a sendto(2) syscall. Returns
the number of characters sent, or the undefined value on error. The
sendmsg(2) syscall is currently unimplemented. See "UDP:
Message Passing" in perlipc for examples.
- setpgrp PID,PGRP
- Sets the current process group for the specified PID, 0 for the current process. Raises an exception when used on a machine that doesn't implement POSIX setpgid(2) or BSD setpgrp(2). If the arguments are omitted, it defaults to "0,0". Note that the BSD 4.2 version of "setpgrp" does not accept any arguments, so only "setpgrp(0,0)" is portable. See also "POSIX::setsid()".
- setpriority WHICH,WHO,PRIORITY
- Sets the current priority for a process, a process group, or a user. (See setpriority(2).) Raises an exception when used on a machine that doesn't implement setpriority(2).
- setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
- Sets the socket option requested. Returns "undef"
on error. Use integer constants provided by the "Socket" module
for LEVEL and OPNAME. Values for LEVEL can also be obtained from
getprotobyname. OPTVAL might either be a packed string or an integer. An
integer OPTVAL is shorthand for pack("i", OPTVAL).
use Socket qw(IPPROTO_TCP TCP_NODELAY); setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
- shift ARRAY
- shift EXPR
- shift
- Shifts the first value of the array off and returns it,
shortening the array by 1 and moving everything down. If there are no
elements in the array, returns the undefined value. If ARRAY is omitted,
shifts the @_ array within the lexical scope of subroutines and formats,
and the @ARGV array outside a subroutine and also within the lexical
scopes established by the "eval STRING", "BEGIN {}",
"INIT {}", "CHECK {}", "UNITCHECK {}", and
"END {}" constructs.
- shmctl ID,CMD,ARG
- Calls the System V IPC function shmctl. You'll probably
have to say
use IPC::SysV;
- shmget KEY,SIZE,FLAGS
- Calls the System V IPC function shmget. Returns the shared memory segment id, or "undef" on error. See also "SysV IPC" in perlipc and "IPC::SysV" documentation.
- shmread ID,VAR,POS,SIZE
- shmwrite ID,STRING,POS,SIZE
- Reads or writes the System V shared memory segment ID starting at position POS for size SIZE by attaching to it, copying in/out, and detaching from it. When reading, VAR must be a variable that will hold the data read. When writing, if STRING is too long, only SIZE bytes are used; if STRING is too short, nulls are written to fill out SIZE bytes. Return true if successful, false on error. shmread() taints the variable. See also "SysV IPC" in perlipc, "IPC::SysV", and the "IPC::Shareable" module from CPAN.
- shutdown SOCKET,HOW
- Shuts down a socket connection in the manner indicated by
HOW, which has the same interpretation as in the syscall of the same name.
shutdown(SOCKET, 0); # I/we have stopped reading data shutdown(SOCKET, 1); # I/we have stopped writing data shutdown(SOCKET, 2); # I/we have stopped using this socket
- sin EXPR
- sin
- Returns the sine of EXPR (expressed in radians). If EXPR is
omitted, returns sine of $_.
sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
- sleep EXPR
- sleep
- Causes the script to sleep for (integer) EXPR seconds, or
forever if no argument is given. Returns the integer number of seconds
actually slept.
eval { local $SIG{ALARM} = sub { die "Alarm!\n" }; sleep; }; die $@ unless $@ eq "Alarm!\n";
- socket SOCKET,DOMAIN,TYPE,PROTOCOL
- Opens a socket of the specified kind and attaches it to
filehandle SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as
for the syscall of the same name. You should "use Socket" first
to get the proper definitions imported. See the examples in "Sockets:
Client/Server Communication" in perlipc.
- socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
- Creates an unnamed pair of sockets in the specified domain,
of the specified type. DOMAIN, TYPE, and PROTOCOL are specified the same
as for the syscall of the same name. If unimplemented, raises an
exception. Returns true if successful.
use Socket; socketpair(Rdr, Wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC); shutdown(Rdr, 1); # no more writing for reader shutdown(Wtr, 0); # no more reading for writer
- sort SUBNAME LIST
- sort BLOCK LIST
- sort LIST
- In list context, this sorts the LIST and returns the sorted
list value. In scalar context, the behaviour of "sort()" is
undefined.
# sort lexically @articles = sort @files; # same thing, but with explicit sort routine @articles = sort {$a cmp $b} @files; # now case-insensitively @articles = sort {uc($a) cmp uc($b)} @files; # same thing in reversed order @articles = sort {$b cmp $a} @files; # sort numerically ascending @articles = sort {$a <=> $b} @files; # sort numerically descending @articles = sort {$b <=> $a} @files; # this sorts the %age hash by value instead of key # using an in-line function @eldest = sort { $age{$b} <=> $age{$a} } keys %age; # sort using explicit subroutine name sub byage { $age{$a} <=> $age{$b}; # presuming numeric } @sortedclass = sort byage @class; sub backwards { $b cmp $a } @harry = qw(dog cat x Cain Abel); @george = qw(gone chased yz Punished Axed); print sort @harry; # prints AbelCaincatdogx print sort backwards @harry; # prints xdogcatCainAbel print sort @george, 'to', @harry; # prints AbelAxedCainPunishedcatchaseddoggonetoxyz # inefficiently sort by descending numeric compare using # the first integer after the first = sign, or the # whole record case-insensitively otherwise my @new = sort { ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0] || uc($a) cmp uc($b) } @old; # same thing, but much more efficiently; # we'll build auxiliary indices instead # for speed my @nums = @caps = (); for (@old) { push @nums, ( /=(\d+)/ ? $1 : undef ); push @caps, uc($_); } my @new = @old[ sort { $nums[$b] <=> $nums[$a] || $caps[$a] cmp $caps[$b] } 0..$#old ]; # same thing, but without any temps @new = map { $_->[0] } sort { $b->[1] <=> $a->[1] || $a->[2] cmp $b->[2] } map { [$_, /=(\d+)/, uc($_)] } @old; # using a prototype allows you to use any comparison subroutine # as a sort subroutine (including other package's subroutines) package other; sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are not set here package main; @new = sort other::backwards @old; # guarantee stability, regardless of algorithm use sort 'stable'; @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old; # force use of mergesort (not portable outside Perl 5.8) use sort '_mergesort'; # note discouraging _ @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
@contact = sort { $a cmp $b } find_records @key; @contact = sort +find_records(@key); @contact = sort &find_records(@key); @contact = sort(find_records(@key));
@contact = sort { find_records() } @key; @contact = sort find_records(@key); @contact = sort(find_records @key); @contact = sort(find_records (@key));
@articles = sort {$b <=> $a} @files;
@articles = sort {$FooPack::b <=> $FooPack::a} @files;
@result = sort { $a <=> $b } grep { $_ == $_ } @input;
- splice ARRAY or EXPR,OFFSET,LENGTH,LIST
- splice ARRAY or EXPR,OFFSET,LENGTH
- splice ARRAY or EXPR,OFFSET
- splice ARRAY or EXPR
- Removes the elements designated by OFFSET and LENGTH from
an array, and replaces them with the elements of LIST, if any. In list
context, returns the elements removed from the array. In scalar context,
returns the last element removed, or "undef" if no elements are
removed. The array grows or shrinks as necessary. If OFFSET is negative
then it starts that far from the end of the array. If LENGTH is omitted,
removes everything from OFFSET onward. If LENGTH is negative, removes the
elements from OFFSET onward except for -LENGTH elements at the end of the
array. If both OFFSET and LENGTH are omitted, removes everything. If
OFFSET is past the end of the array, Perl issues a warning, and splices at
the end of the array.
push(@a,$x,$y) splice(@a,@a,0,$x,$y) pop(@a) splice(@a,-1) shift(@a) splice(@a,0,1) unshift(@a,$x,$y) splice(@a,0,0,$x,$y) $a[$i] = $y splice(@a,$i,1,$y)
sub aeq { # compare two list values my(@a) = splice(@_,0,shift); my(@b) = splice(@_,0,shift); return 0 unless @a == @b; # same len? while (@a) { return 0 if pop(@a) ne pop(@b); } return 1; } if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
- split /PATTERN/,EXPR,LIMIT
- split /PATTERN/,EXPR
- split /PATTERN/
- split
- Splits the string EXPR into a list of strings and returns
that list. By default, empty leading fields are preserved, and empty
trailing ones are deleted. (If all fields are empty, they are considered
to be trailing.)
print join(':', split(/ */, 'hi there')), "\n";
print join(':', split(//, 'hi there')), "\n";
print join(':', split(/(?=\w)/, 'hi there!'));
print join(':', split(//, 'hi there!', -1)), "\n"; print join(':', split(/\W/, 'hi there!', -1)), "\n";
($login, $passwd, $remainder) = split(/:/, $_, 3);
split(/([,-])/, "1-10,20", 3);
(1, '-', 10, ',', 20)
$header =~ s/\n(?=\s)//g; # fix continuation lines %hdrs = (UNIX_FROM => split /^(\S*?):\s*/m, $header);
open(PASSWD, '/etc/passwd'); while (<PASSWD>) { chomp; ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(/:/); #... }
@fields = split /(A)|B/, "1A2B3"; # @fields is (1, 'A', 2, undef, 3)
- sprintf FORMAT, LIST
- Returns a string formatted by the usual "printf"
conventions of the C library function "sprintf". See below for
more details and see sprintf(3) or printf(3) on your system for an
explanation of the general principles.
# Format number with up to 8 leading zeroes $result = sprintf("%08d", $number); # Round number to 3 digits after decimal point $rounded = sprintf("%.3f", $number);
%% a percent sign %c a character with the given number %s a string %d a signed integer, in decimal %u an unsigned integer, in decimal %o an unsigned integer, in octal %x an unsigned integer, in hexadecimal %e a floating-point number, in scientific notation %f a floating-point number, in fixed decimal notation %g a floating-point number, in %e or %f notation
%X like %x, but using upper-case letters %E like %e, but using an upper-case "E" %G like %g, but with an upper-case "E" (if applicable) %b an unsigned integer, in binary %B like %b, but using an upper-case "B" with the # flag %p a pointer (outputs the Perl value's address in hexadecimal) %n special: *stores* the number of characters output so far into the next variable in the parameter list
%i a synonym for %d %D a synonym for %ld %U a synonym for %lu %O a synonym for %lo %F a synonym for %f
- format parameter index
- An explicit format parameter index, such as "2$".
By default sprintf will format the next unused argument in the list, but
this allows you to take the arguments out of order:
printf '%2$d %1$d', 12, 34; # prints "34 12" printf '%3$d %d %1$d', 1, 2, 3; # prints "3 1 1"
- flags
- one or more of:
space prefix non-negative number with a space + prefix non-negative number with a plus sign - left-justify within the field 0 use zeros, not spaces, to right-justify # ensure the leading "0" for any octal, prefix non-zero hexadecimal with "0x" or "0X", prefix non-zero binary with "0b" or "0B"
printf '<% d>', 12; # prints "< 12>" printf '<%+d>', 12; # prints "<+12>" printf '<%6s>', 12; # prints "< 12>" printf '<%-6s>', 12; # prints "<12 >" printf '<%06s>', 12; # prints "<000012>" printf '<%#o>', 12; # prints "<014>" printf '<%#x>', 12; # prints "<0xc>" printf '<%#X>', 12; # prints "<0XC>" printf '<%#b>', 12; # prints "<0b1100>" printf '<%#B>', 12; # prints "<0B1100>"
printf '<%+ d>', 12; # prints "<+12>" printf '<% +d>', 12; # prints "<+12>"
printf '<%#.5o>', 012; # prints "<00012>" printf '<%#.5o>', 012345; # prints "<012345>" printf '<%#.0o>', 0; # prints "<0>"
- vector flag
- This flag tells Perl to interpret the supplied string as a
vector of integers, one for each character in the string. Perl applies the
format to each integer in turn, then joins the resulting strings with a
separator (a dot "." by default). This can be useful for
displaying ordinal values of characters in arbitrary strings:
printf "%vd", "AB\x{100}"; # prints "65.66.256" printf "version is v%vd\n", $^V; # Perl's version
printf "address is %*vX\n", ":", $addr; # IPv6 address printf "bits are %0*v8b\n", " ", $bits; # random bitstring
printf '%*4$vX %*4$vX %*4$vX', @addr[1..3], ":"; # 3 IPv6 addresses
- (minimum) width
- Arguments are usually formatted to be only as wide as
required to display the given value. You can override the width by putting
a number here, or get the width from the next argument (with
"*") or from a specified argument (e.g., with "*2$"):
printf "<%s>", "a"; # prints "<a>" printf "<%6s>", "a"; # prints "< a>" printf "<%*s>", 6, "a"; # prints "< a>" printf "<%*2$s>", "a", 6; # prints "< a>" printf "<%2s>", "long"; # prints "<long>" (does not truncate)
- precision, or maximum width
- You can specify a precision (for numeric conversions) or a
maximum width (for string conversions) by specifying a "."
followed by a number. For floating-point formats except "g" and
"G", this specifies how many places right of the decimal point
to show (the default being 6). For example:
# these examples are subject to system-specific variation printf '<%f>', 1; # prints "<1.000000>" printf '<%.1f>', 1; # prints "<1.0>" printf '<%.0f>', 1; # prints "<1>" printf '<%e>', 10; # prints "<1.000000e+01>" printf '<%.1e>', 10; # prints "<1.0e+01>"
# These examples are subject to system-specific variation. printf '<%g>', 1; # prints "<1>" printf '<%.10g>', 1; # prints "<1>" printf '<%g>', 100; # prints "<100>" printf '<%.1g>', 100; # prints "<1e+02>" printf '<%.2g>', 100.01; # prints "<1e+02>" printf '<%.5g>', 100.01; # prints "<100.01>" printf '<%.4g>', 100.01; # prints "<100>"
printf '<%.6d>', 1; # prints "<000001>" printf '<%+.6d>', 1; # prints "<+000001>" printf '<%-10.6d>', 1; # prints "<000001 >" printf '<%10.6d>', 1; # prints "< 000001>" printf '<%010.6d>', 1; # prints "< 000001>" printf '<%+10.6d>', 1; # prints "< +000001>" printf '<%.6x>', 1; # prints "<000001>" printf '<%#.6x>', 1; # prints "<0x000001>" printf '<%-10.6x>', 1; # prints "<000001 >" printf '<%10.6x>', 1; # prints "< 000001>" printf '<%010.6x>', 1; # prints "< 000001>" printf '<%#10.6x>', 1; # prints "< 0x000001>"
printf '<%.5s>', "truncated"; # prints "<trunc>" printf '<%10.5s>', "truncated"; # prints "< trunc>"
printf '<%.6x>', 1; # prints "<000001>" printf '<%.*x>', 6, 1; # prints "<000001>"
printf '<%.*s>', 7, "string"; # prints "<string>" printf '<%.*s>', 3, "string"; # prints "<str>" printf '<%.*s>', 0, "string"; # prints "<>" printf '<%.*s>', -1, "string"; # prints "<string>" printf '<%.*d>', 1, 0; # prints "<0>" printf '<%.*d>', 0, 0; # prints "<>" printf '<%.*d>', -1, 0; # prints "<0>"
printf "<%.*2$x>", 1, 6; # INVALID, but in future will print "<000001>"
- size
- For numeric conversions, you can specify the size to
interpret the number as using "l", "h", "V",
"q", "L", or "ll". For integer conversions
("d u o x X b i D U O"), numbers are usually assumed to be
whatever the default integer size is on your platform (usually 32 or 64
bits), but you can override this to use instead one of the standard C
types, as supported by the compiler used to build Perl:
hh interpret integer as C type "char" or "unsigned char" on Perl 5.14 or later h interpret integer as C type "short" or "unsigned short" j intepret integer as C type "intmax_t" on Perl 5.14 or later, and only with a C99 compiler (unportable) l interpret integer as C type "long" or "unsigned long" q, L, or ll interpret integer as C type "long long", "unsigned long long", or "quad" (typically 64-bit integers) t intepret integer as C type "ptrdiff_t" on Perl 5.14 or later z intepret integer as C type "size_t" on Perl 5.14 or later
use warnings FATAL => "printf";
use 5.014; # for hh/j/t/z/ printf modifiers
use Config; if ($Config{use64bitint} eq "define" || $Config{longsize} >= 8) { print "Nice quads!\n"; }
use Config; print "long doubles\n" if $Config{d_longdbl} eq "define";
use Config; if ($Config{uselongdouble} eq "define") { print "long doubles by default\n"; }
use Config; ($Config{doublesize} == $Config{longdblsize}) && print "doubles are long doubles\n";
- order of arguments
- Normally, sprintf() takes the next unused argument
as the value to format for each format specification. If the format
specification uses "*" to require additional arguments, these
are consumed from the argument list in the order they appear in the format
specification before the value to format. Where an argument is
specified by an explicit index, this does not affect the normal order for
the arguments, even when the explicitly specified index would have been
the next argument.
printf "<%*.*s>", $a, $b, $c;
printf "<%*1$.*s>", $a, $b;
printf "%2\$d %d\n", 12, 34; # will print "34 12\n" printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n" printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n" printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n"
- sqrt EXPR
- sqrt
- Return the positive square root of EXPR. If EXPR is
omitted, uses $_. Works only for non-negative operands unless you've
loaded the "Math::Complex" module.
use Math::Complex; print sqrt(-4); # prints 2i
- srand EXPR
- srand
- Sets and returns the random number seed for the
"rand" operator.
srand (time ^ $$ ^ unpack "%L*", `ps axww | gzip -f`);
time ^ $$
a^b == (a+1)^(b+1)
- stat FILEHANDLE
- stat EXPR
- stat DIRHANDLE
- stat
- Returns a 13-element list giving the status info for a
file, either the file opened via FILEHANDLE or DIRHANDLE, or named by
EXPR. If EXPR is omitted, it stats $_ (not "_"!). Returns the
empty list if "stat" fails. Typically used as follows:
($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size, $atime,$mtime,$ctime,$blksize,$blocks) = stat($filename);
0 dev device number of filesystem 1 ino inode number 2 mode file mode (type and permissions) 3 nlink number of (hard) links to the file 4 uid numeric user ID of file's owner 5 gid numeric group ID of file's owner 6 rdev the device identifier (special files only) 7 size total size of file, in bytes 8 atime last access time in seconds since the epoch 9 mtime last modify time in seconds since the epoch 10 ctime inode change time in seconds since the epoch (*) 11 blksize preferred block size for file system I/O 12 blocks actual number of blocks allocated
if (-x $file && (($d) = stat(_)) && $d < 0) { print "$file is executable NFS file\n"; }
$mode = (stat($filename))[2]; printf "Permissions are %04o\n", $mode & 07777;
use File::stat; $sb = stat($filename); printf "File is %s, size is %s, perm %04o, mtime %s\n", $filename, $sb->size, $sb->mode & 07777, scalar localtime $sb->mtime;
use Fcntl ':mode'; $mode = (stat($filename))[2]; $user_rwx = ($mode & S_IRWXU) >> 6; $group_read = ($mode & S_IRGRP) >> 3; $other_execute = $mode & S_IXOTH; printf "Permissions are %04o\n", S_IMODE($mode), "\n"; $is_setuid = $mode & S_ISUID; $is_directory = S_ISDIR($mode);
# Permissions: read, write, execute, for user, group, others. S_IRWXU S_IRUSR S_IWUSR S_IXUSR S_IRWXG S_IRGRP S_IWGRP S_IXGRP S_IRWXO S_IROTH S_IWOTH S_IXOTH # Setuid/Setgid/Stickiness/SaveText. # Note that the exact meaning of these is system dependent. S_ISUID S_ISGID S_ISVTX S_ISTXT # File types. Not necessarily all are available on your system. S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT # The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR. S_IREAD S_IWRITE S_IEXEC
S_IMODE($mode) the part of $mode containing the permission bits and the setuid/setgid/sticky bits S_IFMT($mode) the part of $mode containing the file type which can be bit-anded with (for example) S_IFREG or with the following functions # The operators -f, -d, -l, -b, -c, -p, and -S. S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode) S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode) # No direct -X operator counterpart, but for the first one # the -g operator is often equivalent. The ENFMT stands for # record flocking enforcement, a platform-dependent feature. S_ISENFMT($mode) S_ISWHT($mode)
- state EXPR
- state TYPE EXPR
- state EXPR : ATTRS
- state TYPE EXPR : ATTRS
- "state" declares a lexically scoped variable,
just like "my" does. However, those variables will never be
reinitialized, contrary to lexical variables that are reinitialized each
time their enclosing block is entered.
- study SCALAR
- study
- Takes extra time to study SCALAR ($_ if unspecified) in
anticipation of doing many pattern matches on the string before it is next
modified. This may or may not save time, depending on the nature and
number of patterns you are searching and the distribution of character
frequencies in the string to be searched; you probably want to compare run
times with and without it to see which is faster. Those loops that scan
for many short constant strings (including the constant parts of more
complex patterns) will benefit most. You may have only one
"study" active at a time: if you study a different scalar the
first is "unstudied". (The way "study" works is this:
a linked list of every character in the string to be searched is made, so
we know, for example, where all the 'k' characters are. From each search
string, the rarest character is selected, based on some static frequency
tables constructed from some C programs and English text. Only those
places that contain this "rarest" character are examined.)
while (<>) { study; print ".IX foo\n" if /\bfoo\b/; print ".IX bar\n" if /\bbar\b/; print ".IX blurfl\n" if /\bblurfl\b/; # ... print; }
$search = 'while (<>) { study;'; foreach $word (@words) { $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n"; } $search .= "}"; @ARGV = @files; undef $/; eval $search; # this screams $/ = "\n"; # put back to normal input delimiter foreach $file (sort keys(%seen)) { print $file, "\n"; }
- sub NAME BLOCK
- sub NAME (PROTO) BLOCK
- sub NAME : ATTRS BLOCK
- sub NAME (PROTO) : ATTRS BLOCK
- This is subroutine definition, not a real function per
se. Without a BLOCK it's just a forward declaration. Without a NAME,
it's an anonymous function declaration, so does return a value: the CODE
ref of the closure just created.
- substr EXPR,OFFSET,LENGTH,REPLACEMENT
- substr EXPR,OFFSET,LENGTH
- substr EXPR,OFFSET
- Extracts a substring out of EXPR and returns it. First
character is at offset 0 (or whatever you've set $[ to (but <don't
do that)). If OFFSET is negative (or more precisely, less than $[),
starts that far back from the end of the string. If LENGTH is omitted,
returns everything through the end of the string. If LENGTH is negative,
leaves that many characters off the end of the string.
my $s = "The black cat climbed the green tree"; my $color = substr $s, 4, 5; # black my $middle = substr $s, 4, -11; # black cat climbed the my $end = substr $s, 14; # climbed the green tree my $tail = substr $s, -4; # tree my $z = substr $s, -4, 2; # tr
my $name = 'fred'; substr($name, 4) = 'dy'; # $name is now 'freddy' my $null = substr $name, 6, 2; # returns "" (no warning) my $oops = substr $name, 7; # returns undef, with warning substr($name, 7) = 'gap'; # raises an exception
my $s = "The black cat climbed the green tree"; my $z = substr $s, 14, 7, "jumped from"; # climbed # $s is now "The black cat jumped from the green tree"
$x = '1234'; for (substr($x,1,2)) { $_ = 'a'; print $x,"\n"; # prints 1a4 $_ = 'xyz'; print $x,"\n"; # prints 1xyz4 $x = '56789'; $_ = 'pq'; print $x,"\n"; # prints 5pq9 }
- symlink OLDFILE,NEWFILE
- Creates a new filename symbolically linked to the old
filename. Returns 1 for success, 0 otherwise. On systems that don't
support symbolic links, raises an exception. To check for that, use eval:
$symlink_exists = eval { symlink("",""); 1 };
- syscall NUMBER, LIST
- Calls the system call specified as the first element of the
list, passing the remaining elements as arguments to the system call. If
unimplemented, raises an exception. The arguments are interpreted as
follows: if a given argument is numeric, the argument is passed as an int.
If not, the pointer to the string value is passed. You are responsible to
make sure a string is pre-extended long enough to receive any result that
might be written into a string. You can't use a string literal (or other
read-only string) as an argument to "syscall" because Perl has
to assume that any string pointer might be written through. If your
integer arguments are not literals and have never been interpreted in a
numeric context, you may need to add 0 to them to force them to look like
numbers. This emulates the "syswrite" function (or vice versa):
require 'syscall.ph'; # may need to run h2ph $s = "hi there\n"; syscall(&SYS_write, fileno(STDOUT), $s, length $s);
- sysopen FILEHANDLE,FILENAME,MODE
- sysopen FILEHANDLE,FILENAME,MODE,PERMS
- Opens the file whose filename is given by FILENAME, and
associates it with FILEHANDLE. If FILEHANDLE is an expression, its value
is used as the real filehandle wanted; an undefined scalar will be
suitably autovivified. This function calls the underlying operating
system's open(2) function with the parameters FILENAME, MODE, and
PERMS.
- sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
- sysread FILEHANDLE,SCALAR,LENGTH
- Attempts to read LENGTH bytes of data into variable SCALAR
from the specified FILEHANDLE, using the read(2). It bypasses
buffered IO, so mixing this with other kinds of reads, "print",
"write", "seek", "tell", or "eof"
can cause confusion because the perlio or stdio layers usually buffers
data. Returns the number of bytes actually read, 0 at end of file, or
undef if there was an error (in the latter case $! is also set). SCALAR
will be grown or shrunk so that the last byte actually read is the last
byte of the scalar after the read.
- sysseek FILEHANDLE,POSITION,WHENCE
- Sets FILEHANDLE's system position in bytes using
lseek(2). FILEHANDLE may be an expression whose value gives the
name of the filehandle. The values for WHENCE are 0 to set the new
position to POSITION; 1 to set the it to the current position plus
POSITION; and 2 to set it to EOF plus POSITION, typically negative.
use Fcntl 'SEEK_CUR'; sub systell { sysseek($_[0], 0, SEEK_CUR) }
- system LIST
- system PROGRAM LIST
- Does exactly the same thing as "exec LIST",
except that a fork is done first and the parent process waits for the
child process to exit. Note that argument processing varies depending on
the number of arguments. If there is more than one argument in LIST, or if
LIST is an array with more than one value, starts the program given by the
first element of the list with arguments given by the rest of the list. If
there is only one scalar argument, the argument is checked for shell
metacharacters, and if there are any, the entire argument is passed to the
system's command shell for parsing (this is "/bin/sh -c" on Unix
platforms, but varies on other platforms). If there are no shell
metacharacters in the argument, it is split into words and passed directly
to "execvp", which is more efficient.
@args = ("command", "arg1", "arg2"); system(@args) == 0 or die "system @args failed: $?"
if ($? == -1) { print "failed to execute: $!\n"; } elsif ($? & 127) { printf "child died with signal %d, %s coredump\n", ($? & 127), ($? & 128) ? 'with' : 'without'; } else { printf "child exited with value %d\n", $? >> 8; }
- syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
- syswrite FILEHANDLE,SCALAR,LENGTH
- syswrite FILEHANDLE,SCALAR
- Attempts to write LENGTH bytes of data from variable SCALAR
to the specified FILEHANDLE, using write(2). If LENGTH is not
specified, writes whole SCALAR. It bypasses buffered IO, so mixing this
with reads (other than sysread()), "print", "write",
"seek", "tell", or "eof" may cause confusion
because the perlio and stdio layers usually buffer data. Returns the
number of bytes actually written, or "undef" if there was an
error (in this case the errno variable $! is also set). If the LENGTH is
greater than the data available in the SCALAR after the OFFSET, only as
much data as is available will be written.
- tell FILEHANDLE
- tell
- Returns the current position in bytes for
FILEHANDLE, or -1 on error. FILEHANDLE may be an expression whose value
gives the name of the actual filehandle. If FILEHANDLE is omitted, assumes
the file last read.
- telldir DIRHANDLE
- Returns the current position of the "readdir" routines on DIRHANDLE. Value may be given to "seekdir" to access a particular location in a directory. "telldir" has the same caveats about possible directory compaction as the corresponding system library routine.
- tie VARIABLE,CLASSNAME,LIST
- This function binds a variable to a package class that will
provide the implementation for the variable. VARIABLE is the name of the
variable to be enchanted. CLASSNAME is the name of a class implementing
objects of correct type. Any additional arguments are passed to the
"new" method of the class (meaning "TIESCALAR",
"TIEHANDLE", "TIEARRAY", or "TIEHASH").
Typically these are arguments such as might be passed to the
"dbm_open()" function of C. The object returned by the
"new" method is also returned by the "tie" function,
which would be useful if you want to access other methods in CLASSNAME.
# print out history file offsets use NDBM_File; tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0); while (($key,$val) = each %HIST) { print $key, ' = ', unpack('L',$val), "\n"; } untie(%HIST);
TIEHASH classname, LIST FETCH this, key STORE this, key, value DELETE this, key CLEAR this EXISTS this, key FIRSTKEY this NEXTKEY this, lastkey SCALAR this DESTROY this UNTIE this
TIEARRAY classname, LIST FETCH this, key STORE this, key, value FETCHSIZE this STORESIZE this, count CLEAR this PUSH this, LIST POP this SHIFT this UNSHIFT this, LIST SPLICE this, offset, length, LIST EXTEND this, count DESTROY this UNTIE this
TIEHANDLE classname, LIST READ this, scalar, length, offset READLINE this GETC this WRITE this, scalar, length, offset PRINT this, LIST PRINTF this, format, LIST BINMODE this EOF this FILENO this SEEK this, position, whence TELL this OPEN this, mode, LIST CLOSE this DESTROY this UNTIE this
TIESCALAR classname, LIST FETCH this, STORE this, value DESTROY this UNTIE this
- tied VARIABLE
- Returns a reference to the object underlying VARIABLE (the same value that was originally returned by the "tie" call that bound the variable to a package.) Returns the undefined value if VARIABLE isn't tied to a package.
- time
- Returns the number of non-leap seconds since whatever time
the system considers to be the epoch, suitable for feeding to
"gmtime" and "localtime". On most systems the epoch is
00:00:00 UTC, January 1, 1970; a prominent exception being Mac OS Classic
which uses 00:00:00, January 1, 1904 in the current local time zone for
its epoch.
- times
- Returns a four-element list giving the user and system
times in seconds for this process and any exited children of this process.
($user,$system,$cuser,$csystem) = times;
- tr///
- The transliteration operator. Same as "y///". See "Quote and Quote-like Operators" in perlop.
- truncate FILEHANDLE,LENGTH
- truncate EXPR,LENGTH
- Truncates the file opened on FILEHANDLE, or named by EXPR,
to the specified length. Raises an exception if truncate isn't implemented
on your system. Returns true if successful, "undef" on error.
- uc EXPR
- uc
- Returns an uppercased version of EXPR. This is the internal
function implementing the "\U" escape in double-quoted strings.
It does not attempt to do titlecase mapping on initial letters. See
"ucfirst" for that.
- ucfirst EXPR
- ucfirst
- Returns the value of EXPR with the first character in
uppercase (titlecase in Unicode). This is the internal function
implementing the "\u" escape in double-quoted strings.
- umask EXPR
- umask
- Sets the umask for the process to EXPR and returns the
previous value. If EXPR is omitted, merely returns the current umask.
- undef EXPR
- undef
- Undefines the value of EXPR, which must be an lvalue. Use
only on a scalar value, an array (using "@"), a hash (using
"%"), a subroutine (using "&"), or a typeglob
(using "*"). Saying "undef $hash{$key}" will probably
not do what you expect on most predefined variables or DBM list values, so
don't do that; see delete. Always returns the undefined value. You can
omit the EXPR, in which case nothing is undefined, but you still get an
undefined value that you could, for instance, return from a subroutine,
assign to a variable, or pass as a parameter. Examples:
undef $foo; undef $bar{'blurfl'}; # Compare to: delete $bar{'blurfl'}; undef @ary; undef %hash; undef &mysub; undef *xyz; # destroys $xyz, @xyz, %xyz, &xyz, etc. return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it; select undef, undef, undef, 0.25; ($a, $b, undef, $c) = &foo; # Ignore third value returned
- unlink LIST
- unlink
- Deletes a list of files. On success, it returns the number
of files it successfully deleted. On failure, it returns false and sets $!
(errno):
my $unlinked = unlink 'a', 'b', 'c'; unlink @goners; unlink glob "*.bak";
foreach my $file ( @goners ) { unlink $file or warn "Could not unlink $file: $!"; }
- unpack TEMPLATE,EXPR
- unpack TEMPLATE
- "unpack" does the reverse of "pack": it
takes a string and expands it out into a list of values. (In scalar
context, it returns merely the first value produced.)
sub substr { my($what,$where,$howmuch) = @_; unpack("x$where a$howmuch", $what); }
sub ordinal { unpack("W",$_[0]); } # same as ord()
$checksum = do { local $/; # slurp! unpack("%32W*",<>) % 65535; };
$setbits = unpack("%32b*", $selectmask);
- untie VARIABLE
- Breaks the binding between a variable and a package. (See "tie".) Has no effect if the variable is not tied.
- unshift ARRAY,LIST
- unshift EXPR,LIST
- Does the opposite of a "shift". Or the opposite
of a "push", depending on how you look at it. Prepends list to
the front of the array and returns the new number of elements in the
array.
unshift(@ARGV, '-e') unless $ARGV[0] =~ /^-/;
- use Module VERSION LIST
- use Module VERSION
- use Module LIST
- use Module
- use VERSION
- Imports some semantics into the current package from the
named module, generally by aliasing certain subroutine or variable names
into your package. It is exactly equivalent to
BEGIN { require Module; Module->import( LIST ); }
use v5.6.1; # compile time version check use 5.6.1; # ditto use 5.006_001; # ditto; preferred for backwards compatibility
use Module ();
BEGIN { require Module }
use constant; use diagnostics; use integer; use sigtrap qw(SEGV BUS); use strict qw(subs vars refs); use subs qw(afunc blurfl); use warnings qw(all); use sort qw(stable _quicksort _mergesort);
use if $] < 5.008, "utf8"; use if WANT_WARNINGS, warnings => qw(all);
no integer; no strict 'refs'; no warnings;
- utime LIST
- Changes the access and modification times on each file of a
list of files. The first two elements of the list must be the NUMERIC
access and modification times, in that order. Returns the number of files
successfully changed. The inode change time of each file is set to the
current time. For example, this code has the same effect as the Unix
touch(1) command when the files already exist and belong to
the user running the program:
#!/usr/bin/perl $atime = $mtime = time; utime $atime, $mtime, @ARGV;
for $file (@ARGV) { utime(undef, undef, $file) || warn "couldn't touch $file: $!"; }
- values HASH
- values ARRAY
- values EXPR
- Returns a list consisting of all the values of the named
hash, or the values of an array. (In scalar context, returns the number of
values.)
for (values %hash) { s/foo/bar/g } # modifies %hash values for (@hash{keys %hash}) { s/foo/bar/g } # same
for (values $hashref) { ... } for (values $obj->get_arrayref) { ... }
- vec EXPR,OFFSET,BITS
- Treats the string in EXPR as a bit vector made up of
elements of width BITS and returns the value of the element specified by
OFFSET as an unsigned integer. BITS therefore specifies the number of bits
that are reserved for each element in the bit vector. This must be a power
of two from 1 to 32 (or 64, if your platform supports that).
vec($image, $max_x * $x + $y, 8) = 3;
my $foo = ''; vec($foo, 0, 32) = 0x5065726C; # 'Perl' # $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits print vec($foo, 0, 8); # prints 80 == 0x50 == ord('P') vec($foo, 2, 16) = 0x5065; # 'PerlPe' vec($foo, 3, 16) = 0x726C; # 'PerlPerl' vec($foo, 8, 8) = 0x50; # 'PerlPerlP' vec($foo, 9, 8) = 0x65; # 'PerlPerlPe' vec($foo, 20, 4) = 2; # 'PerlPerlPe' . "\x02" vec($foo, 21, 4) = 7; # 'PerlPerlPer' # 'r' is "\x72" vec($foo, 45, 2) = 3; # 'PerlPerlPer' . "\x0c" vec($foo, 93, 1) = 1; # 'PerlPerlPer' . "\x2c" vec($foo, 94, 1) = 1; # 'PerlPerlPerl' # 'l' is "\x6c"
$bits = unpack("b*", $vector); @bits = split(//, unpack("b*", $vector));
#!/usr/bin/perl -wl print <<'EOT'; 0 1 2 3 unpack("V",$_) 01234567890123456789012345678901 ------------------------------------------------------------------ EOT for $w (0..3) { $width = 2**$w; for ($shift=0; $shift < $width; ++$shift) { for ($off=0; $off < 32/$width; ++$off) { $str = pack("B*", "0"x32); $bits = (1<<$shift); vec($str, $off, $width) = $bits; $res = unpack("b*",$str); $val = unpack("V", $str); write; } } } format STDOUT = vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> $off, $width, $bits, $val, $res . __END__
0 1 2 3 unpack("V",$_) 01234567890123456789012345678901 ------------------------------------------------------------------ vec($_, 0, 1) = 1 == 1 10000000000000000000000000000000 vec($_, 1, 1) = 1 == 2 01000000000000000000000000000000 vec($_, 2, 1) = 1 == 4 00100000000000000000000000000000 vec($_, 3, 1) = 1 == 8 00010000000000000000000000000000 vec($_, 4, 1) = 1 == 16 00001000000000000000000000000000 vec($_, 5, 1) = 1 == 32 00000100000000000000000000000000 vec($_, 6, 1) = 1 == 64 00000010000000000000000000000000 vec($_, 7, 1) = 1 == 128 00000001000000000000000000000000 vec($_, 8, 1) = 1 == 256 00000000100000000000000000000000 vec($_, 9, 1) = 1 == 512 00000000010000000000000000000000 vec($_,10, 1) = 1 == 1024 00000000001000000000000000000000 vec($_,11, 1) = 1 == 2048 00000000000100000000000000000000 vec($_,12, 1) = 1 == 4096 00000000000010000000000000000000 vec($_,13, 1) = 1 == 8192 00000000000001000000000000000000 vec($_,14, 1) = 1 == 16384 00000000000000100000000000000000 vec($_,15, 1) = 1 == 32768 00000000000000010000000000000000 vec($_,16, 1) = 1 == 65536 00000000000000001000000000000000 vec($_,17, 1) = 1 == 131072 00000000000000000100000000000000 vec($_,18, 1) = 1 == 262144 00000000000000000010000000000000 vec($_,19, 1) = 1 == 524288 00000000000000000001000000000000 vec($_,20, 1) = 1 == 1048576 00000000000000000000100000000000 vec($_,21, 1) = 1 == 2097152 00000000000000000000010000000000 vec($_,22, 1) = 1 == 4194304 00000000000000000000001000000000 vec($_,23, 1) = 1 == 8388608 00000000000000000000000100000000 vec($_,24, 1) = 1 == 16777216 00000000000000000000000010000000 vec($_,25, 1) = 1 == 33554432 00000000000000000000000001000000 vec($_,26, 1) = 1 == 67108864 00000000000000000000000000100000 vec($_,27, 1) = 1 == 134217728 00000000000000000000000000010000 vec($_,28, 1) = 1 == 268435456 00000000000000000000000000001000 vec($_,29, 1) = 1 == 536870912 00000000000000000000000000000100 vec($_,30, 1) = 1 == 1073741824 00000000000000000000000000000010 vec($_,31, 1) = 1 == 2147483648 00000000000000000000000000000001 vec($_, 0, 2) = 1 == 1 10000000000000000000000000000000 vec($_, 1, 2) = 1 == 4 00100000000000000000000000000000 vec($_, 2, 2) = 1 == 16 00001000000000000000000000000000 vec($_, 3, 2) = 1 == 64 00000010000000000000000000000000 vec($_, 4, 2) = 1 == 256 00000000100000000000000000000000 vec($_, 5, 2) = 1 == 1024 00000000001000000000000000000000 vec($_, 6, 2) = 1 == 4096 00000000000010000000000000000000 vec($_, 7, 2) = 1 == 16384 00000000000000100000000000000000 vec($_, 8, 2) = 1 == 65536 00000000000000001000000000000000 vec($_, 9, 2) = 1 == 262144 00000000000000000010000000000000 vec($_,10, 2) = 1 == 1048576 00000000000000000000100000000000 vec($_,11, 2) = 1 == 4194304 00000000000000000000001000000000 vec($_,12, 2) = 1 == 16777216 00000000000000000000000010000000 vec($_,13, 2) = 1 == 67108864 00000000000000000000000000100000 vec($_,14, 2) = 1 == 268435456 00000000000000000000000000001000 vec($_,15, 2) = 1 == 1073741824 00000000000000000000000000000010 vec($_, 0, 2) = 2 == 2 01000000000000000000000000000000 vec($_, 1, 2) = 2 == 8 00010000000000000000000000000000 vec($_, 2, 2) = 2 == 32 00000100000000000000000000000000 vec($_, 3, 2) = 2 == 128 00000001000000000000000000000000 vec($_, 4, 2) = 2 == 512 00000000010000000000000000000000 vec($_, 5, 2) = 2 == 2048 00000000000100000000000000000000 vec($_, 6, 2) = 2 == 8192 00000000000001000000000000000000 vec($_, 7, 2) = 2 == 32768 00000000000000010000000000000000 vec($_, 8, 2) = 2 == 131072 00000000000000000100000000000000 vec($_, 9, 2) = 2 == 524288 00000000000000000001000000000000 vec($_,10, 2) = 2 == 2097152 00000000000000000000010000000000 vec($_,11, 2) = 2 == 8388608 00000000000000000000000100000000 vec($_,12, 2) = 2 == 33554432 00000000000000000000000001000000 vec($_,13, 2) = 2 == 134217728 00000000000000000000000000010000 vec($_,14, 2) = 2 == 536870912 00000000000000000000000000000100 vec($_,15, 2) = 2 == 2147483648 00000000000000000000000000000001 vec($_, 0, 4) = 1 == 1 10000000000000000000000000000000 vec($_, 1, 4) = 1 == 16 00001000000000000000000000000000 vec($_, 2, 4) = 1 == 256 00000000100000000000000000000000 vec($_, 3, 4) = 1 == 4096 00000000000010000000000000000000 vec($_, 4, 4) = 1 == 65536 00000000000000001000000000000000 vec($_, 5, 4) = 1 == 1048576 00000000000000000000100000000000 vec($_, 6, 4) = 1 == 16777216 00000000000000000000000010000000 vec($_, 7, 4) = 1 == 268435456 00000000000000000000000000001000 vec($_, 0, 4) = 2 == 2 01000000000000000000000000000000 vec($_, 1, 4) = 2 == 32 00000100000000000000000000000000 vec($_, 2, 4) = 2 == 512 00000000010000000000000000000000 vec($_, 3, 4) = 2 == 8192 00000000000001000000000000000000 vec($_, 4, 4) = 2 == 131072 00000000000000000100000000000000 vec($_, 5, 4) = 2 == 2097152 00000000000000000000010000000000 vec($_, 6, 4) = 2 == 33554432 00000000000000000000000001000000 vec($_, 7, 4) = 2 == 536870912 00000000000000000000000000000100 vec($_, 0, 4) = 4 == 4 00100000000000000000000000000000 vec($_, 1, 4) = 4 == 64 00000010000000000000000000000000 vec($_, 2, 4) = 4 == 1024 00000000001000000000000000000000 vec($_, 3, 4) = 4 == 16384 00000000000000100000000000000000 vec($_, 4, 4) = 4 == 262144 00000000000000000010000000000000 vec($_, 5, 4) = 4 == 4194304 00000000000000000000001000000000 vec($_, 6, 4) = 4 == 67108864 00000000000000000000000000100000 vec($_, 7, 4) = 4 == 1073741824 00000000000000000000000000000010 vec($_, 0, 4) = 8 == 8 00010000000000000000000000000000 vec($_, 1, 4) = 8 == 128 00000001000000000000000000000000 vec($_, 2, 4) = 8 == 2048 00000000000100000000000000000000 vec($_, 3, 4) = 8 == 32768 00000000000000010000000000000000 vec($_, 4, 4) = 8 == 524288 00000000000000000001000000000000 vec($_, 5, 4) = 8 == 8388608 00000000000000000000000100000000 vec($_, 6, 4) = 8 == 134217728 00000000000000000000000000010000 vec($_, 7, 4) = 8 == 2147483648 00000000000000000000000000000001 vec($_, 0, 8) = 1 == 1 10000000000000000000000000000000 vec($_, 1, 8) = 1 == 256 00000000100000000000000000000000 vec($_, 2, 8) = 1 == 65536 00000000000000001000000000000000 vec($_, 3, 8) = 1 == 16777216 00000000000000000000000010000000 vec($_, 0, 8) = 2 == 2 01000000000000000000000000000000 vec($_, 1, 8) = 2 == 512 00000000010000000000000000000000 vec($_, 2, 8) = 2 == 131072 00000000000000000100000000000000 vec($_, 3, 8) = 2 == 33554432 00000000000000000000000001000000 vec($_, 0, 8) = 4 == 4 00100000000000000000000000000000 vec($_, 1, 8) = 4 == 1024 00000000001000000000000000000000 vec($_, 2, 8) = 4 == 262144 00000000000000000010000000000000 vec($_, 3, 8) = 4 == 67108864 00000000000000000000000000100000 vec($_, 0, 8) = 8 == 8 00010000000000000000000000000000 vec($_, 1, 8) = 8 == 2048 00000000000100000000000000000000 vec($_, 2, 8) = 8 == 524288 00000000000000000001000000000000 vec($_, 3, 8) = 8 == 134217728 00000000000000000000000000010000 vec($_, 0, 8) = 16 == 16 00001000000000000000000000000000 vec($_, 1, 8) = 16 == 4096 00000000000010000000000000000000 vec($_, 2, 8) = 16 == 1048576 00000000000000000000100000000000 vec($_, 3, 8) = 16 == 268435456 00000000000000000000000000001000 vec($_, 0, 8) = 32 == 32 00000100000000000000000000000000 vec($_, 1, 8) = 32 == 8192 00000000000001000000000000000000 vec($_, 2, 8) = 32 == 2097152 00000000000000000000010000000000 vec($_, 3, 8) = 32 == 536870912 00000000000000000000000000000100 vec($_, 0, 8) = 64 == 64 00000010000000000000000000000000 vec($_, 1, 8) = 64 == 16384 00000000000000100000000000000000 vec($_, 2, 8) = 64 == 4194304 00000000000000000000001000000000 vec($_, 3, 8) = 64 == 1073741824 00000000000000000000000000000010 vec($_, 0, 8) = 128 == 128 00000001000000000000000000000000 vec($_, 1, 8) = 128 == 32768 00000000000000010000000000000000 vec($_, 2, 8) = 128 == 8388608 00000000000000000000000100000000 vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
- wait
- Behaves like wait(2) on your system: it waits for a
child process to terminate and returns the pid of the deceased process, or
"-1" if there are no child processes. The status is returned in
$? and "${^CHILD_ERROR_NATIVE}". Note that a return value of
"-1" could mean that child processes are being automatically
reaped, as described in perlipc.
- waitpid PID,FLAGS
- Waits for a particular child process to terminate and
returns the pid of the deceased process, or "-1" if there is no
such child process. On some systems, a value of 0 indicates that there are
processes still running. The status is returned in $? and
"${^CHILD_ERROR_NATIVE}". If you say
use POSIX ":sys_wait_h"; #... do { $kid = waitpid(-1, WNOHANG); } while $kid > 0;
- wantarray
- Returns true if the context of the currently executing
subroutine or "eval" is looking for a list value. Returns false
if the context is looking for a scalar. Returns the undefined value if the
context is looking for no value (void context).
return unless defined wantarray; # don't bother doing more my @a = complex_calculation(); return wantarray ? @a : "@a";
- warn LIST
- Prints the value of LIST to STDERR. If the last element of
LIST does not end in a newline, it appends the same file/line number text
as "die" does.
# wipe out *all* compile-time warnings BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } } my $foo = 10; my $foo = 20; # no warning about duplicate my $foo, # but hey, you asked for it! # no compile-time or run-time warnings before here $DOWARN = 1; # run-time warnings enabled after here warn "\$foo is alive and $foo!"; # does show up
- when EXPR BLOCK
- when BLOCK
- "when" is analogous to the "case"
keyword in other languages. Used with a "foreach" loop or the
experimental "given" block, "when" can be used in Perl
to implement "switch"/"case" like statements.
Available as a statement after Perl 5.10 and as a statement modifier after
5.14. Here are three examples:
use v5.10; foreach (@fruits) { when (/apples?/) { say "I like apples." } when (/oranges?/) { say "I don't like oranges." } default { say "I don't like anything" } } # require 5.14 for when as statement modifier use v5.14; foreach (@fruits) { say "I like apples." when /apples?/; say "I don't like oranges." when /oranges?; default { say "I don't like anything" } } use v5.10; given ($fruit) { when (/apples?/) { say "I like apples." } when (/oranges?/) { say "I don't like oranges." } default { say "I don't like anything" } }
- write FILEHANDLE
- write EXPR
- write
- Writes a formatted record (possibly multi-line) to the
specified FILEHANDLE, using the format associated with that file. By
default the format for a file is the one having the same name as the
filehandle, but the format for the current output channel (see the
"select" function) may be set explicitly by assigning the name
of the format to the $~ variable.
- y///
- The transliteration operator. Same as "tr///". See "Quote and Quote-like Operators" in perlop.
2016-02-27 | perl v5.14.2 |