*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> perlfunc (1)              



NAME    [Toc]    [Back]

       perlfunc - Perl builtin functions

DESCRIPTION    [Toc]    [Back]

       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",

       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",

       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",
       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",

       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",

       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

       Alphabetical Listing of Perl Functions    [Toc]    [Back]

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


                   while (<>) {
                       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

               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

               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 _;

                   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 $_.

               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

               For the tangent operation, you may use the
               "Math::Trig::tan" function, or use the familiar

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

               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,

                   ($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,
                   $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
                   $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,
                   #  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

               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

       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.


                   open(OUTPUT, '|sort >foo')  # pipe to sort
                       or die "Can't start sort: $!";
                   #...                         #  print stuff to
                   close OUTPUT                # wait for sort to
                       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
                   } continue {
                       ### next always comes here
                       # 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

               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
                   while (($key,$val) = each %HIST) {
                       print $key, ' = ', unpack('L',$val), "0;

               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.


                   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

                   %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

               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,

                   delete $ref->[$x][$y][$index];
                   delete   @{$ref->[$x][$y]}[$index1,   $index2,

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

               See also exit(), warn(), and the Carp module.

               If LIST 

 Similar pages
Name OS Title
perljp OpenBSD AEuEU,i Perl Y~YxYE `A^a`I`A Perl xIAx3|xOxex|x3x1/2! Perl 5.8.0 xexeicUni- _ codeYuYYi1/4YEx~AcEyxE...
perlintern OpenBSD autogenerated documentation of purely inter- nal Perl functions
logout FreeBSD shell builtin commands
ls-F FreeBSD shell builtin commands
notify FreeBSD shell builtin commands
onintr FreeBSD shell builtin commands
popd FreeBSD shell builtin commands
pushd FreeBSD shell builtin commands
readonly FreeBSD shell builtin commands
rehash FreeBSD shell builtin commands
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service