Built-In Functions

                    CHAPTER 10: BUILT-IN FUNCTIONS


   Built-In Functions

     - Perl has many useful built-in functions 

     - Many of these perform a function similar to a UNIX system call 
       or library routine

     - See the Perl man page or the Camel book for details on all of 
       the Perl built-in functions


   Context

     - Certain operations know what context they are being used in and 
       evaluate their operands in that context

     - For example, the assignment operator (=) knows if it is being 
       used in an array or a scalar context and evaluates the rvalue 
       in the proper context.

           ($x) = (5,6,7,8);       # Array context, $x is 5
           $x = (5,6,7,8);         # Scalar context, $x is 4
                                   #   (the length of the list)
   
     - Other operations supply a context and evaluate their operands in 
       that context

     - For example, the addition operator (+) always evaluates its 
       operands in a scalar context

           @y = (5,6,7,8);
           $x = 9 + @y;            # $x is 13


   List Arguments

     - Many of these built-in functions take a list as an argument

     - Elements of the list are separated by commas

     - Each element of the list is evaluated in an array context

 
   Function Call vs Unary Operator

     - All of the built-in functions can be used as a function call 
       (duh, obviously!)

     - But some of them can also be used as a unary operator

     - To use the operation as a function call, the next token on the 
       same line must be a left parenthesis

     - If any token other than a left parenthesis follows the operation, 
       it is a unary operator

     - This is important because the named unary operators have a higher 
       precedence then some of the binary operators!  When in doubt, use 
       parentheses!

     - Also remember this rule: If it looks like a function, it is a
                                function!


   Example: The Chop Function

     - The chop function can be used as follows:

         chop (LIST)
         chop (SCALAR)
         chop SCALAR
         chop

     - Note that chop can be used as a function call with either a list 
       or a scalar argument

     - But chop can also be used as a unary operator (no parentheses) on 
       a single scalar

     - Chop can also be used without ANY arguments, in which case it 
       operates on $_ (the default variable)

     - Note that chop can NOT be used as a unary operator on a single 
       list argument

     - Thus, if you want to have chop operate on $_, you must use just 
       "chop".  If you use "chop ()", chop operates on the empty list.


   Example: The Print Function

     - The print function can be used as follows:

         print (FILEHANDLE LIST)
         print (LIST)
         print FILEHANDLE LIST
         print LIST
         print

     - Note that print can be used as a function call with either a 
       filehandle and a list argument or just a list argument

     - But print can also be used as a unary operator (no parentheses) 
       on a single list or a list preceded by a filehandle (in this 
       latter case the filehandle is detected and used to control where 
       print sends the data; the unary argument is still the list)

     - Note that there is NO comma after the FILEHANDLE!  But the 
       elements of LIST must be comma-separated.  This allows the 
       FILEHANDLE to be the value of a scalar variable.

     - Ex.

         $outfile = "OUT";
         print ($outfile "Hi");    # Prints: "Hi" to FH OUT
         print ($outfile, "Hi");   # Prints: "OUTHi" to STDOUT

         Note that when a comma follows $outfile, the scalar
         $outfile is interpreted as just another item to be
         added to the list of items to be printed!  Without 
         the comma, it is assumed to be a scalar holding the 
         name of a filehandle.


     - Ex.

         $x = 1;
         print ($x), "is x\n";     # Prints: 1
         print $x, "is x\n";       # Prints: 1 is x
         print ($x, "is x\n");     # Prints: 1 is x
         print "Now", ($x), "is x\n";     # Prints: Now 1 is x1

         Remember, if it looks like a function it IS a function.
         So in the first print, "print ($x)" is a call to the
         function print with the argument being the single-element
         list ($x)!  So only "1" is printed!


   The $! Variable

     - Whenever a Perl built-in function invokes a UNIX system call,
       the value of errno is saved in the special $! variable

     - If $! is used in a numeric context, the numeric value of errno 
       is used

     - If $! is used in a string context, the error string for that
       value of errno is used


   Conventions

         EXPR       - any valid expression (list or scalar)
         FILEHANDLE - a filehandle operand
         LIST       - an operand evaluated in a list context
         NUMERIC    - an operand evaluated in a scalar numeric context
         SCALAR     - an operand evaluated in a scalar context
         STRING     - an operand evaluated in a scalar string context


   Categories Of Functions

     - Functions followed by an "*" are described in detail in
       these notes

     - Math Functions

       atan2		cos		exp		int
       log		rand		sin		sqrt
       srand

     - Conversion Functions

       hex (*)		oct (*)		ord		vec

     - Structure Conversion Functions

       pack		unpack

     - Time Functions

       gmtime		localtime	time

     - Scalar Functions

       // (*)		?? (*)		chop (*)	crypt
       index (*)	length (*)	reverse (*)	rindex (*)
       s (*)		study		substr (*)	tr (*)

     - Array And Associative Array Functions

       chop (*)		delete (*)	each (*)	grep (*)
       join (*)		keys (*)	pop (*)		push (*)
       reverse (*)	scalar		shift (*)	sort (*)
       splice		split (*)	unshift (*)	values (*)

     - File Operation Functions

       chmod (*)	chown (*)	link (*)	lstat (*)
       mkdir (*)	readlink (*)	rename (*)	rmdir (*)
       stat (*)		symlink (*)	truncate	unlink (*)
       utime (*)
 
     - Directory Reading Functions

       closedir (*)	opendir (*)	readdir (*)	rewinddir (*)
       seekdir (*)	telldir

     - I/O Functions

       binmode		close (*)	dbmclose	dbmopen
       eof (*)		fcntl		fileno		flock
       getc		iotcl		open (*)	pipe
       print (*)	printf (*)	read		seek
       select (*)	sprintf (*)	sysread		syswrite
       tell		write

     - Process Management Functions

       alarm (*)	chdir (*)	chroot		die (*)
       dump		exec (*)	exit (*)	fork (*)
       getpgrp (*)	getppid (*)	getpriority (*)	kill (*)
       setpgrp (*)	setpriority (*)	sleep (*)	syscall
       system (*)	times (*)	umask		wait (*)
       waitpid (*)	warn (*)

     - Networking Functions

       accept		bind		connect		gethostbyaddr
       gethostbyname	gethostent	getnetbyaddr	getnetbyname
       getnetent	getpeername	getprotobyname	getprotobynumber
       getprotoent	getservbyname	getservbyport	getservent
       getsockname	getsockopt	listen		recv
       send		setsockopt	shutdown	socket
       socketpair

     - IPC Functions
    
       msgctl		msgget		msgsnd		msgrcv
       semctl		semget		semop		shmctl
       shmget		shmread		shmwrite

     - System Info Functions

       getgrent		getgrgid	getgrnam	getlogin
       getpwent		getpwnam	getpwuid

     - Misc Functions

       caller		defined		eval		local (*)
       package (*)	require (*)	reset		return (*)
       sub (*)		undef		wantarray