=head1 NAME X perlfunc - Perl builtin functions =head1 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 L.) 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, L|/splice ARRAY,OFFSET,LENGTH,LIST> has three scalar arguments followed by a list, whereas L|/gethostbyname NAME> 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 I like a function, therefore it I 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 L|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 L|/time> and L|/endpwent>. For example, C always means C. 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 B 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. X 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 C<(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 L, L, L, etc.) return true when they succeed and L|/undef EXPR> otherwise, as is usually mentioned in the descriptions below. This is different from the C interfaces, which return C<-1> on failure. Exceptions to this rule include L|/wait>, L|/waitpid PID,FLAGS>, and L|/syscall NUMBER, LIST>. System calls also set the special L|perlvar/$!> 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 L for the mechanism. If you are using such a module, see the module's documentation for details of the syntax that it defines. =head2 Perl Functions by Category X 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 L and L. =over 4 =item Functions for SCALARs or strings X X X =for Pod::Functions =String L|/chomp VARIABLE>, L|/chop VARIABLE>, L|/chr NUMBER>, L|/crypt PLAINTEXT,SALT>, L|/fc EXPR>, L|/hex EXPR>, L|/index STR,SUBSTR,POSITION>, L|/lc EXPR>, L|/lcfirst EXPR>, L|/length EXPR>, L|/oct EXPR>, L|/ord EXPR>, L|/pack TEMPLATE,LIST>, LE>|/qESTRINGE>, LE>|/qqESTRINGE>, L|/reverse LIST>, L|/rindex STR,SUBSTR,POSITION>, L|/sprintf FORMAT, LIST>, L|/substr EXPR,OFFSET,LENGTH,REPLACEMENT>, LEE>|/trEEE>, L|/uc EXPR>, L|/ucfirst EXPR>, LEE>|/yEEE> L|/fc EXPR> is available only if the L feature|feature/The 'fc' feature> is enabled or if it is prefixed with C. The L feature|feature/The 'fc' feature> is enabled automatically with a C (or higher) declaration in the current scope. =item Regular expressions and pattern matching X X X =for Pod::Functions =Regexp LE>|/mEE>, L|/pos SCALAR>, LE>|/qrESTRINGE>, L|/quotemeta EXPR>, LEE>|/sEEE>, L|/split EPATTERNE,EXPR,LIMIT>, L|/study SCALAR> =item Numeric functions X X X X =for Pod::Functions =Math L|/abs VALUE>, L|/atan2 Y,X>, L|/cos EXPR>, L|/exp EXPR>, L|/hex EXPR>, L|/int EXPR>, L|/log EXPR>, L|/oct EXPR>, L|/rand EXPR>, L|/sin EXPR>, L|/sqrt EXPR>, L|/srand EXPR> =item Functions for real @ARRAYs X =for Pod::Functions =ARRAY L|/each HASH>, L|/keys HASH>, L|/pop ARRAY>, L|/push ARRAY,LIST>, L|/shift ARRAY>, L|/splice ARRAY,OFFSET,LENGTH,LIST>, L|/unshift ARRAY,LIST>, L|/values HASH> =item Functions for list data X =for Pod::Functions =LIST L|/grep BLOCK LIST>, L|/join EXPR,LIST>, L|/map BLOCK LIST>, LE>|/qwESTRINGE>, L|/reverse LIST>, L|/sort SUBNAME LIST>, L|/unpack TEMPLATE,EXPR> =item Functions for real %HASHes X =for Pod::Functions =HASH L|/delete EXPR>, L|/each HASH>, L|/exists EXPR>, L|/keys HASH>, L|/values HASH> =item Input and output functions X X X X =for Pod::Functions =I/O L|/binmode FILEHANDLE, LAYER>, L|/close FILEHANDLE>, L|/closedir DIRHANDLE>, L|/dbmclose HASH>, L|/dbmopen HASH,DBNAME,MASK>, L|/die LIST>, L|/eof FILEHANDLE>, L|/fileno FILEHANDLE>, L|/flock FILEHANDLE,OPERATION>, L|/format>, L|/getc FILEHANDLE>, L|/print FILEHANDLE LIST>, L|/printf FILEHANDLE FORMAT, LIST>, L|/read FILEHANDLE,SCALAR,LENGTH,OFFSET>, L|/readdir DIRHANDLE>, L|/readline EXPR>, L|/rewinddir DIRHANDLE>, L|/say FILEHANDLE LIST>, L|/seek FILEHANDLE,POSITION,WHENCE>, L|/seekdir DIRHANDLE,POS>, L|/select RBITS,WBITS,EBITS,TIMEOUT>, L|/syscall NUMBER, LIST>, L|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>, L|/sysseek FILEHANDLE,POSITION,WHENCE>, L|/syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET>, L|/tell FILEHANDLE>, L|/telldir DIRHANDLE>, L|/truncate FILEHANDLE,LENGTH>, L|/warn LIST>, L|/write FILEHANDLE> L|/say FILEHANDLE LIST> is available only if the L feature|feature/The 'say' feature> is enabled or if it is prefixed with C. The L feature|feature/The 'say' feature> is enabled automatically with a C (or higher) declaration in the current scope. =item Functions for fixed-length data or records =for Pod::Functions =Binary L|/pack TEMPLATE,LIST>, L|/read FILEHANDLE,SCALAR,LENGTH,OFFSET>, L|/syscall NUMBER, LIST>, L|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>, L|/sysseek FILEHANDLE,POSITION,WHENCE>, L|/syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET>, L|/unpack TEMPLATE,EXPR>, L|/vec EXPR,OFFSET,BITS> =item Functions for filehandles, files, or directories X X X X X X =for Pod::Functions =File L>|/-X FILEHANDLE>, L|/chdir EXPR>, L|/chmod LIST>, L|/chown LIST>, L|/chroot FILENAME>, L|/fcntl FILEHANDLE,FUNCTION,SCALAR>, L|/glob EXPR>, L|/ioctl FILEHANDLE,FUNCTION,SCALAR>, L|/link OLDFILE,NEWFILE>, L|/lstat FILEHANDLE>, L|/mkdir FILENAME,MODE>, L|/open FILEHANDLE,MODE,EXPR>, L|/opendir DIRHANDLE,EXPR>, L|/readlink EXPR>, L|/rename OLDNAME,NEWNAME>, L|/rmdir FILENAME>, L|/select FILEHANDLE>, L|/stat FILEHANDLE>, L|/symlink OLDFILE,NEWFILE>, L|/sysopen FILEHANDLE,FILENAME,MODE>, L|/umask EXPR>, L|/unlink LIST>, L|/utime LIST> =item Keywords related to the control flow of your Perl program X =for Pod::Functions =Flow L|/break>, L|/caller EXPR>, L|/continue BLOCK>, L|/die LIST>, L|/do BLOCK>, L|/dump LABEL>, L|/eval EXPR>, L|/evalbytes EXPR>, L|/exit EXPR>, L|/__FILE__>, L|/goto LABEL>, L|/last LABEL>, L|/__LINE__>, L|/method NAME BLOCK>, L|/next LABEL>, L|/__PACKAGE__>, L|/redo LABEL>, L|/return EXPR>, L|/sub NAME BLOCK>, L|/__SUB__>, L|/wantarray> L|/break> is available only if you enable the experimental L feature|feature/The 'switch' feature> or use the C prefix. The L feature|feature/The 'switch' feature> also enables the C, C and C statements, which are documented in L. The L feature|feature/The 'switch' feature> is enabled automatically with a C (or higher) declaration in the current scope. In Perl v5.14 and earlier, L|/continue BLOCK> required the L feature|feature/The 'switch' feature>, like the other keywords. L|/evalbytes EXPR> is only available with the L feature|feature/The 'unicode_eval' and 'evalbytes' features> (see L) or if prefixed with C. L|/__SUB__> is only available with the L feature|feature/The 'current_sub' feature> or if prefixed with C. Both the L|feature/The 'unicode_eval' and 'evalbytes' features> and L|feature/The 'current_sub' feature> features are enabled automatically with a C (or higher) declaration in the current scope. =item Keywords related to scoping =for Pod::Functions =Namespace L|/caller EXPR>, L|/class NAMESPACE>, L|/field VARNAME>, L|/import LIST>, L|/local EXPR>, L|/my VARLIST>, L|/our VARLIST>, L|/package NAMESPACE>, L|/state VARLIST>, L|/use Module VERSION LIST> L|/state VARLIST> is available only if the L feature|feature/The 'state' feature> is enabled or if it is prefixed with C. The L feature|feature/The 'state' feature> is enabled automatically with a C (or higher) declaration in the current scope. =item Miscellaneous functions =for Pod::Functions =Misc L|/defined EXPR>, L|/formline PICTURE,LIST>, L|/lock THING>, L|/prototype FUNCTION>, L|/reset EXPR>, L|/scalar EXPR>, L|/undef EXPR> =item Functions for processes and process groups X X X =for Pod::Functions =Process L|/alarm SECONDS>, L|/exec LIST>, L|/fork>, L|/getpgrp PID>, L|/getppid>, L|/getpriority WHICH,WHO>, L|/kill SIGNAL, LIST>, L|/pipe READHANDLE,WRITEHANDLE>, LE>|/qxESTRINGE>, L|/readpipe EXPR>, L|/setpgrp PID,PGRP>, L|/setpriority WHICH,WHO,PRIORITY>, L|/sleep EXPR>, L|/system LIST>, L|/times>, L|/wait>, L|/waitpid PID,FLAGS> =item Keywords related to Perl modules X =for Pod::Functions =Modules L|/do EXPR>, L|/import LIST>, L|/no MODULE VERSION LIST>, L|/package NAMESPACE>, L|/require VERSION>, L|/use Module VERSION LIST> =item Keywords related to classes and object-orientation X X X =for Pod::Functions =Objects L|/bless REF,CLASSNAME>, L|/class NAMESPACE>, L|/dbmclose HASH>, L|/dbmopen HASH,DBNAME,MASK>, L|/field VARNAME>, L|/method NAME BLOCK>, L|/package NAMESPACE>, L|/ref EXPR>, L|/tie VARIABLE,CLASSNAME,LIST>, L|/tied VARIABLE>, L|/untie VARIABLE>, L|/use Module VERSION LIST> =item Low-level socket functions X X =for Pod::Functions =Socket L|/accept NEWSOCKET,GENERICSOCKET>, L|/bind SOCKET,NAME>, L|/connect SOCKET,NAME>, L|/getpeername SOCKET>, L|/getsockname SOCKET>, L|/getsockopt SOCKET,LEVEL,OPTNAME>, L|/listen SOCKET,QUEUESIZE>, L|/recv SOCKET,SCALAR,LENGTH,FLAGS>, L|/send SOCKET,MSG,FLAGS,TO>, L|/setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL>, L|/shutdown SOCKET,HOW>, L|/socket SOCKET,DOMAIN,TYPE,PROTOCOL>, L|/socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL> =item System V interprocess communication functions X X X X X X =for Pod::Functions =SysV L|/msgctl ID,CMD,ARG>, L|/msgget KEY,FLAGS>, L|/msgrcv ID,VAR,SIZE,TYPE,FLAGS>, L|/msgsnd ID,MSG,FLAGS>, L|/semctl ID,SEMNUM,CMD,ARG>, L|/semget KEY,NSEMS,FLAGS>, L|/semop KEY,OPSTRING>, L|/shmctl ID,CMD,ARG>, L|/shmget KEY,SIZE,FLAGS>, L|/shmread ID,VAR,POS,SIZE>, L|/shmwrite ID,STRING,POS,SIZE> =item Fetching user and group info X X X X X X X =for Pod::Functions =User L|/endgrent>, L|/endhostent>, L|/endnetent>, L|/endpwent>, L|/getgrent>, L|/getgrgid GID>, L|/getgrnam NAME>, L|/getlogin>, L|/getpwent>, L|/getpwnam NAME>, L|/getpwuid UID>, L|/setgrent>, L|/setpwent> =item Fetching network info X X X X X X
X =for Pod::Functions =Network L|/endprotoent>, L|/endservent>, L|/gethostbyaddr ADDR,ADDRTYPE>, L|/gethostbyname NAME>, L|/gethostent>, L|/getnetbyaddr ADDR,ADDRTYPE>, L|/getnetbyname NAME>, L|/getnetent>, L|/getprotobyname NAME>, L|/getprotobynumber NUMBER>, L|/getprotoent>, L|/getservbyname NAME,PROTO>, L|/getservbyport PORT,PROTO>, L|/getservent>, L|/sethostent STAYOPEN>, L|/setnetent STAYOPEN>, L|/setprotoent STAYOPEN>, L|/setservent STAYOPEN> =item Time-related functions X