X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=4043301a5ea4ca0279f213df2ed3ae6b2ee6665e;hb=202975e60ee076fd8796877b28774137051a97c4;hp=a193d672f68444fb569bc44d07a69e1b732a5833;hpb=fed34a19f844dc41c481323fae2b2e39e655b50a;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index a193d67..4043301 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 @@ -290,8 +290,8 @@ X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C> -g File has setgid bit set. -k File has sticky bit set. - -T File is a text file. - -B File is a binary file (opposite of -T). + -T File is an ASCII text file. + -B File is a "binary" file (opposite of -T). -M Age of file in days when script started. -A Same for access time. @@ -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. -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; @@ -493,12 +515,12 @@ to go back before the current one. ($package, $filename, $line, $subroutine, $hasargs, $wantarray, $evaltext, $is_require) = 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. @@ -507,16 +529,16 @@ 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 @@ -546,6 +568,9 @@ number of characters removed from all its arguments. It's often used to remove the newline from the end of an input record when you're worried that the final record may be missing its newline. When in paragraph mode (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: while (<>) { @@ -586,16 +611,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; @@ -603,9 +630,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"; @@ -617,6 +644,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 @@ -639,30 +670,35 @@ 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 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 @@ -679,7 +715,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 @@ -688,7 +724,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. @@ -703,8 +739,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) { @@ -718,7 +754,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 @@ -739,14 +775,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). @@ -771,34 +807,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 @@ -833,13 +875,13 @@ 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 +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 +of C upon aggregates (hashes and arrays) is not guaranteed to produce intuitive results, and should probably be avoided. When used on a hash element, it tells you whether the value is defined, @@ -855,7 +897,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 @@ -866,28 +908,18 @@ 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: +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" } -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 @@ -896,7 +928,7 @@ 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 +deletes the entry from the DBM file. (But deleting from a Cd hash doesn't necessarily return anything.) The following deletes all the values of a hash: @@ -923,12 +955,13 @@ operation is a hash element lookup or hash slice: =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: @@ -965,21 +998,43 @@ This is useful for propagating exceptions: If C<$@> is empty then the string C<"Died"> is used. -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. +die() can also be called with a reference argument. If this happens to be +trapped within an eval(), $@ contains the reference. This behavior permits +a more elaborate exception handling implementation using objects that +maintain arbitary state about the nature of the exception. Such a scheme +is sometimes preferable to matching particular string values of $@ using +regular expressions. Here's an example: -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 + eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) }; + if ($@) { + if (ref($@) && UNIVERSAL::isa($@,"Some::Module::Exception")) { + # handle Some::Module::Exception + } + else { + # handle all other possible exceptions + } + } + +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. 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 @@ -1023,7 +1078,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 @@ -1044,40 +1099,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