Appendix C

Function List

CONTENTS

Functions by Category
Functions by Name

Perl has a large number of functions and an even wider range of additional modules each with its own additional functions. This appendix lists all the standard functions alphabetically for reference.

Each function has been assigned one or more categories to aid you in finding the function that you need. This is a very rough categorization, as many functions might overlap in any category scheme.

For each function, the needed parameters are shown. The parameters are described in the text where the meaning is not obvious.

Quite a few of Perl's function mirror those available to C programmers under the UNIX system and are at least moderately complicated to use. Please look in the UNIX documentation for additional information if you're interested in the socket, shared memory, or semaphore functions.

Functions by Category

This section listed Perl's functions by category.

Array: chomp, join, keys, map, pop, push, reverse, shift, sort, splice, split, unshift, values
Database: dbmclose, dbmopen
Directory: chdir, closedir, mkdir, opendir, readdir, rewinddir, rmdir, seekdir, telldir
File: binmode, chdir, chmod, chown, chroot, close, eof, fnctl, fileno, flock, getc, glob, ioctl, link, lstat, open, print, printf, read, readdir, readlink, rename, rmdir, seek, select, stat, symlink, sysopen, sysread, syswrite, tell, truncate, umask, unlink, utime, write
Group: endgrent, getgrent, getgrgid, getgrname, getpgrp, setgrent, setpgrp
Hash: delete, each, exists, keys, values
Host: endhostent, gethostbyaddr, gethostbyname, sethostent
Input: getc, read, sysread
Inter-process Communication: msgctl, msgget, msgrcv, msgsnd, pipe, semctl, semget, semop, shmctl, shmget, shmread, shmwrite
Math: abs, atan2, cos, exp, hex, int, log, oct, rand, sin, sqrt, srand
Message Queues: msgctl, msgget, msgrcv, msgsnd
Miscellaneous: bless, defined, do, eval, formline, import, ref, scalar, syscall, tie, tied, undef, untie, wantarray
Network: endnetent, getnetbyaddr, getnetbyname, getnetent, setnetent
Output: die, print, printf, syswrite, warn, write
Password: endpwent, getpwent, getpwname, getpwuid, setpwent
Process: alarm, die, dump, exec, exit, fork, getlogin, getpgrp, getppid, getpriority, kill, setpriority, sleep, system, times, umask, wait, waitpid
Protocol: endprotent, getprotobyname, getprotobynumber, getprotoent, getservbyname, getservbyport, getservent, setprotoent
Regular Expression: grep, pos, quotemeta, reset, split, study
Scope: caller, local, my
Service: endservent, getservbyname, getservbyport, getservent, setservent
Socket: accept, bind, connect, gethostbyaddr, gethostbyname, gethostent, getpeername, getservbyname, getservbyport, getservent, getsockname, getsockopt, listen, recv, select, send, setsockopt, shutdown, socket, socketpair
String: chop, chr, crypt, hex, index, join, lc, lcfirst, length, oct, pack, q, qq, quotemeta, qw, qx, reverse, rindex, split, sprintf, substr, uc, ucfirst, unpack, vec
Time: gmtime, localtime, time
UNIX: chmod, chown, chroot, dump, endgrent, endhostent, endnetent, endprotent, endpwent, endservent, fnctl, fork, getgrent, getgrgid, getgrname, gethostent, getlogin, getnetent, getpgrp, getppid, getpriority, getprotobyname, getprotobynumber, getprotoent, getpwent, getpwname, getpwuid, getservbyname, getservbyport, getservent, ioctl, link, lstat, readlink, select, setgrent, sethostent, setnetent, setpgrp, setpriority, setprotoent, setpwent, setservent, sleep, syscall, times, umask, wait, waitpid

Functions by Name

Here is the list of Perl's function sorted by name.

abs([EXPR])

Category: Math
Return Value: scalar, the absolute value of EXPR or $_ if no expression is specified.
Definition: Calculates an absolute value. For example, abs(-10) is 10.

accept (NEWSOCKET, GENERICSOCKET)

Category: Socket
Return Value: SCALAR, the packed address of the client or false if a problem occurred.
Definition: Accepts a socket connection from clients waiting for a connection. The GENERICSOCKET parameter must have already been opened using the socket() function. You can find more information about accept() in section 2 of the UNIX manual pages.

alarm (NUM_OF_SECONDS)

