X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=c21ca0dde01021a3e50f94faf86e3caa1c382b9e;hb=28a5cf3b760f8b6322a0839e3b3e060e7a6f23ea;hp=97d0b752abca9187ce4b7efb0767a4dfe94e308f;hpb=28be1210e1847088dea44932568ceeb145a4a140;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 97d0b75..c21ca0d 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -226,7 +226,7 @@ C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, -C, C, C, C, +C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, @@ -603,6 +603,12 @@ previous time C was called. =item chdir EXPR +=item chdir FILEHANDLE + +=item chdir DIRHANDLE + +=item chdir + Changes the working directory to EXPR, if possible. If EXPR is omitted, changes to the directory specified by C<$ENV{HOME}>, if set; if not, changes to the directory specified by C<$ENV{LOGDIR}>. (Under VMS, the @@ -610,6 +616,10 @@ variable C<$ENV{SYS$LOGIN}> is also checked, and used if it is set.) If neither is set, C does nothing. It returns true upon success, false otherwise. See the example under C. +On systems that support fchdir, you might pass a file handle or +directory handle as argument. On systems that don't support fchdir, +passing handles produces a fatal error at run time. + =item chmod LIST Changes the permissions of a list of files. The first element of the @@ -625,6 +635,14 @@ successfully changed. See also L, if all you have is a string. $mode = '0644'; chmod oct($mode), 'foo'; # this is better $mode = 0644; chmod $mode, 'foo'; # this is best +On systems that support fchmod, you might pass file handles among the +files. On systems that don't support fchmod, passing file handles +produces a fatal error at run time. + + open(my $fh, "<", "foo"); + my $perm = (stat $fh)[2] & 07777; + chmod($perm | 0600, $fh); + You can also import the symbolic C constants from the Fcntl module: @@ -710,6 +728,10 @@ successfully changed. $cnt = chown $uid, $gid, 'foo', 'bar'; chown $uid, $gid, @filenames; +On systems that support fchown, you might pass file handles among the +files. On systems that don't support fchown, passing file handles +produces a fatal error at run time. + Here's an example that looks up nonnumeric uids in the passwd file: print "User: "; @@ -742,6 +764,10 @@ chr(0x263a) is a Unicode smiley face. Note that characters from 128 to 255 (inclusive) are by default not encoded in UTF-8 Unicode for backward compatibility reasons (but see L). +Negative values give the Unicode replacement character (chr(0xfffd)), +except under the L pragma, where low eight bits of the value +(truncated to an integer) are used. + If NUMBER is omitted, uses C<$_>. For the reverse, use L. @@ -782,7 +808,8 @@ 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<$?>. +implicitly puts the exit status value of that command into C<$?> and +C<${^CHILD_ERROR_NATIVE}>. 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 @@ -858,31 +885,42 @@ function, or use this relation: =item crypt PLAINTEXT,SALT -Encrypts a string exactly like the crypt(3) function in the C library -(assuming that you actually have a version there that has not been -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 L is intended to be a one-way function, much like -breaking eggs to make an omelette. There is no (known) corresponding -decrypt function (in other words, the crypt() is a one-way hash -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 L -and with more exotic implementations. In other words, do not assume -anything about the returned string itself, or how many bytes in -the encrypted string matter. +Creates a digest string exactly like the crypt(3) function in the C +library (assuming that you actually have a version there that has not +been extirpated as a potential munition). + +crypt() is a one-way hash function. The PLAINTEXT and SALT is turned +into a short string, called a digest, which is returned. The same +PLAINTEXT and SALT will always return the same string, but there is no +(known) way to get the original PLAINTEXT from the hash. Small +changes in the PLAINTEXT or SALT will result in large changes in the +digest. + +There is no decrypt function. This function isn't all that useful for +cryptography (for that, look for F modules on your nearby CPAN +mirror) and the name "crypt" is a bit of a misnomer. Instead it is +primarily used to check if two pieces of text are the same without +having to transmit or store the text itself. An example is checking +if a correct password is given. The digest of the password is stored, +not the password itself. The user types in a password which is +crypt()'d with the same salt as the stored digest. If the two digests +match the password is correct. + +When verifying an existing digest string you should use the digest as +the salt (like C). The SALT used +to create the digest is visible as part of the digest so this ensures +crypt() will hash the new string with the same salt as the digest. +This allows your code to work with the standard L and +with more exotic implementations. In other words, do not assume +anything about the returned string itself, or how many bytes in the +digest matter. Traditionally the result is a string of 13 bytes: two first bytes of the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only -the first eight bytes of the encrypted string mattered, but -alternative hashing schemes (like MD5), higher level security schemes -(like C2), and implementations on non-UNIX platforms may produce -different strings. +the first eight bytes of the digest string mattered, but alternative +hashing schemes (like MD5), higher level security schemes (like C2), +and implementations on non-UNIX platforms may produce different +strings. When choosing a new salt create a random two character string whose characters come from the set C<[./0-9A-Za-z]> (like C function is unsuitable for encrypting large quantities +The L function is unsuitable for hashing 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. +back. Look at the L module for more robust algorithms. If using crypt() on a Unicode string (which I has characters with codepoints above 255), Perl tries to make sense @@ -1145,7 +1181,7 @@ This is useful for propagating exceptions: If LIST is empty and C<$@> contains an object reference that has a C method, that method will be called with additional file and line number parameters. The return value replaces the value in -C<$@>. ie. as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >> +C<$@>. i.e. as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >> were called. If C<$@> is empty then the string C<"Died"> is used. @@ -1157,9 +1193,11 @@ maintain arbitrary 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: + use Scalar::Util 'blessed'; + eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) }; if ($@) { - if (ref($@) && UNIVERSAL::isa($@,"Some::Module::Exception")) { + if (blessed($@) && $@->isa("Some::Module::Exception")) { # handle Some::Module::Exception } else { @@ -1371,6 +1409,8 @@ there was an error. =item eval BLOCK +=item eval + In the first form, the return value of EXPR is parsed and executed as if it were a little Perl program. The value of the expression (which is itself determined within scalar context) is first parsed, and if there weren't any @@ -1619,6 +1659,8 @@ to exists() is an error. =item exit EXPR +=item exit + Evaluates EXPR and exits immediately with that value. Example: $ans = ; @@ -2142,6 +2184,8 @@ C extension. See L for details. =item gmtime EXPR +=item gmtime + Converts a time as returned by the time function to an 8-element list with the time localized for the standard Greenwich time zone. Typically used as follows: @@ -2185,6 +2229,8 @@ This scalar value is B locale dependent (see L), but is instead a Perl builtin. To get somewhat similar but locale dependent date strings, see the example in L. +See L for portability concerns. + =item goto LABEL =item goto EXPR @@ -2276,7 +2322,7 @@ integer overflow trigger a warning. Leading whitespace is not stripped, unlike oct(). To present something as hex, look into L, L, or L. -=item import +=item import LIST There is no builtin C function. It is just an ordinary method (subroutine) defined (or inherited) by modules that wish to export @@ -2312,9 +2358,9 @@ functions will serve you better than will int(). Implements the ioctl(2) function. You'll probably first have to say - require "ioctl.ph"; # probably in /usr/local/lib/perl/ioctl.ph + require "sys/ioctl.ph"; # probably in $Config{archlib}/ioctl.ph -to get the correct function definitions. If F doesn't +to get the correct function definitions. If F doesn't exist or doesn't have the correct definitions you'll have to roll your own, based on your C header files such as F<< >>. (There is a Perl script called B that comes with the Perl kit that @@ -2582,6 +2628,8 @@ try for example: Note that the C<%a> and C<%b>, the short forms of the day of the week and the month of the year, may not necessarily be three characters wide. +See L for portability concerns. + =item lock THING This function places an advisory lock on a shared variable, or referenced @@ -2687,10 +2735,13 @@ and you get list of anonymous hashes each with only 1 entry. =item mkdir FILENAME +=item mkdir + Creates the directory specified by FILENAME, with permissions specified by MASK (as modified by C). If it succeeds it returns true, otherwise it returns false and sets C<$!> (errno). -If omitted, MASK defaults to 0777. +If omitted, MASK defaults to 0777. If omitted, FILENAME defaults +to C<$_>. In general, it is better to create directories with permissive MASK, and let the user modify that with their C, than it is to supply @@ -2944,7 +2995,7 @@ to the temporary file first. You will need to seek() to do the reading. Since v5.8.0, perl has built using PerlIO by default. Unless you've -changed this (ie Configure -Uuseperlio), you can open file handles to +changed this (i.e. Configure -Uuseperlio), you can open file handles to "in memory" files held in Perl scalars via: open($fh, '>', \$variable) || .. @@ -3123,7 +3174,8 @@ be set for the newly opened file descriptor as determined by the value of $^F. See L. Closing any piped filehandle causes the parent process to wait for the -child to finish, and returns the status value in C<$?>. +child to finish, and returns the status value in C<$?> and +C<${^CHILD_ERROR_NATIVE}>. The filename passed to 2-argument (or 1-argument) form of open() will have leading and trailing whitespace deleted, and the normal @@ -3219,15 +3271,24 @@ See L and L for more about Unicode. =item our TYPE EXPR : ATTRS -An C declares the listed variables to be valid globals within -the enclosing block, file, or C. That is, it has the same -scoping rules as a "my" declaration, but does not create a local -variable. If more than one value is listed, the list must be placed -in parentheses. The C declaration has no semantic effect unless -"use strict vars" is in effect, in which case it lets you use the -declared global variable without qualifying it with a package name. -(But only within the lexical scope of the C declaration. In this -it differs from "use vars", which is package scoped.) +C associates a simple name with a package variable in the current +package for use within the current scope. When C is in +effect, C lets you use declared global variables without qualifying +them with package names, within the lexical scope of the C declaration. +In this way C differs from C, which is package scoped. + +Unlike C, which both allocates storage for a variable and associates a +a simple name with that storage for use within the current scope, C +associates a simple name with a package variable in the current package, +for use within the current scope. In other words, C has the same +scoping rules as C, but does not necessarily create a +variable. + +If more than one value is listed, the list must be placed +in parentheses. + + our $foo; + our($bar, $baz); An C declaration declares a global variable that will be visible across its entire lexical scope, even across package boundaries. The @@ -3240,11 +3301,15 @@ behavior holds: $bar = 20; package Bar; - print $bar; # prints 20 + print $bar; # prints 20, as it refers to $Foo::bar -Multiple C declarations in the same lexical scope are allowed -if they are in different packages. If they happened to be in the same -package, Perl will emit warnings if you have asked for them. +Multiple C declarations with the same name in the same lexical +scope are allowed if they are in different packages. If they happen +to be in the same package, Perl will emit warnings if you have asked +for them, just like multiple C declarations. Unlike a second +C declaration, which will bind the name to a fresh variable, a +second C declaration in the same package, in the same scope, is +merely redundant. use warnings; package Foo; @@ -3255,7 +3320,8 @@ package, Perl will emit warnings if you have asked for them. our $bar = 30; # declares $Bar::bar for rest of lexical scope print $bar; # prints 30 - our $bar; # emits warning + our $bar; # emits warning but has no other effect + print $bar; # still prints 30 An C declaration may also have a list of attributes associated with it. @@ -3358,10 +3424,10 @@ of values, as follows: U A Unicode character number. Encodes to UTF-8 internally (or UTF-EBCDIC in EBCDIC platforms). - w A BER compressed integer. Its bytes represent an unsigned - integer in base 128, most significant digit first, with as - few digits as possible. Bit eight (the high bit) is set - on each byte except the last. + w A BER compressed integer (not an ASN.1 BER, see perlpacktut for + details). Its bytes represent an unsigned integer in base 128, + most significant digit first, with as few digits as possible. Bit + eight (the high bit) is set on each byte except the last. x A null byte. X Back up a byte. @@ -3650,7 +3716,7 @@ binary representation (e.g. IEEE floating point format). Even if all platforms are using IEEE, there may be subtle differences. Being able to use C> or C> on floating point values can be very useful, but also very dangerous if you don't know exactly what you're doing. -It is definetely not a general way to portably store floating point +It is definitely not a general way to portably store floating point values. When using C> or C> on an C<()>-group, this will affect @@ -3910,8 +3976,9 @@ the corresponding right parenthesis to terminate the arguments to the print--interpose a C<+> or put parentheses around all the arguments. -Note that if you're storing FILEHANDLES in an array or other expression, -you will have to use a block returning its value instead: +Note that if you're storing FILEHANDLEs in an array, or if you're using +any other expression more complex than a scalar variable to retrieve it, +you will have to use a block returning the filehandle value instead: print { $files[$i] } "stuff\n"; print { $OK ? STDOUT : STDERR } "stuff\n"; @@ -4186,9 +4253,6 @@ name is returned instead. You can think of C as a C operator. unless (ref($r)) { print "r is not a reference at all.\n"; } - if (UNIVERSAL::isa($r, "HASH")) { # for subclassing - print "r is a reference to something that isa hash.\n"; - } See also L. @@ -4300,7 +4364,7 @@ a bareword argument, there is a little extra functionality going on behind the scenes. Before C looks for a "F<.pm>" extension, it will first look for a filename with a "F<.pmc>" extension. A file with this extension is assumed to be Perl bytecode generated by -L. If this file is found, and it's modification +L. If this file is found, and its modification time is newer than a coinciding "F<.pm>" non-compiled file, it will be loaded in place of that non-compiled file ending in a "F<.pm>" extension. @@ -4603,6 +4667,14 @@ Note that whether C. +On error, C, except as permitted by POSIX, and even then only on POSIX systems. You have to use C instead. @@ -4695,9 +4767,9 @@ Shifts the first value of the array off and returns it, shortening the array by 1 and moving everything down. If there are no elements in the array, returns the undefined value. If ARRAY is omitted, shifts the C<@_> array within the lexical scope of subroutines and formats, and the -C<@ARGV> array at file scopes or within the lexical scopes established by -the C, C, C, C, and C -constructs. +C<@ARGV> array outside of a subroutine and also within the lexical scopes +established by the C, C, C, C +and C constructs. See also C, C, and C. C and C do the same thing to the left end of an array that C and C do to the @@ -5066,14 +5138,19 @@ characters at each point it matches that way. For example: produces the output 'h:i:t:h:e:r:e'. -Using the empty pattern C specifically matches the null string, and is -not be confused with the use of C to mean "the last successful pattern -match". +As a special case for C, using the empty pattern C specifically +matches only the null string, and is not be confused with the regular use +of C to mean "the last successful pattern match". So, for C, +the following: -Empty leading (or trailing) fields are produced when there are positive width -matches at the beginning (or end) of the string; a zero-width match at the -beginning (or end) of the string does not produce an empty field. For -example: + print join(':', split(//, 'hi there')); + +produces the output 'h:i: :t:h:e:r:e'. + +Empty leading (or trailing) fields are produced when there are positive +width matches at the beginning (or end) of the string; a zero-width match +at the beginning (or end) of the string does not produce an empty field. +For example: print join(':', split(/(?=\w)/, 'hi there!')); @@ -5959,8 +6036,8 @@ C<$?> like this: printf "child exited with value %d\n", $? >> 8; } -or more portably by using the W*() calls of the POSIX extension; -see L for more information. +Alternatively you might inspect the value of C<${^CHILD_ERROR_NATIVE}> +with the W*() calls of the POSIX extension. When the arguments get executed via the system shell, results and return codes will be subject to its quirks and capabilities. @@ -6745,7 +6822,8 @@ example should print the following table: Behaves like the wait(2) system call on your system: it waits for a child process to terminate and returns the pid of the deceased process, or -C<-1> if there are no child processes. The status is returned in C<$?>. +C<-1> if there are no child processes. The status is returned in C<$?> +and C<{^CHILD_ERROR_NATIVE}>. Note that a return value of C<-1> could mean that child processes are being automatically reaped, as described in L. @@ -6754,7 +6832,7 @@ being automatically reaped, as described in L. Waits for a particular child process to terminate and returns the pid of the deceased process, or C<-1> if there is no such child process. On some systems, a value of 0 indicates that there are processes still running. -The status is returned in C<$?>. If you say +The status is returned in C<$?> and C<{^CHILD_ERROR_NATIVE}>. If you say use POSIX ":sys_wait_h"; #...