perlfunc - Perl builtin functions
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 a scalar context to its argument, while a list
operator may provide either scalar or list contexts for
its arguments. If it does both, the scalar arguments will
be first, and the list argument will follow. (Note that
there can ever be only 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 the 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. Elements of the LIST should be separated
by commas.
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 the 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.
And whitespace between the function and left parenthesis
doesn't count--so you need to be careful sometimes:
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 a
scalar context by returning the undefined value, and in a
list context by returning the null 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 it 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 of the same name (like chown(2), fork(2),
closedir(2), etc.) all 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 are
"wait", "waitpid", and "syscall". System calls also set
the special $! variable on failure. Other functions do
not, except accidentally.
Perl Functions by Category [Toc] [Back]
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/STRING/", "qq/STRING/", "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
"pop", "push", "shift", "splice", "unshift"
Functions for list data
"grep", "join", "map", "qw/STRING/", "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",
"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 scoping
"caller", "import", "local", "my", "our", "package",
"use"
Miscellaneous functions
"defined", "dump", "eval", "formline", "local", "my",
"our", "reset", "scalar", "undef", "wantarray"
Functions for processes and process groups
"alarm", "exec", "fork", "getpgrp", "getppid", "getpriority",
"kill", "pipe", "qx/STRING/", "setpgrp",
"setpriority", "sleep", "system", "times", "wait",
"waitpid"
Keywords related to perl modules
"do", "import", "no", "package", "require", "use"
Keywords related to classes and object-orientedness
"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", "chomp", "chr", "exists", "formline",
"glob", "import", "lc", "lcfirst", "map", "my", "no",
"our", "prototype", "qx", "qw", "readline", "readpipe",
"ref", "sub*", "sysopen", "tie", "tied", "uc",
"ucfirst", "untie", "use"
* - "sub" was a keyword in perl4, but in perl5 it is
an operator, which can be used in expressions.
Functions obsoleted in perl5
"dbmclose", "dbmopen"
Portability [Toc] [Back]
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", "getprgp", "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 [Toc] [Back]
-X FILEHANDLE
-X EXPR
-X A file test, where X is one of the letters listed
below. This unary operator takes one argument,
either a filename or a filehandle, 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, and the
argument may be parenthesized like any other 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)
Example:
while (<>) {
chomp;
next unless -f $_; # ignore specials
#...
}
The interpretation of the file permission operators
"-r", "-R", "-w", "-W", "-x", and "-X" is by
default based solely on the mode of the file and
the uids and gids of the user. There may be other
reasons you can't actually read, write, or execute
the file. Such reasons may be for example network
filesystem access controls, ACLs (access control
lists), read-only filesystems, and unrecognized
executable formats.
Also note that, for the superuser on the local
filesystems, the "-r", "-R", "-w", and "-W" tests
always return 1, and "-x" and "-X" return 1 if any
execute bit is set in the mode. Scripts run by
the superuser may thus need to do a stat() to
determine the actual mode of the file, or temporarily
set their effective uid to something
else.
If you are using ACLs, there is a pragma called
"filetest" that may produce more accurate results
than the bare stat() mode bits. When under the
"use filetest 'access'" the above-mentioned
filetests will test whether the permission can
(not) be granted using the access() family of system
calls. Also note that the "-x" and "-X" may
under this pragma return true even if there are no
execute permission bits set (nor any extra execute
permission ACLs). This strangeness is due to the
underlying system calls' definitions. Read the
documentation for the "filetest" pragma for more
information.
Note that "-s/a/b/" does not do a negated substitution.
Saying "-exp($foo)" still works as
expected, however--only single letters following a
minus are interpreted as file tests.
The "-T" and "-B" switches work as follows. The
first block or so of the file is examined for odd
characters such as strange control codes or characters
with the high bit set. If too many strange
characters (>30%) are found, it's a "-B" file,
otherwise it's a "-T" file. Also, any file containing
null in the first block is considered a
binary file. If "-T" or "-B" is used on a filehandle,
the current IO buffer is examined rather
than the first block. Both "-T" and "-B" return
true on a null file, or a file at EOF when testing
a filehandle. Because you have to read a file to
do the "-T" test, on most occasions you want to
use a "-f" against the file first, as in "next
unless -f $file && -T $file".
If any of the file tests (or either the "stat" or
"lstat" operators) are given the special filehandle
consisting of a solitary underline, then the
stat structure of the previous file test (or stat
operator) is used, saving a system call. (This
doesn't work with "-t", and you need to remember
that lstat() and "-l" will leave values in the
stat structure for the symbolic link, not the real
file.) (Also, if the stat buffer was filled by a
"lstat" call, "-T" and "-B" will reset it with the
results of "stat _"). Example:
print "Can do.0 if -r $a || -w _ || -x _;
stat($filename);
print "Readable0 if -r _;
print "Writable0 if -w _;
print "Executable0 if -x _;
print "Setuid0 if -u _;
print "Setgid0 if -g _;
print "Sticky0 if -k _;
print "Text0 if -T _;
print "Binary0 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 the
accept(2) system call does. Returns the packed
address if it succeeded, false otherwise. See the
example in "Sockets: Client/Server Communication"
in perlipc.
On systems that support a close-on-exec flag on
files, the flag will be set for the newly opened
file descriptor, as determined by the value of
$^F. See "$^F" in perlvar.
alarm SECONDS
alarm Arranges to have a SIGALRM delivered to this process
after the specified number of wallclock seconds
have 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.)
Only one timer may be counting at once. Each call
disables the previous timer, and an argument of 0
may be supplied to cancel the previous timer without
starting a new one. The returned value is the
amount of time remaining on the previous timer.
For delays of finer granularity than one second,
you may use Perl's four-argument version of
select() leaving the first three arguments undefined,
or you might be able to use the "syscall"
interface to access setitimer(2) if your system
supports it. The Time::HiRes module (from CPAN,
and starting from Perl 5.8 part of the standard
distribution) may also prove useful.
It is usually a mistake to intermix "alarm" and
"sleep" calls. ("sleep" may be internally implemented
in your system with "alarm")
If you want to use "alarm" to time out a system
call you need to use an "eval"/"die" pair. You
can't rely on the alarm causing the system call to
fail with $! set to "EINTR" because Perl sets up
signal handlers to restart system calls on some
systems. Using "eval"/"die" always works, modulo
the caveats given in "Signals" in perlipc.
eval {
local $SIG{ALRM} = sub { die "alarm0 }; #
NB: required
alarm $timeout;
$nread = sysread SOCKET, $buffer, $size;
alarm 0;
};
if ($@) {
die unless $@ eq "alarm0; # propagate
unexpected errors
# timed out
}
else {
# didn't
}
For more information see perlipc.
atan2 Y,X
Returns the arctangent of Y/X in the range -PI to
PI.
For the tangent operation, you may use the
"Math::Trig::tan" function, or use the familiar
relation:
sub tan { sin($_[0]) / cos($_[0]) }
bind SOCKET,NAME
Binds a network address to a socket, just as the
bind system call 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 runtime
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).
On some systems (in general, DOS and Windows-based
systems) binmode() is necessary when you're not
working with a text file. For the sake of portability
it is a good idea to always use it when
appropriate, and to never use it when it isn't
appropriate. Also, people can set their I/O to be
by default UTF-8 encoded Unicode, not bytes.
In other words: regardless of platform, use bin-
mode() on binary data, like for example images.
If LAYER is present it is a single string, but may
contain multiple directives. The directives alter
the behaviour of the file handle. When LAYER is
present using binmode on text file makes sense.
If LAYER is omitted or specified as ":raw" the
filehandle is made suitable for passing binary
data. This includes turning off possible CRLF
translation and marking it as bytes (as opposed to
Unicode characters). Note that, despite what may
be implied in "Programming Perl" (the Camel) or
elsewhere, ":raw" is not the simply inverse of
":crlf" -- other layers which would affect binary
nature of the stream are also disabled. See PerlIO,
perlrun and the discussion about the PERLIO
environment variable.
The ":bytes", ":crlf", and ":utf8", and any other
directives of the form ":...", are called I/O lay-
ers. The "open" pragma can be used to establish
default I/O layers. See open.
The LAYER parameter of the binmode() function is
described as "DISCIPLINE" in "Programming Perl,
3rd Edition". However, since the publishing of
this book, by many known as "Camel III", the con-
sensus of the naming of this functionality has
moved from "discipline" to "layer". All documen-
tation of this version of Perl therefore refers to
"layers" rather than to "disciplines". Now back
to the regularly scheduled documentation...
To mark FILEHANDLE as UTF-8, use ":utf8".
In general, binmode() should be called after
open() but before any I/O is done on the filehandle.
Calling binmode() will normally flush any
pending buffered output data (and perhaps pending
input data) on the handle. An exception to this
is the ":encoding" layer that changes the default
character encoding of the handle, see open. The
":encoding" layer sometimes needs to be called in
mid-stream, and it doesn't flush the stream. The
":encoding" also implicitly pushes on top of
itself the ":utf8" layer because internally Perl
will operate on UTF-8 encoded Unicode characters.
The operating system, device drivers, C libraries,
and Perl run-time system all work together to let
the programmer treat a single character ("0) as
the line terminator, irrespective of the external
representation. On many operating systems, the
native text file representation matches the internal
representation, but on some platforms the
external representation of "0 is made up of more
than one character.
Mac OS, all variants of Unix, and Stream_LF files
on VMS use a single character to end each line in
the external representation of text (even though
that single character is CARRIAGE RETURN on Mac OS
and LINE FEED on Unix and most VMS files). In
other systems like OS/2, DOS and the various flavors
of MS-Windows your program sees a "0 as a
simple " the two characters "
you don't use binmode() on these systems, " sequences on disk will be converted to "0 on
input, and any "0 in your program will be converted
back to " you want for text
files, but it can be disastrous
for binary files.
Another consequence of using binmode() (on some
systems) is that special end-of-file markers will
be seen as part of the data stream. For systems
from the Microsoft family this means that if your
binary data contains " regard it as
the end of the file, unless you use
binmode().
binmode() is not only important for readline() and
print() operations, but also when using read(),
seek(), sysread(), syswrite() and tell() (see
perlport for more details). See the $/ and "$
variables in perlvar for how to manually set your
input and output line-termination sequences.
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 the function doing the blessing might be inherited
by a derived class. See perltoot and perlobj
for more about the blessing (and blessings) of
objects.
Consider always blessing objects in CLASSNAMEs
that are mixed case. Namespaces with all lowercase
names are considered reserved for Perl pragmata.
Builtin types have all uppercase names, so
to prevent confusion, you may wish to avoid such
package names as well. Make sure that CLASSNAME
is a true value.
See "Perl Modules" in perlmod.
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
($package, $filename, $line) = caller;
With EXPR, it returns some extra information that
the debugger uses to print a stack trace. The
value of EXPR indicates how many call frames to go
back before the current one.
($package, $filename, $line, $subroutine,
$hasargs,
$wantarray, $evaltext, $is_require, $hints,
$bitmask) = caller($i);
Here $subroutine may be "(eval)" if the frame is
not a subroutine call, but an "eval". In such a
case additional elements $evaltext and $is_require
are set: $is_require is true if the frame is created
by a "require" or "use" statement, $evaltext
contains the text of the "eval EXPR" statement.
In particular, for an "eval BLOCK" statement,
$filename is "(eval)", but $evaltext is undefined.
(Note also that each "use" statement creates a
"require" frame inside an "eval EXPR" frame.)
$subroutine may also be "(unknown)" if this particular
subroutine happens to have been deleted
from the symbol table. $hasargs is true if a new
instance of @_ was set up for the frame. $hints
and $bitmask contain pragmatic hints that the
caller was compiled with. The $hints and $bitmask
values are subject to change between versions of
Perl, and are not meant for external use.
Furthermore, when called from within the DB package,
caller returns more detailed information: it
sets the list variable @DB::args to be the arguments
with which the subroutine was invoked.
Be aware that the optimizer might have optimized
call frames away before "caller" had a chance to
get the information. That means that caller(N)
might not return information about the call frame
you expect it do, for "N > 1". In particular,
@DB::args might have information from the previous
time "caller" was called.
chdir EXPR
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 upon 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 numerical
mode, which should probably be an octal number,
and which definitely should not a string of octal
digits: 0644 is okay, '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
You can also import the symbolic "S_I*" constants
from the Fcntl module:
use Fcntl ':mode';
chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH,
@executables;
# This is identical to the chmod 0755 of the
above example.
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 on last field
@array = split(/:/);
# ...
}
If VARIABLE is a hash, it chomps the hash's values,
but not its keys.
You can actually chomp anything that's an lvalue,
including an assignment:
chomp($cwd = `pwd`);
chomp($answer = <STDIN>);
If you chomp a list, each element is chomped, and
the total number of characters removed is
returned.
If the "encoding" pragma is in scope then the
lengths returned are calculated from the length of
$/ in Unicode characters, which is not always the
same as the length of $/ in the native encoding.
Note that parentheses are necessary when you're
chomping anything that is not a simple variable.
This is because "chomp $cwd = `pwd`;" is interpreted
as "(chomp $cwd) = `pwd`;", rather than as
"chomp( $cwd = `pwd` )" which you might expect.
Similarly, "chomp $a, $b" is interpreted as
"chomp($a), $b" rather than as "chomp($a, $b)".
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.
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 "chop" is returned.
Note that "chop" returns the last character. To
return all but the last character, use "substr($string,
0, -1)".
See also "chomp".
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;
Here's an example that looks up nonnumeric uids in
the passwd file:
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;
On most systems, you are not allowed to change the
ownership of the file unless you're the superuser,
although you should be able to change the group to
any of your secondary groups. On insecure systems,
these restrictions may be relaxed, but this
is not a portable assumption. On POSIX systems,
you can detect this condition this way:
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. Note that characters from
128 to 255 (inclusive) are by default not encoded
in UTF-8 Unicode for backward compatibility reasons
(but see encoding).
If NUMBER is omitted, uses $_.
For the reverse, use "ord".
Note that under the "bytes" pragma the NUMBER is
masked to the low eight bits.
See perlunicode and encoding for more about Unicode.
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 file
handle, returning true only if IO buffers are successfully
flushed and closes the system file
descriptor. Closes the currently selected filehandle
if the argument is omitted.
You don't have to close FILEHANDLE if you are
immediately going to do another "open" on it,
because "open" will close it for you. (See
"open".) However, an explicit "close" on an input
file resets the line counter ($.), while the
implicit close done by "open" does not.
If the file handle came from a piped open, "close"
will additionally return false if one of the other
system calls involved fails, or if the program
exits with non-zero status. (If the only problem
was that the program exited non-zero, $! will be
set to 0.) Closing a pipe also waits for the process
executing on the pipe to complete, in case
you want to look at the output of the pipe afterwards,
and implicitly puts the exit status value
of that command into $?.
Prematurely closing the read end of a pipe (i.e.
before the process writing to it at the other end
has closed it) will result in a SIGPIPE being
delivered to the writer. If the other end can't
handle that, be sure to read all the data before
closing the pipe.
Example:
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: $!";
FILEHANDLE may be an expression whose value can be
used as an indirect filehandle, usually the real
filehandle name.
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 as
the connect system call 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.
continue BLOCK
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).
"last", "next", or "redo" may appear within a
"continue" block. "last" and "redo" will behave
as if they had been executed within the main
block. So will "next", but since it will execute
a "continue" block, it may be more entertaining.
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
Omitting the "continue" section is semantically
equivalent to using an empty one, logically
enough. In that case, "next" goes directly back
to check the condition at the top of the loop.
cos EXPR
cos Returns the cosine of EXPR (expressed in radians).
If EXPR is omitted, takes cosine of $_.
For the inverse cosine operation, you may use the
"Math::Trig::acos()" function, or use this relation:
sub acos { atan2( sqrt(1 - $_[0] * $_[0]),
$_[0] ) }
crypt PLAINTEXT,SALT
Encrypts a 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). This can prove useful
for checking the password file for lousy passwords,
amongst other things. Only the guys wearing
white hats should do this.
Note that crypt is intended to be a one-way function,
much like breaking eggs to make an omelette.
There is no (known) corresponding decrypt function
(in other words, the crypt() is a one-way hash
function). As a result, this function isn't all
that useful for cryptography. (For that, see your
nearby CPAN mirror.)
When verifying an existing encrypted string you
should use the encrypted text as the salt (like
"crypt($plain, $crypted) eq $crypted"). This
allows your code to work with the standard crypt
and with more exotic implementations. In other
words, do not assume anything about the returned
string itself, or how many bytes in the encrypted
string matter.
Traditionally the result is a string of 13 bytes:
two first bytes of the salt, followed by 11 bytes
from the set "[./0-9A-Za-z]", and only the first
eight bytes of the encrypted string mattered, but
alternative hashing schemes (like MD5), higher
level security schemes (like C2), and implementations
on non-UNIX platforms may produce different
strings.
When choosing a new salt create a random two character
string whose characters come from the set
"[./0-9A-Za-z]" (like "join '', ('.', '/', 0..9,
'A'..'Z', 'a'..'z')[rand 64, rand 64]"). This set
of characters is just a recommendation; the characters
allowed in the salt depend solely on your
system's crypt library, and Perl can't restrict
what salts "crypt()" accepts.
Here's an example that makes sure that whoever
runs this program knows their own password:
$pwd = (getpwuid($<))[1];
system "stty -echo";
print "Password: ";
chomp($word = <STDIN>);
print "0;
system "stty echo";
if (crypt($word, $pwd) ne $pwd) {
die "Sorry...0;
} else {
print "ok0;
}
Of course, typing in your own password to whoever
asks you for it is unwise.
The crypt function is unsuitable for encrypting
large quantities of data, not least of all because
you can't get the information back. Look at the
by-module/Crypt and by-module/PGP directories on
your favorite CPAN mirror for a slew of potentially
useful modules.
If using crypt() on a Unicode string (which poten-
tially has characters with codepoints above 255),
Perl tries to make sense of the situation by trying
to downgrade (a copy of the string) the string
back to an eight-bit byte string before calling
crypt() (on that copy). If that works, good. If
not, crypt() dies with "Wide character in crypt".
dbmclose HASH
[This function has been largely superseded by the
"untie" function.]
Breaks the binding between a DBM file and a hash.
dbmopen HASH,DBNAME,MASK
[This function has been largely superseded by the
"tie" function.]
This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or
Berkeley DB file to a hash. HASH is the name of
the hash. (Unlike normal "open", the first argument
is not a filehandle, even though it looks
like one). DBNAME is the name of the database
(without the .dir or .pag extension if any). If
the database does not exist, it is created with
protection specified by MASK (as modified by the
"umask"). If your system supports only the older
DBM functions, you may perform only one "dbmopen"
in your program. In older versions of Perl, if
your system had neither DBM nor ndbm, calling
"dbmopen" produced a fatal error; it now falls
back to sdbm(3).
If you don't have write access to the DBM file,
you can only read hash variables, not set them.
If you want to test whether you can write, either
use file tests or try setting a dummy hash entry
inside an "eval", which will trap the error.
Note that functions such as "keys" and "values"
may return huge lists when used on large DBM
files. You may prefer to use the "each" function
to iterate over large DBM files. Example:
# print out history file offsets
dbmopen(%HIST,'/usr/lib/news/history',0666);
while (($key,$val) = each %HIST) {
print $key, ' = ', unpack('L',$val), "0;
}
dbmclose(%HIST);
See also AnyDBM_File for a more general description
of the pros and cons of the various dbm
approaches, as well as DB_File for a particularly
rich implementation.
You can control which DBM library you use by loading
that library before you call dbmopen():
use DB_File;
dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
or die "Can't open netscape history file:
$!";
defined EXPR
defined Returns a Boolean value telling whether EXPR has a
value other than the undefined value "undef". If
EXPR is not present, $_ will be checked.
Many operations return "undef" to indicate failure,
end of file, system error, uninitialized
variable, and other exceptional conditions. This
function allows you to distinguish "undef" from
other values. (A simple Boolean test will not
distinguish among "undef", zero, the empty string,
and "0", which are all equally false.) Note that
since "undef" is a valid scalar, its presence
doesn't necessarily indicate an exceptional condition:
"pop" returns "undef" when its argument is
an empty array, or when the element to return happens
to be "undef".
You may also use "defined(&func)" to check whether
subroutine &func has ever been defined. The
return value is unaffected by any forward declarations
of &func. Note that a subroutine which is
not defined may still be callable: its package may
have an "AUTOLOAD" method that makes it spring
into existence the first time that it is called --
see perlsub.
Use of "defined" on aggregates (hashes and arrays)
is deprecated. It used to report whether memory
for that aggregate has ever been allocated. This
behavior may disappear in future versions of Perl.
You should instead use a simple test for size:
if (@an_array) { print "has array elements0 }
if (%a_hash) { print "has hash members0 }
When used on a hash element, it tells you whether
the value is defined, not whether the key exists
in the hash. Use "exists" for the latter purpose.
Examples:
print if defined $switch{'D'};
print "$val0 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;
Note: Many folks tend to overuse "defined", and
then are surprised to discover that the number 0
and "" (the zero-length string) are, in fact,
defined values. For example, if you say
"ab" =~ /a(.*)b/;
The pattern match succeeds, and $1 is defined,
despite the fact that it matched "nothing". But
it didn't really match nothing--rather, it matched
something that happened to be zero characters
long. This is all very above-board and honest.
When a function returns an undefined value, it's
an admission that it couldn't give you an honest
answer. So you should use "defined" only when
you're questioning the integrity of what you're
trying to do. At other times, a simple comparison
to 0 or "" is what you want.
See also "undef", "exists", "ref".
delete EXPR
Given an expression that specifies a hash element,
array element, hash slice, or array slice, deletes
the specified element(s) from the hash or array.
In the case of an array, if the array elements
happen to be at the end, the size of the array
will shrink to the highest element that tests true
for exists() (or 0 if no such element exists).
Returns a list with the same number of elements as
the number of elements for which deletion was
attempted. Each element of that list consists of
either the value of the element deleted, or the
undefined value. In scalar context, this means
that you get the value of the last element deleted
(or the undefined value if that element did not
exist).
%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)
Deleting from %ENV modifies the environment.
Deleting from a hash tied to a DBM file deletes
the entry from the DBM file. Deleting from a
"tie"d hash or array may not necessarily return
anything.
Deleting an array element effectively returns that
position of the array to its initial, uninitialized
state. Subsequently testing for the same
element with exists() will return false. Note
that deleting array elements in the middle of an
array will not shift the index of the ones after
them down--use splice() for that. See "exists".
The following (inefficiently) deletes all the values
of %HASH and @ARRAY:
foreach $key (keys %HASH) {
delete $HASH{$key};
}
foreach $index (0 .. $#ARRAY) {
delete $ARRAY[$index];
}
And so do these:
delete @HASH{keys %HASH};
delete @ARRAY[0 .. $#ARRAY];
But both of these are slower than just assigning
the empty list or undefining %HASH or @ARRAY:
%HASH = (); # completely empty %HASH
undef %HASH; # forget %HASH ever existed
@ARRAY = (); # completely empty @ARRAY
undef @ARRAY; # forget @ARRAY ever existed
Note that the EXPR can be arbitrarily complicated
as long as the final operation is a hash element,
array element, hash slice, or array slice lookup:
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
Outside an "eval", prints the value of LIST to
"STDERR" and exits with the current value of $!
(errno). If $! is 0, exits with the value of "($?
>> 8)" (backtick `command` status). If "($? >>
8)" is 0, exits with 255. Inside an "eval()," the
error message is stuffed into $@ and the "eval" is
terminated with the undefined value. This makes
"die" the way to raise an exception.
Equivalent examples:
die "Can't cd to spool: $!0 unless chdir
'/usr/spool/news';
chdir '/usr/spool/news' or die "Can't cd to
spool: $!0
If the last element of LIST does not end in a newline,
the current script line number and input
line number (if any) are also printed, and a newline
is supplied. Note that the "input line number"
(also known as "chunk") is subject to whatever
notion of "line" happens to be currently in
effect, and is also available as the special variable
$.. See "$/" in perlvar and "$." in perlvar.
Hint: sometimes appending ", stopped" to your message
will cause it to make better sense when the
string "at foo line 123" is appended. Suppose you
are running script "canasta".
die "/etc/games is no good";
die "/etc/games is no good, stopped";
produce, respectively
/etc/games is no good at canasta line 123.
/etc/games is no good, stopped at canasta line
123.
See also exit(), warn(), and the Carp module.
If LIST
|