Category: Process
Return Value: SCALAR, the number of seconds remaining before the previous alarm was due to go off.
Definition: Sends a SIGALARM to your script after NUM_OF_SECONDS. A call with NUM_OF_SECONDS equal to zero cancels the current alarm. You can find more information about alarm() in section 3 of the UNIX manual pages. It is poss-ible for Perl to trap such signals and call specific signal handling subroutines. See Chapter 13, "Handling Errors and Signals."


alarm(10);

atan2 ([EXPR])

Category: Math
Return Value: SCALAR, the arc tangent of EXPR or of $_ if no expression is specified.
Definition: Calculates an arc tangent.


$arcTangent = atan2(60,2);

bind (SOCKET, NAME)

Category: Socket
Return Value: SCALAR, the socket handle or false if an error occurred.
Definition: Binds a network address to the socket handle. You can find more information about bind() in section 2 of the UNIX manual pages.

binmode (FILEHANDLE)

Category: File
Return Value: SCALAR, true if successful or undefined if not.
Definition: On systems which distinguish between text and binary files (like Windows 95 and Windows NT) this function forces binary mode treatment of FILEHANDLE. In systems which do make the distinction, text files have the end of line characters-carriage return ('\r') and linefeed('\n')-automatically translated into the UNIX end-of-line character ('\n') when reading from the file and when writing to the file. Binary mode files do not have this automatic transformation. See "Example: Binary Files" in Chapter 9 "Using Files," for more information.


open(FILE, "file.dat");

binmode(FILE);

bless (REFEREncE, [CLASSNAME])

Category: Object
Return Value: SCALAR, a reference to the blessed object.
Definition: Changes the type of the referenced variable to CLASSNAME. It is used to assign a class name to the referenced variable, thus changing the string returned by the ref() function. If CLASSNAME is not specified, the name of the current package is used. See Chapter 8, "References," for more information.


$temp = { }

bless $temp, 'ATMPCLASS';

print("bless() \$temp is now has type ", ref($temp), "\n");

Tip

Always specify the CLASSNAME parameter if the blessing function might be inherited.

caller ([EXPR])

Category: Scope
Return Value: in Scalar Context: SCALAR, true if the current code has been called as a subroutine (this includes code which is included using a require() or an eval() call). Otherwise, false.
Return Value in Array Context: ARRAY, contains details of the calling context comprising the package name, file name, and line of the call.
Definition: This function is used to test the current scope of a subroutine call.


sub testcaller {

    ($package, $file, $line) = caller;

print("caller() Package=$package File=$file Line=$line\n");

}

testcaller();

chdir ([DIRNAME])

Category: Directory
Return Value: SCALAR, true if successful, false otherwise.
Definition: Changes the current directory to the directory specified. If no argument is given changes to the home directory of the current user.


chdir("/") ? print("It worked.\n") : print("It didn't work.\n");

chmod (MODE, LIST)

Category: File, UNIX
Return Value: SCALAR, the number of files changed.
Definition: MODE is an octal number representing file permissions which are applied to all the files in LIST.


chmod(0744, "test1.txt", "test2.txt");

chomp ([STRING | LIST])

Category: Array, String
Return Value: SCALAR, the number of characters removed.
Definition: This is a safer alternative than the chop() function for removing characters at the end of strings. Chomp() only removes characters that correspond to the value of $/ (the input line separator). It can be given a list of strings upon which to perform this operation. When given no arguments the chomp operation is performed on $_.


$temp = "AAAAA!\n";

print("chomp(\$temp) returned ", chomp($temp), ".\n");

chop ([STRING | LIST])

Category: Array, String
Return Value: SCALAR, the last character that was removed.
Definition: This function removes the last character of STRING or the last character of each element in LIST.


$tmp = "1234";

print("chop(\$tmp) returned ", chop($tmp), "\n");

Tip

Use chomp() (with $/ set to "\n") rather than chop() if you are not sure that the string has a trailing newline.

chown (NUMERICAL_UID, NUMERICAL_GID, LIST)

Category: File, UNIX
Return Value: SCALAR, the number of files successfully changed.
Definition: Changes the ownership of the files in LIST to the user ID and the group ID specified as parameters.


chown(1, 1, "test1.txt");

chr (NUMBER)

