X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=3fd00325975f956309d5d180684717888baebc6e;hb=cf2649810f00335bd657355d81bcc9384a620135;hp=f2e2b97e5d2b2ba55ace3839eb7ae431e9f4f444;hpb=8a2e08044eac72c17425ec10bbb958834013a72b;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index f2e2b97..3fd0032 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -25,7 +25,7 @@ with LIST as an argument. Such a list may consist of any combination of scalar arguments or list values; the list values will be included in the list as if each individual element were interpolated at that point in the list, forming a longer single-dimensional list value. -Elements of the LIST should be separated by commas. +Commas should separate elements of the LIST. Any function in the list below may be used either with or without parentheses around its arguments. (The syntax descriptions omit the @@ -139,7 +139,7 @@ C, C, C, C, C, C, C, C, C, C, C, C, C, C, C -=item Keywords related to the control flow of your perl program +=item Keywords related to the control flow of your Perl program C, C, C, C, C, C, C, C, C, C, C, C, C, C @@ -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, @@ -337,7 +337,7 @@ following a minus are interpreted as file tests. The C<-T> and C<-B> switches work as follows. The first block or so of the file is examined for odd characters such as strange control codes or characters with the high bit set. If too many strange characters (>30%) -are found, it's a C<-B> file, otherwise it's a C<-T> file. Also, any file +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 IO buffer is examined rather than the first block. Both C<-T> and C<-B> return true on a null @@ -351,7 +351,7 @@ 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 that lstat() and C<-l> will leave values in the stat structure for the symbolic link, not the real file.) (Also, if the stat buffer was filled by -a C call, C<-T> and C<-B> will reset it with the results of C). +an C call, C<-T> and C<-B> will reset it with the results of C). Example: print "Can do.\n" if -r $a || -w _ || -x _; @@ -366,6 +366,12 @@ Example: print "Text\n" if -T _; print "Binary\n" if -B _; +As of Perl 5.9.1, as a form of purely syntactic sugar, you can stack file +test operators, in a way that C<-f -w -x $file> is equivalent to +C<-x $file && -w _ && -f _>. (This is only syntax fancy: if you use +the return value of C<-f $file> as an argument to another filetest +operator, no special magic will happen.) + =item abs VALUE =item abs @@ -388,7 +394,7 @@ value of $^F. See L. =item alarm Arranges to have a SIGALRM delivered to this process after the -specified number of wallclock seconds have elapsed. If SECONDS is not +specified number of wallclock seconds has elapsed. If SECONDS is not specified, the value stored in C<$_> is used. (On some machines, unfortunately, the elapsed time may be up to one second less or more than you specified because of how seconds are counted, and process @@ -541,13 +547,13 @@ 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, 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 -(and blessings) of objects. +version if a derived class might inherit the function doing the blessing. +See L and L for more about the blessing (and blessings) +of objects. Consider always blessing objects in CLASSNAMEs that are mixed case. Namespaces with all lowercase names are considered reserved for -Perl pragmata. Builtin types have all uppercase names, so to prevent +Perl pragmata. Builtin types have all uppercase names. To prevent confusion, you may wish to avoid such package names as well. Make sure that CLASSNAME is a true value. @@ -597,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 @@ -604,11 +616,15 @@ 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 list must be the numerical mode, which should probably be an octal -number, and which definitely should I a string of octal digits: +number, and which definitely should I be a string of octal digits: C<0644> is okay, C<'0644'> is not. Returns the number of files successfully changed. See also L, if all you have is a string. @@ -619,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: @@ -661,6 +685,10 @@ You can actually chomp anything that's an lvalue, including an assignment: If you chomp a list, each element is chomped, and the total number of characters removed is returned. +If the C pragma is in scope then the lengths returned are +calculated from the length of C<$/> in Unicode characters, which is not +always the same as the length of C<$/> in the native encoding. + Note that parentheses are necessary when you're chomping anything that is not a simple variable. This is because C is interpreted as C<(chomp $cwd) = `pwd`;>, rather than as @@ -700,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: "; @@ -732,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. @@ -766,13 +802,14 @@ 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 +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 @@ -807,8 +844,8 @@ L. =item continue BLOCK -Actually a flow control statement rather than a function. If there is a -C BLOCK attached to a BLOCK (typically in a C or +C is actually a flow control statement rather than a function. If +there is a C BLOCK attached to a BLOCK (typically in a C or C), it is always executed just before the conditional is about to be evaluated again, just like the third part of a C loop in C. Thus it can be used to increment a loop variable, even when the loop has been @@ -848,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 munitions). + +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 that 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. 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 accepts. Here's an example that makes sure that whoever runs this program knows -their own password: +their password: $pwd = (getpwuid($<))[1]; @@ -901,11 +949,9 @@ 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 +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 @@ -1015,7 +1061,7 @@ defined values. For example, if you say "ab" =~ /a(.*)b/; The pattern match succeeds, and C<$1> is defined, despite the fact that it -matched "nothing". But it didn't really match nothing--rather, it +matched "nothing". It didn't really fail to match anything. 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 @@ -1033,16 +1079,26 @@ In the case of an array, if the array elements happen to be at the end, the size of the array will shrink to the highest element that tests true for exists() (or 0 if no such element exists). -Returns each element so deleted or the undefined value if there was no such -element. Deleting from C<$ENV{}> modifies the environment. Deleting from +Returns a list with the same number of elements as the number of elements +for which deletion was attempted. Each element of that list consists of +either the value of the element deleted, or the undefined value. In scalar +context, this means that you get the value of the last element deleted (or +the undefined value if that element did not exist). + + %hash = (foo => 11, bar => 22, baz => 33); + $scalar = delete $hash{foo}; # $scalar is 11 + $scalar = delete @hash{qw(foo bar)}; # $scalar is 22 + @array = delete @hash{qw(foo bar baz)}; # @array is (undef,undef,33) + +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. Note that deleting array -elements in the middle of an array will not shift the index of the ones -after them down--use splice() for that. See L. +element with exists() will return false. Also, deleting array elements +in the middle of an array will not shift the index of the elements +after them down. Use splice() for that. See L. The following (inefficiently) deletes all the values of %HASH and @ARRAY: @@ -1125,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. @@ -1137,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 { @@ -1156,7 +1214,7 @@ 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 +L<"eval BLOCK"> for some examples. Although this feature was 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 @@ -1181,13 +1239,12 @@ See L for alternative strategies. =item do SUBROUTINE(LIST) -A deprecated form of subroutine call. See L. +This form of subroutine call is deprecated. See L. =item do EXPR Uses the value of EXPR as a filename and executes the contents of the -file as a Perl script. Its primary use is to include subroutines -from a Perl subroutine library. +file as a Perl script. do 'stat.pl'; @@ -1196,7 +1253,7 @@ is just like eval `cat stat.pl`; except that it's more efficient and concise, keeps track of the current -filename for error messages, searches the @INC libraries, and updates +filename for error messages, searches the @INC directories, and updates C<%INC> if the file is found. See L for these variables. It also differs in that code evaluated with C cannot see lexicals in the enclosing scope; C does. It's the @@ -1352,17 +1409,19 @@ 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 errors, executed in the lexical context of the current Perl program, so that any variable settings or subroutine and format definitions remain -afterwards. Note that the value is parsed every time the eval executes. +afterwards. Note that the value is parsed every time the C executes. If EXPR is omitted, evaluates C<$_>. This form is typically used to delay parsing and subsequent execution of the text of EXPR until run time. In the second form, the code within the BLOCK is parsed only once--at the -same time the code surrounding the eval itself was parsed--and executed +same time the code surrounding the C itself was parsed--and executed within the context of the current Perl program. This form is typically used to trap exceptions more efficiently than the first (see below), while also providing the benefit of checking the code within BLOCK at compile @@ -1374,8 +1433,9 @@ the BLOCK. In both forms, the value returned is the value of the last expression evaluated inside the mini-program; a return statement may be also used, just as with subroutines. The expression providing the return value is evaluated -in void, scalar, or list context, depending on the context of the eval itself. -See L for more on how the evaluation context can be determined. +in void, scalar, or list context, depending on the context of the C +itself. See L for more on how the evaluation context can be +determined. If there is a syntax error or runtime error, or a C statement is executed, an undefined value is returned by C, and C<$@> is set to the @@ -1408,9 +1468,9 @@ Examples: # a run-time error eval '$answer ='; # sets $@ -Due to the current arguably broken state of C<__DIE__> hooks, when using -the C form as an exception trap in libraries, you may wish not -to trigger any C<__DIE__> hooks that user code may have installed. +Using the C form as an exception trap in libraries does have some +issues. Due to the current arguably broken state of C<__DIE__> hooks, you +may wish not to trigger any C<__DIE__> hooks that user code may have installed. You can use the C construct for this purpose, as shown in this example: @@ -1600,6 +1660,8 @@ to exists() is an error. =item exit EXPR +=item exit + Evaluates EXPR and exits immediately with that value. Example: $ans = ; @@ -1654,6 +1716,18 @@ Note that C will produce a fatal error if used on a machine that doesn't implement fcntl(2). See the Fcntl module or your fcntl(2) manpage to learn what functions are available on your system. +Here's an example of setting a filehandle named C to be +non-blocking at the system level. You'll have to negotiate C<$|> +on your own, though. + + use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK); + + $flags = fcntl(REMOTE, F_GETFL, 0) + or die "Can't get flags for the socket: $!\n"; + + $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK) + or die "Can't set flags for the socket: $!\n"; + =item fileno FILEHANDLE Returns the file descriptor for a filehandle, or undefined if the @@ -1684,8 +1758,8 @@ only entire files, not records. Two potentially non-obvious but traditional C semantics are that it waits indefinitely until the lock is granted, and that its locks B. Such discretionary locks are more flexible, but offer -fewer guarantees. This means that files locked with C may be -modified by programs that do not also use C. See L, +fewer guarantees. This means that programs that do not also use C +may modify files locked with C. See L, your port's specific documentation, or your system-specific local manpages for details. It's best to assume traditional behavior if you're writing portable programs. (But if you're not, you should as always feel perfectly @@ -1802,8 +1876,8 @@ too. It formats (see L) a list of values according to the contents of PICTURE, placing the output into the format output accumulator, C<$^A> (or C<$ACCUMULATOR> in English). Eventually, when a C is done, the contents of -C<$^A> are written to some filehandle, but you could also read C<$^A> -yourself and then set C<$^A> back to C<"">. Note that a format typically +C<$^A> are written to some filehandle. You could also read C<$^A> +and then set C<$^A> back to C<"">. Note that a format typically does one C per line of form, but the C function itself doesn't care how many newlines are embedded in the PICTURE. This means that the C<~> and C<~~> tokens will treat the entire PICTURE as a single line. @@ -1852,7 +1926,7 @@ L. =item getlogin -Implements the C library function of the same name, which on most +This implements the C library function of the same name, which on most systems returns the current login from F, if any. If null, use C. @@ -2009,8 +2083,8 @@ C, C, and C. Shadow password files are only supported if your vendor has implemented them in the intuitive fashion that calling the regular C library routines gets the shadow versions if you're running under privilege or if there exists -the shadow(3) functions as found in System V ( this includes Solaris -and Linux.) Those systems which implement a proprietary shadow password +the shadow(3) functions as found in System V (this includes Solaris +and Linux.) Those systems that implement a proprietary shadow password facility are unlikely to be supported. The $members value returned by I is a space separated list of @@ -2023,7 +2097,7 @@ addresses returned by the corresponding system library call. In the Internet domain, each address is four bytes long and you can unpack it by saying something like: - ($a,$b,$c,$d) = unpack('C4',$addr[0]); + ($a,$b,$c,$d) = unpack('W4',$addr[0]); The Socket library makes this slightly easier: @@ -2065,7 +2139,34 @@ IPs that the connection might have come in on. =item getsockopt SOCKET,LEVEL,OPTNAME -Returns the socket option requested, or undef if there is an error. +Queries the option named OPTNAME associated with SOCKET at a given LEVEL. +Options may exist at multiple protocol levels depending on the socket +type, but at least the uppermost socket level SOL_SOCKET (defined in the +C module) will exist. To query options at another level the +protocol number of the appropriate protocol controlling the option +should be supplied. For example, to indicate that an option is to be +interpreted by the TCP protocol, LEVEL should be set to the protocol +number of TCP, which you can get using getprotobyname. + +The call returns a packed string representing the requested socket option, +or C if there is an error (the error reason will be in $!). What +exactly is in the packed string depends in the LEVEL and OPTNAME, consult +your system documentation for details. A very common case however is that +the option is an integer, in which case the result will be a packed +integer which you can decode using unpack with the C (or C) format. + +An example testing if Nagle's algorithm is turned on on a socket: + + use Socket qw(:all); + + defined(my $tcp = getprotobyname("tcp")) + or die "Could not determine the protocol number for tcp"; + # my $tcp = IPPROTO_TCP; # Alternative + my $packed = getsockopt($socket, $tcp, TCP_NODELAY) + or die "Could not query TCP_NODELAY socket option: $!"; + my $nodelay = unpack("I", $packed); + print "Nagle's algorithm is turned ", $nodelay ? "off\n" : "on\n"; + =item glob EXPR @@ -2084,6 +2185,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: @@ -2102,7 +2205,7 @@ is, $year is C<123> in year 2023. $wday is the day of the week, with the year, in the range C<0..364> (or C<0..365> in leap years.) Note that the $year element is I simply the last two digits of -the year. If you assume it is, then you create non-Y2K-compliant +the year. If you assume it is then you create non-Y2K-compliant programs--and you wouldn't want to do that, would you? The proper way to get a complete 4-digit year is simply: @@ -2119,22 +2222,15 @@ In scalar context, C returns the ctime(3) value: $now_string = gmtime; # e.g., "Thu Oct 13 04:54:34 1994" -Also see the C function provided by the C module, -and the strftime(3) function available via the POSIX module. +If you need local time instead of GMT use the L builtin. +See also the C function provided by the C module, +and the strftime(3) and mktime(3) functions available via the L module. -This scalar value is B locale dependent (see L), but -is instead a Perl builtin. Also see the C module, and the -strftime(3) and mktime(3) functions available via the POSIX module. To -get somewhat similar but locale dependent date strings, set up your -locale environment variables appropriately (please see L) -and try for example: +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. - use POSIX qw(strftime); - $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime; - -Note that the C<%a> and C<%b> escapes, which represent the short forms -of the day of the week and the month of the year, may not necessarily -be three characters wide in all locales. +See L for portability concerns. =item goto LABEL @@ -2174,7 +2270,7 @@ After the C, not even C will be able to tell that this routine was called first. NAME needn't be the name of a subroutine; it can be a scalar variable -containing a code reference, or a block which evaluates to a code +containing a code reference, or a block that evaluates to a code reference. =item grep BLOCK LIST @@ -2204,6 +2300,11 @@ element of a list returned by grep (for example, in a C, C or another C) actually modifies the element in the original list. This is usually something to be avoided when writing clear code. +If C<$_> is lexical in the scope where the C appears (because it has +been declared with C) then, in addition to being locally aliased to +the list elements, C<$_> keeps being lexical inside the block; i.e. it +can't be seen from the outside, avoiding any potential side-effects. + See also L for a list composed of the results of the BLOCK or EXPR. =item hex EXPR @@ -2211,7 +2312,7 @@ See also L for a list composed of the results of the BLOCK or EXPR. =item hex Interprets EXPR as a hex string and returns the corresponding value. -(To convert strings that might start with either 0, 0x, or 0b, see +(To convert strings that might start with either C<0>, C<0x>, or C<0b>, see L.) If EXPR is omitted, uses C<$_>. print hex '0xAf'; # prints '175' @@ -2219,9 +2320,10 @@ L.) If EXPR is omitted, uses C<$_>. Hex strings may only represent integers. Strings that would cause integer overflow trigger a warning. Leading whitespace is not stripped, -unlike oct(). +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 @@ -2238,7 +2340,7 @@ It returns the position of the first occurrence of SUBSTR in STR at or after POSITION. If POSITION is omitted, starts searching from the beginning of the string. The return value is based at C<0> (or whatever you've set the C<$[> variable to--but don't do that). If the substring -is not found, returns one less than the base, ordinarily C<-1>. +is not found, C returns one less than the base, ordinarily C<-1>. =item int EXPR @@ -2257,9 +2359,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 @@ -2286,21 +2388,9 @@ system: $retval = ioctl(...) || -1; printf "System returned %d\n", $retval; -The special string "C<0> but true" is exempt from B<-w> complaints +The special string C<"0 but true"> is exempt from B<-w> complaints about improper numeric conversions. -Here's an example of setting a filehandle named C to be -non-blocking at the system level. You'll have to negotiate C<$|> -on your own, though. - - use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK); - - $flags = fcntl(REMOTE, F_GETFL, 0) - or die "Can't get flags for the socket: $!\n"; - - $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK) - or die "Can't set flags for the socket: $!\n"; - =item join EXPR,LIST Joins the separate strings of LIST into a single string with fields @@ -2324,8 +2414,9 @@ Perl 5.8.1 the ordering is different even between different runs of Perl for security reasons (see L). -As a side effect, calling keys() resets the HASH's internal iterator, -see L. +As a side effect, calling keys() resets the HASH's internal iterator +(see L). In particular, calling keys() in void context resets +the iterator with no other overhead. Here is yet another way to print your environment: @@ -2475,36 +2566,44 @@ for details, including issues with tied arrays and hashes. =item localtime EXPR +=item localtime + Converts a time as returned by the time function to a 9-element list with the time analyzed for the local time zone. Typically used as follows: # 0 1 2 3 4 5 6 7 8 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = - localtime(time); + localtime(time); All list elements are numeric, and come straight out of the C `struct -tm'. $sec, $min, and $hour are the seconds, minutes, and hours of the -specified time. $mday is the day of the month, and $mon is the month -itself, in the range C<0..11> with 0 indicating January and 11 -indicating December. $year is the number of years since 1900. That -is, $year is C<123> in year 2023. $wday is the day of the week, with -0 indicating Sunday and 3 indicating Wednesday. $yday is the day of -the year, in the range C<0..364> (or C<0..365> in leap years.) $isdst -is true if the specified time occurs during daylight savings time, -false otherwise. +tm'. C<$sec>, C<$min>, and C<$hour> are the seconds, minutes, and hours +of the specified time. -Note that the $year element is I simply the last two digits of -the year. If you assume it is, then you create non-Y2K-compliant -programs--and you wouldn't want to do that, would you? +C<$mday> is the day of the month, and C<$mon> is the month itself, in +the range C<0..11> with 0 indicating January and 11 indicating December. +This makes it easy to get a month name from a list: -The proper way to get a complete 4-digit year is simply: + my @abbr = qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ); + print "$abbr[$mon] $mday"; + # $mon=9, $mday=18 gives "Oct 18" - $year += 1900; +C<$year> is the number of years since 1900, not just the last two digits +of the year. That is, C<$year> is C<123> in year 2023. The proper way +to get a complete 4-digit year is simply: -And to get the last two digits of the year (e.g., '01' in 2001) do: + $year += 1900; - $year = sprintf("%02d", $year % 100); +To get the last two digits of the year (e.g., '01' in 2001) do: + + $year = sprintf("%02d", $year % 100); + +C<$wday> is the day of the week, with 0 indicating Sunday and 3 indicating +Wednesday. C<$yday> is the day of the year, in the range C<0..364> +(or C<0..365> in leap years.) + +C<$isdst> is true if the specified time occurs during Daylight Saving +Time, false otherwise. If EXPR is omitted, C uses the current time (C). @@ -2512,21 +2611,26 @@ In scalar context, C returns the ctime(3) value: $now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994" -This scalar value is B locale dependent, see L, but -instead a Perl builtin. Also see the C module -(to convert the second, minutes, hours, ... back to seconds since the -stroke of midnight the 1st of January 1970, the value returned by -time()), and the strftime(3) and mktime(3) functions available via the -POSIX module. To get somewhat similar but locale dependent date -strings, set up your locale environment variables appropriately -(please see L) and try for example: +This scalar value is B locale dependent but is a Perl builtin. For GMT +instead of local time use the L builtin. See also the +C module (to convert the second, minutes, hours, ... back to +the integer value returned by time()), and the L module's strftime(3) +and mktime(3) functions. + +To get somewhat similar but locale dependent date strings, set up your +locale environment variables appropriately (please see L) and +try for example: use POSIX qw(strftime); $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime; + # or for GMT formatted appropriately for your locale: + $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime; 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 @@ -2600,6 +2704,11 @@ Using a regular C loop for this purpose would be clearer in most cases. See also L for an array composed of those items of the original list for which the BLOCK or EXPR evaluates to true. +If C<$_> is lexical in the scope where the C appears (because it has +been declared with C) then, in addition to being locally aliased to +the list elements, C<$_> keeps being lexical inside the block; i.e. it +can't be seen from the outside, avoiding any potential side-effects. + C<{> starts both hash references and blocks, so C could be either the start of map BLOCK LIST or map EXPR, LIST. Because perl doesn't look ahead for the closing C<}> it has to take a guess at which its dealing with @@ -2627,10 +2736,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 @@ -2651,7 +2763,7 @@ Calls the System V IPC function msgctl(2). You'll probably have to say use IPC::SysV; first to get the correct constant definitions. If CMD is C, -then ARG must be a variable which will hold the returned C +then ARG must be a variable that will hold the returned C structure. Returns like C: the undefined value for error, C<"0 but true"> for zero, or the actual return value otherwise. See also L, C, and C documentation. @@ -2873,7 +2985,7 @@ modules that can help with that problem)) you should always check the return value from opening a file. The infrequent exception is when working with an unopened filehandle is actually what you want to do. -As a special case the 3 arg form with a read/write mode and the third +As a special case the 3-arg form with a read/write mode and the third argument being C: open(TMP, "+>", undef) or die ... @@ -2883,7 +2995,9 @@ works for symmetry, but you really should consider writing something to the temporary file first. You will need to seek() to do the reading. -File handles can be opened to "in memory" files held in Perl scalars via: +Since v5.8.0, perl has built using PerlIO by default. Unless you've +changed this (i.e. Configure -Uuseperlio), you can open file handles to +"in memory" files held in Perl scalars via: open($fh, '>', \$variable) || .. @@ -2914,7 +3028,7 @@ Examples: open(ARTICLE, "caesar <$article |") # ditto or die "Can't start caesar: $!"; - open(EXTRACT, "|sort >/tmp/Tmp$$") # $$ is our process id + open(EXTRACT, "|sort >Tmp$$") # $$ is our process id or die "Can't start sort: $!"; # in memory files @@ -2946,6 +3060,8 @@ Examples: } } +See L for detailed info on PerlIO. + You may also, in the Bourne shell tradition, specify an EXPR beginning with C<< '>&' >>, in which case the rest of the string is interpreted as the name of a filehandle (or file descriptor, if numeric) to be @@ -2953,7 +3069,7 @@ duped (as L) and opened. You may use C<&> after C<< > >>, C<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>. The mode you specify should match the mode of the original filehandle. (Duping a filehandle does not take into account any existing contents -of IO buffers.) If you use the 3 arg form then you can pass either a +of IO buffers.) If you use the 3-arg form then you can pass either a number, the name of a filehandle or the normal "reference to a glob". Here is a script that saves, redirects, and restores C and @@ -2972,9 +3088,6 @@ C using various methods: print STDOUT "stdout 1\n"; # this works for print STDERR "stderr 1\n"; # subprocesses too - close STDOUT; - close STDERR; - open STDOUT, ">&", $oldout or die "Can't dup \$oldout: $!"; open STDERR, ">&OLDERR" or die "Can't dup OLDERR: $!"; @@ -3062,7 +3175,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 @@ -3158,15 +3272,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 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 @@ -3179,11 +3302,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; @@ -3194,7 +3321,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. @@ -3225,13 +3353,19 @@ fork() emulation on Windows platforms, or by embedding perl in a multi-threaded application. The C attribute does nothing in all other environments. +Warning: the current implementation of this attribute operates on the +typeglob associated with the variable; this means that C +also has the effect of C. This may be +subject to change. + =item pack TEMPLATE,LIST Takes a LIST of values and converts it into a string using the rules given by the TEMPLATE. The resulting string is the concatenation of the converted values. Typically, each converted value looks like its machine-level representation. For example, on 32-bit machines -a converted integer may be represented by a sequence of 4 bytes. +an integer may be represented by a sequence of 4 bytes that will be +converted to a sequence of 4 characters. The TEMPLATE is a sequence of characters that give the order and type of values, as follows: @@ -3245,34 +3379,16 @@ of values, as follows: h A hex string (low nybble first). H A hex string (high nybble first). - c A signed char value. - C An unsigned char value. Only does bytes. See U for Unicode. + c A signed char (8-bit) value. + C An unsigned C char (octet) even under Unicode. Should normally not + be used. See U and W instead. + W An unsigned char value (can be greater than 255). - s A signed short value. + s A signed short (16-bit) value. S An unsigned short value. - (This 'short' is _exactly_ 16 bits, which may differ from - what a local C compiler calls 'short'. If you want - native-length shorts, use the '!' suffix.) - - i A signed integer value. - I An unsigned integer value. - (This 'integer' is _at_least_ 32 bits wide. Its exact - size depends on what a local C compiler calls 'int', - and may even be larger than the 'long' described in - the next item.) - l A signed long value. + l A signed long (32-bit) value. L An unsigned long value. - (This 'long' is _exactly_ 32 bits, which may differ from - what a local C compiler calls 'long'. If you want - native-length longs, use the '!' suffix.) - - n An unsigned short in "network" (big-endian) order. - N An unsigned long in "network" (big-endian) order. - v An unsigned short in "VAX" (little-endian) order. - V An unsigned long in "VAX" (little-endian) order. - (These 'shorts' and 'longs' are _exactly_ 16 bits and - _exactly_ 32 bits, respectively.) q A signed quad (64-bit) value. Q An unsigned quad value. @@ -3280,14 +3396,23 @@ of values, as follows: integer values _and_ if Perl has been compiled to support those. Causes a fatal error otherwise.) - j A signed integer value (a Perl internal integer, IV). - J An unsigned integer value (a Perl internal unsigned integer, UV). + i A signed integer value. + I A unsigned integer value. + (This 'integer' is _at_least_ 32 bits wide. Its exact + size depends on what a local C compiler calls 'int'.) + + n An unsigned short (16-bit) in "network" (big-endian) order. + N An unsigned long (32-bit) in "network" (big-endian) order. + v An unsigned short (16-bit) in "VAX" (little-endian) order. + V An unsigned long (32-bit) in "VAX" (little-endian) order. + + j A Perl internal signed integer value (IV). + J A Perl internal unsigned integer value (UV). f A single-precision float in the native format. d A double-precision float in the native format. - F A floating point value in the native native format - (a Perl internal floating point value, NV). + F A Perl internal floating point value (NV) in the native format D A long double-precision float in the native format. (Long doubles are available only if your system supports long double values _and_ if Perl has been compiled to support those. @@ -3300,17 +3425,43 @@ 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. - @ Null fill to absolute position, counted from the start of - the innermost ()-group. + @ Null fill or truncate to absolute position, counted from the + start of the innermost ()-group. + . Null fill or truncate to absolute position specified by value. ( Start of a ()-group. +One or more of the modifiers below may optionally follow some letters in the +TEMPLATE (the second column lists the letters for which the modifier is +valid): + + ! sSlLiI Forces native (short, long, int) sizes instead + of fixed (16-/32-bit) sizes. + + xX Make x and X act as alignment commands. + + nNvV Treat integers as signed instead of unsigned. + + @. Specify position as byte offset in the internal + representation of the packed string. Efficient but + dangerous. + + > sSiIlLqQ Force big-endian byte-order on the type. + jJfFdDpP (The "big end" touches the construct.) + + < sSiIlLqQ Force little-endian byte-order on the type. + jJfFdDpP (The "little end" touches the construct.) + +The C> and C> modifiers can also be used on C<()>-groups, +in which case they force a certain byte-order on all components of +that group, including subgroups. + The following rules apply: =over 8 @@ -3319,12 +3470,13 @@ The following rules apply: Each letter may optionally be followed by a number giving a repeat count. With all types except C, C, C, C, C, C, -C, C<@>, C, C and C

the pack function will gobble up that -many values from the LIST. A C<*> for the repeat count means to use -however many items are left, except for C<@>, C, C, where it is -equivalent to C<0>, and C, where it is equivalent to 1 (or 45, what -is the same). A numeric repeat count may optionally be enclosed in -brackets, as in C. +C, C<@>, C<.>, C, C and C

type packs a pointer to a structure of the size indicated by the length. A NULL pointer is created if the corresponding value for C

or C

is C, similarly for unpack(). +If your system has a strange pointer size (i.e. a pointer is neither as +big as an int nor as big as a long), it may not be possible to pack or +unpack pointers in big- or little-endian byte order. Attempting to do +so will result in a fatal error. + =item * -The C template character allows packing and unpacking of strings where -the packed structure contains a byte count followed by the string itself. -You write ICI. +The C template character allows packing and unpacking of a sequence of +items where the packed structure contains a packed item count followed by +the packed items themselves. +You write ICI. The I can be any C template letter, and describes how the length value is packed. The ones likely to be of most use are integer-packing ones like C (for Java strings), C (for ASN.1 or SNMP) and C (for Sun XDR). -For C, the I must, at present, be C<"A*">, C<"a*"> or -C<"Z*">. For C the length of the string is obtained from the -I, but if you put in the '*' it will be ignored. For all other -codes, C applies the length value to the next item, which must not -have a repeat count. +For C, the I may have a repeat count, in which case +the minimum of that and the number of available items is used as argument +for the I. If it has no repeat count or uses a '*', the number +of available items is used. For C the repeat count is always obtained +by decoding the packed item count, and the I must not have a +repeat count. + +If the I refers to a string type (C<"A">, C<"a"> or C<"Z">), +the I is a string length, not a number of strings. If there is +an explicit repeat count for pack, the packed string will be adjusted to that +given length. - unpack 'C/a', "\04Gurusamy"; gives 'Guru' - unpack 'a3/A* A*', '007 Bond J '; gives (' Bond','J') - pack 'n/a* w/a*','hello,','world'; gives "\000\006hello,\005world" + unpack 'W/a', "\04Gurusamy"; gives ('Guru') + unpack 'a3/A* A*', '007 Bond J '; gives (' Bond', 'J') + pack 'n/a* w/a','hello,','world'; gives "\000\006hello,\005world" + pack 'a/W2', ord('a') .. ord('z'); gives '2ab' The I is not returned explicitly from C. @@ -3446,7 +3623,7 @@ which Perl does not regard as legal in numeric strings. =item * The integer types C, C, C, and C may be -immediately followed by a C suffix to signify native shorts or +followed by a C modifier to signify native shorts or longs--as you can see from above for example a bare C does mean exactly 32 bits, the native C (as seen by the local C compiler) may be larger. This is an issue mainly in 64-bit platforms. You can @@ -3501,7 +3678,7 @@ Some systems may have even weirder byte orders such as You can see your system's preference with print join(" ", map { sprintf "%#02x", $_ } - unpack("C*",pack("L",0x12345678))), "\n"; + unpack("W*",pack("L",0x12345678))), "\n"; The byteorder on the platform where Perl was built is also available via L: @@ -3512,12 +3689,45 @@ via L: Byteorders C<'1234'> and C<'12345678'> are little-endian, C<'4321'> and C<'87654321'> are big-endian. -If you want portable packed integers use the formats C, C, -C, and C, their byte endianness and size are known. +If you want portable packed integers you can either use the formats +C, C, C, and C, or you can use the C> and C> +modifiers. These modifiers are only available as of perl 5.9.2. See also L. =item * +All integer and floating point formats as well as C

and C

and +C<()>-groups may be followed by the C> or C> modifiers +to force big- or little- endian byte-order, respectively. +This is especially useful, since C, C, C and C don't cover +signed integers, 64-bit integers and floating point values. However, +there are some things to keep in mind. + +Exchanging signed integers between different platforms only works +if all platforms store them in the same format. Most platforms store +signed integers in two's complement, so usually this is not an issue. + +The C> or C> modifiers can only be used on floating point +formats on big- or little-endian machines. Otherwise, attempting to +do so will result in a fatal error. + +Forcing big- or little-endian byte-order on floating point values for +data exchange can only work if all platforms are using the same +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 definitely not a general way to portably store floating point +values. + +When using C> or C> on an C<()>-group, this will affect +all types inside the group that accept the byte-order modifiers, +including all subgroups. It will silently be ignored for all other +types. You are not allowed to override the byte-order within a group +that already has a byte-order modifier suffix. + +=item * + Real numbers (floats and doubles) are in the native machine format only; due to the multiplicity of floating formats around, and the lack of a standard "network" representation, no facility for interchange has been @@ -3526,28 +3736,31 @@ may not be readable on another - even if both use IEEE floating point arithmetic (as the endian-ness of the memory representation is not part of the IEEE spec). See also L. -Note that Perl uses doubles internally for all numeric calculation, and -converting from double into float and thence back to double again will -lose precision (i.e., C) will not in general -equal $foo). +If you know exactly what you're doing, you can use the C> or C> +modifiers to force big- or little-endian byte-order on floating point values. + +Note that Perl uses doubles (or long doubles, if configured) internally for +all numeric calculation, and converting from double into float and thence back +to double again will lose precision (i.e., C) +will not in general equal $foo). =item * -If the pattern begins with a C, the resulting string will be -treated as UTF-8-encoded Unicode. You can force UTF-8 encoding on in a -string with an initial C, and the bytes that follow will be -interpreted as Unicode characters. If you don't want this to happen, -you can begin your pattern with C (or anything else) to force Perl -not to UTF-8 encode your string, and then follow this with a C -somewhere in your pattern. +Pack and unpack can operate in two modes, character mode (C mode) where +the packed string is processed per character and UTF-8 mode (C mode) +where the packed string is processed in its UTF-8-encoded Unicode form on +a byte by byte basis. Character mode is the default unless the format string +starts with an C. You can switch mode at any moment with an explicit +C or C in the format. A mode is in effect until the next mode switch +or until the end of the ()-group in which it was entered. =item * You must yourself do any alignment or padding by inserting for example enough C<'x'>es while packing. There is no way to pack() and unpack() -could know where the bytes are going to or coming from. Therefore +could know where the characters are going to or coming from. Therefore C (and C) handle their output and input as flat -sequences of bytes. +sequences of characters. =item * @@ -3560,14 +3773,13 @@ C<@> starts again at 0. Therefore, the result of is the string "\0a\0\0bc". - =item * C and C accept C modifier. In this case they act as alignment commands: they jump forward/back to the closest position -aligned at a multiple of C bytes. For example, to pack() or +aligned at a multiple of C characters. For example, to pack() or unpack() C's C one may need to -use the template C; this assumes that doubles must be +use the template C; this assumes that doubles must be aligned on the double's size. For alignment commands C of 0 is equivalent to C of 1; @@ -3575,34 +3787,49 @@ both result in no-ops. =item * +C, C, C and C accept the C modifier. In this case they +will represent signed 16-/32-bit integers in big-/little-endian order. +This is only portable if all platforms sharing the packed data use the +same binary representation for signed integers (e.g. all platforms are +using two's complement representation). + +=item * + A comment in a TEMPLATE starts with C<#> and goes to the end of line. White space may be used to separate pack codes from each other, but -a C modifier and a repeat count must follow immediately. +modifiers and a repeat count must follow immediately. =item * If TEMPLATE requires more arguments to pack() than actually given, pack() -assumes additional C<""> arguments. If TEMPLATE requires less arguments +assumes additional C<""> arguments. If TEMPLATE requires fewer arguments to pack() than actually given, extra arguments are ignored. =back Examples: - $foo = pack("CCCC",65,66,67,68); + $foo = pack("WWWW",65,66,67,68); # foo eq "ABCD" - $foo = pack("C4",65,66,67,68); + $foo = pack("W4",65,66,67,68); # same thing + $foo = pack("W4",0x24b6,0x24b7,0x24b8,0x24b9); + # same thing with Unicode circled letters. $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9); - # same thing with Unicode circled letters + # same thing with Unicode circled letters. You don't get the UTF-8 + # bytes because the U at the start of the format caused a switch to + # U0-mode, so the UTF-8 bytes get joined into characters + $foo = pack("C0U4",0x24b6,0x24b7,0x24b8,0x24b9); + # foo eq "\xe2\x92\xb6\xe2\x92\xb7\xe2\x92\xb8\xe2\x92\xb9" + # This is the UTF-8 encoding of the string in the previous example $foo = pack("ccxxcc",65,66,67,68); # foo eq "AB\0\0CD" - # note: the above examples featuring "C" and "c" are true + # note: the above examples featuring "W" and "c" are true # only on ASCII and ASCII-derived systems such as ISO Latin 1 # and UTF-8. In EBCDIC the first example would be - # $foo = pack("CCCC",193,194,195,196); + # $foo = pack("WWWW",193,194,195,196); $foo = pack("s2",1,2); # "\1\0\2\0" on little-endian @@ -3636,6 +3863,17 @@ Examples: $bar = pack('s@4l', 12, 34); # short 12, zero fill to position 4, long 34 # $foo eq $bar + $baz = pack('s.l', 12, 4, 34); + # short 12, zero fill to position 4, long 34 + + $foo = pack('nN', 42, 4711); + # pack big-endian 16- and 32-bit unsigned integers + $foo = pack('S>L>', 42, 4711); + # exactly the same + $foo = pack('s. =item pos Returns the offset of where the last C search left off for the variable -in question (C<$_> is used when the variable is not specified). May be -modified to change that offset. Such modification will also influence -the C<\G> zero-width assertion in regular expressions. See L and +in question (C<$_> is used when the variable is not specified). Note that +0 is a valid match offset. C indicates that the search position +is reset (usually due to match failure, but can also be because no match has +yet been performed on the scalar). C directly accesses the location used +by the regexp engine to store the offset, so assigning to C will change +that offset, and so will also influence the C<\G> zero-width assertion in +regular expressions. Because a failed C match doesn't reset the offset, +the return from C won't change either in this case. See L and L. =item print FILEHANDLE LIST @@ -3734,8 +3977,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"; @@ -3952,8 +4196,8 @@ in that case pretty much any characters can be read. The C command restarts the loop block without evaluating the conditional again. The C block, if any, is not executed. If the LABEL is omitted, the command refers to the innermost enclosing -loop. This command is normally used by programs that want to lie to -themselves about what was just input: +loop. Programs that want to lie to themselves about what was just input +normally use this command: # a simpleminded Pascal comment stripper # (warning: assumes no { or } in strings) @@ -4010,9 +4254,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. @@ -4045,41 +4286,51 @@ Compare with L, which can do a similar check at compile time. Specifying VERSION as a literal of the form v5.6.1 should generally be avoided, because it leads to misleading error messages under earlier -versions of Perl which do not support this syntax. The equivalent numeric +versions of Perl that do not support this syntax. The equivalent numeric version should be used instead. require v5.6.1; # run time version check require 5.6.1; # ditto require 5.006_001; # ditto; preferred for backwards compatibility -Otherwise, demands that a library file be included if it hasn't already +Otherwise, C 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 -subroutine: +essentially just a variety of C. Has semantics similar to the +following subroutine: sub require { - my($filename) = @_; - return 1 if $INC{$filename}; - my($realfilename,$result); - ITER: { - 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; - return $result; + my ($filename) = @_; + if (exists $INC{$filename}) { + return 1 if $INC{$filename}; + die "Compilation failed in require"; + } + my ($realfilename,$result); + ITER: { + foreach $prefix (@INC) { + $realfilename = "$prefix/$filename"; + if (-f $realfilename) { + $INC{$filename} = $realfilename; + $result = do $realfilename; + last ITER; + } + } + die "Can't find $filename in \@INC"; + } + if ($@) { + $INC{$filename} = undef; + die $@; + } elsif (!$result) { + delete $INC{$filename}; + die "$filename did not return true value"; + } else { + 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 @@ -4114,7 +4365,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. @@ -4153,7 +4404,7 @@ or: ... } -If the hook is an object, it must provide an INC method, that will be +If the hook is an object, it must provide an INC method that will be called as above, the first parameter being the object itself. (Note that you must fully qualify the sub's name, as it is always forced into package C

.) Here is a typical code layout: @@ -4224,6 +4475,8 @@ in the opposite order. undef $/; # for efficiency of <> print scalar reverse <>; # character tac, last line tsrif +Used without arguments in scalar context, reverse() reverses C<$_>. + This operator is also handy for inverting a hash, although there are some caveats. If a value is duplicated in the original hash, only one of those can be represented as a key in the inverted hash. Also, this has to @@ -4335,8 +4588,8 @@ cantankerous), then 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 -possible directory compaction as the corresponding system library +must be a value returned by C. C also has the same caveats +about possible directory compaction as the corresponding system library routine. =item select FILEHANDLE @@ -4412,7 +4665,16 @@ You can effect a sleep of 250 milliseconds this way: select(undef, undef, undef, 0.25); Note that whether C. + +On error, C, except as permitted by POSIX, and even @@ -4425,7 +4687,7 @@ Calls the System V IPC function C. You'll probably have to say use IPC::SysV; first to get the correct constant definitions. If CMD is IPC_STAT or -GETALL, then ARG must be a variable which will hold the returned +GETALL, then ARG must be a variable that will hold the returned semid_ds structure or semaphore value array. Returns like C: the undefined value for error, "C<0 but true>" for zero, or the actual return value otherwise. The ARG must consist of a vector of native @@ -4445,8 +4707,8 @@ documentation. Calls the System V IPC function semop to perform semaphore operations such as signalling and waiting. OPSTRING must be a packed array of semop structures. Each semop structure can be generated with -C. The number of semaphore -operations is implied by the length of OPSTRING. Returns true if +C. The length of OPSTRING +implies the number of semaphore operations. Returns true if successful, or false if there is an error. As an example, the following code waits on semaphore $semnum of semaphore id $semid: @@ -4506,9 +4768,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 @@ -4521,7 +4783,7 @@ Calls the System V IPC function shmctl. You'll probably have to say use IPC::SysV; first to get the correct constant definitions. If CMD is C, -then ARG must be a variable which will hold the returned C +then ARG must be a variable that will hold the returned C structure. Returns like ioctl: the undefined value for error, "C<0> but true" for zero, or the actual return value otherwise. See also L and C documentation. @@ -4659,7 +4921,7 @@ 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. +compared are always passed by reference and should not be modified. You also cannot exit out of the sort block or subroutine using any of the loop control operators described in L or with C. @@ -4673,11 +4935,11 @@ preserves the input order of elements that compare equal. Although quicksort's run time is O(NlogN) when averaged over all arrays of length N, the time can be O(N**2), I behavior, for some inputs.) In 5.7, the quicksort implementation was replaced with -a stable mergesort algorithm whose worst case behavior is O(NlogN). +a stable mergesort algorithm whose worst-case behavior is O(NlogN). But benchmarks indicated that for some inputs, on some platforms, the original quicksort was faster. 5.8 has a sort pragma for limited control of the sort. Its rather blunt control of the -underlying algorithm may not persist into future perls, but the +underlying algorithm may not persist into future Perls, but the ability to characterize the input or output in implementation independent ways quite probably will. See L. @@ -4845,8 +5107,9 @@ Example, assuming array lengths are passed before arrays: =item split -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. +Splits the string EXPR into a list of strings and returns that list. By +default, empty leading fields are preserved, and empty trailing ones are +deleted. (If all fields are empty, they are considered to be trailing.) In scalar context, returns the number of fields found and splits into the C<@_> array. Use of split in scalar context is deprecated, however, @@ -4876,14 +5139,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!')); @@ -5020,7 +5288,7 @@ In order, these are: An explicit format parameter index, such as C<2$>. By default sprintf will format the next unused argument in the list, but this allows you -to take the arguments out of order. Eg: +to take the arguments out of order, e.g.: printf '%2$d %1$d', 12, 34; # prints "34 12" printf '%3$d %d %1$d', 1, 2, 3; # prints "3 1 1" @@ -5061,7 +5329,7 @@ use to separate the numbers: printf "bits are %0*v8b\n", " ", $bits; # random bitstring You can also explicitly specify the argument number to use for -the join string using eg C<*2$v>: +the join string using e.g. C<*2$v>: printf '%*4$vX %*4$vX %*4$vX', @addr[1..3], ":"; # 3 IPv6 addresses @@ -5070,7 +5338,7 @@ the join string using eg C<*2$v>: Arguments are usually formatted to be only as wide as required to display the given value. You can override the width by putting a number here, or get the width from the next argument (with C<*>) -or from a specified argument (with eg C<*2$>): +or from a specified argument (with e.g. C<*2$>): printf '<%s>', "a"; # prints "" printf '<%6s>', "a"; # prints "< a>" @@ -5086,7 +5354,7 @@ effect as the C<-> flag: left-justification. You can specify a precision (for numeric conversions) or a maximum width (for string conversions) by specifying a C<.> followed by a number. For floating point formats, with the exception of 'g' and 'G', this specifies -the number of decimal places to show (the default being 6), eg: +the number of decimal places to show (the default being 6), e.g.: # these examples are subject to system-specific variation printf '<%f>', 1; # prints "<1.000000>" @@ -5096,7 +5364,7 @@ the number of decimal places to show (the default being 6), eg: printf '<%.1e>', 10; # prints "<1.0e+01>" For 'g' and 'G', this specifies the maximum number of digits to show, -including prior to the decimal point as well as after it, eg: +including prior to the decimal point as well as after it, e.g.: # these examples are subject to system-specific variation printf '<%g>', 1; # prints "<1>" @@ -5127,7 +5395,7 @@ You can also get the precision from the next argument using C<.*>: You cannot currently get the precision from a specified number, but it is intended that this will be possible in the future using -eg C<.*2$>: +e.g. C<.*2$>: printf '<%.*2$x>', 1, 6; # INVALID, but in future will print "<000001>" @@ -5270,8 +5538,8 @@ current C

