Info file: perl.info, -*-Text-*- produced by `texinfo-format-buffer' from file `perl.texinfo' using `texinfmt.el' version 2.30 of 18 May 1993. This file documents perl, Practical Extraction and Report Language, and was originally based on Larry Wall's unix-style man page for perl. GNU Texinfo version adapted by Jeff Kellem . Copyright (C) 1989, 1990, 1991, 1992, 1993 Larry Wall Texinfo version Copyright (C) 1990, 1991, 1993 Jeff Kellem Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled "GNU General Public License" and "Conditions for Using Perl" are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" and this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English.  File: perl.info, Node: Packages, Next: Style, Prev: Predefined Names, Up: Top Packages ******** Perl provides a mechanism for alternate namespaces to protect packages from stomping on each others variables. By default, a perl script starts compiling into the package known as `main'. By use of the `package' declaration, you can switch namespaces. The scope of the `package' declaration is from the declaration itself to the end of the enclosing block (the same scope as the `local()' operator). Typically it would be the first declaration in a file to be included by the `require' operator. You can switch into a package in more than one place; it merely influences which symbol table is used by the compiler for the rest of that block. You can refer to variables and filehandles in other packages by prefixing the identifier with the package name and a single quote. If the package name is null, the `main' package as assumed. Only identifiers starting with letters are stored in the packages symbol table. All other symbols are kept in package `main'. In addition, the identifiers `STDIN', `STDOUT', `STDERR', `ARGV', `ARGVOUT', `ENV', `INC' and `SIG' are forced to be in package `main', even when used for other purposes than their built-in one. Note also that, if you have a package called `m', `s' or `y', the you can't use the qualified form of an identifier since it will be interpreted instead as a pattern match, a substitution or a translation. `eval''ed strings are compiled in the package in which the `eval' was compiled in. (Assignments to `$SIG{}', however, assume the signal handler specified is in the `main' package. Qualify the signal handler name if you wish to have a signal handler in a package.) For an example, examine `perldb.pl' in the perl library. It initially switches to the `DB' package so that the debugger doesn't interfere with variables in the script you are trying to debug. At various points, however, it temporarily switches back to the `main' package to evaluate various expressions in the context of the `main' package. The symbol table for a package happens to be stored in the associative array of that name prepended with an underscore. The value in each entry of the associative array is what you are referring to when you use the `*name' notation. In fact, the following have the same effect (in package `main', anyway), though the first is more efficient because it does the symbol table lookups at compile time: local(*foo) = *bar; local($_main{'foo'}) = $_main{'bar'}; You can use this to print out all the variables in a package, for instance. Here is `dumpvar.pl' from the perl library: package dumpvar; sub main'dumpvar { ($package) = @_; local(*stab) = eval("*_$package"); while (($key,$val) = each(%stab)) { { local(*entry) = $val; if (defined $entry) { print "\$$key = '$entry'\n"; } if (defined @entry) { print "\@$key = (\n"; foreach $num ($[ .. $#entry) { print " $num\t'",$entry[$num],"'\n"; } print ")\n"; } if ($key ne "_$package" && defined %entry) { print "\%$key = (\n"; foreach $key (sort keys(%entry)) { print " $key\t'",$entry{$key},"'\n"; } print ")\n"; } } } } Note that, even though the subroutine is compiled in package `dumpvar', the name of the subroutine is qualified so that its name is inserted into package `main'.  File: perl.info, Node: Style, Next: Debugging, Prev: Packages, Up: Top Style ***** Each programmer will, of course, have his or her own preferences in regards to formatting, but there are some general guidelines that will make your programs easier to read. 1. Just because you *CAN* do something a particular way doesn't mean that you *SHOULD* do it that way. *Perl* is designed to give you several ways to do anything, so consider picking the most readable one. For instance open(FOO,$foo) || die "Can't open $foo: $!"; is better than die "Can't open $foo: $!" unless open(FOO,$foo); because the second way hides the main point of the statement in a modifier. On the other hand print "Starting analysis\n" if $verbose; is better than $verbose && print "Starting analysis\n"; since the main point isn't whether the user typed `-v' or not. Similarly, just because an operator lets you assume default arguments doesn't mean that you have to make use of the defaults. The defaults are there for lazy systems programmers writing one-shot programs. If you want your program to be readable, consider supplying the argument. Along the same lines, just because you *can* omit parentheses in many places doesn't mean that you ought to: return print reverse sort num values array; return print(reverse(sort num (values(%array)))); When in doubt, parenthesize. At the very least it will let some poor schmuck bounce on the `%' key in *vi*. Even if you aren't in doubt, consider the mental welfare of the person who has to maintain the code after you, and who will probably put parens in the wrong place. 2. Don't go through silly contortions to exit a loop at the top or the bottom, when *perl* provides the `last' operator so you can exit in the middle. Just outdent it a little to make it more visible: line: for (;;) { statements; last line if $foo; next line if /^#/; statements; } 3. Don't be afraid to use loop labels--they're there to enhance readability as well as to allow multi-level loop breaks. See last example. 4. For portability, when using features that may not be implemented on every machine, test the construct in an `eval' to see if it fails. If you know what version or patchlevel a particular feature was implemented, you can test `$]' to see if it will be there. 5. Choose mnemonic identifiers. 6. Be consistent.  File: perl.info, Node: Debugging, Next: Setuid Scripts, Prev: Style, Up: Top Debugging ********* If you invoke *perl* with a `-d' switch, your script will be run under a debugging monitor. It will halt before the first executable statement and ask you for a command, such as: `h' Prints out a help message. `T' Stack trace. `s' Single step. Executes until it reaches the beginning of another statement. `n' Next. Executes over subroutine calls, until it reaches the beginning of the next statement. `f' Finish. Executes statements until it has finished the current subroutine. `c' Continue. Executes until the next breakpoint is reached. `c LINE' Continue to the specified line. Inserts a one-time-only breakpoint at the specified line. `' Repeat last `n' or `s'. `n' Single step around subroutine call. `l MIN+INCR' List `INCR+1' lines starting at MIN. If MIN is omitted, starts where last listing left off. If INCR is omitted, previous value of INCR is used. `l MIN-MAX' List lines in the indicated range. `l LINE' List just the indicated line. `l' List next window. `-' List previous window. `w LINE' List window around LINE `l SUBNAME' List subroutine. If it's a long subroutine it just lists the beginning. Use `l' to list more. `/PATTERN/' Regular expression search forward for PATTERN; the final `/' is optional. `?PATTERN?' Regular expression search backward for PATTERN; the final `?' is optional. `L' List lines that have breakpoints or actions. `S' Lists the names of all subroutines. `t' Toggle trace mode on or off. `b LINE CONDITION' Set a breakpoint. If LINE is omitted, sets a breakpoint on the line that is about to be executed. If a CONDITION is specified, it is evaluated each time the statement is reached and a breakpoint is taken only if the condition is true. Breakpoints may only be set on lines that begin an executable statement. `b SUBNAME CONDITION' Set breakpoint at first executable line of subroutine. `d LINE' Delete breakpoint. If LINE is omitted, deletes the breakpoint on the line that is about to be executed. `D' Delete all breakpoints. `a LINE COMMAND' Set an action for LINE. A multi-line COMMAND may be entered by backslashing the newlines. `A' Delete all line actions. `< COMMAND' Set an action to happen before every debugger prompt. A multi-line command may be entered by backslashing the newlines. `> COMMAND' Set an action to happen after the prompt when you've just given a command to return to executing the script. A multi-line command may be entered by backslashing the newlines. `V PACKAGE' List all variables in PACKAGE. Default is `main' package. `! NUMBER' Redo a debugging command. If NUMBER is omitted, redoes the previous command. `! -NUMBER' Redo the command that was that many (NUMBER) commands ago. `H -NUMBER' Display last NUMBER commands. Only commands longer than one character are listed. If NUMBER is omitted, lists them all. `q' `' Quit. `COMMAND' Execute COMMAND as a perl statement. A missing semicolon will be supplied. `p EXPR' Same as `print DB'OUT expr'. The `DB'OUT' filehandle is opened to `/dev/tty', regardless of where `STDOUT' may be redirected to. If you want to modify the debugger, copy `perldb.pl' from the perl library to your current directory and modify it as necessary. (You'll also have to put `-I.' on your command line.) You can do some customization by setting up a `.perldb' file which contains initialization code. For instance, you could make aliases like these: $DB'alias{'len'} = 's/^len(.*)/p length($1)/'; $DB'alias{'stop'} = 's/^stop (at|in)/b/'; $DB'alias{'.'} = 's/^\./p "\$DB\'sub(\$DB\'line):\t",\$DB\'line[\$DB\'line]/';  File: perl.info, Node: Setuid Scripts, Next: Environment, Prev: Debugging, Up: Top Setuid Scripts ************** *Perl* is designed to make it easy to write secure setuid and setgid scripts. Unlike shells, which are based on multiple substitution passes on each line of the script, *perl* uses a more conventional evaluation scheme with fewer hidden "gotchas". Additionally, since the language has more built-in functionality, it has to rely less upon external (and possibly untrustworthy) programs to accomplish its purposes. In an unpatched 4.2 or 4.3bsd kernel, setuid scripts are intrinsically insecure, but this kernel feature can be disabled. If it is, *perl* can emulate the setuid and setgid mechanism when it notices the otherwise useless setuid/gid bits on perl scripts. If the kernel feature isn't disabled, *perl* will complain loudly that your setuid script is insecure. You'll need to either disable the kernel setuid script feature, or put a C wrapper around the script. When perl is executing a setuid script, it takes special precautions to prevent you from falling into any obvious traps. (In some ways, a perl script is more secure than the corresponding C program.) Any *command line argument*, *environment variable*, or *input* is marked as "tainted", and may not be used, directly or indirectly, in any command that invokes a subshell, or in any command that modifies files, directories or processes. Any variable that is set within an expression that has previously referenced a tainted value also becomes tainted (even if it is logically impossible for the tainted value to influence the variable). For example: $foo = shift; # $foo is tainted $bar = $foo,'bar'; # $bar is also tainted $xxx = <>; # Tainted $path = $ENV{'PATH'}; # Tainted, but see below $abc = 'abc'; # Not tainted system "echo $foo"; # Insecure system "/bin/echo", $foo; # Secure (doesn't use sh) system "echo $bar"; # Insecure system "echo $abc"; # Insecure until PATH set $ENV{'PATH'} = '/bin:/usr/bin'; $ENV{'IFS'} = '' if $ENV{'IFS'} ne ''; $path = $ENV{'PATH'}; # Not tainted system "echo $abc"; # Is secure now! open(FOO,"$foo"); # OK open(FOO,">$foo"); # Not OK open(FOO,"echo $foo|"); # Not OK, but... open(FOO,"-|") || exec 'echo', $foo; # OK $zzz = `echo $foo`; # Insecure, zzz tainted unlink $abc,$foo; # Insecure umask $foo; # Insecure exec "echo $foo"; # Insecure exec "echo", $foo; # Secure (doesn't use sh) exec "sh", '-c', $foo; # Considered secure, alas The taintedness is associated with each scalar value, so some elements of an array can be tainted, and others not. If you try to do something insecure, you will get a fatal error saying something like "Insecure dependency" or "Insecure PATH". Note that you can still write an insecure system call or `exec', but only by explicitly doing something like the last example above. You can also bypass the tainting mechanism by referencing subpatterns---*perl* presumes that if you reference a substring using `$1', `$2', etc, you knew what you were doing when you wrote the pattern: $ARGV[0] =~ /^-P(\w+)$/; $printer = $1; # Not tainted This is fairly secure since `\w+' doesn't match shell metacharacters. Use of `.+' would have been insecure, but *perl* doesn't check for that, so you must be careful with your patterns. This is the *ONLY* mechanism for untainting user supplied filenames if you want to do file operations on them (unless you make `$>' equal to `$<'). It's also possible to get into trouble with other operations that don't care whether they use tainted values. Make judicious use of the file tests in dealing with any user-supplied filenames. When possible, do opens and such after setting `$> = $<'. *Perl* doesn't prevent you from opening tainted filenames for reading, so be careful what you print out. The tainting mechanism is intended to prevent stupid mistakes, not to remove the need for thought.  File: perl.info, Node: Environment, Next: a2p, Prev: Setuid Scripts, Up: Top Environment *********** HOME Used if `chdir' has no argument. LOGDIR Used if `chdir' has no argument and `HOME' is not set. PATH Used im executing subprocesses, and in finding the script if `-S' is used. PERLLIB A colon-separated list of directories in which to look for *Perl* library files before looking in the standard library and the current directory. PERLDB The command used to get the debugger code. If unset, uses: require 'perldb.pl' Apart from these, *perl* uses no other environment variables, except to make them available to the script being executed, and to child processes. However, scripts running setuid would do well to execute the following lines before doing anything else, just to keep people honest: $ENV{'PATH'} = '/bin:/usr/bin'; # or whatever you need $ENV{'SHELL'} = '/bin/sh' if $ENV{'SHELL'} ne ''; $ENV{'IFS'} = '' if $ENV{'IFS'} ne ''; Files ===== The only file that *perl* creates, other than user specified files, is: /tmp/perl-eXXXXXX temporary file for `-e' commands.  File: perl.info, Node: a2p, Next: s2p, Prev: Environment, Up: Top a2p - Awk to Perl Translator **************************** *A2p* takes an `awk' script specified on the command line (or from standard input) and produces a comparable *perl* script on the standard output. * Menu: * a2p Options:: Options to a2p. * a2p Considerations:: Considerations when using a2p. * a2p Bugs:: Problems with a2p.  File: perl.info, Node: a2p Options, Next: a2p Considerations, Up: a2p Options for a2p =============== Options include: `-D' sets debugging flags. `-F' tells *a2p* that this `awk' script is always invoked with this `-F' switch. `-n' specifies the names of the input fields if input does not have to be split into an array. If you were translating an `awk' script that processes the password file, you might say: a2p -7 -nlogin.password.uid.gid.gcos.shell.home Any delimiter can be used to separate the field names. `-' causes *a2p* to assume that input will always have that many fields.  File: perl.info, Node: a2p Considerations, Next: a2p Bugs, Prev: a2p Options, Up: a2p Considerations for Using a2p ============================ *A2p* cannot do as good a job translating as a human would, but it usually does pretty well. There are some areas where you may want to examine the perl script produced and tweak it some. Here are some of them, in no particular order. There is an `awk' idiom of putting `int()' around a string expression to force numeric interpretation, even though the argument is always integer anyway. This is generally unneeded in *perl*, but *a2p* can't tell if the argument is always going to be integer, so it leaves it in. You may wish to remove it. Perl differentiates numeric comparison from string comparison. `Awk' has one operator for both that decides at run time which comparison to do. *A2p* does not try to do a complete job of `awk' emulation at this point. Instead it guesses which one you want. It's almost always right, but it can be spoofed. All such guesses are marked with the comment `#???'. You should go through and check them. You might want to run at least once with the `-w' switch to *perl*, which will warn you if you use `==' where you should have used *eq*. Perl does not attempt to emulate the behavior of `awk' in which nonexistent array elements spring into existence simply by being referenced. If somehow you are relying on this mechanism to create null entries for a subsequent for...in, they won't be there in perl. If *a2p* makes a split line that assigns to a list of variables that looks like `(Fld1, Fld2, Fld3...)' you may want to rerun *a2p* using the `-n' option mentioned above. This will let you name the fields throughout the script. If it splits to an array instead, the script is probably referring to the number of fields somewhere. The `exit' statement in `awk' doesn't necessarily exit; it goes to the END block if there is one. `Awk' scripts that do contortions within the END block to bypass the block under such circumstances can be simplified by removing the conditional in the END block and just exiting directly from the perl script. Perl has two kinds of arrays, numerically-indexed and associative. `Awk' arrays are usually translated to associative arrays, but if you happen to know that the index is always going to be numeric you could change the `{...}' to `[...]'. Iteration over an associative array is done using the `keys()' function, but iteration over a numeric array is NOT. You might need to modify any loop that is iterating over the array in question. `Awk' starts by assuming OFMT has the value `%.6g'. Perl starts by assuming its equivalent, `$#', to have the value `%.20g'. You'll want to set `$#' explicitly if you use the default value of OFMT. Near the top of the line loop will be the split operation that is implicit in the `awk' script. There are times when you can move this down past some conditionals that test the entire record so that the split is not done as often. For aesthetic reasons you may wish to change the array base `$[' from 1 back to perl's default of 0, but remember to change all array subscripts AND all `substr()' and `index()' operations to match. Cute comments that say "# Here is a workaround because awk is dumb" are passed through unmodified. `Awk' scripts are often embedded in a shell script that pipes stuff into and out of `awk'. Often the shell script wrapper can be incorporated into the perl script, since perl can start up pipes into and out of itself, and can do other things that `awk' can't do by itself. Scripts that refer to the special variables RSTART and RLENGTH can often be simplified by referring to the variables `$`', `$&' and `$'', as long as they are within the scope of the pattern match that sets them. The produced perl script may have subroutines defined to deal with awk's semantics regarding `getline' and `print'. Since *a2p* usually picks correctness over efficiency. it is almost always possible to rewrite such code to be more efficient by discarding the semantic sugar. For efficiency, you may wish to remove the keyword from any return statement that is the last statement executed in a subroutine. *A2p* catches the most common case, but doesn't analyze embedded blocks for subtler cases. `ARGV[0]' translates to `$ARGV0', but `ARGV[n]' translates to `$ARGV[$n]'. A loop that tries to iterate over `ARGV[0]' won't find it. *A2p* uses no environment variables.  File: perl.info, Node: a2p Bugs, Prev: a2p Considerations, Up: a2p Bugs in a2p =========== It would be possible to emulate awk's behavior in selecting string versus numeric operations at run time by inspection of the operands, but it would be gross and inefficient. Besides, *a2p* almost always guesses right. Storage for the `awk' syntax tree is currently static, and can run out.  File: perl.info, Node: s2p, Next: h2ph, Prev: a2p, Up: Top s2p - Sed to Perl Translator **************************** *S2p* takes a `sed' script specified on the command line (or from standard input) and produces a comparable *perl* script on the standard output. * Menu: * s2p Options:: Options to s2p * s2p Considerations:: Considerations when using s2p.  File: perl.info, Node: s2p Options, Next: s2p Considerations, Up: s2p Options for s2p =============== Options include: `-D' sets debugging flags. `-n' specifies that this `sed' script was always invoked with a `sed -n'. Otherwise a switch parser is prepended to the front of the script. `-p' specifies that this `sed' script was never invoked with a `sed -n'. Otherwise a switch parser is prepended to the front of the script.  File: perl.info, Node: s2p Considerations, Prev: s2p Options, Up: s2p Considerations ============== The perl script produced looks very `sed'-ish, and there may very well be better ways to express what you want to do in perl. For instance, *s2p* does not make any use of the `split' operator, but you might want to. The perl script you end up with may be either faster or slower than the original `sed' script. If you're only interested in speed you'll just have to try it both ways. Of course, if you want to do something `sed' doesn't do, you have no choice. *S2p* uses no environment variables.  File: perl.info, Node: h2ph, Next: Diagnostics, Prev: s2p, Up: Top h2ph - Converting C header files into Perl ****************************************** *h2ph* converts any C header files specified to the corresponding Perl header file format. It is most easily run while in `/usr/include': cd /usr/include; h2ph * sys/* C header files are located in the `/usr/include' directory and end with the extension `.h'. Perl header files are typically located in `/usr/local/lib/perl', with the extension `.ph' to distinguish the files from a C header file. Tidbits and Messages in h2ph ============================ No environment variables are used. The only warnings you will probably see from *h2ph* are the usual warnings if it can't read or write the files involved. Bugs in h2ph ============ * *h2ph* doesn't construct the `%sizeof' array for you. * It doesn't handle all C constructs, but it does attempt to isolate definitions inside `eval's so that you can get at the definitions that it can translate. * *h2ph* is only intended as a rough tool. You may need to dicker with the files produced.  File: perl.info, Node: Diagnostics, Next: Traps, Prev: h2ph, Up: Top Diagnostics *********** Compilation errors will tell you the line number of the error, with an indication of the next token or token type that was to be examined. (In the case of a script passed to *perl* via `-e' switches, each `-e' is counted as one line.) Setuid scripts have additional constraints that can produce error messages such as "Insecure dependency". *Note Setuid Scripts::.  File: perl.info, Node: Traps, Next: Bugs, Prev: Diagnostics, Up: Top Traps ***** This chapter points out traps and pitfalls you may run into if you are used to `awk', `C', `sed' or `shell' programming. * Menu: * Awk Traps:: Notes for awk users. * C Traps:: Notes for C programmers. * Sed Traps:: Notes for sed programmers. * Shell Traps:: Notes for shell programmers.  File: perl.info, Node: Awk Traps, Next: C Traps, Up: Traps Awk Traps ========= Accustomed `awk' users should take special note of the following: * Semicolons are required after all simple statements in *perl* (except at the end of a block). Newline is not a statement delimiter. * Curly brackets are required on `if's and `while's. * Variables begin with `$' or `@' in *perl*. * Arrays index from 0 unless you set `$['. Likewise string positions in `substr()' and `index()'. * You have to decide whether your array has numeric or string indices. * Associative array values do not spring into existence upon mere reference. * You have to decide whether you want to use string or numeric comparisons. * Reading an input line does not split it for you. You get to split it yourself to an array. And the `split' operator has different arguments. * The current input line is normally in `$_', not `$0'. It generally does not have the newline stripped. (`$0' is the name of the program executed.) * `$' does not refer to fields--it refers to substrings matched by the last match pattern. * The `print' statement does not add field and record separators unless you set `$,' and `$\'. * You must open your files before you print to them. * The range operator is `..', not comma. (The comma operator works as in C.) * The match operator is `=~', not `~'. (`~' is the one's complement operator, as in C.) * The exponentiation operator is `**', not `^'. (`^' is the XOR operator, as in C.) * The concatenation operator is `.', not the null string. (Using the null string would render `/pat/ /pat/' unparsable, since the third slash would be interpreted as a division operator--the tokener is in fact slightly context sensitive for operators like `/', `?', and `<'. And in fact, `.' itself can be the beginning of a number.) * `next', `exit' and `continue' work differently. * The following variables work differently *Awk* *Perl* ARGC $#ARGV ARGV[0] $0 FILENAME $ARGV FNR $. - something FS (whatever you like) NF $#Fld, or some such NR $. OFMT $# OFS $, ORS $\ RLENGTH length($&) RS $/ RSTART length($`) SUBSEP $; * When in doubt, run the `awk' construct through *a2p* and see what it gives you (*Note a2p:: for more info).  File: perl.info, Node: C Traps, Next: Sed Traps, Prev: Awk Traps, Up: Traps C Traps ======= Cerebral C programmers should take note of the following: * Curly brackets are required on `if's and `while's. * You should use `elsif' rather than `else if' * `break' and `continue' become `last' and `next', respectively. * There's no `switch' statement. * Variables begin with `$', `@' or `%' in *perl*. * `printf' does not implement `*'. * Comments begin with `#', not `/*'. * You can't take the address of anything. * `ARGV' must be capitalized. * The "system" calls `link', `unlink', `rename', etc. return nonzero for success, not zero (0). * Signal handlers deal with signal names, not numbers.  File: perl.info, Node: Sed Traps, Next: Shell Traps, Prev: C Traps, Up: Traps Sed Traps ========= Seasoned `sed' programmers should take note of the following: * Backreferences in substitutions use `$' rather than `\'. * The pattern matching metacharacters `(', `)', and `|' do not have backslashes in front. * The range operator is `..' rather than comma.  File: perl.info, Node: Shell Traps, Prev: Sed Traps, Up: Traps Shell Traps =========== Sharp shell programmers should take note of the following: * The backtick operator does variable interpretation without regard to the presence of single quotes in the command. * The backtick operator does no translation of the return value, unlike `csh'. * Shells (especially `csh') do several levels of substitution on each command line. *Perl* does substitution only in certain constructs such as double quotes, backticks, angle brackets and search patterns. * Shells interpret scripts a little bit at a time. *Perl* compiles the whole program before executing it. * The arguments are available via `@ARGV', not `$1', `$2', etc. * The environment is not automatically made available as variables.  File: perl.info, Node: Bugs, Next: Credits, Prev: Traps, Up: Top Bugs **** *Perl* is at the mercy of your machine's definitions of various operations such as type casting, `atof()' and `sprintf()'. If your stdio requires a `seek' or `eof' between reads and writes on a particular stream, so does *perl*. (This doesn't apply to `sysread()' and `syswrite()'.) While none of the built-in data types have any arbitrary size limits (apart from memory size), there are still a few arbitrary limits: a given identifier may not be longer than 255 characters, and no component of your `PATH' may be longer than 255 if you use `-S'. A regular expression may not compile to more than 32767 bytes internally. *Perl* actually stands for Pathologically Eclectic Rubbish Lister, but don't tell anyone I said that.  File: perl.info, Node: Credits, Next: Errata, Prev: Bugs, Up: Top The Credits *********** Perl was designed and implemented by... ...Larry Wall MS-DOS port of perl by... ...Diomidis Spinellis Texinfo version of *perl* manual by... ...Jeff Kellem  File: perl.info, Node: Errata, Next: Command Summary, Prev: Credits, Up: Top Errata and Addenda ****************** The Perl book, Programming Perl, has the following omissions and goofs. * On page 5, the examples which read eval '/usr/bin/perl should read eval 'exec /usr/bin/perl * On page 195, the equivalent to the System V `sum' program only works for very small files. To do larger files, use undef $/; $checksum = unpack("%32C*",<>) % 32767; * The descriptions of `alarm' and `sleep' refer to signal `SIGALARM'. These should refer to `SIGALRM'. * The `-0' switch to set the initial value of `$/' was added to Perl after the book went to press. * The `-l' switch now does automatic line ending processing. * The `qx//' construct is now a synonym for backticks. * `$0' may now be assigned to set the argument displayed by `ps(1)'. * The new `@###.##' format was omitted accidentally from the description on formats. * It wasn't known at press time that `s///ee' caused multiple evaluations of the replacement expression. This is to be construed as a feature. * `(LIST) x $count' now does array replication. * There is now no limit on the number of parentheses in a regular expression. * In double-quote context, more escapes are supported: \e, \a, \x1b, \c[, \l, \L, \u, \U, \E. The latter five control up/lower case translation. * The `$/' variable may now be set to a multi-character delimiter. * There is now a `g' modifier on ordinary pattern matching that causes it to iterate through a string finding multiple matches. * All of the `$^X' variables are new except for `$^T'. * The default top-of-form format for FILEHANDLE is now `FILEHANDLE_TOP' rather than `top'. * The `eval {}' and `sort {}' constructs were added in version 4.018. * The `v' and `V' (little-endian) template options for `pack' and `unpack' were added in 4.019.  File: perl.info, Node: Command Summary, Next: Function Index, Prev: Errata, Up: Top Command Summary (syntax only) ***************************** THIS SECTION IS CURRENTLY INCOMPLETE and may change without notice!! (As may the rest of this document... ;-) /PATTERN/io ?PATTERN? accept(NEWSOCKET,GENERICSOCKET) atan2(X,Y) bind(SOCKET,NAME) binmode(FILEHANDLE) binmode FILEHANDLE chdir(EXPR) chdir EXPR chdir chmod(LIST) chmod LIST chop(LIST) chop(VARIABLE) chop VARIABLE chop chown(LIST) chown LIST chroot(FILENAME) chroot FILENAME chroot close(FILEHANDLE) close FILEHANDLE closedir(DIRHANDLE) closedir DIRHANDLE connect(SOCKET,NAME) cos(EXPR) cos EXPR cos crypt(PLAINTEXT,SALT) dbmclose(ASSOC_ARRAY) dbmclose ASSOC_ARRAY dbmopen(ASSOC,DBNAME,MODE) defined(EXPR) defined EXPR delete $ASSOC{KEY} die(LIST) die LIST die do BLOCK do EXPR do SUBROUTINE (LIST) dump LABEL dump each(ASSOC_ARRAY) each ASSOC_ARRAY endpwent endgrent endhostent endnetent endprotoent endpwent endservent eof(FILEHANDLE) eof() eof eval(EXPR) eval EXPR eval exec(LIST) exec LIST exit(EXPR) exit EXPR exp(EXPR) exp EXPR exp fcntl(FILEHANDLE,FUNCTION,SCALAR) fileno(FILEHANDLE) fileno FILEHANDLE flock(FILEHANDLE,OPERATION) fork getc(FILEHANDLE) getc FILEHANDLE getc getgrent getgrgid(GID) getgrnam(NAME) gethostbyaddr(ADDR,ADDRTYPE) gethostbyname(NAME) gethostent getlogin getnetbyaddr(ADDR,ADDRTYPE) getnetbyname(NAME) getnetent getpeername(SOCKET) getpgrp(PID) getpgrp PID getpgrp getppid getpriority(WHICH,WHO) getprotobyname(NAME) getprotobynumber(NUMBER) getprotoent getpwent getpwnam(NAME) getpwuid(UID) getservbyname(NAME,PROTO) getservbyport(PORT,PROTO) getservent getsockname(SOCKET) getsockopt(SOCKET,LEVEL,OPTNAME) gmtime(EXPR) gmtime EXPR gmtime goto LABEL grep(EXPR,LIST) hex(EXPR) hex EXPR hex index(STR,SUBSTR) int(EXPR) int EXPR int ioctl(FILEHANDLE,FUNCTION,SCALAR) join(EXPR,LIST) join(EXPR,ARRAY) keys(ASSOC_ARRAY) keys ASSOC_ARRAY kill(LIST) kill LIST last LABEL last length(EXPR) length EXPR length link(OLDFILE,NEWFILE) listen(SOCKET,QUEUESIZE) local(LIST) localtime(EXPR) localtime EXPR localtime log(EXPR) log EXPR log lstat(FILEHANDLE) lstat FILEHANDLE lstat(EXPR) lstat SCALARVARIABLE m/PATTERN/io /PATTERN/io mkdir(FILENAME,MODE) next LABEL next oct(EXPR) oct EXPR oct open(FILEHANDLE,EXPR) open(FILEHANDLE) open FILEHANDLE opendir(DIRHANDLE,EXPR) ord(EXPR) ord EXPR ord pack(TEMPLATE,LIST) pipe(READHANDLE,WRITEHANDLE) pop(ARRAY) pop ARRAY print(FILEHANDLE LIST) print(LIST) print FILEHANDLE LIST print LIST print printf(FILEHANDLE LIST) printf(LIST) printf FILEHANDLE LIST printf LIST printf push(ARRAY,LIST) q/STRING/ qq/STRING/ rand(EXPR) rand EXPR rand read(FILEHANDLE,SCALAR,LENGTH) readdir(DIRHANDLE) readdir DIRHANDLE readlink(EXPR) readlink EXPR readlink recv(SOCKET,SCALAR,LEN,FLAGS) redo LABEL redo rename(OLDNAME,NEWNAME) require(EXPR) require EXPR require reset(EXPR) reset EXPR reset return LIST reverse(LIST) reverse LIST rewinddir(DIRHANDLE) rewinddir DIRHANDLE rindex(STR,SUBSTR) rmdir(FILENAME) rmdir FILENAME rmdir s/PATTERN/REPLACEMENT/gieo seek(FILEHANDLE,POSITION,WHENCE) seekdir(DIRHANDLE,POS) select(FILEHANDLE) select select(RBITS,WBITS,EBITS,TIMEOUT) send(SOCKET,MSG,FLAGS,TO) send(SOCKET,MSG,FLAGS) setgrent sethostent(STAYOPEN) setnetent(STAYOPEN) setpgrp(PID,PGRP) setpriority(WHICH,WHO,PRIORITY) setprotoent(STAYOPEN) setpwent setservent(STAYOPEN) setsockopt(SOCKET,LEVEL,OPTNAME,OPTVAL) shift(ARRAY) shift ARRAY shift shutdown(SOCKET,HOW) sin(EXPR) sin EXPR sin sleep(EXPR) sleep EXPR sleep socket(SOCKET,DOMAIN,TYPE,PROTOCOL) socketpair(SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL) sort(SUBROUTINE LIST) sort(LIST) sort SUBROUTINE LIST sort LIST splice(ARRAY,OFFSET,LENGTH,LIST) splice(ARRAY,OFFSET,LENGTH) splice(ARRAY,OFFSET) split(/PATTERN/,EXPR,LIMIT) split(/PATTERN/,EXPR) split(/PATTERN/) split sprintf(FORMAT,LIST) sqrt(EXPR) sqrt EXPR sqrt srand(EXPR) srand EXPR srand stat(FILEHANDLE) stat FILEHANDLE stat(EXPR) stat SCALARVARIABLE study(SCALAR) study SCALAR study substr(EXPR,OFFSET,LEN) symlink(OLDFILE,NEWFILE) syscall(LIST) syscall LIST system(LIST) system LIST tell(FILEHANDLE) tell FILEHANDLE tell telldir(DIRHANDLE) telldir DIRHANDLE time times tr/SEARCHLIST/REPLACEMENTLIST/ umask(EXPR) umask EXPR umask undef(EXPR) undef EXPR undef unlink(LIST) unlink LIST unlink unpack(TEMPLATE,EXPR) unshift(ARRAY,LIST) utime(LIST) utime LIST values(ASSOC_ARRAY) values ASSOC_ARRAY vec(EXPR,OFFSET,BITS) wait wantarray warn(LIST) warn LIST write(FILEHANDLE) write(EXPR) write y/SEARCHLIST/REPLACEMENTLIST/  File: perl.info, Node: Function Index, Next: Concept Index, Prev: Command Summary, Up: Top Function Index ************** * Menu: * accept: Networking Functions. 7. * alarm: System Interaction. 9. * atan2: Math Functions. 7. * bind: Networking Functions. 13. * binmode: Input/Output. 9. * caller: Subroutine Functions. 9. * chdir: Directory Reading Functions. 11. * chgrp (part of chown): File Operations. 20. * chmod: File Operations. 12. * chop: String Functions. 13. * chown: File Operations. 20. * chroot: System Interaction. 24. * close: Input/Output. 20. * closedir: Directory Reading Functions. 19. * connect: Networking Functions. 20. * continue: Compound Statements. 10. * cos: Math Functions. 16. * crypt: String Functions. 36. * dbmclose: DBM Functions. 9. * dbmopen: DBM Functions. 16. * defined: Variable Functions. 9. * delete: Array and List Functions. 7. * die: System Interaction. 34. * do BLOCK: Flow Control Functions. 7. * do EXPR: Perl Library Functions. 42. * do SUBROUTINE: Subroutine Functions. 19. * dump: Miscellaneous Functions. 9. * each: Array and List Functions. 26. * else: Compound Statements. 10. * elsif: Compound Statements. 10. * endgrent: System Interaction. 170. * endhostent: System Interaction. 170. * endnetent: System Interaction. 170. * endprotoent: System Interaction. 170. * endpwent: System Interaction. 170. * endservent: System Interaction. 170. * eof: Input/Output. 44. * eval: Miscellaneous Functions. 48. * exec: System Interaction. 68. * exit: System Interaction. 96. * exp: Math Functions. 25. * fcntl: File Operations. 52. * fileno: File Operations. 69. * flock: File Operations. 75. * for: Compound Statements. 10. * foreach: Compound Statements. 10. * fork: System Interaction. 105. * getc: Input/Output. 78. * getgrent: System Interaction. 170. * getgrgid: System Interaction. 170. * getgrnam: System Interaction. 170. * gethostbyaddr: System Interaction. 170. * gethostbyname: System Interaction. 170. * gethostent: System Interaction. 170. * getlogin: System Interaction. 211. * getnetbyaddr: System Interaction. 170. * getnetbyname: System Interaction. 170. * getnetent: System Interaction. 170. * getpeername: Networking Functions. 27. * getpgrp: System Interaction. 222. * getppid: System Interaction. 229. * getpriority: System Interaction. 233. * getprotobyname: System Interaction. 170. * getprotobynumber: System Interaction. 170. * getprotoent: System Interaction. 170. * getpwent: System Interaction. 170. * getpwnam: System Interaction. 170. * getpwuid: System Interaction. 170. * getservbyname: System Interaction. 170. * getservbyport: System Interaction. 170. * getservent: System Interaction. 170. * getsockname: Networking Functions. 37. * getsockopt: Networking Functions. 47. * gmtime: Time Functions. 11. * goto: Flow Control Functions. 14. * grep: Array and List Functions. 47. * hex: Math Functions. 34. * if: Compound Statements. 10. * if: Simple Statements. 14. * index: String Functions. 44. * int: Math Functions. 44. * ioctl: System Interaction. 239. * join: Array and List Functions. 63. * keys: Array and List Functions. 75. * kill: System Interaction. 286. * last: Flow Control Functions. 27. * length: String Functions. 57. * link: File Operations. 106. * listen: Networking Functions. 52. * local: Subroutine Functions. 42. * localtime: Time Functions. 29. * log: Math Functions. 53. * lstat: File Operations. 117. * mkdir: Directory Reading Functions. 23. * m/PATTERN/: Search and Replace Functions. 9. * msgctl: System V IPC. 7. * msgget: System V IPC. 14. * msgrcv: System V IPC. 26. * msgsnd: System V IPC. 19. * next: Flow Control Functions. 41. * oct: Math Functions. 62. * open: Input/Output. 88. * opendir: Directory Reading Functions. 29. * ord: Miscellaneous Functions. 93. * pack: Structure Conversion. 7. * /PATTERN/: Search and Replace Functions. 9. * ?PATTERN?: Search and Replace Functions. 92. * pipe: Input/Output. 206. * pop: Array and List Functions. 98. * print: Input/Output. 224. * printf: Input/Output. 252. * push: Array and List Functions. 107. * q (single quote operator): Miscellaneous Functions. 102. * qq (double quote operator): Miscellaneous Functions. 102. * qx (backquote operator): Miscellaneous Functions. 102. * rand: Miscellaneous Functions. 125. * read: Input/Output. 258. * readdir: Directory Reading Functions. 38. * readlink: File Operations. 127. * recv: Networking Functions. 58. * redo: Flow Control Functions. 57. * rename: File Operations. 134. * require: Perl Library Functions. 11. * reset: Variable Functions. 35. * return: Subroutine Functions. 89. * reverse: Array and List Functions. 121. * rewinddir: Directory Reading Functions. 48. * rindex: String Functions. 64. * rmdir: Directory Reading Functions. 57. * scalar: Variable Functions. 58. * seek: Input/Output. 307. * seekdir: Directory Reading Functions. 63. * select(FILEHANDLE): Input/Output. 316. * select(RBITS,WBITS,EBITS,TIMEOUT): Input/Output. 268. * semctl: System V IPC. 35. * semget: System V IPC. 43. * semop: System V IPC. 48. * send: Networking Functions. 69. * setgrent: System Interaction. 170. * sethostent: System Interaction. 170. * setnetent: System Interaction. 170. * setpgrp: System Interaction. 300. * setpriority: System Interaction. 306. * setprotoent: System Interaction. 170. * setpwent: System Interaction. 170. * setservent: System Interaction. 170. * setsockopt: Networking Functions. 76. * shift: Array and List Functions. 132. * shmctl: System V IPC. 64. * shmget: System V IPC. 71. * shmread: System V IPC. 78. * shmwrite: System V IPC. 78. * shutdown: Networking Functions. 82. * sin: Math Functions. 77. * sleep: System Interaction. 316. * socket: Networking Functions. 88. * socketpair: Networking Functions. 97. * sort: Array and List Functions. 151. * s/PATTERN/REPLACEMENT/: Search and Replace Functions. 100. * splice: Array and List Functions. 206. * split: Array and List Functions. 239. * sprintf: Miscellaneous Functions. 140. * sqrt: Math Functions. 86. * srand: Miscellaneous Functions. 135. * stat: File Operations. 145. * study: Search and Replace Functions. 152. * substitute function: Search and Replace Functions. 100. * substr: String Functions. 72. * symlink: File Operations. 167. * syscall: System Interaction. 326. * sysread: System Interaction. 344. * system: System Interaction. 367. * syswrite: System Interaction. 356. * tell: Input/Output. 340. * telldir: Directory Reading Functions. 72. * time: Time Functions. 43. * times: System Interaction. 376. * translate function: Search and Replace Functions. 213. * tr/SEARCHLIST/REPLACEMENTLIST/: Search and Replace Functions. 213. * umask: System Interaction. 387. * undef: Variable Functions. 67. * unless: Compound Statements. 10. * unless: Simple Statements. 14. * unlink: File Operations. 188. * unpack: Structure Conversion. 94. * unshift: Array and List Functions. 302. * utime: File Operations. 205. * values: Array and List Functions. 312. * vec: Miscellaneous Functions. 145. * wait: System Interaction. 392. * waitpid: System Interaction. 398. * wantarray: Subroutine Functions. 96. * warn: System Interaction. 419. * while: Compound Statements. 10. * while: Simple Statements. 14. * write: Input/Output. 350. * y/SEARCHLIST/REPLACEMENTLIST/: Search and Replace Functions. 213.