Category: String
Return Value: SCALAR, the character represented by NUMBER.
Definition: Returns the ASCII character represented by NUMBER. For example, chr(69) is the letter E. See Appendix E, "ASCII Table" for more information.

chroot (DIR_NAME)

Category: File, UNIX
Return Value: SCALAR, true if successful, false otherwise.
Definition: Changes the root directory of the current process to DIR_NAME. Which means that a filename like /john.dat might really refer to /root/users/~jmiller/john.dat.


chroot("/usr/~waters");

Tip

Your process must have superuser rights in order to successfully use this function. It is used to make processes safer by only allowing them access to the subdirectory tree relevant to their purpose.

close (FILEHANDLE)

Category: File
Return Value: SCALAR, true if the file was closed correctly, false if not.
Definition: Closes the file opened with FILEHANDLE. This operation flushes all buffered output. If the file handle refers to a pipe the Perl program waits until the process being piped to has finished.


open(FILE, "test1.txt");

# some file activity

close(FILE);

closedir (DIRHANDLE)

Category: Directory, Files
Return Value: SCALAR, true if the directory was closed correctly, false if not.
Definition: Closes the directory opened by opendir().


opendir(DIR, ".");

# some directory activity

closedir(DIR);

connect (SOCKET, NAME)

Category: Socket
Return Value: SCALAR, true if the connection was successful, otherwise false.
Definition: Attempts to connect to a remote socket. NAME must be a packed address of the correct type for the socket.

cos ([EXPR])

Category: Math
Return Value: SCALAR, the cosine of EXPR or else $_ is used if no expression is specified.
Definition: Calculates a cosine.


$temp = cos(60);

crypt (TEXT, SALT)

Category: String
Return Value: SCALAR, an encrypted string.
Definition: Encrypts TEXT using a key (either SALT or the first two letters of TEXT).


$encyptedString = crypt("Password","TR");

dbmclose (HASH)

Category: Database
Return Value: SCALAR, true if the close was successful, false otherwise.
Definition: Undoes the linking of HASH to a dbm file.

Tip

This function has been superseded by the untie() function.

dbmopen (HASH, DATABASE_NAME, MODE)

Category: Database
Return Value: None
Definition: Links HASH to DATABASE_NAME. If the database does not exist, a new one with the specified MODE will be created.

Tip

This function has been superseded by the tie() function.

defined (EXPR)

Category: Miscellaneous
Return Value: SCALAR, true if EXPR has a real value, false otherwise.
Definition: There is a subtle distinction between an undefined null value and a defined null value. Some functions return undefined null to indicate errors, while others return a defined null to indicate a particular result (use a comparison with the null string to test for this rather than using defined()).


@iexist = (1,2,3);

print("exists.\n") if defined(@iexist);

print("does not exist.\n") unless defined(@iexist);

delete (EXPR)

Category: Hash
Return Value: SCALAR, the deleted value or the undefined value if nothing was deleted.
Definition: Deletes an entry from an associative array. EXPR is the key for the entry to delete.


%Hash = ('Jan' => 'One', 'Feb' => 'Two', 'Mar' => 'Three');

delete($Hash{'Jan'});

die ([LIST])

Category: Process
Return Value: None.
Definition: Terminates execution of the Perl script, printing LIST to STDERR. The exit value is the current value of $! which may have been set by a previous function. If $! has a value of zero, $? will be returned instead. If $? is zero, it exits with an exit value of 255. If LIST does not end in a newline, the text similar to "at test.pl at line 10" will be appended to the end.


die("Something fatal has happened and the script must die!");

do (SCRIPTNAME)

Category: Miscellaneous
Return Value: None
Definition: Executes the contents of a file as a Perl script. It is usually used to include subroutines however it has been mostly superseded by use() and require().

dump ([LABEL])

Category: Process, UNIX
Return Value: None.
Definition: Causes the program to create a binary image or core dump. You can reload the image using undump program. When reloaded, the program begins execution from the optional label specified. So it is possible to set up a program which initializes data structures to dump() after the initialization so that execution is faster when reloading the dumped image.

each (HASH)

Category: Hash
Return Value: ARRAY, an entry (the key-value pair) in HASH.
Definition: Allows iteration over the entries in an associative array. Each time it is evaluated, another key-value pair is returned. When all the entries have been returned, it returns an empty array.


%NumberWord = ('1' => 'One', '2' => 'Two', '3' => 'Three');

