/

perlfunc (1) Linux Manual Page

ByLinux Manual Posted on Updated on

NAME

perlfunc – Perl builtin functions

DESCRIPTION

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 "use warnings" pragma, 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 concatenation 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. Any warnings, including those produced by keywords, are described in perldiag and warnings.

Functions for SCALARs or strings

"chomp", "chop", "chr", "crypt", "fc", "hex", "index", "lc", "lcfirst", "length", "oct", "ord", "pack", "q//", "qq//", "reverse", "rindex", "sprintf", "substr", "tr///", "uc", "ucfirst", "y///"

"fc" is available only if the "fc" feature is enabled or if it is prefixed with "CORE::". The "fc" feature is enabled automatically with a "use v5.16" (or higher) declaration in the current scope.

Regular expressions and pattern matching

"m//", "pos", "qr//", "quotemeta", "s///", "split", "study"

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", "readline", "rewinddir", "say", "seek", "seekdir", "select", "syscall", "sysread", "sysseek", "syswrite", "tell", "telldir", "truncate", "warn", "write"

"say" is available only if the "say" feature is enabled or if it is prefixed with "CORE::". The "say" feature is enabled automatically with a "use v5.10" (or higher) declaration in the current scope.

Functions for fixed-length data or records

"pack", "read", "syscall", "sysread", "sysseek", "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", "select", "stat", "symlink", "sysopen", "umask", "unlink", "utime"

Keywords related to the control flow of your Perl program

"break", "caller", "continue", "die", "do", "dump", "eval", "evalbytes", "exit", "__FILE__", "goto", "last", "__LINE__", "next", "__PACKAGE__", "redo", "return", "sub", "__SUB__", "wantarray"

"break" is available only if you enable the experimental "switch" feature or use the "CORE::" prefix. The "switch" feature also enables the "default", "given" and "when" statements, which are documented in “Switch Statements” in perlsyn. The "switch" feature is enabled automatically with a "use v5.10" (or higher) declaration in the current scope. In Perl v5.14 and earlier, "continue" required the "switch" feature, like the other keywords.

"evalbytes" is only available with the "evalbytes" feature (see feature) or if prefixed with "CORE::". "__SUB__" is only available with the "current_sub" feature or if prefixed with "CORE::". Both the "evalbytes" and "current_sub" features are enabled automatically with a "use v5.16" (or higher) declaration in the current scope.

Keywords related to scoping

"caller", "import", "local", "my", "our", "package", "state", "use"

"state" is available only if the "state" feature is enabled or if it is prefixed with "CORE::". The "state" feature is enabled automatically with a "use v5.10" (or higher) declaration in the current scope.

Miscellaneous functions

"defined", "formline", "lock", "prototype", "reset", "scalar", "undef"

Functions for processes and process groups

"alarm", "exec", "fork", "getpgrp", "getppid", "getpriority", "kill", "pipe", "qx//", "readpipe", "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"

Non-function keywords

"and", "AUTOLOAD", "BEGIN", "CHECK", "cmp", "CORE", "__DATA__", "default", "DESTROY", "else", "elseif", "elsif", "END", "__END__", "eq", "for", "foreach", "ge", "given", "gt", "if", "INIT", "le", "lt", "ne", "not", "or", "UNITCHECK", "unless", "until", "when", "while", "x", "xor"

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. If the file doesn’t exist or can’t be examined, it returns "undef" and sets $! (errno). With the exception of the "-l" test they all follow symbolic links because they use "stat()" and not "lstat()" (so dangling symlinks can’t be examined and will therefore report failure).

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 (false if symlinks aren’t
supported by the file system).
-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 or UTF-8 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
#…
}

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.

These operators are exempt from the “looks like a function rule” described above. That is, an opening parenthesis after the operator does not affect how much of the following code constitutes the argument. Put the opening parentheses before the operator to separate it from code that follows (this applies only to operators with higher precedence than unary operators, of course): 

    -s($file) + 1024   # probably wrong; same as -s($file + 1024)
    (-s $file) + 1024  # correct

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: for example network filesystem access controls, ACLs (access control lists), read-only filesystems, and unrecognized executable formats. Note that the use of these six specific operators to verify if some operation is possible is usually a mistake, because it may be open to race conditions.

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 "use filetest 'access'", the above-mentioned filetests test whether the permission can(not) be granted using the access(2) family of system calls. Also note that the "-x" and "-X" tests 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. Note also that, due to the implementation of "use filetest 'access'", the "_" special filehandle won’t cache the results of the file tests when this pragma is in effect. Read the documentation for the "filetest" pragma for more information.

