This is Info file perl.info, produced by Makeinfo version 1.68 from the input file bigperl.texi. settitle perl  File: perl.info, Node: perlsec, Next: perltrap, Prev: perlnumber, Up: Top Perl security ************* NAME ==== perlsec - Perl security DESCRIPTION =========== Perl is designed to make it easy to program securely even when running with extra privileges, like setuid or setgid programs. Unlike most command line shells, which are based on multiple substitution passes on each line of the script, Perl uses a more conventional evaluation scheme with fewer hidden snags. Additionally, because the language has more builtin functionality, it can rely less upon external (and possibly untrustworthy) programs to accomplish its purposes. Perl automatically enables a set of special security checks, called *taint mode*, when it detects its program running with differing real and effective user or group IDs. The setuid bit in Unix permissions is mode 04000, the setgid bit mode 02000; either or both may be set. You can also enable taint mode explicitly by using the -T command line flag. This flag is *strongly* suggested for server programs and any program run on behalf of someone else, such as a CGI script. Once taint mode is on, it's on for the remainder of your script. While in this mode, Perl takes special precautions called *taint checks* to prevent both obvious and subtle traps. Some of these checks are reasonably simple, such as verifying that path directories aren't writable by others; careful programmers have always used checks like these. Other checks, however, are best supported by the language itself, and it is these checks especially that contribute to making a set-id Perl program more secure than the corresponding C program. You may not use data derived from outside your program to affect something else outside your program-at least, not by accident. All command line arguments, environment variables, locale information (see *Note Perllocale: perllocale,), results of certain system calls (readdir(), readlink(), the variable of shmread(), the messages returned by msgrcv(), the password, gcos and shell fields returned by the getpwxxx() calls), and all file input are marked as "tainted". Tainted data may not be used directly or indirectly in any command that invokes a sub-shell, nor in any command that modifies files, directories, or processes. (*Important exception*: If you pass a list of arguments to either system or exec, the elements of that list are *NOT* checked for taintedness.) Any variable set to a value derived from tainted data will itself be tainted, even if it is logically impossible for the tainted data to alter the variable. Because taintedness is associated with each scalar value, some elements of an array can be tainted and others not. For example: $arg = shift; # $arg is tainted $hid = $arg, 'bar'; # $hid is also tainted $line = <>; # Tainted $line = ; # Also tainted open FOO, "/home/me/bar" or die $!; $line = ; # Still tainted $path = $ENV{'PATH'}; # Tainted, but see below $data = 'abc'; # Not tainted system "echo $arg"; # Insecure system "/bin/echo", $arg; # Secure (doesn't use sh) system "echo $hid"; # Insecure system "echo $data"; # Insecure until PATH set $path = $ENV{'PATH'}; # $path now tainted $ENV{'PATH'} = '/bin:/usr/bin'; delete @ENV{'IFS', 'CDPATH', 'ENV', 'BASH_ENV'}; $path = $ENV{'PATH'}; # $path now NOT tainted system "echo $data"; # Is secure now! open(FOO, "< $arg"); # OK - read-only file open(FOO, "> $arg"); # Not OK - trying to write open(FOO,"echo $arg|"); # Not OK, but... open(FOO,"-|") or exec 'echo', $arg; # OK $shout = `echo $arg`; # Insecure, $shout now tainted unlink $data, $arg; # Insecure umask $arg; # Insecure exec "echo $arg"; # Insecure exec "echo", $arg; # Secure (doesn't use the shell) exec "sh", '-c', $arg; # Considered secure, alas! @files = <*.c>; # insecure (uses readdir() or similar) @files = glob('*.c'); # insecure (uses readdir() or similar) If you try to do something insecure, you will get a fatal error saying something like "Insecure dependency" or "Insecure $ENV{PATH}". Note that you can still write an insecure system or exec, but only by explicitly doing something like the "considered secure" example above. Laundering and Detecting Tainted Data ------------------------------------- To test whether a variable contains tainted data, and whose use would thus trigger an "Insecure dependency" message, check your nearby CPAN mirror for the `Taint.pm' module, which should become available around November 1997. Or you may be able to use the following *is_tainted()* function. sub is_tainted { return ! eval { join('',@_), kill 0; 1; }; } This function makes use of the fact that the presence of tainted data anywhere within an expression renders the entire expression tainted. It would be inefficient for every operator to test every argument for taintedness. Instead, the slightly more efficient and conservative approach is used that if any tainted value has been accessed within the same expression, the whole expression is considered tainted. But testing for taintedness gets you only so far. Sometimes you have just to clear your data's taintedness. The only way to bypass the tainting mechanism is by referencing subpatterns from a regular expression match. Perl presumes that if you reference a substring using $1, $2, etc., that you knew what you were doing when you wrote the pattern. That means using a bit of thought-don't just blindly untaint anything, or you defeat the entire mechanism. It's better to verify that the variable has only good characters (for certain values of "good") rather than checking whether it has any bad characters. That's because it's far too easy to miss bad characters that you never thought of. Here's a test to make sure that the data contains nothing but "word" characters (alphabetics, numerics, and underscores), a hyphen, an at sign, or a dot. if ($data =~ /^([-\@\w.]+)$/) { $data = $1; # $data now untainted } else { die "Bad data in $data"; # log this somewhere } This is fairly secure because `/\w+/' doesn't normally match shell metacharacters, nor are dot, dash, or at going to mean something special to the shell. Use of `/.+/' would have been insecure in theory because it lets everything through, but Perl doesn't check for that. The lesson is that when untainting, you must be exceedingly careful with your patterns. Laundering data using regular expression is the *only* mechanism for untainting dirty data, unless you use the strategy detailed below to fork a child of lesser privilege. The example does not untaint $data if `use locale' is in effect, because the characters matched by `\w' are determined by the locale. Perl considers that locale definitions are untrustworthy because they contain data from outside the program. If you are writing a locale-aware program, and want to launder data with a regular expression containing `\w', put `no locale' ahead of the expression in the same block. See `SECURITY', *Note Perllocale: perllocale, for further discussion and examples. Switches On the "#!" Line ------------------------- When you make a script executable, in order to make it usable as a command, the system will pass switches to perl from the script's #! line. Perl checks that any command line switches given to a setuid (or setgid) script actually match the ones set on the #! line. Some Unix and Unix-like environments impose a one-switch limit on the #! line, so you may need to use something like `-wU' instead of `-w -U' under such systems. (This issue should arise only in Unix or Unix-like environments that support #! and setuid or setgid scripts.) Cleaning Up Your Path --------------------- For "Insecure `$ENV{PATH}'" messages, you need to set `$ENV{'PATH'}' to a known value, and each directory in the path must be non-writable by others than its owner and group. You may be surprised to get this message even if the pathname to your executable is fully qualified. This is not generated because you didn't supply a full path to the program; instead, it's generated because you never set your PATH environment variable, or you didn't set it to something that was safe. Because Perl can't guarantee that the executable in question isn't itself going to turn around and execute some other program that is dependent on your PATH, it makes sure you set the PATH. The PATH isn't the only environment variable which can cause problems. Because some shells may use the variables IFS, CDPATH, ENV, and BASH_ENV, Perl checks that those are either empty or untainted when starting subprocesses. You may wish to add something like this to your setid and taint-checking scripts. delete @ENV{qw(IFS CDPATH ENV BASH_ENV)}; # Make %ENV safer 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 properly dropping any special user (or group!) privileges. 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. Perl does not call the shell to expand wild cards when you pass system and exec explicit parameter lists instead of strings with possible shell wildcards in them. Unfortunately, the open, glob, and backtick functions provide no such alternate calling convention, so more subterfuge will be required. Perl provides a reasonably safe way to open a file or pipe from a setuid or setgid program: just create a child process with reduced privilege who does the dirty work for you. First, fork a child using the special open syntax that connects the parent and child by a pipe. Now the child resets its ID set and any other per-process attributes, like environment variables, umasks, current working directories, back to the originals or known safe values. Then the child process, which no longer has any special permissions, does the open or other system call. Finally, the child passes the data it managed to access back to the parent. Because the file or pipe was opened in the child while running under less privilege than the parent, it's not apt to be tricked into doing something it shouldn't. Here's a way to do backticks reasonably safely. Notice how the exec is not called with a string that the shell could expand. This is by far the best way to call something that might be subjected to shell escapes: just never call the shell at all. use English; die "Can't fork: $!" unless defined $pid = open(KID, "-|"); if ($pid) { # parent while () { # do something } close KID; } else { my @temp = ($EUID, $EGID); $EUID = $UID; $EGID = $GID; # initgroups() also called! # Make sure privs are really gone ($EUID, $EGID) = @temp; die "Can't drop privileges" unless $UID == $EUID && $GID eq $EGID; $ENV{PATH} = "/bin:/usr/bin"; exec 'myprog', 'arg1', 'arg2' or die "can't exec myprog: $!"; } A similar strategy would work for wildcard expansion via glob, although you can use readdir instead. Taint checking is most useful when although you trust yourself not to have written a program to give away the farm, you don't necessarily trust those who end up using it not to try to trick it into doing something bad. This is the kind of security checking that's useful for set-id programs and programs launched on someone else's behalf, like CGI programs. This is quite different, however, from not even trusting the writer of the code not to try to do something evil. That's the kind of trust needed when someone hands you a program you've never seen before and says, "Here, run this." For that kind of safety, check out the Safe module, included standard in the Perl distribution. This module allows the programmer to set up special compartments in which all system operations are trapped and namespace access is carefully controlled. Security Bugs ------------- Beyond the obvious problems that stem from giving special privileges to systems as flexible as scripts, on many versions of Unix, set-id scripts are inherently insecure right from the start. The problem is a race condition in the kernel. Between the time the kernel opens the file to see which interpreter to run and when the (now-set-id) interpreter turns around and reopens the file to interpret it, the file in question may have changed, especially if you have symbolic links on your system. Fortunately, sometimes this kernel "feature" can be disabled. Unfortunately, there are two ways to disable it. The system can simply outlaw scripts with any set-id bit set, which doesn't help much. Alternately, it can simply ignore the set-id bits on scripts. If the latter is true, Perl can emulate the setuid and setgid mechanism when it notices the otherwise useless setuid/gid bits on Perl scripts. It does this via a special executable called suidperl that is automatically invoked for you if it's needed. However, if the kernel set-id script feature isn't disabled, Perl will complain loudly that your set-id script is insecure. You'll need to either disable the kernel set-id script feature, or put a C wrapper around the script. A C wrapper is just a compiled program that does nothing except call your Perl program. Compiled programs are not subject to the kernel bug that plagues set-id scripts. Here's a simple wrapper, written in C: #define REAL_PATH "/path/to/script" main(ac, av) char **av; { execv(REAL_PATH, av); } Compile this wrapper into a binary executable and then make it rather than your script setuid or setgid. See the program wrapsuid in the `eg' directory of your Perl distribution for a convenient way to do this automatically for all your setuid Perl programs. It moves setuid scripts into files with the same name plus a leading dot, and then compiles a wrapper like the one above for each of them. In recent years, vendors have begun to supply systems free of this inherent security bug. On such systems, when the kernel passes the name of the set-id script to open to the interpreter, rather than using a pathname subject to meddling, it instead passes */dev/fd/3*. This is a special file already opened on the script, so that there can be no race condition for evil scripts to exploit. On these systems, Perl should be compiled with `-DSETUID_SCRIPTS_ARE_SECURE_NOW'. The Configure program that builds Perl tries to figure this out for itself, so you should never have to specify this yourself. Most modern releases of SysVr4 and BSD 4.4 use this approach to avoid the kernel race condition. Prior to release 5.003 of Perl, a bug in the code of suidperl could introduce a security hole in systems compiled with strict POSIX compliance. Protecting Your Programs ------------------------ There are a number of ways to hide the source to your Perl programs, with varying levels of "security". First of all, however, you *can't* take away read permission, because the source code has to be readable in order to be compiled and interpreted. (That doesn't mean that a CGI script's source is readable by people on the web, though.) So you have to leave the permissions at the socially friendly 0755 level. This lets people on your local system only see your source. Some people mistakenly regard this as a security problem. If your program does insecure things, and relies on people not knowing how to exploit those insecurities, it is not secure. It is often possible for someone to determine the insecure things and exploit them without viewing the source. Security through obscurity, the name for hiding your bugs instead of fixing them, is little security indeed. You can try using encryption via source filters (Filter::* from CPAN). But crackers might be able to decrypt it. You can try using the byte code compiler and interpreter described below, but crackers might be able to de-compile it. You can try using the native-code compiler described below, but crackers might be able to disassemble it. These pose varying degrees of difficulty to people wanting to get at your code, but none can definitively conceal it (this is true of every language, not just Perl). If you're concerned about people profiting from your code, then the bottom line is that nothing but a restrictive licence will give you legal security. License your software and pepper it with threatening statements like "This is unpublished proprietary software of XYZ Corp. Your access to it does not give you permission to use it blah blah blah." You should see a lawyer to be sure your licence's wording will stand up in court. SEE ALSO ======== *Note Perlrun: perlrun, for its description of cleaning up environment variables.  File: perl.info, Node: perlstyle, Next: perlpod, Prev: perlport, Up: Top Perl style guide **************** NAME ==== perlstyle - Perl style guide DESCRIPTION =========== 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, understand, and maintain. The most important thing is to run your programs under the -w flag at all times. You may turn it off explicitly for particular portions of code via the `use warnings' pragma or the $^W variable if you must. You should also always run under `use strict' or know the reason why not. The `use sigtrap' and even `use diagnostics' pragmas may also prove useful. Regarding aesthetics of code lay out, about the only thing Larry cares strongly about is that the closing curly bracket of a multi-line BLOCK should line up with the keyword that started the construct. Beyond that, he has other preferences that aren't so strong: * 4-column indent. * Opening curly on same line as keyword, if possible, otherwise line up. * Space before the opening curly of a multi-line BLOCK. * One-line BLOCK may be put on one line, including curlies. * No space before the semicolon. * Semicolon omitted in "short" one-line BLOCK. * Space around most operators. * Space around a "complex" subscript (inside brackets). * Blank lines between chunks that do different things. * Uncuddled elses. * No space between function name and its opening parenthesis. * Space after each comma. * Long lines broken after an operator (except "and" and "or"). * Space after last parenthesis matching on current line. * Line up corresponding items vertically. * Omit redundant punctuation as long as clarity doesn't suffer. Larry has his reasons for each of these things, but he doesn't claim that everyone else's mind works the same as his does. Here are some other more substantive style issues to think about: * 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"; because 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 parentheses in the wrong place. * 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; } * Don't be afraid to use loop labels-they're there to enhance readability as well as to allow multilevel loop breaks. See the previous example. * Avoid using grep() (or map()) or `backticks` in a void context, that is, when you just throw away their return values. Those functions all have return values, so use them. Otherwise use a foreach() loop or the system() function instead. * 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 $] ($PERL_VERSION in English) to see if it will be there. The Config module will also let you interrogate values determined by the Configure program when Perl was installed. * Choose mnemonic identifiers. If you can't remember what mnemonic means, you've got a problem. * While short identifiers like $gotit are probably ok, use underscores to separate words. It is generally easier to read $var_names_like_this than $VarNamesLikeThis, especially for non-native speakers of English. It's also a simple rule that works consistently with VAR_NAMES_LIKE_THIS. Package names are sometimes an exception to this rule. Perl informally reserves lowercase module names for "pragma" modules like integer and strict. Other modules should begin with a capital letter and use mixed case, but probably without underscores due to limitations in primitive file systems' representations of module names as files that must fit into a few sparse bytes. * You may find it helpful to use letter case to indicate the scope or nature of a variable. For example: $ALL_CAPS_HERE constants only (beware clashes with perl vars!) $Some_Caps_Here package-wide global/static $no_caps_here function scope my() or local() variables Function and method names seem to work best as all lowercase. E.g., $obj->as_string(). You can use a leading underscore to indicate that a variable or function should not be used outside the package that defined it. * If you have a really hairy regular expression, use the `/x' modifier and put in some whitespace to make it look a little less like line noise. Don't use slash as a delimiter when your regexp has slashes or backslashes. * Use the new "and" and "or" operators to avoid having to parenthesize list operators so much, and to reduce the incidence of punctuation operators like `&&' and `||'. Call your subroutines as if they were functions or list operators to avoid excessive ampersands and parentheses. * Use here documents instead of repeated print() statements. * Line up corresponding things vertically, especially if it'd be too long to fit on one line anyway. $IDX = $ST_MTIME; $IDX = $ST_ATIME if $opt_u; $IDX = $ST_CTIME if $opt_c; $IDX = $ST_SIZE if $opt_s; mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!"; chdir($tmpdir) or die "can't chdir $tmpdir: $!"; mkdir 'tmp', 0777 or die "can't mkdir $tmpdir/tmp: $!"; * Always check the return codes of system calls. Good error messages should go to STDERR, include which program caused the problem, what the failed system call and arguments were, and (VERY IMPORTANT) should contain the standard system error message for what went wrong. Here's a simple but sufficient example: opendir(D, $dir) or die "can't opendir $dir: $!"; * Line up your transliterations when it makes sense: tr [abc] [xyz]; * Think about reusability. Why waste brainpower on a one-shot when you might want to do something like it again? Consider generalizing your code. Consider writing a module or object class. Consider making your code run cleanly with `use strict' and `use warnings' (or -w) in effect Consider giving away your code. Consider changing your whole world view. Consider... oh, never mind. * Be consistent. * Be nice.  File: perl.info, Node: perlsub, Next: perlmod, Prev: perlvar, Up: Top Perl subroutines **************** NAME ==== perlsub - Perl subroutines SYNOPSIS ======== To declare subroutines: sub NAME; # A "forward" declaration. sub NAME(PROTO); # ditto, but with prototypes sub NAME : ATTRS; # with attributes sub NAME(PROTO) : ATTRS; # with attributes and prototypes sub NAME BLOCK # A declaration and a definition. sub NAME(PROTO) BLOCK # ditto, but with prototypes sub NAME : ATTRS BLOCK # with attributes sub NAME(PROTO) : ATTRS BLOCK # with prototypes and attributes To define an anonymous subroutine at runtime: $subref = sub BLOCK; # no proto $subref = sub (PROTO) BLOCK; # with proto $subref = sub : ATTRS BLOCK; # with attributes $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes To import subroutines: use MODULE qw(NAME1 NAME2 NAME3); To call subroutines: NAME(LIST); # & is optional with parentheses. NAME LIST; # Parentheses optional if predeclared/imported. &NAME(LIST); # Circumvent prototypes. &NAME; # Makes current @_ visible to called subroutine. DESCRIPTION =========== Like many languages, Perl provides for user-defined subroutines. These may be located anywhere in the main program, loaded in from other files via the do, require, or use keywords, or generated on the fly using eval or anonymous subroutines (closures). You can even call a function indirectly using a variable containing its name or a CODE reference. The Perl model for function call and return values is simple: all functions are passed as parameters one single flat list of scalars, and all functions likewise return to their caller one single flat list of scalars. Any arrays or hashes in these call and return lists will collapse, losing their identities-but you may always use pass-by-reference instead to avoid this. Both call and return lists may contain as many or as few scalar elements as you'd like. (Often a function without an explicit return statement is called a subroutine, but there's really no difference from Perl's perspective.) Any arguments passed in show up in the array `@_'. Therefore, if you called a function with two arguments, those would be stored in `$_[0]' and `$_[1]'. The array `@_' is a local array, but its elements are aliases for the actual scalar parameters. In particular, if an element `$_[0]' is updated, the corresponding argument is updated (or an error occurs if it is not updatable). If an argument is an array or hash element which did not exist when the function was called, that element is created only when (and if) it is modified or a reference to it is taken. (Some earlier versions of Perl created the element whether or not the element was assigned to.) Assigning to the whole array `@_' removes that aliasing, and does not update any arguments. The return value of a subroutine is the value of the last expression evaluated. More explicitly, a return statement may be used to exit the subroutine, optionally specifying the returned value, which will be evaluated in the appropriate context (list, scalar, or void) depending on the context of the subroutine call. If you specify no return value, the subroutine returns an empty list in list context, the undefined value in scalar context, or nothing in void context. If you return one or more aggregates (arrays and hashes), these will be flattened together into one large indistinguishable list. Perl does not have named formal parameters. In practice all you do is assign to a my() list of these. Variables that aren't declared to be private are global variables. For gory details on creating private variables, see `"Private Variables via my()"' in this node and `"Temporary Values via local()"' in this node. To create protected environments for a set of functions in a separate package (and probably a separate file), see `"Packages"', *Note Perlmod: perlmod,. Example: sub max { my $max = shift(@_); foreach $foo (@_) { $max = $foo if $max < $foo; } return $max; } $bestday = max($mon,$tue,$wed,$thu,$fri); Example: # get a line, combining continuation lines # that start with whitespace sub get_line { $thisline = $lookahead; # global variables! LINE: while (defined($lookahead = )) { if ($lookahead =~ /^[ \t]/) { $thisline .= $lookahead; } else { last LINE; } } return $thisline; } $lookahead = ; # get first line while (defined($line = get_line())) { ... } Assigning to a list of private variables to name your arguments: sub maybeset { my($key, $value) = @_; $Foo{$key} = $value unless $Foo{$key}; } Because the assignment copies the values, this also has the effect of turning call-by-reference into call-by-value. Otherwise a function is free to do in-place modifications of `@_' and change its caller's values. upcase_in($v1, $v2); # this changes $v1 and $v2 sub upcase_in { for (@_) { tr/a-z/A-Z/ } } You aren't allowed to modify constants in this way, of course. If an argument were actually literal and you tried to change it, you'd take a (presumably fatal) exception. For example, this won't work: upcase_in("frederick"); It would be much safer if the `upcase_in()' function were written to return a copy of its parameters instead of changing them in place: ($v3, $v4) = upcase($v1, $v2); # this doesn't change $v1 and $v2 sub upcase { return unless defined wantarray; # void context, do nothing my @parms = @_; for (@parms) { tr/a-z/A-Z/ } return wantarray ? @parms : $parms[0]; } Notice how this (unprototyped) function doesn't care whether it was passed real scalars or arrays. Perl sees all arugments as one big, long, flat parameter list in `@_'. This is one area where Perl's simple argument-passing style shines. The `upcase()' function would work perfectly well without changing the `upcase()' definition even if we fed it things like this: @newlist = upcase(@list1, @list2); @newlist = upcase( split /:/, $var ); Do not, however, be tempted to do this: (@a, @b) = upcase(@list1, @list2); Like the flattened incoming parameter list, the return list is also flattened on return. So all you have managed to do here is stored everything in `@a' and made `@b' an empty list. See `Pass by Reference' in this node for alternatives. A subroutine may be called using an explicit & prefix. The & is optional in modern Perl, as are parentheses if the subroutine has been predeclared. The & is not optional when just naming the subroutine, such as when it's used as an argument to defined() or undef(). Nor is it optional when you want to do an indirect subroutine call with a subroutine name or reference using the `&$subref()' or `&{$subref}()' constructs, although the `< $subref-'() >> notation solves that problem. See *Note Perlref: perlref, for more about all that. Subroutines may be called recursively. If a subroutine is called using the & form, the argument list is optional, and if omitted, no `@_' array is set up for the subroutine: the `@_' array at the time of the call is visible to subroutine instead. This is an efficiency mechanism that new users may wish to avoid. &foo(1,2,3); # pass three arguments foo(1,2,3); # the same foo(); # pass a null list &foo(); # the same &foo; # foo() get current args, like foo(@_) !! foo; # like foo() IFF sub foo predeclared, else "foo" Not only does the & form make the argument list optional, it also disables any prototype checking on arguments you do provide. This is partly for historical reasons, and partly for having a convenient way to cheat if you know what you're doing. See `Prototypes' in this node below. Functions whose names are in all upper case are reserved to the Perl core, as are modules whose names are in all lower case. A function in all capitals is a loosely-held convention meaning it will be called indirectly by the run-time system itself, usually due to a triggered event. Functions that do special, pre-defined things include BEGIN, CHECK, `INIT', END, AUTOLOAD, and DESTROY-plus all functions mentioned in *Note Perltie: perltie,. Private Variables via my() -------------------------- Synopsis: my $foo; # declare $foo lexically local my (@wid, %get); # declare list of variables local my $foo = "flurp"; # declare $foo lexical, and init it my @oof = @bar; # declare @oof lexical, and init it my $x : Foo = $y; # similar, with an attribute applied WARNING: The use of attribute lists on my declarations is experimental. This feature should not be relied upon. It may change or disappear in future releases of Perl. See *Note Attributes: (pm.info)attributes,. The my operator declares the listed variables to be lexically confined to the enclosing block, conditional (`if/unless/elsif/else'), loop (`for/foreach/while/until/continue'), subroutine, eval, or `do/require/use''d file. If more than one value is listed, the list must be placed in parentheses. All listed elements must be legal lvalues. Only alphanumeric identifiers may be lexically scoped-magical built-ins like $/ must currently be localize with local instead. Unlike dynamic variables created by the local operator, lexical variables declared with my are totally hidden from the outside world, including any called subroutines. This is true if it's the same subroutine called from itself or elsewhere-every call gets its own copy. This doesn't mean that a my variable declared in a statically enclosing lexical scope would be invisible. Only dynamic scopes are cut off. For example, the `bumpx()' function below has access to the lexical $x variable because both the my and the sub occurred at the same scope, presumably file scope. my $x = 10; sub bumpx { $x++ } An `eval()', however, can see lexical variables of the scope it is being evaluated in, so long as the names aren't hidden by declarations within the `eval()' itself. See *Note Perlref: perlref,. The parameter list to my() may be assigned to if desired, which allows you to initialize your variables. (If no initializer is given for a particular variable, it is created with the undefined value.) Commonly this is used to name input parameters to a subroutine. Examples: $arg = "fred"; # "global" variable $n = cube_root(27); print "$arg thinks the root is $n\n"; fred thinks the root is 3 sub cube_root { my $arg = shift; # name doesn't matter $arg **= 1/3; return $arg; } The my is simply a modifier on something you might assign to. So when you do assign to variables in its argument list, my doesn't change whether those variables are viewed as a scalar or an array. So my ($foo) = ; # WRONG? my @FOO = ; both supply a list context to the right-hand side, while my $foo = ; supplies a scalar context. But the following declares only one variable: my $foo, $bar = 1; # WRONG That has the same effect as my $foo; $bar = 1; The declared variable is not introduced (is not visible) until after the current statement. Thus, my $x = $x; can be used to initialize a new $x with the value of the old $x, and the expression my $x = 123 and $x == 123 is false unless the old $x happened to have the value 123. Lexical scopes of control structures are not bounded precisely by the braces that delimit their controlled blocks; control expressions are part of that scope, too. Thus in the loop while (my $line = <>) { $line = lc $line; } continue { print $line; } the scope of $line extends from its declaration throughout the rest of the loop construct (including the continue clause), but not beyond it. Similarly, in the conditional if ((my $answer = ) =~ /^yes$/i) { user_agrees(); } elsif ($answer =~ /^no$/i) { user_disagrees(); } else { chomp $answer; die "'$answer' is neither 'yes' nor 'no'"; } the scope of $answer extends from its declaration through the rest of that conditional, including any `elsif' and else clauses, but not beyond it. None of the foregoing text applies to `if/unless' or `while/until' modifiers appended to simple statements. Such modifiers are not control structures and have no effect on scoping. The foreach loop defaults to scoping its index variable dynamically in the manner of local. However, if the index variable is prefixed with the keyword my, or if there is already a lexical by that name in scope, then a new lexical is created instead. Thus in the loop for my $i (1, 2, 3) { some_function(); } the scope of $i extends to the end of the loop, but not beyond it, rendering the value of $i inaccessible within `some_function()'. Some users may wish to encourage the use of lexically scoped variables. As an aid to catching implicit uses to package variables, which are always global, if you say use strict 'vars'; then any variable mentioned from there to the end of the enclosing block must either refer to a lexical variable, be predeclared via our or `use vars', or else must be fully qualified with the package name. A compilation error results otherwise. An inner block may countermand this with `no strict 'vars''. A my has both a compile-time and a run-time effect. At compile time, the compiler takes notice of it. The principle usefulness of this is to quiet `use strict 'vars'', but it is also essential for generation of closures as detailed in *Note Perlref: perlref,. Actual initialization is delayed until run time, though, so it gets executed at the appropriate time, such as each time through a loop, for example. Variables declared with my are not part of any package and are therefore never fully qualified with the package name. In particular, you're not allowed to try to make a package variable (or other global) lexical: my $pack::var; # ERROR! Illegal syntax my $_; # also illegal (currently) In fact, a dynamic variable (also known as package or global variables) are still accessible using the fully qualified `::' notation even while a lexical of the same name is also visible: package main; local $x = 10; my $x = 20; print "$x and $::x\n"; That will print out 20 and 10. You may declare my variables at the outermost scope of a file to hide any such identifiers from the world outside that file. This is similar in spirit to C's static variables when they are used at the file level. To do this with a subroutine requires the use of a closure (an anonymous function that accesses enclosing lexicals). If you want to create a private subroutine that cannot be called from outside that block, it can declare a lexical variable containing an anonymous sub reference: my $secret_version = '1.001-beta'; my $secret_sub = sub { print $secret_version }; &$secret_sub(); As long as the reference is never returned by any function within the module, no outside module can see the subroutine, because its name is not in any package's symbol table. Remember that it's not *REALLY* called `$some_pack::secret_version' or anything; it's just $secret_version, unqualified and unqualifiable. This does not work with object methods, however; all object methods have to be in the symbol table of some package to be found. See `"Function Templates"', *Note Perlref: perlref, for something of a work-around to this. Persistent Private Variables ---------------------------- Just because a lexical variable is lexically (also called statically) scoped to its enclosing block, eval, or do FILE, this doesn't mean that within a function it works like a C static. It normally works more like a C auto, but with implicit garbage collection. Unlike local variables in C or C++, Perl's lexical variables don't necessarily get recycled just because their scope has exited. If something more permanent is still aware of the lexical, it will stick around. So long as something else references a lexical, that lexical won't be freed-which is as it should be. You wouldn't want memory being free until you were done using it, or kept around once you were done. Automatic garbage collection takes care of this for you. This means that you can pass back or save away references to lexical variables, whereas to return a pointer to a C auto is a grave error. It also gives us a way to simulate C's function statics. Here's a mechanism for giving a function private variables with both lexical scoping and a static lifetime. If you do want to create something like C's static variables, just enclose the whole function in an extra block, and put the static variable outside the function but in the block. { my $secret_val = 0; sub gimme_another { return ++$secret_val; } } # $secret_val now becomes unreachable by the outside # world, but retains its value between calls to gimme_another If this function is being sourced in from a separate file via require or use, then this is probably just fine. If it's all in the main program, you'll need to arrange for the my to be executed early, either by putting the whole block above your main program, or more likely, placing merely a BEGIN sub around it to make sure it gets executed before your program starts to run: sub BEGIN { my $secret_val = 0; sub gimme_another { return ++$secret_val; } } See `"Package Constructors and Destructors"', *Note Perlmod: perlmod, about the special triggered functions, BEGIN, CHECK, `INIT' and END. If declared at the outermost scope (the file scope), then lexicals work somewhat like C's file statics. They are available to all functions in that same file declared below them, but are inaccessible from outside that file. This strategy is sometimes used in modules to create private variables that the whole module can see. Temporary Values via local() ---------------------------- WARNING: In general, you should be using my instead of local, because it's faster and safer. Exceptions to this include the global punctuation variables, filehandles and formats, and direct manipulation of the Perl symbol table itself. Format variables often use local though, as do other variables whose current value must be visible to called subroutines. Synopsis: local $foo; # declare $foo dynamically local local (@wid, %get); # declare list of variables local local $foo = "flurp"; # declare $foo dynamic, and init it local @oof = @bar; # declare @oof dynamic, and init it local *FH; # localize $FH, @FH, %FH, &FH ... local *merlyn = *randal; # now $merlyn is really $randal, plus # @merlyn is really @randal, etc local *merlyn = 'randal'; # SAME THING: promote 'randal' to *randal local *merlyn = \$randal; # just alias $merlyn, not @merlyn etc A local modifies its listed variables to be "local" to the enclosing block, eval, or `do FILE'-and to *any subroutine called from within that block*. A local just gives temporary values to global (meaning package) variables. It does not create a local variable. This is known as dynamic scoping. Lexical scoping is done with my, which works more like C's auto declarations. If more than one variable is given to local, they must be placed in parentheses. All listed elements must be legal lvalues. This operator works by saving the current values of those variables in its argument list on a hidden stack and restoring them upon exiting the block, subroutine, or eval. This means that called subroutines can also reference the local variable, but not the global one. The argument list may be assigned to if desired, which allows you to initialize your local variables. (If no initializer is given for a particular variable, it is created with an undefined value.) Commonly this is used to name the parameters to a subroutine. Examples: for $i ( 0 .. 9 ) { $digits{$i} = $i; } # assume this function uses global %digits hash parse_num(); # now temporarily add to %digits hash if ($base12) { # (NOTE: not claiming this is efficient!) local %digits = (%digits, 't' => 10, 'e' => 11); parse_num(); # parse_num gets this new %digits! } # old %digits restored here Because local is a run-time operator, it gets executed each time through a loop. In releases of Perl previous to 5.0, this used more stack storage each time until the loop was exited. Perl now reclaims the space each time through, but it's still more efficient to declare your variables outside the loop. A local is simply a modifier on an lvalue expression. When you assign to a localized variable, the local doesn't change whether its list is viewed as a scalar or an array. So local($foo) = ; local @FOO = ; both supply a list context to the right-hand side, while local $foo = ; supplies a scalar context. A note about `local()' and composite types is in order. Something like `local(%foo)' works by temporarily placing a brand new hash in the symbol table. The old hash is left alone, but is hidden "behind" the new one. This means the old variable is completely invisible via the symbol table (i.e. the hash entry in the `*foo' typeglob) for the duration of the dynamic scope within which the `local()' was seen. This has the effect of allowing one to temporarily occlude any magic on composite types. For instance, this will briefly alter a tied hash to some other implementation: tie %ahash, 'APackage'; [...] { local %ahash; tie %ahash, 'BPackage'; [..called code will see %ahash tied to 'BPackage'..] { local %ahash; [..%ahash is a normal (untied) hash here..] } } [..%ahash back to its initial tied self again..] As another example, a custom implementation of %ENV might look like this: { local %ENV; tie %ENV, 'MyOwnEnv'; [..do your own fancy %ENV manipulation here..] } [..normal %ENV behavior here..] It's also worth taking a moment to explain what happens when you localize a member of a composite type (i.e. an array or hash element). In this case, the element is localized *by name*. This means that when the scope of the `local()' ends, the saved value will be restored to the hash element whose key was named in the `local()', or the array element whose index was named in the `local()'. If that element was deleted while the `local()' was in effect (e.g. by a delete() from a hash or a shift() of an array), it will spring back into existence, possibly extending an array and filling in the skipped elements with undef. For instance, if you say %hash = ( 'This' => 'is', 'a' => 'test' ); @ary = ( 0..5 ); { local($ary[5]) = 6; local($hash{'a'}) = 'drill'; while (my $e = pop(@ary)) { print "$e . . .\n"; last unless $e > 3; } if (@ary) { $hash{'only a'} = 'test'; delete $hash{'a'}; } } print join(' ', map { "$_ $hash{$_}" } sort keys %hash),".\n"; print "The array has ",scalar(@ary)," elements: ", join(', ', map { defined $_ ? $_ : 'undef' } @ary),"\n"; Perl will print 6 . . . 4 . . . 3 . . . This is a test only a test. The array has 6 elements: 0, 1, 2, undef, undef, 5 The behavior of local() on non-existent members of composite types is subject to change in future. Lvalue subroutines ------------------ WARNING: Lvalue subroutines are still experimental and the implementation may change in future versions of Perl. It is possible to return a modifiable value from a subroutine. To do this, you have to declare the subroutine to return an lvalue. my $val; sub canmod : lvalue { $val; } sub nomod { $val; } canmod() = 5; # assigns to $val nomod() = 5; # ERROR The scalar/list context for the subroutine and for the right-hand side of assignment is determined as if the subroutine call is replaced by a scalar. For example, consider: data(2,3) = get_data(3,4); Both subroutines here are called in a scalar context, while in: (data(2,3)) = get_data(3,4); and in: (data(2),data(3)) = get_data(3,4); all the subroutines are called in a list context. The current implementation does not allow arrays and hashes to be returned from lvalue subroutines directly. You may return a reference instead. This restriction may be lifted in future. Passing Symbol Table Entries (typeglobs) ---------------------------------------- WARNING: The mechanism described in this section was originally the only way to simulate pass-by-reference in older versions of Perl. While it still works fine in modern versions, the new reference mechanism is generally easier to work with. See below. Sometimes you don't want to pass the value of an array to a subroutine but rather the name of it, so that the subroutine can modify the global copy of it rather than working with a local copy. In perl you can refer to all objects of a particular name by prefixing the name with a star: `*foo'. This is often known as a "typeglob", because the star on the front can be thought of as a wildcard match for all the funny prefix characters on variables and subroutines and such. When evaluated, the typeglob produces a scalar value that represents all the objects of that name, including any filehandle, format, or subroutine. When assigned to, it causes the name mentioned to refer to whatever * value was assigned to it. Example: sub doubleary { local(*someary) = @_; foreach $elem (@someary) { $elem *= 2; } } doubleary(*foo); doubleary(*bar); Scalars are already passed by reference, so you can modify scalar arguments without using this mechanism by referring explicitly to `$_[0]' etc. You can modify all the elements of an array by passing all the elements as scalars, but you have to use the * mechanism (or the equivalent reference mechanism) to push, pop, or change the size of an array. It will certainly be faster to pass the typeglob (or reference). Even if you don't want to modify an array, this mechanism is useful for passing multiple arrays in a single LIST, because normally the LIST mechanism will merge all the array values so that you can't extract out the individual arrays. For more on typeglobs, see `"Typeglobs and Filehandles"', *Note Perldata: perldata,. When to Still Use local() ------------------------- Despite the existence of my, there are still three places where the local operator still shines. In fact, in these three places, you must use local instead of my. 1. You need to give a global variable a temporary value, especially $_. The global variables, like `@ARGV' or the punctuation variables, must be localized with `local()'. This block reads in `/etc/motd', and splits it up into chunks separated by lines of equal signs, which are placed in `@Fields'. { local @ARGV = ("/etc/motd"); local $/ = undef; local $_ = <>; @Fields = split /^\s*=+\s*$/; } It particular, it's important to localize $_ in any routine that assigns to it. Look out for implicit assignments in while conditionals. 2. You need to create a local file or directory handle or a local function. A function that needs a filehandle of its own must use `local()' on a complete typeglob. This can be used to create new symbol table entries: sub ioqueue { local (*READER, *WRITER); # not my! pipe (READER, WRITER); or die "pipe: $!"; return (*READER, *WRITER); } ($head, $tail) = ioqueue(); See the Symbol module for a way to create anonymous symbol table entries. Because assignment of a reference to a typeglob creates an alias, this can be used to create what is effectively a local function, or at least, a local alias. { local *grow = \&shrink; # only until this block exists grow(); # really calls shrink() move(); # if move() grow()s, it shrink()s too } grow(); # get the real grow() again See `"Function Templates"', *Note Perlref: perlref, for more about manipulating functions by name in this way. 3. You want to temporarily change just one element of an array or hash. You can localize just one element of an aggregate. Usually this is done on dynamics: { local $SIG{INT} = 'IGNORE'; funct(); # uninterruptible } # interruptibility automatically restored here But it also works on lexically declared aggregates. Prior to 5.005, this operation could on occasion misbehave. Pass by Reference ----------------- If you want to pass more than one array or hash into a function-or return them from it-and have them maintain their integrity, then you're going to have to use an explicit pass-by-reference. Before you do that, you need to understand references as detailed in *Note Perlref: perlref,. This section may not make much sense to you otherwise. Here are a few simple examples. First, let's pass in several arrays to a function and have it pop all of then, returning a new list of all their former last elements: @tailings = popmany ( \@a, \@b, \@c, \@d ); sub popmany { my $aref; my @retlist = (); foreach $aref ( @_ ) { push @retlist, pop @$aref; } return @retlist; } Here's how you might write a function that returns a list of keys occurring in all the hashes passed to it: @common = inter( \%foo, \%bar, \%joe ); sub inter { my ($k, $href, %seen); # locals foreach $href (@_) { while ( $k = each %$href ) { $seen{$k}++; } } return grep { $seen{$_} == @_ } keys %seen; } So far, we're using just the normal list return mechanism. What happens if you want to pass or return a hash? Well, if you're using only one of them, or you don't mind them concatenating, then the normal calling convention is ok, although a little expensive. Where people get into trouble is here: (@a, @b) = func(@c, @d); or (%a, %b) = func(%c, %d); That syntax simply won't work. It sets just `@a' or `%a' and clears the `@b' or `%b'. Plus the function didn't get passed into two separate arrays or hashes: it got one long list in `@_', as always. If you can arrange for everyone to deal with this through references, it's cleaner code, although not so nice to look at. Here's a function that takes two array references as arguments, returning the two array elements in order of how many elements they have in them: ($aref, $bref) = func(\@c, \@d); print "@$aref has more than @$bref\n"; sub func { my ($cref, $dref) = @_; if (@$cref > @$dref) { return ($cref, $dref); } else { return ($dref, $cref); } } It turns out that you can actually do this also: (*a, *b) = func(\@c, \@d); print "@a has more than @b\n"; sub func { local (*c, *d) = @_; if (@c > @d) { return (\@c, \@d); } else { return (\@d, \@c); } } Here we're using the typeglobs to do symbol table aliasing. It's a tad subtle, though, and also won't work if you're using my variables, because only globals (even in disguise as locals) are in the symbol table. If you're passing around filehandles, you could usually just use the bare typeglob, like `*STDOUT', but typeglobs references work, too. For example: splutter(\*STDOUT); sub splutter { my $fh = shift; print $fh "her um well a hmmm\n"; } $rec = get_rec(\*STDIN); sub get_rec { my $fh = shift; return scalar <$fh>; } If you're planning on generating new filehandles, you could do this. Notice to pass back just the bare *FH, not its reference. sub openit { my $path = shift; local *FH; return open (FH, $path) ? *FH : undef; } Prototypes ---------- Perl supports a very limited kind of compile-time argument checking using function prototyping. If you declare sub mypush (\@@) then `mypush()' takes arguments exactly like `push()' does. The function declaration must be visible at compile time. The prototype affects only interpretation of new-style calls to the function, where new-style is defined as not using the & character. In other words, if you call it like a built-in function, then it behaves like a built-in function. If you call it like an old-fashioned subroutine, then it behaves like an old-fashioned subroutine. It naturally falls out from this rule that prototypes have no influence on subroutine references like `\&foo' or on indirect subroutine calls like `&{$subref}' or `< $subref-'() >>. Method calls are not influenced by prototypes either, because the function to be called is indeterminate at compile time, since the exact code called depends on inheritance. Because the intent of this feature is primarily to let you define subroutines that work like built-in functions, here are prototypes for some other functions that parse almost exactly like the corresponding built-in. Declared as Called as sub mylink ($$) mylink $old, $new sub myvec ($$$) myvec $var, $offset, 1 sub myindex ($$;$) myindex &getstring, "substr" sub mysyswrite ($$$;$) mysyswrite $buf, 0, length($buf) - $off, $off sub myreverse (@) myreverse $a, $b, $c sub myjoin ($@) myjoin ":", $a, $b, $c sub mypop (\@) mypop @array sub mysplice (\@$$@) mysplice @array, @array, 0, @pushme sub mykeys (\%) mykeys %{$hashref} sub myopen (*;$) myopen HANDLE, $name sub mypipe (**) mypipe READHANDLE, WRITEHANDLE sub mygrep (&@) mygrep { /foo/ } $a, $b, $c sub myrand ($) myrand 42 sub mytime () mytime Any backslashed prototype character represents an actual argument that absolutely must start with that character. The value passed as part of `@_' will be a reference to the actual argument given in the subroutine call, obtained by applying \ to that argument. Unbackslashed prototype characters have special meanings. Any unbackslashed `@' or % eats all remaining arguments, and forces list context. An argument represented by `$' forces scalar context. An & requires an anonymous subroutine, which, if passed as the first argument, does not require the sub keyword or a subsequent comma. A * allows the subroutine to accept a bareword, constant, scalar expression, typeglob, or a reference to a typeglob in that slot. The value will be available to the subroutine either as a simple scalar, or (in the latter two cases) as a reference to the typeglob. If you wish to always convert such arguments to a typeglob reference, use Symbol::qualify_to_ref() as follows: use Symbol 'qualify_to_ref'; sub foo (*) { my $fh = qualify_to_ref(shift, caller); ... } A semicolon separates mandatory arguments from optional arguments. It is redundant before `@' or %, which gobble up everything else. Note how the last three examples in the table above are treated specially by the parser. `mygrep()' is parsed as a true list operator, `myrand()' is parsed as a true unary operator with unary precedence the same as `rand()', and `mytime()' is truly without arguments, just like `time()'. That is, if you say mytime +2; you'll get `mytime() + 2', not `mytime(2)', which is how it would be parsed without a prototype. The interesting thing about & is that you can generate new syntax with it, provided it's in the initial position: sub try (&@) { my($try,$catch) = @_; eval { &$try }; if ($@) { local $_ = $@; &$catch; } } sub catch (&) { $_[0] } try { die "phooey"; } catch { /phooey/ and print "unphooey\n"; }; That prints `"unphooey"'. (Yes, there are still unresolved issues having to do with visibility of `@_'. I'm ignoring that question for the moment. (But note that if we make `@_' lexically scoped, those anonymous subroutines can act like closures... (Gee, is this sounding a little Lispish? (Never mind.)))) And here's a reimplementation of the Perl grep operator: sub mygrep (&@) { my $code = shift; my @result; foreach $_ (@_) { push(@result, $_) if &$code; } @result; } Some folks would prefer full alphanumeric prototypes. Alphanumerics have been intentionally left out of prototypes for the express purpose of someday in the future adding named, formal parameters. The current mechanism's main goal is to let module writers provide better diagnostics for module users. Larry feels the notation quite understandable to Perl programmers, and that it will not intrude greatly upon the meat of the module, nor make it harder to read. The line noise is visually encapsulated into a small pill that's easy to swallow. It's probably best to prototype new functions, not retrofit prototyping into older ones. That's because you must be especially careful about silent impositions of differing list versus scalar contexts. For example, if you decide that a function should take just one parameter, like this: sub func ($) { my $n = shift; print "you gave me $n\n"; } and someone has been calling it with an array or expression returning a list: func(@foo); func( split /:/ ); Then you've just supplied an automatic scalar in front of their argument, which can be more than a bit surprising. The old `@foo' which used to hold one thing doesn't get passed in. Instead, `func()' now gets passed in a 1; that is, the number of elements in `@foo'. And the split gets called in scalar context so it starts scribbling on your `@_' parameter list. Ouch! This is all very powerful, of course, and should be used only in moderation to make the world a better place. Constant Functions ------------------ Functions with a prototype of `()' are potential candidates for inlining. If the result after optimization and constant folding is either a constant or a lexically-scoped scalar which has no other references, then it will be used in place of function calls made without &. Calls made using & are never inlined. (See `constant.pm' for an easy way to declare most constants.) The following functions would all be inlined: sub pi () { 3.14159 } # Not exact, but close. sub PI () { 4 * atan2 1, 1 } # As good as it gets, # and it's inlined, too! sub ST_DEV () { 0 } sub ST_INO () { 1 } sub FLAG_FOO () { 1 << 8 } sub FLAG_BAR () { 1 << 9 } sub FLAG_MASK () { FLAG_FOO | FLAG_BAR } sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) } sub BAZ_VAL () { if (OPT_BAZ) { return 23; } else { return 42; } } sub N () { int(BAZ_VAL) / 3 } BEGIN { my $prod = 1; for (1..N) { $prod *= $_ } sub N_FACTORIAL () { $prod } } If you redefine a subroutine that was eligible for inlining, you'll get a mandatory warning. (You can use this warning to tell whether or not a particular subroutine is considered constant.) The warning is considered severe enough not to be optional because previously compiled invocations of the function will still be using the old value of the function. If you need to be able to redefine the subroutine, you need to ensure that it isn't inlined, either by dropping the `()' prototype (which changes calling semantics, so beware) or by thwarting the inlining mechanism in some other way, such as sub not_inlined () { 23 if $]; } Overriding Built-in Functions ----------------------------- Many built-in functions may be overridden, though this should be tried only occasionally and for good reason. Typically this might be done by a package attempting to emulate missing built-in functionality on a non-Unix system. Overriding may be done only by importing the name from a module-ordinary predeclaration isn't good enough. However, the `use subs' pragma lets you, in effect, predeclare subs via the import syntax, and these names may then override built-in ones: use subs 'chdir', 'chroot', 'chmod', 'chown'; chdir $somewhere; sub chdir { ... } To unambiguously refer to the built-in form, precede the built-in name with the special package qualifier `CORE::'. For example, saying `CORE::open()' always refers to the built-in open(), even if the current package has imported some other subroutine called `&open()' from elsewhere. Even though it looks like a regular function call, it isn't: you can't take a reference to it, such as the incorrect `\&CORE::open' might appear to produce. Library modules should not in general export built-in names like open or chdir as part of their default `@EXPORT' list, because these may sneak into someone else's namespace and change the semantics unexpectedly. Instead, if the module adds that name to `@EXPORT_OK', then it's possible for a user to import the name explicitly, but not implicitly. That is, they could say use Module 'open'; and it would import the open override. But if they said use Module; they would get the default imports without overrides. The foregoing mechanism for overriding built-in is restricted, quite deliberately, to the package that requests the import. There is a second method that is sometimes applicable when you wish to override a built-in everywhere, without regard to namespace boundaries. This is achieved by importing a sub into the special namespace `CORE::GLOBAL::'. Here is an example that quite brazenly replaces the glob operator with something that understands regular expressions. package REGlob; require Exporter; @ISA = 'Exporter'; @EXPORT_OK = 'glob'; sub import { my $pkg = shift; return unless @_; my $sym = shift; my $where = ($sym =~ s/^GLOBAL_// ? 'CORE::GLOBAL' : caller(0)); $pkg->export($where, $sym, @_); } sub glob { my $pat = shift; my @got; local *D; if (opendir D, '.') { @got = grep /$pat/, readdir D; closedir D; } return @got; } 1; And here's how it could be (ab)used: #use REGlob 'GLOBAL_glob'; # override glob() in ALL namespaces package Foo; use REGlob 'glob'; # override glob() in Foo:: only print for <^[a-z_]+\.pm\$>; # show all pragmatic modules The initial comment shows a contrived, even dangerous example. By overriding glob globally, you would be forcing the new (and subversive) behavior for the glob operator for every namespace, without the complete cognizance or cooperation of the modules that own those namespaces. Naturally, this should be done with extreme caution-if it must be done at all. The `REGlob' example above does not implement all the support needed to cleanly override perl's glob operator. The built-in glob has different behaviors depending on whether it appears in a scalar or list context, but our `REGlob' doesn't. Indeed, many perl built-in have such context sensitive behaviors, and these must be adequately supported by a properly written override. For a fully functional example of overriding glob, study the implementation of File::DosGlob in the standard library. Autoloading ----------- If you call a subroutine that is undefined, you would ordinarily get an immediate, fatal error complaining that the subroutine doesn't exist. (Likewise for subroutines being used as methods, when the method doesn't exist in any base class of the class's package.) However, if an AUTOLOAD subroutine is defined in the package or packages used to locate the original subroutine, then that AUTOLOAD subroutine is called with the arguments that would have been passed to the original subroutine. The fully qualified name of the original subroutine magically appears in the global $AUTOLOAD variable of the same package as the AUTOLOAD routine. The name is not passed as an ordinary argument because, er, well, just because, that's why... Many AUTOLOAD routines load in a definition for the requested subroutine using eval(), then execute that subroutine using a special form of goto() that erases the stack frame of the AUTOLOAD routine without a trace. (See the source to the standard module documented in *Note AutoLoader: (pm.info)AutoLoader,, for example.) But an AUTOLOAD routine can also just emulate the routine and never define it. For example, let's pretend that a function that wasn't defined should just invoke system with those arguments. All you'd do is: sub AUTOLOAD { my $program = $AUTOLOAD; $program =~ s/.*:://; system($program, @_); } date(); who('am', 'i'); ls('-l'); In fact, if you predeclare functions you want to call that way, you don't even need parentheses: use subs qw(date who ls); date; who "am", "i"; ls -l; A more complete example of this is the standard Shell module, which can treat undefined subroutine calls as calls to external programs. Mechanisms are available to help modules writers split their modules into autoloadable files. See the standard AutoLoader module described in *Note AutoLoader: (pm.info)AutoLoader, and in *Note AutoSplit: (pm.info)AutoSplit,, the standard SelfLoader modules in *Note SelfLoader: (pm.info)SelfLoader,, and the document on adding C functions to Perl code in *Note Perlxs: perlxs,. Subroutine Attributes --------------------- A subroutine declaration or definition may have a list of attributes associated with it. If such an attribute list is present, it is broken up at space or colon boundaries and treated as though a `use attributes' had been seen. See *Note Attributes: (pm.info)attributes, for details about what attributes are currently supported. Unlike the limitation with the obsolescent `use attrs', the `sub : ATTRLIST' syntax works to associate the attributes with a pre-declaration, and not just with a subroutine definition. The attributes must be valid as simple identifier names (without any punctuation other than the '_' character). They may have a parameter list appended, which is only checked for whether its parentheses ('(',')') nest properly. Examples of valid syntax (even though the attributes are unknown): sub fnord (&\%) : switch(10,foo(7,3)) : expensive ; sub plugh () : Ugly('\(") :Bad ; sub xyzzy : _5x5 { ... } Examples of invalid syntax: sub fnord : switch(10,foo() ; # ()-string not balanced sub snoid : Ugly('(') ; # ()-string not balanced sub xyzzy : 5x5 ; # "5x5" not a valid identifier sub plugh : Y2::north ; # "Y2::north" not a simple identifier sub snurt : foo + bar ; # "+" not a colon or space The attribute list is passed as a list of constant strings to the code which associates them with the subroutine. In particular, the second example of valid syntax above currently looks like this in terms of how it's parsed and invoked: use attributes __PACKAGE__, \&plugh, q[Ugly('\(")], 'Bad'; For further details on attribute lists and their manipulation, see *Note Attributes: (pm.info)attributes,. SEE ALSO ======== See `"Function Templates"', *Note Perlref: perlref, for more about references and closures. See `"Function Templates"', *Note Perlxs: perlxs, if you'd like to learn about calling C subroutines from Perl. See `"Function Templates"', *Note Perlembed: perlembed, if you'd like to learn about calling PErl subroutines from C. See `"Function Templates"', *Note Perlmod: perlmod, to learn about bundling up your functions in separate files. See `"Function Templates"', *Note Perlmodlib: perlmodlib, to learn what library modules come standard on your system. See `"Function Templates"', *Note Perltoot: perltoot, to learn how to make object method calls.