while (($key, $value) = each(%NumberWord)) {

    print("$key: $value\n");

}

endgrent ( )

Category: Group, UNIX
Return Value: SCALAR, true if successful, false if not.
Definition: Closes the /etc/group file used by getgrent() and other group related functions.


($name, $pw, $gid, @members) = getgrent();

endgrent();

endhostent ( )

Category: Host, Sockets, UNIX
Return Value: SCALAR, true if successful, false if not.
Definition: Closes the TCP socket used by gethostbyname() and host related functions.


$host = gethostbyname("lynch");

endhostent();

endnetent ( )

Category: Network, UNIX
Return Value: SCALAR, true if successful, false if not.
Definition: Closes the /etc/networks file used by getnetent() and network related functions.


($name, $aliases, $addrtype, $net) = getnetent();

endnetent();

endprotoent ( )

Category: Protocol, UNIX
Return Value: SCALAR, true if successful, false if not.
Definition: Closes the /etc/protocols file used by getprotoent() and protocol related functions.


($name, $alias, $protocol) = getprotoent();

endprotoent();

endpwent ( )

Category: Password, UNIX
Return Value: SCALAR, true if successful, false if not.
Definition: Closes the /etc/passwd file used by getpwent() and password related functions.


($name, $pass, $uid, $gid, $quota, $name, 

    $gcos, $logindir, $shell) = getpwent();

endpwent();

endservent ( )

Category: Server, UNIX
Return Value: SCALAR, true if successful, false if not.
Definition: Closes the /etc/servers file used by getservent() and related functions.


($name, $aliases, $port, $protocol) = getservent();

endservent();

eof ([FILEHANDLE])

Category: File
Return Value: SCALAR, true if the next read on FILEHANDLE will be at the end of file, false if not.
Definition: Tests for the end of a file. This is done by reading the next character and then undoing this operation (so is only suitable on files where this can be done safely). If no argument is supplied the file tested is the last file which was read. If the empty list is supplied then a pseudo file is created of the files listed on the command line. This lets you test for the end of the last file on the command line.


open(FILE, "test1.txt");

# some file activity

print("eof() returned ", eof(FILE) ? "TRUE" : "FALSE", "\n");

close(FILE);

eval ([EXPR | BLOCK])

Category: Miscellaneous
Return Value: The undefined value if a syntax error, a runtime error, or a die() function occurs. Otherwise, the return value is the value of EXPR or the last statement in BLOCK. The return value can be any type.
Definition: Treats the expression like a Perl program and executes it. As the context of this execution is the same as that of the script itself, variable definitions and subroutine definitions persist. Syntax errors, runtime errors, and execution of the die() function are trapped and an undefined result is returned. If such an error does occur $@ is set. $@ will be equal to a defined null string if no errors are found. If no expression is supplied, $_ is the default argument. If the block syntax is used then the expressions in the block are evaluated only once within the script (which may be more efficient for certain situations).

Tip

eval() traps possible error conditions which would otherwise crash a program and so can be used to test if certain features are available which would cause runtime errors if used when not available. See Chapter 13, "Handling Errors and Signals," for more information.


$answer = 3;

eval("$answer = ;");

if ($@ eq "") {

    print("eval() returned success.\n");

}

else {

    print("eval() error: $@");

}

exec (LIST)

Category: Process
Return Value: None.
Definition: This function passes control from the script to an external system command. There is no return from this call. Note that system() calls external commands and does return.


exec("cat /etc/motd");

exists (EXPR)

Category: Hash
Return Value: SCALAR, true if EXPR is an entry in a hash, false if not.
Definition: Tests whether a given key value exists in an associative array.


%test = ( 'One' => '1', 'Two' => '2');

if (exists($test{'One'})) {

    print("exists() returned success.\n");

}

else {

    print("exists() returned an error.\n");

}

exit ([EXPR])

Category: Process
Return Value: None.
Definition: Evaluates EXPR and exits the program with that value as the exit code. The default value for the exit code is 0 if no argument is supplied. If an END block
has been defined, it will be called. Also, object destructors may be called before the process truly ends.


exit(16);

exp ([EXPR])

Category: Math
Return Value: SCALAR, the natural log base (e) to the power of EXPR.
Definition: Returns the natural log base (e) to the power of EXPR. If no parameter is specified, $_ is used.