The "-T" and "-B" tests work as follows. The first block or so of the file is examined to see if it is valid UTF-8 that includes non-ASCII characters. If so, it’s a "-T" file. Otherwise, that same portion of the file is examined for odd characters such as strange control codes or characters with the high bit set. If more than a third of the characters are strange, it’s a "-B" file; otherwise it’s a "-T" file. Also, any file containing a zero byte in the examined portion is considered a binary file. (If executed within the scope of a use locale which includes "LC_CTYPE", odd characters are anything that isn’t a printable nor space in the current locale.) 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 an empty 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" operator) is 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" leave values in the stat structure for the symbolic link, not the real file.) (Also, if the stat buffer was filled by an "lstat" call, "-T" and "-B" will reset it with the results of "stat _"). Example:

print “Can do.
” if – r $a || -w _ || -x _;
stat($filename);
print “Readable
” if – r _;
print “Writable
” if – w _;
print “Executable
” if – x _;
print “Setuid
” if – u _;
print “Setgid
” if – g _;
print “Sticky
” if – k _;
print “Text
” if – T _;
print “Binary
” if – B _;

As of Perl 5.10.0, as a form of purely syntactic sugar, you can stack file test operators, in a way that "-f -w -x $file" is equivalent to "-x $file && -w _ && -f _". (This is only fancy syntax: if you use the return value of "-f $file" as an argument to another filetest operator, no special magic will happen.)

Portability issues: “-X” in perlport.

To avoid confusing would-be users of your code with mysterious syntax errors, put something like this at the top of your script: 

    use 5.010;  # so filetest ops can stack
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.

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 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.)

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, the Time::HiRes module (from CPAN, and starting from Perl 5.8 part of the standard distribution) provides "ualarm". You may also 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. See perlfaq8 for details.

It is usually a mistake to intermix "alarm" and "sleep" calls, because "sleep" may be internally implemented on 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 “alarm
”};
#NB :
required
alarm $timeout;
my $nread = sysread $socket, $buffer, $size;
alarm 0;
};
if ($ @) {
die unless $ @eq “alarm
”;
#propagate unexpected errors
#timed out
} else {
#didn’t
}

For more information see perlipc.

Portability issues: “alarm” in perlport.

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])
}

The return value for "atan2(0,0)" is implementation-defined; consult your atan2(3) manpage for more information.

Portability issues: “atan2” in perlport.

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).

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 always to use it when appropriate, and never to use it when it isn’t appropriate. Also, people can set their I/O to be by default UTF8-encoded Unicode, not bytes.

In other words: regardless of platform, use "binmode" on binary data, like images, for example.

If LAYER is present it is a single string, but may contain multiple directives. The directives alter the behaviour of the filehandle. When LAYER is present, using binmode on a 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, 3rd edition) or elsewhere, ":raw" is not simply the inverse of ":crlf". Other layers that would affect the binary nature of the stream are also disabled. See PerlIO, perlrun, and the discussion about the PERLIO environment variable.

The ":bytes", ":crlf", ":utf8", and any other directives of the form ":...", are called I/O layers. The open pragma can be used to establish default I/O layers.

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 consensus of the naming of this functionality has moved from “discipline” to “layer”. All documentation 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" or ":encoding(UTF-8)". ":utf8" just marks the data as UTF-8 without further checking, while ":encoding(UTF-8)" checks the data for actually being valid UTF-8. More details can be found in PerlIO::encoding.

In general, "binmode" should be called after "open" but before any I/O is done on the filehandle. Calling "binmode" normally flushes 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. The ":encoding" layer sometimes needs to be called in mid-stream, and it doesn’t flush the stream. ":encoding" also implicitly pushes on top of itself the ":utf8" layer because internally Perl operates on UTF8-encoded Unicode characters.

The operating system, device drivers, C libraries, and Perl run-time system all conspire to let the programmer treat a single character ("
") as the line terminator, irrespective of external representation. On many operating systems, the native text file representation matches the internal representation, but on some platforms the external representation of "
" is made up of more than one character.

All variants of Unix, Mac OS (old and new), 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 old, pre-Darwin flavors of Mac OS, and is 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 "
" as a simple "

Leave a Reply

Your email address will not be published. Required fields are marked *