arranged by category. Some functions appear in more
than one place.
-=over
+=over 4
=item Functions for SCALARs or strings
-O File is owned by real uid.
-e File exists.
- -z File has zero size.
- -s File has nonzero size (returns size).
+ -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.
Example:
while (<>) {
- chop;
+ chomp;
next unless -f $_; # ignore specials
#...
}
=item chop
Chops off the last character of a string and returns the character
-chopped. It's used primarily to remove the newline from the end of an
-input record, but is much more efficient than C<s/\n//> because it neither
+chopped. It is much more efficient than C<s/.$//s> because it neither
scans nor copies the string. If VARIABLE is omitted, chops C<$_>.
-Example:
-
- while (<>) {
- chop; # avoid \n on last field
- @array = split(/:/);
- #...
- }
-
If VARIABLE is a hash, it chops the hash's values, but not its keys.
-You can actually chop anything that's an lvalue, including an assignment:
-
- chop($cwd = `pwd`);
- chop($answer = <STDIN>);
+You can actually chop anything that's an lvalue, including an assignment.
If you chop a list, each element is chopped. Only the value of the
last C<chop> is returned.
You may also use C<defined(&func)> to check whether subroutine C<&func>
has ever been defined. The return value is unaffected by any forward
-declarations of C<&foo>.
+declarations of C<&foo>. Note that a subroutine which is not defined
+may still be callable: its package may have an C<AUTOLOAD> method that
+makes it spring into existence the first time that it is called -- see
+L<perlsub>.
Use of C<defined> on aggregates (hashes and arrays) is deprecated. It
used to report whether memory for that aggregate has ever been
When called in list context, returns a 2-element list consisting of the
key and value for the next element of a hash, so that you can iterate over
-it. When called in scalar context, returns the key for only the "next"
+it. When called in scalar context, returns only the key for the next
element in the hash.
Entries are returned in an apparently random order. The actual random
C<keys>, and C<values> function calls in the program; it can be reset by
reading all the elements from the hash, or by evaluating C<keys HASH> or
C<values HASH>. If you add or delete elements of a hash while you're
-iterating over it, you may get entries skipped or duplicated, so don't.
+iterating over it, you may get entries skipped or duplicated, so
+don't. Exception: It is always safe to delete the item most recently
+returned by C<each()>, which means that the following code will work:
+
+ while (($key, $value) = each %hash) {
+ print $key, "\n";
+ delete $hash{$key}; # This is safe
+ }
The following prints out your environment like the printenv(1) program,
only in a different order:
Given an expression that specifies the name of a subroutine,
returns true if the specified subroutine has ever been declared, even
if it is undefined. Mentioning a subroutine name for exists or defined
-does not count as declaring it.
+does not count as declaring it. Note that a subroutine which does not
+exist may still be callable: its package may have an C<AUTOLOAD>
+method that makes it spring into existence the first time that it is
+called -- see L<perlsub>.
print "Exists\n" if exists &subroutine;
print "Defined\n" if defined &subroutine;
=item local EXPR
You really probably want to be using C<my> instead, because C<local> isn't
-what most people think of as "local". See L<perlsub/"Private Variables
-via my()"> for details.
+what most people think of as "local". See
+L<perlsub/"Private Variables via my()"> for details.
A local modifies the listed variables to be local to the enclosing
block, file, or eval. If more than one value is listed, the list must
most cases. See also L</grep> for an array composed of those items of
the original list for which the BLOCK or EXPR evaluates to true.
+C<{> starts both hash references and blocks, so C<map { ...> could be either
+the start of map BLOCK LIST or map EXPR, LIST. Because perl doesn't look
+ahead for the closing C<}> it has to take a guess at which its dealing with
+based what it finds just after the C<{>. Usually it gets it right, but if it
+doesn't it won't realize something is wrong until it gets to the C<}> and
+encounters the missing (or unexpected) comma. The syntax error will be
+reported close to the C<}> but you'll need to change something near the C<{>
+such as using a unary C<+> to give perl some help:
+
+ %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)
+
+or to force an anon hash constructor use C<+{>
+
+ @hashes = map +{ lc($_), 1 }, @array # EXPR, so needs , at end
+
+and you get list of anonymous hashes each with only 1 entry.
+
=item mkdir FILENAME,MASK
=item mkdir FILENAME
kept private (mail files, for instance). The perlfunc(1) entry on
C<umask> discusses the choice of MASK in more detail.
+Note that according to the POSIX 1003.1-1996 the FILENAME may have any
+number of trailing slashes. Some operating and filesystems do not get
+this right, so Perl automatically removes all trailing slashes to keep
+everyone happy.
+
=item msgctl ID,CMD,ARG
Calls the System V IPC function msgctl(2). You'll probably have to say
sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL)
or die "sysopen $path: $!";
$oldfh = select(HANDLE); $| = 1; select($oldfh);
- print HANDLE "stuff $$\n");
+ print HANDLE "stuff $$\n";
seek(HANDLE, 0, 0);
print "File contains: ", <HANDLE>;
=item read FILEHANDLE,SCALAR,LENGTH
Attempts to read LENGTH bytes of data into variable SCALAR from the
-specified FILEHANDLE. Returns the number of bytes actually read,
-C<0> at end of file, or undef if there was an error. SCALAR will be grown
-or shrunk to the length actually read. An OFFSET may be specified to
-place the read data at some other place than the beginning of the
-string. This call is actually implemented in terms of stdio's fread(3)
-call. To get a true read(2) system call, see C<sysread>.
+specified FILEHANDLE. Returns the number of bytes actually read, C<0>
+at end of file, or undef if there was an error. SCALAR will be grown
+or shrunk to the length actually read. If SCALAR needs growing, the
+new bytes will be zero bytes. An OFFSET may be specified to place
+the read data into some other place in SCALAR than the beginning.
+The call is actually implemented in terms of stdio's fread(3) call.
+To get a true read(2) system call, see C<sysread>.
=item readdir DIRHANDLE
If you're using strict, you I<must not> declare $a
and $b as lexicals. They are package globals. That means
if you're in the C<main> package and type
-
+
@articles = sort {$b <=> $a} @files;
-
+
then C<$a> and C<$b> are C<$main::a> and C<$main::b> (or C<$::a> and C<$::b>),
but if you're in the C<FooPack> package, it's the same as typing
produces the output 'h:i:t:h:e:r:e'.
+Empty leading (or trailing) fields are produced when there positive width
+matches at the beginning (or end) of the string; a zero-width match at the
+beginning (or end) of the string does not produce an empty field. For
+example:
+
+ print join(':', split(/(?=\w)/, 'hi there!'));
+
+produces the output 'h:i :t:h:e:r:e!'.
+
The LIMIT parameter can be used to split a line partially
($login, $passwd, $remainder) = split(/:/, $_, 3);
open(PASSWD, '/etc/passwd');
while (<PASSWD>) {
- ($login, $passwd, $uid, $gid,
+ chomp;
+ ($login, $passwd, $uid, $gid,
$gcos, $home, $shell) = split(/:/);
#...
}
-(Note that $shell above will still have a newline on it. See L</chop>,
-L</chomp>, and L</join>.)
=item sprintf FORMAT, LIST
=item tell
-Returns the current position for FILEHANDLE. FILEHANDLE may be an
-expression whose value gives the name of the actual filehandle. If
-FILEHANDLE is omitted, assumes the file last read.
+Returns the current position 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.
+
+The return value of tell() for the standard streams like the STDIN
+depends on the operating system: it may return -1 or something else.
+tell() on pipes, fifos, and sockets usually returns -1.
There is no C<systell> function. Use C<sysseek(FH, 0, 1)> for that.
If no C<unimport> method can be found the call fails with a fatal error.
-See L<perlmod> for a list of standard modules and pragmas. See L<perlrun>
+See L<perlmodlib> for a list of standard modules and pragmas. See L<perlrun>
for the C<-M> and C<-m> command-line options to perl that give C<use>
functionality from the command-line.