print "exp() e**1 is ", exp(1), "\n";

fcntl (FILEHANDLE, FUncTION, PACKED_FLAGS)

Category: File, UNIX
Return Value: None.
Definition: In Perl 5 use the fntcl module. In Perl 4 there should be some mechanism for linking the perl functions to the system functions which is usually executed when Perl is installed. See the perlfunc man page for more information.

fileno (FILEHANDLE)

Category: File
Return Value: SCALAR, the file descriptor for FILEHANDLE.
Definition: Returns the file descriptor given a file handle. File descriptors are useful when using bitmaps for the select() function.


print("fileno() ", fileno(FILE), "\n");

flock (FILEHANDLE, OPERATION_FLAGS)

Category: File
Return Value: SCALAR, true if successful, false if not.
Definition: Lets you access file locks. You can place an exclusive lock, place a shared lock, or remove locks. You can find more information about flock() in section 2 of the UNIX manual pages.

fork ( )

Category: Process UNIX
Return Value: SCALAR, the pid of the child process or undef is unsuccessful.
Definition: Starts a child process. Both child and parent processes start executing the line of code immediately following the fork() call. You can find more information about fork() in section 2 of the UNIX manual pages.

formline (PICTURE, LIST)

Category: Miscellaneous
Return Value: None.
Definition: This internal function is used by the format mechanism. It allows direct manipulation of the format process by adding values to the format accumulator ($^A). For more information about formats, see Chapter 11, "Creating Reports."

getc ([FILEHANDLE])

Category: File, Input
Return Value: SCALAR, the inputted character. Null if at end of file.
Definition: Returns the next character FILEHANDLE or STDIN if no filehandle is specified.


open(FILE, "/etc/motd");

print "getc() ", getc(FILE), "\n";

close(FILE);

getgrent ( )

Category: Group, UNIX
Return Value: in Scalar Context : Returns the next group name or the undefined value if no more groups or an error occurred.
Return Value in Array Context : ($name, $passwd, $gid, $members) or an empty list.
Definition: Returns information about groups taken from the /etc/group system file. If called repeatedly, it will iterate through the entries in the /etc/group file.


($name, $pw, $gid, @members) = getgrent();

print("getgrent() Examines /etc/group [$name,$gid] file.\n");

getgrgid (GID)

Category: Group, UNIX
Return Value: in Scalar Context: The next group name that belongs to GID.

Return Value in Array Context: ($name, $passwd, $gid, $members) or an empty list.
Definition: Returns information about groups taken from the /etc/group system file.


($grname, $grpw, $gid, @members) = getgrgid(0);

print("getgrgid() Returns group name given GID [$grname]\n");

getgrname (NAME)

Category: Group, UNIX
Return Value: in Scalar Context: The next group id that belongs to NAME.
Return Value in Array Context: ($name, $passwd, $gid, $members) or an empty list.
Definition: Returns information about groups taken from the /etc/group system file.


($grname, $grpw, $gid, @members) = getgrnam("root");

print("getgrnam() Returns group GID given name [$gid]\n");

gethostbyaddr (ADDRESS, AF_INIT)

Category: Host, Socket
Return Value: in Scalar Context: Name of host addressed by ADDRESS or undefined if the host could not be found.
Return Value in Array Context: ($name, $aliases, $addrtype, $length, @addrs) or an empty list.
Definition: Looks in the /etc/hosts system file or checks a Domain Name Server for a server with ADDRESS. The value for AF_INIT is always 2.


use Socket;

$addr = pack('C4', (140,203,7,103));

($name, $alias, $addrtype, $length, @addrs) = gethostbyaddr($addr, AF_INET);

print("gethostbyaddr() [$alias].\n");

gethostbyname (NAME, [PROTOCOL])

Category: Host, Socket
Return Value: in Scalar Context: Address of the host called NAME or undefined if the host could not be found.
Return Value in Array Context: ($name, $aliases, $addrtype, $length, @addrs) or an empty list.
Definition: Looks in the /etc/hosts system file or checks a Domain Name Server for a server called NAME.


($name, $alias, $addrtype, $length, @addrs) = gethostbyname("lynch");

print("gethostbyname() [$alias].\n");

gethostent ( )