the pack function will gobble up +that many values from the LIST. A C<*> for the repeat count means to +use however many items are left, except for C<@>, C, C, where it +is equivalent to C<0>, for <.> where it means relative to string start +and C, where it is equivalent to 1 (or 45, which is the same). +A numeric repeat count may optionally be enclosed in brackets, as in +C. One can replace the numeric repeat count by a template enclosed in brackets; then the packed length of this template in bytes is used as a count. @@ -3338,72 +3490,84 @@ When used with C, C<*> results in the addition of a trailing null byte (so the packed result will be one longer than the byte C of the item). +When used with C<@>, the repeat count represents an offset from the start +of the innermost () group. + +When used with C<.>, the repeat count is used to determine the starting +position from where the value offset is calculated. If the repeat count +is 0, it's relative to the current position. If the repeat count is C<*>, +the offset is relative to the start of the packed string. And if its an +integer C the offset is relative to the start of the n-th innermost +() group (or the start of the string if C is bigger then the group +level). + The repeat count for C is interpreted as the maximal number of bytes -to encode per line of output, with 0 and 1 replaced by 45. +to encode per line of output, with 0, 1 and 2 replaced by 45. The repeat +count should not be more than 65. =item * The C, C, and C types gobble just one value, but pack it as a string of length count, padding with nulls or spaces as necessary. When -unpacking, C strips trailing spaces and nulls, C strips everything -after the first null, and C returns data verbatim. When packing, -C, and C are equivalent. +unpacking, C strips trailing whitespace and nulls, C strips everything +after the first null, and C returns data verbatim. If the value-to-pack is too long, it is truncated. If too long and an explicit count is provided, C packs only C<$count-1> bytes, followed -by a null byte. Thus C always packs a trailing null byte under -all circumstances. +by a null byte. Thus C always packs a trailing null (except when the +count is 0). =item * Likewise, the C and C fields pack a string that many bits long. -Each byte of the input field of pack() generates 1 bit of the result. +Each character of the input field of pack() generates 1 bit of the result. Each result bit is based on the least-significant bit of the corresponding -input byte, i.e., on C. In particular, bytes C<"0"> and -C<"1"> generate bits 0 and 1, as do bytes C<"\0"> and C<"\1">. +input character, i.e., on C. In particular, characters C<"0"> +and C<"1"> generate bits 0 and 1, as do characters C<"\0"> and C<"\1">. Starting from the beginning of the input string of pack(), each 8-tuple -of bytes is converted to 1 byte of output. With format C -the first byte of the 8-tuple determines the least-significant bit of a -byte, and with format C it determines the most-significant bit of -a byte. +of characters is converted to 1 character of output. With format C +the first character of the 8-tuple determines the least-significant bit of a +character, and with format C it determines the most-significant bit of +a character. If the length of the input string is not exactly divisible by 8, the -remainder is packed as if the input string were padded by null bytes +remainder is packed as if the input string were padded by null characters at the end. Similarly, during unpack()ing the "extra" bits are ignored. -If the input string of pack() is longer than needed, extra bytes are ignored. -A C<*> for the repeat count of pack() means to use all the bytes of -the input field. On unpack()ing the bits are converted to a string -of C<"0">s and C<"1">s. +If the input string of pack() is longer than needed, extra characters are +ignored. A C<*> for the repeat count of pack() means to use all the +characters of the input field. On unpack()ing the bits are converted to a +string of C<"0">s and C<"1">s. =item * The C and C fields pack a string that many nybbles (4-bit groups, representable as hexadecimal digits, 0-9a-f) long. -Each byte of the input field of pack() generates 4 bits of the result. -For non-alphabetical bytes the result is based on the 4 least-significant -bits of the input byte, i.e., on C. In particular, -bytes C<"0"> and C<"1"> generate nybbles 0 and 1, as do bytes -C<"\0"> and C<"\1">. For bytes C<"a".."f"> and C<"A".."F"> the result +Each character of the input field of pack() generates 4 bits of the result. +For non-alphabetical characters the result is based on the 4 least-significant +bits of the input character, i.e., on C. In particular, +characters C<"0"> and C<"1"> generate nybbles 0 and 1, as do bytes +C<"\0"> and C<"\1">. For characters C<"a".."f"> and C<"A".."F"> the result is compatible with the usual hexadecimal digits, so that C<"a"> and -C<"A"> both generate the nybble C<0xa==10>. The result for bytes +C<"A"> both generate the nybble C<0xa==10>. The result for characters C<"g".."z"> and C<"G".."Z"> is not well-defined. Starting from the beginning of the input string of pack(), each pair -of bytes is converted to 1 byte of output. With format C the -first byte of the pair determines the least-significant nybble of the -output byte, and with format C it determines the most-significant +of characters is converted to 1 character of output. With format C the +first character of the pair determines the least-significant nybble of the +output character, and with format C it determines the most-significant nybble. If the length of the input string is not even, it behaves as if padded -by a null byte at the end. Similarly, during unpack()ing the "extra" +by a null character at the end. Similarly, during unpack()ing the "extra" nybbles are ignored. -If the input string of pack() is longer than needed, extra bytes are ignored. -A C<*> for the repeat count of pack() means to use all the bytes of -the input field. On unpack()ing the bits are converted to a string +If the input string of pack() is longer than needed, extra characters are +ignored. +A C<*> for the repeat count of pack() means to use all the characters of +the input field. On unpack()ing the nybbles are converted to a string of hexadecimal digits. =item * @@ -3415,26 +3579,39 @@ The C