X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=d730b43e47eecc667f68e74104209479d4c7f56e;hb=f472eb5c07ed95306a11c98250bda17aae994339;hp=d409319a09f8ad96e911d7909faabff64c3e2180;hpb=2cdbc966996b991c40c8522dcf668b1e34b5e76b;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index d409319..d730b43 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -30,7 +30,7 @@ Elements of the LIST should be separated by commas. Any function in the list below may be used either with or without parentheses around its arguments. (The syntax descriptions omit the parentheses.) If you use the parentheses, the simple (but occasionally -surprising) rule is this: It I like a function, therefore it I a +surprising) rule is this: It I like a function, therefore it I a function, and precedence doesn't matter. Otherwise it's a list operator or unary operator, and precedence does matter. And whitespace between the function and left parenthesis doesn't count--so you need to @@ -80,8 +80,8 @@ In general, functions in Perl that serve as wrappers for system calls of the same name (like chown(2), fork(2), closedir(2), etc.) all return true when they succeed and C otherwise, as is usually mentioned in the descriptions below. This is different from the C interfaces, -which return C<-1> on failure. Exceptions to this rule are C, -C, and C. System calls also set the special C<$!> +which return C<-1> on failure. Exceptions to this rule are C, +C, and C. System calls also set the special C<$!> variable on failure. Other functions do not, except accidentally. =head2 Perl Functions by Category @@ -255,7 +255,7 @@ A file test, where X is one of the letters listed below. This unary operator takes one argument, either a filename or a filehandle, and tests the associated file to see if something is true about it. If the argument is omitted, tests C<$_>, except for C<-t>, which tests STDIN. -Unless otherwise documented, it returns C<1> for TRUE and C<''> for FALSE, or +Unless otherwise documented, it returns C<1> for true and C<''> for false, or the undefined value if the file doesn't exist. Despite the funny names, precedence is the same as any other named unary operator, and the argument may be parenthesized like any other unary operator. The @@ -339,12 +339,12 @@ characters with the high bit set. If too many strange characters (E30%) are found, it's a C<-B> file, otherwise it's a C<-T> file. Also, any file containing null in the first block is considered a binary file. If C<-T> or C<-B> is used on a filehandle, the current stdio buffer is examined -rather than the first block. Both C<-T> and C<-B> return TRUE on a null +rather than the first block. Both C<-T> and C<-B> return true on a null file, or a file at EOF when testing a filehandle. Because you have to read a file to do the C<-T> test, on most occasions you want to use a C<-f> against the file first, as in C. -If any of the file tests (or either the C or C operators) are given +If any of the file tests (or either the C or C operators) are given the special filehandle consisting of a solitary underline, then the stat structure of the previous file test (or stat operator) is used, saving a system call. (This doesn't work with C<-t>, and you need to remember @@ -373,7 +373,7 @@ If VALUE is omitted, uses C<$_>. =item accept NEWSOCKET,GENERICSOCKET Accepts an incoming socket connect, just as the accept(2) system call -does. Returns the packed address if it succeeded, FALSE otherwise. +does. Returns the packed address if it succeeded, false otherwise. See the example in L. =item alarm SECONDS @@ -391,18 +391,18 @@ starting a new one. The returned value is the amount of time remaining on the previous timer. For delays of finer granularity than one second, you may use Perl's -four-arugment version of select() leaving the first three arguments -undefined, or you might be able to use the C interface to +four-argument version of select() leaving the first three arguments +undefined, or you might be able to use the C interface to access setitimer(2) if your system supports it. The Time::HiRes module from CPAN may also prove useful. -It is usually a mistake to intermix C -and C calls. +It is usually a mistake to intermix C and C calls. +(C may be internally implemented in your system with C) -If you want to use C to time out a system call you need to use an -C/C pair. You can't rely on the alarm causing the system call to +If you want to use C to time out a system call you need to use an +C/C pair. You can't rely on the alarm causing the system call to fail with C<$!> set to C because Perl sets up signal handlers to -restart system calls on some systems. Using C/C always works, +restart system calls on some systems. Using C/C always works, modulo the caveats given in L. eval { @@ -431,29 +431,51 @@ function, or use the familiar relation: =item bind SOCKET,NAME Binds a network address to a socket, just as the bind system call -does. Returns TRUE if it succeeded, FALSE otherwise. NAME should be a +does. Returns true if it succeeded, false otherwise. NAME should be a packed address of the appropriate type for the socket. See the examples in L. =item binmode FILEHANDLE -Arranges for the file to be read or written in "binary" mode in operating -systems that distinguish between binary and text files. Files that -are not in binary mode have CR LF sequences translated to LF on input -and LF translated to CR LF on output. Binmode has no effect under -many sytems, but in MS-DOS and similarly archaic systems, it may be -imperative--otherwise your MS-DOS-damaged C library may mangle your file. -The key distinction between systems that need C and those -that don't is their text file formats. Systems like Unix, MacOS, and -Plan9 that delimit lines with a single character, and that encode that -character in C as C<"\n">, do not need C. The rest may need it. -If FILEHANDLE is an expression, the value is taken as the name of the -filehandle. - -If the system does care about it, using it when you shouldn't is just as -perilous as failing to use it when you should. Fortunately for most of -us, you can't go wrong using binmode() on systems that don't care about -it, though. +Arranges for FILEHANDLE to be read or written in "binary" mode on +systems whose run-time libraries force the programmer to guess +between binary and text files. If FILEHANDLE is an expression, the +value is taken as the name of the filehandle. binmode() should be +called after the C but before any I/O is done on the filehandle. +The only way to reset binary mode on a filehandle is to reopen the +file. + +The operating system, device drivers, C libraries, and Perl run-time +system all conspire to let the programmer conveniently treat a +simple, one-byte C<\n> as the line terminator, irrespective of its +external representation. On Unix and its brethren, the native file +representation exactly matches the internal representation, making +everyone's lives unbelievably simpler. Consequently, L +has no effect under Unix, Plan9, or Mac OS, all of which use C<\n> +to end each line. (Unix and Plan9 think C<\n> means C<\cJ> and +C<\r> means C<\cM>, whereas the Mac goes the other way--it uses +C<\cM> for c<\n> and C<\cJ> to mean C<\r>. But that's ok, because +it's only one byte, and the internal and external representations +match.) + +In legacy systems like MS-DOS and its embellishments, your program +sees a C<\n> as a simple C<\cJ> (just as in Unix), but oddly enough, +that's not what's physically stored on disk. What's worse, these +systems refuse to help you with this; it's up to you to remember +what to do. And you mustn't go applying binmode() with wild abandon, +either, because if your system does care about binmode(), then using +it when you shouldn't is just as perilous as failing to use it when +you should. + +That means that on any version of Microsoft WinXX that you might +care to name (or not), binmode() causes C<\cM\cJ> sequences on disk +to be converted to C<\n> when read into your program, and causes +any C<\n> in your program to be converted back to C<\cM\cJ> on +output to disk. This sad discrepancy leads to no end of +problems in not just the readline operator, but also when using +seek(), tell(), and read() calls. See L for other painful +details. See the C<$/> and C<$\> variables in L for how +to manually set your input and output line-termination sequences. =item bless REF,CLASSNAME @@ -461,7 +483,7 @@ it, though. This function tells the thingy referenced by REF that it is now an object in the CLASSNAME package. If CLASSNAME is omitted, the current package -is used. Because a C is often the last thing in a constructor. +is used. Because a C is often the last thing in a constructor, it returns the reference for convenience. Always use the two-argument version if the function doing the blessing might be inherited by a derived class. See L and L for more about the blessing @@ -481,7 +503,7 @@ See L. Returns the context of the current subroutine call. In scalar context, returns the caller's package name if there is a caller, that is, if -we're in a subroutine or C or C, and the undefined value +we're in a subroutine or C or C, and the undefined value otherwise. In list context, returns ($package, $filename, $line) = caller; @@ -490,33 +512,35 @@ With EXPR, it returns some extra information that the debugger uses to print a stack trace. The value of EXPR indicates how many call frames to go back before the current one. - ($package, $filename, $line, $subroutine, - $hasargs, $wantarray, $evaltext, $is_require) = caller($i); + ($package, $filename, $line, $subroutine, $hasargs, + $wantarray, $evaltext, $is_require, $hints) = caller($i); -Here C<$subroutine> may be C<"(eval)"> if the frame is not a subroutine -call, but an C. In such a case additional elements C<$evaltext> and +Here $subroutine may be C<(eval)> if the frame is not a subroutine +call, but an C. In such a case additional elements $evaltext and C<$is_require> are set: C<$is_require> is true if the frame is created by a -C or C statement, C<$evaltext> contains the text of the +C or C statement, $evaltext contains the text of the C statement. In particular, for a C statement, -C<$filename> is C<"(eval)">, but C<$evaltext> is undefined. (Note also that +$filename is C<(eval)>, but $evaltext is undefined. (Note also that each C statement creates a C frame inside an C) -frame. +frame. C<$hints> contains pragmatic hints that the caller was +compiled with. It currently only reflects the hint corresponding to +C. Furthermore, when called from within the DB package, caller returns more detailed information: it sets the list variable C<@DB::args> to be the arguments with which the subroutine was invoked. Be aware that the optimizer might have optimized call frames away before -C had a chance to get the information. That means that C +C had a chance to get the information. That means that C might not return information about the call frame you expect it do, for -C 1>. In particular, C<@DB::args> might have information from the -previous time C was called. +C 1>. In particular, C<@DB::args> might have information from the +previous time C was called. =item chdir EXPR Changes the working directory to EXPR, if possible. If EXPR is omitted, -changes to the user's home directory. Returns TRUE upon success, -FALSE otherwise. See the example under C. +changes to the user's home directory. Returns true upon success, +false otherwise. See the example under C. =item chmod LIST @@ -548,7 +572,8 @@ that the final record may be missing its newline. When in paragraph mode (C<$/ = "">), it removes all trailing newlines from the string. When in slurp mode (C<$/ = undef>) or fixed-length record mode (C<$/> is a reference to an integer or the like, see L) chomp() won't -remove anything. If VARIABLE is omitted, it chomps C<$_>. Example: +remove anything. +If VARIABLE is omitted, it chomps C<$_>. Example: while (<>) { chomp; # avoid \n on last field @@ -588,16 +613,18 @@ You can actually chop anything that's an lvalue, including an assignment: chop($answer = ); If you chop a list, each element is chopped. Only the value of the -last C is returned. +last C is returned. -Note that C returns the last character. To return all but the last +Note that C returns the last character. To return all but the last character, use C. =item chown LIST Changes the owner (and group) of a list of files. The first two -elements of the list must be the I uid and gid, in that order. -Returns the number of files successfully changed. +elements of the list must be the I uid and gid, in that +order. A value of -1 in either position is interpreted by most +systems to leave that value unchanged. Returns the number of files +successfully changed. $cnt = chown $uid, $gid, 'foo', 'bar'; chown $uid, $gid, @filenames; @@ -605,9 +632,9 @@ Returns the number of files successfully changed. Here's an example that looks up nonnumeric uids in the passwd file: print "User: "; - chop($user = ); + chomp($user = ); print "Files: "; - chop($pattern = ); + chomp($pattern = ); ($login,$pass,$uid,$gid) = getpwnam($user) or die "$user not in passwd file"; @@ -619,6 +646,10 @@ On most systems, you are not allowed to change the ownership of the file unless you're the superuser, although you should be able to change the group to any of your secondary groups. On insecure systems, these restrictions may be relaxed, but this is not a portable assumption. +On POSIX systems, you can detect this condition this way: + + use POSIX qw(sysconf _PC_CHOWN_RESTRICTED); + $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED); =item chr NUMBER @@ -638,33 +669,38 @@ If NUMBER is omitted, uses C<$_>. This function works like the system call by the same name: it makes the named directory the new root directory for all further pathnames that -begin with a C<"/"> by your process and all its children. (It doesn't +begin with a C by your process and all its children. (It doesn't change your current working directory, which is unaffected.) For security reasons, this call is restricted to the superuser. If FILENAME is -omitted, does a C to C<$_>. +omitted, does a C to C<$_>. =item close FILEHANDLE =item close -Closes the file or pipe associated with the file handle, returning TRUE +Closes the file or pipe associated with the file handle, returning true only if stdio successfully flushes buffers and closes the system file -descriptor. Closes the currently selected filehandle if the argument +descriptor. Closes the currently selected filehandle if the argument is omitted. You don't have to close FILEHANDLE if you are immediately going to do -another C on it, because C will close it for you. (See -C.) However, an explicit C on an input file resets the line -counter (C<$.>), while the implicit close done by C does not. +another C on it, because C will close it for you. (See +C.) However, an explicit C on an input file resets the line +counter (C<$.>), while the implicit close done by C does not. -If the file handle came from a piped open C will additionally -return FALSE if one of the other system calls involved fails or if the +If the file handle came from a piped open C will additionally +return false if one of the other system calls involved fails or if the program exits with non-zero status. (If the only problem was that the program exited non-zero C<$!> will be set to C<0>.) Closing a pipe also waits for the process executing on the pipe to complete, in case you want to look at the output of the pipe afterwards, and implicitly puts the exit status value of that command into C<$?>. +Prematurely closing the read end of a pipe (i.e. before the process +writing to it at the other end has closed it) will result in a +SIGPIPE being delivered to the writer. If the other end can't +handle that, be sure to read all the data before closing the pipe. + Example: open(OUTPUT, '|sort >foo') # pipe to sort @@ -681,7 +717,7 @@ filehandle, usually the real filehandle name. =item closedir DIRHANDLE -Closes a directory opened by C and returns the success of that +Closes a directory opened by C and returns the success of that system call. DIRHANDLE may be an expression whose value can be used as an indirect @@ -690,7 +726,7 @@ dirhandle, usually the real dirhandle name. =item connect SOCKET,NAME Attempts to connect to a remote socket, just as the connect system call -does. Returns TRUE if it succeeded, FALSE otherwise. NAME should be a +does. Returns true if it succeeded, false otherwise. NAME should be a packed address of the appropriate type for the socket. See the examples in L. @@ -705,8 +741,8 @@ continued via the C statement (which is similar to the C C statement). C, C, or C may appear within a C -block. C and C will behave as if they had been executed within -the main block. So will C, but since it will execute a C +block. C and C will behave as if they had been executed within +the main block. So will C, but since it will execute a C block, it may be more entertaining. while (EXPR) { @@ -720,7 +756,7 @@ block, it may be more entertaining. ### last always comes here Omitting the C section is semantically equivalent to using an -empty one, logically enough. In that case, C goes directly back +empty one, logically enough. In that case, C goes directly back to check the condition at the top of the loop. =item cos EXPR @@ -741,14 +777,14 @@ extirpated as a potential munition). This can prove useful for checking the password file for lousy passwords, amongst other things. Only the guys wearing white hats should do this. -Note that C is intended to be a one-way function, much like breaking +Note that C is intended to be a one-way function, much like breaking eggs to make an omelette. There is no (known) corresponding decrypt function. As a result, this function isn't all that useful for cryptography. (For that, see your nearby CPAN mirror.) When verifying an existing encrypted string you should use the encrypted text as the salt (like C). This -allows your code to work with the standard C and with more +allows your code to work with the standard C and with more exotic implementations. When choosing a new salt create a random two character string whose characters come from the set C<[./0-9A-Za-z]> (like C). @@ -773,34 +809,40 @@ their own password: Of course, typing in your own password to whoever asks you for it is unwise. +The L function is unsuitable for encrypting large quantities +of data, not least of all because you can't get the information +back. Look at the F and F directories +on your favorite CPAN mirror for a slew of potentially useful +modules. + =item dbmclose HASH -[This function has been largely superseded by the C function.] +[This function has been largely superseded by the C function.] Breaks the binding between a DBM file and a hash. -=item dbmopen HASH,DBNAME,MODE +=item dbmopen HASH,DBNAME,MASK -[This function has been largely superseded by the C function.] +[This function has been largely superseded by the C function.] This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a -hash. HASH is the name of the hash. (Unlike normal C, the first -argument is I a filehandle, even though it looks like one). DBNAME +hash. HASH is the name of the hash. (Unlike normal C, the first +argument is I a filehandle, even though it looks like one). DBNAME is the name of the database (without the F<.dir> or F<.pag> extension if any). If the database does not exist, it is created with protection -specified by MODE (as modified by the C). If your system supports -only the older DBM functions, you may perform only one C in your +specified by MASK (as modified by the C). If your system supports +only the older DBM functions, you may perform only one C in your program. In older versions of Perl, if your system had neither DBM nor -ndbm, calling C produced a fatal error; it now falls back to +ndbm, calling C produced a fatal error; it now falls back to sdbm(3). If you don't have write access to the DBM file, you can only read hash variables, not set them. If you want to test whether you can write, -either use file tests or try setting a dummy hash entry inside an C, +either use file tests or try setting a dummy hash entry inside an C, which will trap the error. -Note that functions such as C and C may return huge lists -when used on large DBM files. You may prefer to use the C +Note that functions such as C and C may return huge lists +when used on large DBM files. You may prefer to use the C function to iterate over large DBM files. Example: # print out history file offsets @@ -835,14 +877,21 @@ conditions. This function allows you to distinguish C from other values. (A simple Boolean test will not distinguish among C, zero, the empty string, and C<"0">, which are all equally false.) Note that since C is a valid scalar, its presence -doesn't I indicate an exceptional condition: C +doesn't I indicate an exceptional condition: C returns C when its argument is an empty array, I when the element to return happens to be C. -You may also use C to check whether a subroutine exists, by -saying C without parentheses. On the other hand, use -of C upon aggregates (hashes and arrays) is not guaranteed to -produce intuitive results, and should probably be avoided. +You may also use C to check whether subroutine C<&func> +has ever been defined. The return value is unaffected by any forward +declarations of C<&foo>. + +Use of C on aggregates (hashes and arrays) is deprecated. It +used to report whether memory for that aggregate has ever been +allocated. This behavior may disappear in future versions of Perl. +You should instead use a simple test for size: + + if (@an_array) { print "has array elements\n" } + if (%a_hash) { print "has hash members\n" } When used on a hash element, it tells you whether the value is defined, not whether the key exists in the hash. Use L for the latter @@ -857,7 +906,7 @@ Examples: sub foo { defined &$bar ? &$bar(@_) : die "No bar"; } $debugging = 0 unless defined $debugging; -Note: Many folks tend to overuse C, and then are surprised to +Note: Many folks tend to overuse C, and then are surprised to discover that the number C<0> and C<""> (the zero-length string) are, in fact, defined values. For example, if you say @@ -868,69 +917,72 @@ matched "nothing". But it didn't really match nothing--rather, it matched something that happened to be zero characters long. This is all very above-board and honest. When a function returns an undefined value, it's an admission that it couldn't give you an honest answer. So you -should use C only when you're questioning the integrity of what +should use C only when you're questioning the integrity of what you're trying to do. At other times, a simple comparison to C<0> or C<""> is what you want. -Currently, using C on an entire array or hash reports whether -memory for that aggregate has ever been allocated. So an array you set -to the empty list appears undefined initially, and one that once was full -and that you then set to the empty list still appears defined. You -should instead use a simple test for size: - - if (@an_array) { print "has array elements\n" } - if (%a_hash) { print "has hash members\n" } - -Using C on these, however, does clear their memory and then report -them as not defined anymore, but you shouldn't do that unless you don't -plan to use them again, because it saves time when you load them up -again to have memory already ready to be filled. The normal way to -free up space used by an aggregate is to assign the empty list. - -This counterintuitive behavior of C on aggregates may be -changed, fixed, or broken in a future release of Perl. - See also L, L, L. =item delete EXPR -Deletes the specified key(s) and their associated values from a hash. -For each key, returns the deleted value associated with that key, or -the undefined value if there was no such key. Deleting from C<$ENV{}> -modifies the environment. Deleting from a hash tied to a DBM file -deletes the entry from the DBM file. (But deleting from a Cd hash -doesn't necessarily return anything.) +Given an expression that specifies a hash element, array element, hash slice, +or array slice, deletes the specified element(s) from the hash or array. +If the array elements happen to be at the end of the array, the size +of the array will shrink by that number of elements. + +Returns each element so deleted or the undefined value if there was no such +element. Deleting from C<$ENV{}> modifies the environment. Deleting from +a hash tied to a DBM file deletes the entry from the DBM file. Deleting +from a Cd hash or array may not necessarily return anything. + +Deleting an array element effectively returns that position of the array +to its initial, uninitialized state. Subsequently testing for the same +element with exists() will return false. See L. -The following deletes all the values of a hash: +The following (inefficiently) deletes all the values of %HASH and @ARRAY: foreach $key (keys %HASH) { delete $HASH{$key}; } -And so does this: + foreach $index (0 .. $#ARRAY) { + delete $ARRAY[$index]; + } + +And so do these: + + delete @HASH{keys %HASH}; - delete @HASH{keys %HASH} + delete @ARRAY[0 .. $#ARRAY]; But both of these are slower than just assigning the empty list -or undefining it: +or undefining %HASH or @ARRAY: - %hash = (); # completely empty %hash - undef %hash; # forget %hash every existed + %HASH = (); # completely empty %HASH + undef %HASH; # forget %HASH ever existed + + @ARRAY = (); # completely empty @ARRAY + undef @ARRAY; # forget @ARRAY ever existed Note that the EXPR can be arbitrarily complicated as long as the final -operation is a hash element lookup or hash slice: +operation is a hash element, array element, hash slice, or array slice +lookup: delete $ref->[$x][$y]{$key}; delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys}; + delete $ref->[$x][$y][$index]; + delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices]; + =item die LIST -Outside an C, prints the value of LIST to C and exits with -the current value of C<$!> (errno). If C<$!> is C<0>, exits with the value of -C<($? EE 8)> (backtick `command` status). If C<($? EE 8)> -is C<0>, exits with C<255>. Inside an C the error message is stuffed into -C<$@> and the C is terminated with the undefined value. This makes -C the way to raise an exception. +Outside an C, prints the value of LIST to C and +exits with the current value of C<$!> (errno). If C<$!> is C<0>, +exits with the value of C<($? EE 8)> (backtick `command` +status). If C<($? EE 8)> is C<0>, exits with C<255>. Inside +an C the error message is stuffed into C<$@> and the +C is terminated with the undefined value. This makes +C the way to raise an exception. Equivalent examples: @@ -984,25 +1036,26 @@ regular expressions. Here's an example: } } -Since perl will stringify uncaught exception messages before displaying +Because perl will stringify uncaught exception messages before displaying them, you may want to overload stringification operations on such custom exception objects. See L for details about that. -You can arrange for a callback to be run just before the C does -its deed, by setting the C<$SIG{__DIE__}> hook. The associated handler -will be called with the error text and can change the error message, if -it sees fit, by calling C again. See L for details on -setting C<%SIG> entries, and L<"eval BLOCK"> for some examples. - -Note that the C<$SIG{__DIE__}> hook is currently called even inside -eval()ed blocks/strings! If one wants the hook to do nothing in such -situations, put +You can arrange for a callback to be run just before the C +does its deed, by setting the C<$SIG{__DIE__}> hook. The associated +handler will be called with the error text and can change the error +message, if it sees fit, by calling C again. See +L for details on setting C<%SIG> entries, and +L<"eval BLOCK"> for some examples. Although this feature was meant +to be run only right before your program was to exit, this is not +currently the case--the C<$SIG{__DIE__}> hook is currently called +even inside eval()ed blocks/strings! If one wants the hook to do +nothing in such situations, put die @_ if $^S; -as the first line of the handler (see L). Because this -promotes action at a distance, this counterintuitive behavior may be fixed -in a future release. +as the first line of the handler (see L). Because +this promotes strange action at a distance, this counterintuitive +behavior may be fixed in a future release. =item do BLOCK @@ -1046,7 +1099,7 @@ successfully compiled, C returns the value of the last expression evaluated. Note that inclusion of library modules is better done with the -C and C operators, which also do automatic error checking +C and C operators, which also do automatic error checking and raise an exception if there's a problem. You might like to use C to read in a program configuration @@ -1067,40 +1120,31 @@ file. Manual error checking can be done this way: =item dump -This causes an immediate core dump. Primarily this is so that you can -use the B program to turn your core dump into an executable binary -after having initialized all your variables at the beginning of the -program. When the new binary is executed it will begin by executing a -C (with all the restrictions that C suffers). Think of -it as a goto with an intervening core dump and reincarnation. If C for an illustration of how C, C, and C work. @@ -3105,20 +3468,21 @@ C work. =item ref -Returns a TRUE value if EXPR is a reference, FALSE otherwise. If EXPR +Returns a true value if EXPR is a reference, false otherwise. If EXPR is not specified, C<$_> will be used. The value returned depends on the type of thing the reference is a reference to. Builtin types include: - REF SCALAR ARRAY HASH CODE + REF GLOB + LVALUE If the referenced object has been blessed into a package, then that package -name is returned instead. You can think of C as a C operator. +name is returned instead. You can think of C as a C operator. if (ref($r) eq "HASH") { print "r is a reference to a hash.\n"; @@ -3134,7 +3498,9 @@ See also L. =item rename OLDNAME,NEWNAME -Changes the name of a file. Returns C<1> for success, C<0> otherwise. +Changes the name of a file; an existing file NEWNAME will be +clobbered. Returns true for success, false otherwise. + Behavior of this function varies wildly depending on your system implementation. For example, it will usually not work across file system boundaries, even though the system I command sometimes compensates @@ -3152,7 +3518,7 @@ supplied. If EXPR is numeric, demands that the current version of Perl Otherwise, demands that a library file be included if it hasn't already been included. The file is included via the do-FILE mechanism, which is -essentially just a variety of C. Has semantics similar to the following +essentially just a variety of C. Has semantics similar to the following subroutine: sub require { @@ -3163,23 +3529,24 @@ subroutine: foreach $prefix (@INC) { $realfilename = "$prefix/$filename"; if (-f $realfilename) { + $INC{$filename} = $realfilename; $result = do $realfilename; last ITER; } } die "Can't find $filename in \@INC"; } + delete $INC{$filename} if $@ || !$result; die $@ if $@; die "$filename did not return true value" unless $result; - $INC{$filename} = $realfilename; return $result; } Note that the file will not be included twice under the same specified -name. The file must return TRUE as the last statement to indicate +name. The file must return true as the last statement to indicate successful execution of any initialization code, so it's customary to -end such a file with "C<1;>" unless you're sure it'll return TRUE -otherwise. But it's better just to put the "C<1;>", in case you add more +end such a file with C<1;> unless you're sure it'll return true +otherwise. But it's better just to put the C<1;>, in case you add more statements. If EXPR is a bareword, the require assumes a "F<.pm>" extension and @@ -3202,7 +3569,7 @@ But if you try this: require "Foo::Bar"; # not a bareword because of the "" The require function will look for the "F" file in the @INC array and -will complain about not finding "F" there. In this case you can do: +will complain about not finding "F" there. In this case you can do: eval "require $class"; @@ -3235,10 +3602,10 @@ See L. =item return -Returns from a subroutine, C, or C with the value +Returns from a subroutine, C, or C with the value given in EXPR. Evaluation of EXPR may be in list, scalar, or void context, depending on how the return value will be used, and the context -may vary from one execution to the next (see C). If no EXPR +may vary from one execution to the next (see C). If no EXPR is given, returns an empty list in list context, the undefined value in scalar context, and (of course) nothing at all in a void context. @@ -3269,7 +3636,7 @@ on a large hash, such as from a DBM file. =item rewinddir DIRHANDLE Sets the current position to the beginning of the directory for the -C routine on DIRHANDLE. +C routine on DIRHANDLE. =item rindex STR,SUBSTR,POSITION @@ -3284,7 +3651,7 @@ last occurrence at or before that position. =item rmdir Deletes the directory specified by FILENAME if that directory is empty. If it -succeeds it returns TRUE, otherwise it returns FALSE and sets C<$!> (errno). If +succeeds it returns true, otherwise it returns false and sets C<$!> (errno). If FILENAME is omitted, uses C<$_>. =item s/// @@ -3304,7 +3671,7 @@ needed. If you really wanted to do so, however, you could use the construction C<@{[ (some expression) ]}>, but usually a simple C<(some expression)> suffices. -Wince C is unary operator, if you accidentally use for EXPR a +Because C is unary operator, if you accidentally use for EXPR a parenthesized list, this behaves as a scalar comma expression, evaluating all but the last element in void context and returning the final element evaluated in scalar context. This is seldom what you want. @@ -3322,17 +3689,19 @@ See L for more details on unary operators and the comma operator. =item seek FILEHANDLE,POSITION,WHENCE -Sets FILEHANDLE's position, just like the C call of C. +Sets FILEHANDLE's position, just like the C call of C. FILEHANDLE may be an expression whose value gives the name of the filehandle. The values for WHENCE are C<0> to set the new position to -POSITION, C<1> to set it to the current position plus POSITION, and C<2> to -set it to EOF plus POSITION (typically negative). For WHENCE you may -use the constants C, C, and C from either the -C or the POSIX module. Returns C<1> upon success, C<0> otherwise. +POSITION, C<1> to set it to the current position plus POSITION, and +C<2> to set it to EOF plus POSITION (typically negative). For WHENCE +you may use the constants C, C, and C +(start of the file, current position, end of the file) from any of the +modules Fcntl, C, or POSIX. Returns C<1> upon success, +C<0> otherwise. -If you want to position file for C or C, don't use -C -- buffering makes its effect on the file's system position -unpredictable and non-portable. Use C instead. +If you want to position file for C or C, don't use +C--buffering makes its effect on the file's system position +unpredictable and non-portable. Use C instead. Due to the rules and rigors of ANSI C, on some systems you have to do a seek whenever you switch between reading and writing. Amongst other @@ -3343,7 +3712,7 @@ A WHENCE of C<1> (C) is useful for not moving the file position: This is also useful for applications emulating C. Once you hit EOF on your read, and then sleep for a while, you might have to stick in a -seek() to reset things. The C doesn't change the current position, +seek() to reset things. The C doesn't change the current position, but it I clear the end-of-file condition on the handle, so that the next CFILEE> makes Perl try again to read something. We hope. @@ -3361,8 +3730,8 @@ you may need something more like this: =item seekdir DIRHANDLE,POS -Sets the current position for the C routine on DIRHANDLE. POS -must be a value returned by C. Has the same caveats about +Sets the current position for the C routine on DIRHANDLE. POS +must be a value returned by C. Has the same caveats about possible directory compaction as the corresponding system library routine. @@ -3372,7 +3741,7 @@ routine. Returns the currently selected filehandle. Sets the current default filehandle for output, if FILEHANDLE is supplied. This has two -effects: first, a C or a C without a filehandle will +effects: first, a C or a C without a filehandle will default to this FILEHANDLE. Second, references to variables related to output will refer to this output channel. For example, if you have to set the top of form format for more than one output channel, you might @@ -3397,7 +3766,7 @@ methods, preferring to write the last example as: =item select RBITS,WBITS,EBITS,TIMEOUT This calls the select(2) system call with the bit masks specified, which -can be constructed using C and C, along these lines: +can be constructed using C and C, along these lines: $rin = $win = $ein = ''; vec($rin,fileno(STDIN),1) = 1; @@ -3426,32 +3795,32 @@ or to block until something becomes ready just do this $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef); -Most systems do not bother to return anything useful in C<$timeleft>, so -calling select() in scalar context just returns C<$nfound>. +Most systems do not bother to return anything useful in $timeleft, so +calling select() in scalar context just returns $nfound. Any of the bit masks can also be undef. The timeout, if specified, is in seconds, which may be fractional. Note: not all implementations are -capable of returning theC<$timeleft>. If not, they always return -C<$timeleft> equal to the supplied C<$timeout>. +capable of returning the$timeleft. If not, they always return +$timeleft equal to the supplied $timeout. You can effect a sleep of 250 milliseconds this way: select(undef, undef, undef, 0.25); -B: One should not attempt to mix buffered I/O (like C -or EFHE) with C, except as permitted by POSIX, and even -then only on POSIX systems. You have to use C instead. +B: One should not attempt to mix buffered I/O (like C +or EFHE) with C above. +C interface to access setitimer(2) if your system supports +it, or else see L above. The Time::HiRes module from CPAN +may also help. -See also the POSIX module's C function. +See also the POSIX module's C function. =item socket SOCKET,DOMAIN,TYPE,PROTOCOL Opens a socket of the specified kind and attaches it to filehandle -SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for the -system call of the same name. You should "C" first to get -the proper definitions imported. See the examples in L. +SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for +the system call of the same name. You should C first +to get the proper definitions imported. See the examples in +L. =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL Creates an unnamed pair of sockets in the specified domain, of the specified type. DOMAIN, TYPE, and PROTOCOL are specified the same as for the system call of the same name. If unimplemented, yields a fatal -error. Returns TRUE if successful. +error. Returns true if successful. -Some systems defined C in terms of C, in which a call +Some systems defined C in terms of C, in which a call to C is essentially: use Socket; @@ -3632,25 +4006,29 @@ See L for an example of socketpair use. =item sort LIST Sorts the LIST and returns the sorted list value. If SUBNAME or BLOCK -is omitted, Cs in standard string comparison order. If SUBNAME is +is omitted, Cs in standard string comparison order. If SUBNAME is specified, it gives the name of a subroutine that returns an integer less than, equal to, or greater than C<0>, depending on how the elements -of the array are to be ordered. (The C=E> and C +of the list are to be ordered. (The C=E> and C operators are extremely useful in such routines.) SUBNAME may be a scalar variable name (unsubscripted), in which case the value provides the name of (or a reference to) the actual subroutine to use. In place of a SUBNAME, you can provide a BLOCK as an anonymous, in-line sort subroutine. -In the interests of efficiency the normal calling code for subroutines is -bypassed, with the following effects: the subroutine may not be a -recursive subroutine, and the two elements to be compared are passed into -the subroutine not via C<@_> but as the package global variables C<$a> and -C<$b> (see example below). They are passed by reference, so don't -modify C<$a> and C<$b>. And don't try to declare them as lexicals either. +If the subroutine's prototype is C<($$)>, the elements to be compared +are passed by reference in C<@_>, as for a normal subroutine. If not, +the normal calling code for subroutines is bypassed in the interests of +efficiency, and the elements to be compared are passed into the subroutine +as the package global variables $a and $b (see example below). Note that +in the latter case, it is usually counter-productive to declare $a and +$b as lexicals. + +In either case, the subroutine may not be recursive. The values to be +compared are always passed by reference, so don't modify them. You also cannot exit out of the sort block or subroutine using any of the -loop control operators described in L or with C. +loop control operators described in L or with C. When C is in effect, C sorts LIST according to the current collation locale. See L. @@ -3675,19 +4053,19 @@ Examples: # sort numerically descending @articles = sort {$b <=> $a} @files; + # this sorts the %age hash by value instead of key + # using an in-line function + @eldest = sort { $age{$b} <=> $age{$a} } keys %age; + # sort using explicit subroutine name sub byage { $age{$a} <=> $age{$b}; # presuming numeric } @sortedclass = sort byage @class; - # this sorts the %age hash by value instead of key - # using an in-line function - @eldest = sort { $age{$b} <=> $age{$a} } keys %age; - - sub backwards { $b cmp $a; } - @harry = ('dog','cat','x','Cain','Abel'); - @george = ('gone','chased','yz','Punished','Axed'); + sub backwards { $b cmp $a } + @harry = qw(dog cat x Cain Abel); + @george = qw(gone chased yz Punished Axed); print sort @harry; # prints AbelCaincatdogx print sort backwards @harry; @@ -3721,15 +4099,23 @@ Examples: } 0..$#old ]; - # same thing using a Schwartzian Transform (no temps) + # same thing, but without any temps @new = map { $_->[0] } - sort { $b->[1] <=> $a->[1] - || - $a->[2] cmp $b->[2] - } map { [$_, /=(\d+)/, uc($_)] } @old; - -If you're using strict, you I declare C<$a> -and C<$b> as lexicals. They are package globals. That means + sort { $b->[1] <=> $a->[1] + || + $a->[2] cmp $b->[2] + } map { [$_, /=(\d+)/, uc($_)] } @old; + + # using a prototype allows you to use any comparison subroutine + # as a sort subroutine (including other package's subroutines) + package other; + sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are not set here + + package main; + @new = sort other::backwards @old; + +If you're using strict, you I declare $a +and $b as lexicals. They are package globals. That means if you're in the C
package, it's @articles = sort {$main::b <=> $main::a} @files; @@ -3758,7 +4144,7 @@ replaces them with the elements of LIST, if any. In list context, returns the elements removed from the array. In scalar context, returns the last element removed, or C if no elements are removed. The array grows or shrinks as necessary. -If OFFSET is negative then it start that far from the end of the array. +If OFFSET is negative then it starts that far from the end of the array. If LENGTH is omitted, removes everything from OFFSET onward. If LENGTH is negative, leave that many elements off the end of the array. The following equivalences hold (assuming C<$[ == 0>): @@ -3790,7 +4176,7 @@ Example, assuming array lengths are passed before arrays: =item split -Splits a string into an array of strings, and returns it. By default, +Splits a string into a list of strings and returns that list. By default, empty leading fields are preserved, and empty trailing ones are deleted. If not in list context, returns the number of fields found and splits into @@ -3807,7 +4193,7 @@ that the delimiter may be longer than one character.) If LIMIT is specified and positive, splits into no more than that many fields (though it may split into fewer). If LIMIT is unspecified or zero, trailing null fields are stripped (which potential users -of C would do well to remember). If LIMIT is negative, it is +of C would do well to remember). If LIMIT is negative, it is treated as if an arbitrarily large LIMIT had been specified. A pattern matching the null string (not to be confused with @@ -3829,7 +4215,7 @@ unnecessary work. For the list above LIMIT would have been 4 by default. In time critical applications it behooves you not to split into more fields than you really need. -If the PATTERN contains parentheses, additional array elements are +If the PATTERN contains parentheses, additional list elements are created from each matching substring in the delimiter. split(/([,-])/, "1-10,20", 3); @@ -3838,7 +4224,7 @@ produces the list value (1, '-', 10, ',', 20) -If you had the entire header of a normal Unix email message in C<$header>, +If you had the entire header of a normal Unix email message in $header, you could split it up into fields and their values this way: $header =~ s/\n\s+/ /g; # fix continuation lines @@ -3849,11 +4235,11 @@ patterns that vary at runtime. (To do runtime compilation only once, use C.) As a special case, specifying a PATTERN of space (C<' '>) will split on -white space just as C with no arguments does. Thus, C can +white space just as C with no arguments does. Thus, C can be used to emulate B's default behavior, whereas C will give you as many null initial fields as there are leading spaces. -A C on C is like a C except that any leading -whitespace produces a null first field. A C with no arguments +A C on C is like a C except that any leading +whitespace produces a null first field. A C with no arguments really does a C internally. Example: @@ -3865,22 +4251,22 @@ Example: #... } -(Note that C<$shell> above will still have a newline on it. See L, +(Note that $shell above will still have a newline on it. See L, L, and L.) =item sprintf FORMAT, LIST -Returns a string formatted by the usual C conventions of the -C library function C. See L or L +Returns a string formatted by the usual C conventions of the +C library function C. See L or L on your system for an explanation of the general principles. -Perl does its own C formatting -- it emulates the C -function C, but it doesn't use it (except for floating-point +Perl does its own C formatting--it emulates the C +function C, but it doesn't use it (except for floating-point numbers, and even then only the standard modifiers are allowed). As a -result, any non-standard extensions in your local C are not +result, any non-standard extensions in your local C are not available from Perl. -Perl's C permits the following universally-known conversions: +Perl's C permits the following universally-known conversions: %% a percent sign %c a character with the given number @@ -3926,21 +4312,60 @@ and the conversion letter: for integer l interpret integer as C type "long" or "unsigned long" h interpret integer as C type "short" or "unsigned short" + If no flags, interpret integer as C type "int" or "unsigned" There is also one Perl-specific flag: V interpret integer as Perl's standard integer type -Where a number would appear in the flags, an asterisk ("C<*>") may be +Where a number would appear in the flags, an asterisk (C<*>) may be used instead, in which case Perl uses the next item in the parameter list as the given number (that is, as the field width or precision). -If a field width obtained through "C<*>" is negative, it has the same -effect as the "C<->" flag: left-justification. +If a field width obtained through C<*> is negative, it has the same +effect as the C<-> flag: left-justification. If C is in effect, the character used for the decimal point in formatted real numbers is affected by the LC_NUMERIC locale. See L. +If Perl understands "quads" (64-bit integers) (this requires +either that the platform natively supports quads or that Perl +has been specifically compiled to support quads), the characters + + d u o x X b i D U O + +print quads, and they may optionally be preceded by + + ll L q + +For example + + %lld %16LX %qo + +You can find out whether your Perl supports quads via L: + + use Config; + ($Config{use64bits} eq 'define' || $Config{longsize} == 8) && + print "quads\n"; + +If Perl understands "long doubles" (this requires that the platform +supports long doubles), the flags + + e f g E F G + +may optionally be preceded by + + ll L + +For example + + %llf %Lg + +You can find out whether your Perl supports long doubles via L: + + use Config; + $Config{d_longdbl} eq 'define' && print "long doubles\n"; + =item sqrt EXPR =item sqrt @@ -3956,19 +4381,19 @@ loaded the standard Math::Complex module. =item srand -Sets the random number seed for the C operator. If EXPR is +Sets the random number seed for the C operator. If EXPR is omitted, uses a semi-random value supplied by the kernel (if it supports the F device) or based on the current time and process ID, among other things. In versions of Perl prior to 5.004 the default -seed was just the current C. This isn't a particularly good seed, +seed was just the current C