Category: Host, UNIX
Return Value: in Scalar Context: Name of the next host in /etc/hosts. or the undefined value.
Return Value in Array Context: ($name, $aliases, $addrtype, $length, @addrs) or an empty list.
Definition: Looks in the /etc/hosts system file.


($name, $alias, $addrtype, $length, @addrs) = gethostent();

print("gethostent() [$alias].\n");

getlogin ( )

Category: Process, UNIX
Return Value: SCALAR, the name of the current login.
Definition: Gets the current login name from the /etc/utmp system file. Use getpwuid()for more information on the login because the information stored in /etc/utmp is limited.


print ("getlogin() ", getlogin(), "\n");

getnetbyaddr (ADDRESS, ADDR_TYPE)

Category: Network
Return Value: in Scalar Context: The network name that has an address of ADDRESS or undefined.
Return Value in Array Context: ($name, $aliases, $addrtype, $net) or an empty list.
Definition: Looks for the network information in the /etc/networks system file.


($addrtype) = (getnetent())[2];

($name, $alias, $addrtype, $net) = getnetbyaddr($net, $addrtype);

print("getnetbyaddr() Reads /etc/networks [$name]\n");

getnetbyname (NAME)

Category: Network
Return Value: in Scalar Context: The network address of NAME or undefined.
Return Value in Array Context: ($name, $aliases, $addrtype, $net) or an empty list.
Definition: Looks for the network information in the /etc/networks system file.


($name, $alias, $addrtype, $net) = getnetbyname("localnet");

print("getnetbyname() Reads /etc/networks [$name]\n");

getnetent ( )

Category: Network
Return Value in Scalar Context: The next network name in /etc/networks or undefined.
Return Value in Array Context: ($name, $aliases, $addrtype, $net) or an empty list.
Definition: When called repeatedly, it iterates over the information in the /etc/networks system file.


($name, $alias, $addrtype, $net) = getnetent();

print("getnetent() Reads /etc/networks [$name, $addrtype]\n");

getpeername (SOCKET)

Category: Sockets
Return Value: SCALAR, the address of the remote side of a socket connection represented by SOCKET.
Definition: Gets the packed address of the remote side of a socket. The address can then be used with the unpack() function to retrieve the protocol family, port and ip address values.


$sockaddr = 'S n a4 x8';

$packedRemoteAddr = getpeername(S);

($family, $port, $remoteAddr) = unpack($sockaddr,$packedRemoteAddr);

getpgrp (PID)

Category: Groups, Process, UNIX
Return Value: SCALAR, the current process group for PID. If PID is not specified or 0 is used, the current group of the current process is returned.
Definition: Finds the current process group for a given pid.


print("getpgrp() ", getpgrp(0), "\n");

getppid ( )

Category: Process, UNIX
Return Value: SCALAR, the pid of the parent process.
Definition: Finds the pid of the parent process.


print("getppid() ", getppid(), "\n");

getpriority (WHICH, WHO)

Category: Process, UNIX
Return Value: SCALAR, the current priority associated with the parameters.
Definition: Returns the current priority of WHO (the pid, group pid, uid, or 0 for the current process). The WHICH parameter can one of PRIO_PROCESS (0), PRIO_PGGRP (1), PRIO_USER (2).


print("getpriority() ", getpriority(0, 0), "\n");

getprotobyname (NAME)

Category: Protocols, UNIX
Return Value: in Scalar Context: The protocol number assigned to NAME.
Return Value in Array Context: ($name, $aliases, $proto) or an empty list. $proto is the protocol number.
Definition: Looks in the /etc/protocols system file for the protocol called NAME.


($name, $alias, $proto) = getprotobyname("IP");

print("getprotobyname() /etc/proto [$name, $alias, $proto].\n");

getprotobynumber (NUMBER)

Category: Protocols, UNIX
Return Value: in Scalar Context: The protocol name associated with NUMBER.
Return Value in Array Context: ($name, $aliases, $proto) or an empty list.
Definition: Looks in the /etc/protocols system file for NUMBER.


($name, $alias, $proto) = getprotobynumber(0);

print("getprotobynumber() /etc/protocols [$name, $alias, $proto].\n");

getprotoent ( )

Category: Protocols, UNIX
Return Value: ARRAY. ($name, $aliases, $proto) or an empty list.
Definition: When called repeatedly, getprotoent() iterates over the /etc/protocols system file.


($name, $alias, $proto) = getprotoent();

print("getprotoent() Closes /etc/protocols [$name, $alias, $proto].\n");

getpwent ( )

Category: Password, UNIX
Return Value: in Scalar Context: The username.
Return Value in Array Context: ARRAY. ($name, $passwd, $uid, $gid, $quota, $comment, $gcos, $dir, $shell) or an empty list.
Definition: When called repeatedly, getpwent() iterates over the /etc/passwd system file.


($name, $pass, $uid, $gid, $quota, $name, $gcos, $dir, $shell) = getpwent();

print("getpwent() /etc/passwd [$dir, $shell].\n");

getpwnam (NAME)

Category: Password, UNIX
Return Value: in Scalar Context: The userid of NAME.
Return Value in Array Context: ($name, $passwd, $uid, $gid, $quota, $comment, $gcos, $dir, $shell) or an empty list.
Definition: Looks in the /etc/passwd system file for NAME.


($name, $pass, $uid, $gid, $quota, $name, 

    $gcos, $dir, $shell) = getpwnam("root");

print("getpwnam() /etc/passwd [$dir, $shell].\n");

getpwuid (UID)

Category: Password, UNIX
Return Value: in Scalar Context: The username of UID.
Return Value in Array Context: ($name, $passwd, $uid, $gid, $quota, $comment, $gcos, $dir, $shell) or an empty list.
Definition: Looks in the /etc/passwd system file for UID.


($name, $pass, $uid, $gid, $quota, $name, 

    $gcos, $dir, $shell) = getpwuid(0);

print("getpwuid() /etc/passwd [$dir, $shell].\n");

getservbyname (NAME, PROTOCOL)

Category: Protocol, Service, Socket, UNIX
Return Value: in Scalar Context: The port number.
Return Value in Array Context: ($name, $aliases, $port, $proto) or an empty list.
Definition: Gets services by name. Looks in the /etc/services system file.


($name, $aliases, $port, $protol) = getservbyname("tcpmux", "tcp");

getservbyport (PORT_NUMBER, PROTOCOL)

Category: Protocol, Service, Socket, UNIX
Return Value: in Scalar Context: The service name.
Return Value in Array Context: ($name, $aliases, $port, $proto) or an empty list.
Definition: Gets services by port. Looks in the /etc/services system file.


($name, $aliases, $port, $protol) = getservbyport(512, "tcp");

getservent ( )

Category: Protocol, Service, Socket, UNIX
Return Value: in Scalar Context: The next service name.
Return Value in Array Context: ($name, $aliases, $port, $proto) or an empty list.
Definition: When called repeatedly, iterates over the /etc/services system file.


($name, $aliases, $port, $protol) = getservent();

print("getservent() /etc/servers [$name].\n");

getsockname (SOCKET)

Category: Sockets
Return Value: SCALAR, the packed address of the local end of the socket.
Definition: Finds out the address of your script's socket.


$packedAddr = getsockname(S);

($family, $port, $localAddr) = unpack('S n a4 x8', $packedAddr);

getsockopt (SOCKET, LEVEL, OPTNAME)

Category: Sockets
Return Value: SCALAR, the socket option requested or the undefined value.
Definition: Gets the value of a specified socket option.

glob (EXPR)

Category: File
Return Value: ARRAY, the list of files represented by EXPR.
Definition: Looks for file name that match EXPR. You can use wildcards in EXPR.


@files = glob("*.txt");

gmtime ([EXPR])

Category: Time
Return Value: in Scalar Context: A string like 'Sat Jul 13 07:34:46 1986' describing EXPR.
Return Value in Array Context: ($sec, $min, $hour, $mday, $mon, $year, $wday, $ydat, $isdst).
Definition: Breaks EXPR (a number of seconds since 1st Jan 1970) into a 9-element list. If no argument is used the current time is used. If your system supports POSIX time zones, the time returned is localized for the Greenwich Mean Time time zone. Note that $mon ranges from 0..11, $wday ranges from 0..6, and $year does not handle centuries.


($sec, $min, $hour, $mday, $mon, $year, $wday, $ydat, $isdst) = gmtime();

print "gmtime() 19$year-$mon-$mday\n";

grep (BLOCK | EXPR, LIST)

Category: Regular Expressions
Return Value: in Scalar Context: The number of times that BLOCK or EXPR evaluated to true.
Return Value in Array Context: A list of the elements of LIST that causes BLOCK or EXPR to evaluate as true.
Definition: Evaluates the expression or block for each of the elements in LIST. Think of this function as having an internal foreach loop. Each element in LIST is assigned to $_ and then the block or expression is evaluated. The most common use for this is with a pattern match operation as the expression, and a list of strings to be processed. You may be tempted to use grep() as an easy way to interate over an array as shown in the second example below, don't do this. Use the map() function instead.


# Look for all elements that begin with the letter T.

@a = ('One', 'Two', 'Three', 'Four', 'Five');

print("grep(), ", grep(/^T/, @a), "\n");



# Print all elements in a list.

@a = ('One', 'Two', 'Three', 'Four', 'Five');

grep( print("$_\n"), @a);

hex (EXPR)

Category: Math, String
Return Value: SCALAR, the decimal value of EXPR.
Definition: Converts EXPR from hexadecimal to decimal. For example, hex('FF0') will return '4080'. You can use the string returned as a number because Perl will automatically convert strings to numbers in numeric contexts.


print("hex() ", hex("ff"), "\n");

import ( )

Category: Miscellaneous
Return Value: None.
Definition: This is the only user-defined function in this list. If a module has an import() function then the use() function will call it as the module is being loaded. You can use the import() function to initialize variables, open files, or do any other setup work.

index (STRING, SUBSTRING, [POSITION])

Category: String
Return Value: SCALAR, the position of the first occurrence of SUBSTRING in STRING at or after POSITION or -1 if not found.
Definition: When called repeatedly, you can iterate over all the occurrences of SUBSTRING in STRING. The returned value is an offset from $[ (which is normally zero). If $[ is altered it will change the way index() works as it will start its search from $[ if no position argument is supplied, and it will return $[ - 1 when there is no match found.


$answer1 = index("abcdefghijiklmdef:-)", "def");

$answer2 = index("abcdefghijiklmdef", "def", $answer1 + 3);

print("index() def is at $answer1 and next at $answer2\n");

int ([EXPR])

Category: Math
Return Value: SCALAR, the integer portion of EXPR.
Definition: Chops of any fractional part of EXPR or $_ if no expression is specified.
For example, int(21.45) would return 21.


print("int() ", int(345.678), "\n");

ioctl (FILEHANDLE, FUncTION, SCALAR)

Category: File, UNIX
Return Value: SCALAR, true if successful; false if not and the undefined value in some cases.
Definition: Controls Input/Output operations, mainly used for terminals. It calls the UNIX ioctl() function with the specified parameters. Returns undefined if the operating system returns -1. Returns string "0 but true" if the operating system returns 0. Otherwise returns the value returned by the operating system. You can find more information about ioctl() in section 2 of the UNIX manual pages.

join (EXPR, LIST)

Category: Array, String
Return Value: SCALAR, a string with each element of LIST alternating with EXPR.
Definition: Concatenates all of the elements of LIST together with EXPR as the glue. For example, join('!', ('QQ', 'AA')) will return 'QQ!AA'.


@listone = (0, 1, 2, 3);

print("join() ", join("-",@listone), "\n");

keys (HASH)

Category: Array, Hash
Return Value: in Scalar Context: The number of keys and, therefore, the number of entries in HASH.
Return Value in Array Context: All of the keys to HASH in no particular order.
Definition: Gets a list of all keys in HASH. The returned list is ordered by the internal storage requirements, so it is often useful to use the sort() function before processing. For example, sort(keys(%hash)).


%hash = ('One' => 1, 'Two' => 2, 'Three' => 3, 'Four' => 4);

print("keys() ", join("-", keys(%hash)), "\n");

kill (SIGNAL, LIST)

Category: Process
Return Value: SCALAR, the number of processes successfully signaled.
Definition: Sends SIGNAL to the processes identified by LIST. If SIGNAL is negative then process groups are killed instead.

lc (EXPR)

Category: String
Return Value: SCALAR, a copy of EXPR with all letters in lowercase.
Definition: Creates a copy of EXPR with all letters in lowercase.


print("lc() ", lc("ABCDef"), "\n");

lcfirst (EXPR)

Category: String
Return Value: SCALAR, a copy of EXPR with the first letter in lowercase.
Definition: Creates a copy of EXPR with the first letter in lowercase.


print("lcfirst() ", lcfirst("ABCDef"), "\n");