From 5e6388b2d6cf7153b8cccc122e74fe4e729cffe3 Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Tue, 6 May 2025 07:01:51 -0600 Subject: [PATCH] perlfunc: Remove self-referential links It is misleading to link to the top of a section from within that section. This is like having a link to a home page from that home page; it doesn't do any good, and can cause you to lose your place in the middle of reading the section. --- pod/perlfunc.pod | 612 +++++++++++++++++++++++------------------------ 1 file changed, 306 insertions(+), 306 deletions(-) diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index fc9b6c6d7ac6..99f40e54c6d2 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -776,11 +776,11 @@ arguments undefined, or you might be able to use the L|/syscall NUMBER, LIST> interface to access L if your system supports it. See L for details. -It is usually a mistake to intermix L|/alarm SECONDS> and +It is usually a mistake to intermix C and L|/sleep EXPR> calls, because L|/sleep EXPR> may be -internally implemented on your system with L|/alarm SECONDS>. +internally implemented on your system with C. -If you want to use L|/alarm SECONDS> to time out a system call +If you want to use C to time out a system call you need to use an L|/eval EXPR>/L|/die LIST> pair. You can't rely on the alarm causing the system call to fail with L|perlvar/$!> set to C because Perl sets up signal handlers @@ -910,14 +910,14 @@ otherwise it returns L|/undef EXPR> and sets L|perlvar/$!> (errno). On some systems (in general, DOS- and Windows-based systems) -L|/binmode FILEHANDLE, LAYER> is necessary when you're not +C is necessary when you're not working with a text file. For the sake of portability it is a good idea always to use it when appropriate, and never to use it when it isn't appropriate. Also, people can set their I/O to be by default UTF8-encoded Unicode, not bytes. In other words: regardless of platform, use -L|/binmode FILEHANDLE, LAYER> on binary data, like images, +C on binary data, like images, for example. If LAYER is present it is a single string, but may contain multiple @@ -937,7 +937,7 @@ The C<:bytes>, C<:crlf>, C<:utf8>, and any other directives of the form C<:...>, are called I/O I. The L pragma can be used to establish default I/O layers. -I|/binmode FILEHANDLE, LAYER> +I function is described as "DISCIPLINE" in "Programming Perl, 3rd Edition". However, since the publishing of this book, by many known as "Camel III", the consensus of the naming of this functionality has moved @@ -950,9 +950,9 @@ C<:utf8> just marks the data as UTF-8 without further checking, while C<:encoding(UTF-8)> checks the data for actually being valid UTF-8. More details can be found in L. -In general, L|/binmode FILEHANDLE, LAYER> should be called +In general, C should be called after L|/open FILEHANDLE,MODE,EXPR> but before any I/O is done on the -filehandle. Calling L|/binmode FILEHANDLE, LAYER> normally +filehandle. Calling C normally flushes any pending buffered output data (and perhaps pending input data) on the handle. An exception to this is the C<:encoding> layer that changes the default character encoding of the handle. @@ -976,19 +976,19 @@ flavors of Mac OS, and is LINE FEED on Unix and most VMS files). In other systems like OS/2, DOS, and the various flavors of MS-Windows, your program sees a C<\n> as a simple C<\cJ>, but what's stored in text files are the two characters C<\cM\cJ>. That means that if you don't use -L|/binmode FILEHANDLE, LAYER> on these systems, C<\cM\cJ> +C on these systems, C<\cM\cJ> sequences on disk will be converted to C<\n> on input, and any C<\n> in your program will be converted back to C<\cM\cJ> on output. This is what you want for text files, but it can be disastrous for binary files. -Another consequence of using L|/binmode FILEHANDLE, LAYER> +Another consequence of using C (on some systems) is that special end-of-file markers will be seen as part of the data stream. For systems from the Microsoft family this means that, if your binary data contain C<\cZ>, the I/O subsystem will regard it as the end of the file, unless you use -L|/binmode FILEHANDLE, LAYER>. +C. -L|/binmode FILEHANDLE, LAYER> is important not only for +C is important not only for L|/readline EXPR> and L|/print FILEHANDLE LIST> operations, but also when using L|/read FILEHANDLE,SCALAR,LENGTH,OFFSET>, @@ -1047,7 +1047,7 @@ one-argument C is discouraged. See L for more about the blessing (and blessings) of objects. -L|/bless REF,CLASSNAME> returns its first argument, the +C returns its first argument, the supplied reference, as the value of the function; since C is commonly the last thing executed in constructors, this means that the reference to the object is returned as the @@ -1062,7 +1062,7 @@ confusion. Also avoid Cing things into the class name C<0>; this will cause code which (erroneously) checks the result of -L|/ref EXPR> to see if a reference is Ced to fail, +C to see if a reference is Ced to fail, as "0", a false value, is returned. See L for more details. @@ -1073,7 +1073,7 @@ See L for more details. Break out of a C block. -L|/break> is available only if the +C is available only if the L feature|feature/The 'switch' feature> is enabled or if it is prefixed with C. The L feature|feature/The 'switch' feature> is enabled @@ -1151,10 +1151,10 @@ detailed information: it sets the list variable C<@DB::args> to be the arguments with which the subroutine was invoked. Be aware that the optimizer might have optimized call frames away before -L|/caller EXPR> had a chance to get the information. That +C had a chance to get the information. That means that C might not return information about the call frame you expect it to, for C<< N > 1 >>. In particular, C<@DB::args> -might have information from the previous time L|/caller EXPR> +might have information from the previous time C was called. Be aware that setting C<@DB::args> is I, intended for @@ -1190,7 +1190,7 @@ 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 variable C<$ENV{'SYS$LOGIN'}> is also checked, and used if it is set.) If -neither is set, L|/chdir EXPR> does nothing and fails. It +neither is set, C does nothing and fails. It returns true on success, false otherwise. See the example under L|/die LIST>. @@ -1254,7 +1254,7 @@ that the final record may be missing its newline. When in paragraph mode (C<$/ = ''>), it removes all trailing newlines from the string. When in slurp mode (C<$/ = undef>) or fixed-length record mode (L>|perlvar/$E> is a reference to an integer or the like; -see L), L|/chomp VARIABLE> won't remove anything. +see L), C won't remove anything. If VARIABLE is omitted, it chomps L|perlvar/$_>. Example: while (<>) { @@ -1300,9 +1300,9 @@ resetting the L|/each HASH> iterator in the process. You can actually chop anything that's an lvalue, including an assignment. If you chop a list, each element is chopped. Only the value of the -last L|/chop VARIABLE> is returned. +last C is returned. -Note that L|/chop VARIABLE> returns the last character. To +Note that C returns the last character. To return all but the last character, use C. See also L|/chomp VARIABLE>. @@ -1387,11 +1387,11 @@ named directory the new root directory for all further pathnames that begin with a C by your process and all its children. (It doesn't change your current working directory, which is unaffected.) For security reasons, this call is restricted to the superuser. If FILENAME is -omitted, does a L|/chroot FILENAME> to L|perlvar/$_>. +omitted, does a C to L|perlvar/$_>. B It is mandatory for security to C (L|/chdir EXPR> to the root directory) immediately after a -L|/chroot FILENAME>, otherwise the current working directory +C, otherwise the current working directory may be outside of the new root. Portability issues: L. @@ -1435,11 +1435,11 @@ You don't have to close FILEHANDLE if you are immediately going to do another L|/open FILEHANDLE,MODE,EXPR> on it, because L|/open FILEHANDLE,MODE,EXPR> closes it for you. (See L|/open FILEHANDLE,MODE,EXPR>.) However, an explicit -L|/close FILEHANDLE> on an input file resets the line counter +C on an input file resets the line counter (L|perlvar/$.>), while the implicit close done by L|/open FILEHANDLE,MODE,EXPR> does not. -If the filehandle came from a piped open, L|/close FILEHANDLE> +If the filehandle came from a piped open, C returns false if one of the other syscalls involved fails or if its program exits with non-zero status. If the only problem was that the program exited non-zero, L|perlvar/$!> will be set to C<0>. @@ -1449,7 +1449,7 @@ implicitly puts the exit status value of that command into L|perlvar/$?> and L|perlvar/${^CHILD_ERROR_NATIVE}>. -If there are multiple threads running, L|/close FILEHANDLE> on +If there are multiple threads running, C on a filehandle from a piped open returns true without waiting for the child process to terminate, if the filehandle is still open in another thread. @@ -1503,22 +1503,22 @@ X =for Pod::Functions optional trailing block in a while or foreach -When followed by a BLOCK, L|/continue BLOCK> is actually a +When followed by a BLOCK, C is actually a flow control statement rather than a function. If there is a -L|/continue BLOCK> BLOCK attached to a BLOCK (typically in 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 continued via the L|/next LABEL> -statement (which is similar to the C L|/continue BLOCK> +statement (which is similar to the C C statement). L|/last LABEL>, L|/next LABEL>, or L|/redo LABEL> may appear within a -L|/continue BLOCK> block; L|/last LABEL> and +C block; L|/last LABEL> and L|/redo LABEL> behave as if they had been executed within the main block. So will L|/next LABEL>, but since it will execute a -L|/continue BLOCK> block, it may be more entertaining. +C block, it may be more entertaining. while (EXPR) { ### redo always comes here @@ -1530,15 +1530,15 @@ L|/continue BLOCK> block, it may be more entertaining. } ### last always comes here -Omitting the L|/continue BLOCK> section is equivalent to +Omitting the C section is equivalent to using an empty one, logically enough, so L|/next LABEL> goes directly back to check the condition at the top of the loop. -When there is no BLOCK, L|/continue BLOCK> is a function +When there is no BLOCK, C is a function that falls through the current C or C block instead of iterating a dynamically enclosing C or exiting a lexically enclosing C. In Perl 5.14 and earlier, this form of -L|/continue BLOCK> was only available when the +C was only available when the L feature|feature/The 'switch' feature> was enabled. See L and L for more information. @@ -1567,7 +1567,7 @@ Creates a digest string exactly like the L function in the C library (assuming that you actually have a version there that has not been extirpated as a potential munition). -L|/crypt PLAINTEXT,SALT> is a one-way hash function. The +C is a one-way hash function. The PLAINTEXT and SALT are 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 @@ -1582,15 +1582,15 @@ 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 -L|/crypt PLAINTEXT,SALT>'d with the same salt as the stored +C'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 -L|/crypt PLAINTEXT,SALT> will hash the new string with the same +C will hash the new string with the same salt as the digest. This allows your code to work with the standard -L|/crypt PLAINTEXT,SALT> and with more exotic implementations. +C and with more exotic implementations. In other words, assume nothing about the returned string itself nor about how many bytes of SALT may matter. @@ -1606,7 +1606,7 @@ characters come from the set C<[./0-9A-Za-z]> (like C). This set of characters is just a recommendation; the characters allowed in the salt depend solely on your system's crypt library, and Perl can't -restrict what salts L|/crypt PLAINTEXT,SALT> accepts. +restrict what salts C accepts. Here's an example that makes sure that whoever runs this program knows their password: @@ -1628,17 +1628,17 @@ their password: Of course, typing in your own password to whoever asks you for it is unwise. -The L|/crypt PLAINTEXT,SALT> function is unsuitable for hashing +The C function is unsuitable for hashing large quantities of data, not least of all because you can't get the information back. Look at the L module for more robust algorithms. -If using L|/crypt PLAINTEXT,SALT> on a Unicode string (which +If using C on a Unicode string (which I has characters with codepoints above 255), Perl tries to make sense of the situation by trying to downgrade (a copy of) the string back to an eight-bit byte string before calling -L|/crypt PLAINTEXT,SALT> (on that copy). If that works, good. -If not, L|/crypt PLAINTEXT,SALT> dies with +C (on that copy). If that works, good. +If not, C dies with L|perldiag/Wide character in %s>. Portability issues: L. @@ -1673,9 +1673,9 @@ database does not exist, it is created with protection specified by MASK the database if it doesn't exist, you may specify a MASK of 0, and the function will return a false value if it can't find an existing database. If your system supports only the older DBM functions, you may -make only one L|/dbmopen HASH,DBNAME,MASK> call in your +make only one C call in your program. In older versions of Perl, if your system had neither DBM nor -ndbm, calling L|/dbmopen HASH,DBNAME,MASK> produced a fatal +ndbm, calling C produced a fatal error; it now falls back to L. If you don't have write access to the DBM file, you can only read hash @@ -1700,7 +1700,7 @@ cons of the various dbm approaches, as well as L for a particularly rich implementation. You can control which DBM library you use by loading that library -before you call L|/dbmopen HASH,DBNAME,MASK>: +before you call C: use DB_File; dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db") @@ -1737,7 +1737,7 @@ may still be callable: its package may have an C method that makes it spring into existence the first time that it is called; see L. -Use of L|/defined EXPR> on aggregates (hashes and arrays) is +Use of C on aggregates (hashes and arrays) is no longer supported. It used to report whether memory for that aggregate had ever been allocated. You should instead use a simple test for size: @@ -1758,7 +1758,7 @@ Examples: sub foo { defined &$bar ? $bar->(@_) : die "No bar"; } $debugging = 0 unless defined $debugging; -Note: Many folks tend to overuse L|/defined EXPR> and are +Note: Many folks tend to overuse C and are then surprised to discover that the number C<0> and C<""> (the zero-length string) are, in fact, defined values. For example, if you say @@ -1770,7 +1770,7 @@ 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 -should use L|/defined EXPR> only when questioning the +should use C only when questioning the integrity of what you're trying to do. At other times, a simple comparison to C<0> or C<""> is what you want. @@ -1783,7 +1783,7 @@ X =for Pod::Functions deletes a value from a hash Given an expression that specifies an element or slice of a hash, -L|/delete EXPR> deletes the specified elements from that hash +C deletes the specified elements from that hash so that L|/exists EXPR> on that element no longer returns true. Setting a hash element to the undefined value does not remove its key, but deleting it does; see L|/exists EXPR>. @@ -1796,7 +1796,7 @@ Lvalue hash slice|perldata/KeyEValue Hash Slices> can be passed to C, and the return value is a list of key/value pairs (two elements for each item deleted from the hash). -L|/delete EXPR> may also be used on arrays and array slices, +C may also be used on arrays and array slices, but its behavior is less straightforward. Although L|/exists EXPR> will return false for deleted entries, deleting array elements never changes indices of existing values; use @@ -1807,7 +1807,7 @@ the highest element that still tests true for L|/exists EXPR>, or to 0 if none do. In other words, an array won't have trailing nonexistent elements after a delete. -B Calling L|/delete EXPR> on array values is +B Calling C on array values is strongly discouraged. The notion of deleting or checking the existence of Perl array elements is not conceptually coherent, and can lead to surprising behavior. @@ -1869,7 +1869,7 @@ X X X X X<$@> X =for Pod::Functions raise an exception or bail out -L|/die LIST> raises an exception. Inside an L|/eval EXPR> +C raises an exception. Inside an L|/eval EXPR> the exception is stuffed into L|perlvar/$@> and the L|/eval EXPR> is terminated with the undefined value. If the exception is outside of all enclosing L|/eval EXPR>s, then the uncaught @@ -1924,7 +1924,7 @@ C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >> were called. If LIST was empty or made an empty string, and L|perlvar/$@> is also empty, then the string C<"Died"> is used. -You can also call L|/die LIST> with a reference argument, and if +You can also call C with a reference argument, and if this is trapped within an L|/eval EXPR>, L|perlvar/$@> contains that reference. This permits more elaborate exception handling using objects that maintain arbitrary state about the exception. Such a @@ -1977,15 +1977,15 @@ The intent is to squeeze as much possible information about the likely cause into the limited space of the system exit code. However, as L|perlvar/$!> is the value of C's C, which can be set by any system call, this means that the value of the exit code used by -L|/die LIST> can be non-predictable, so should not be relied +C can be non-predictable, so should not be relied upon, other than to be non-zero. You can arrange for a callback to be run just before the -L|/die LIST> does its deed, by setting the +C does its deed, by setting the L|perlvar/%SIG> hook. The associated handler is called with the exception as an argument, and can change the exception, if it sees fit, by -calling L|/die LIST> again. See L for details on +calling C again. See L for details on setting L|perlvar/%SIG> entries, and L|/eval EXPR> for some examples. Although this feature was to be run only right before your program was to exit, this is not currently so: the @@ -2059,20 +2059,20 @@ in perl versions 5.26.0 onwards. Instead, perl will now warn: do "stat.pl" failed, '.' is no longer in @INC; did you mean do "./stat.pl"? -If L|/do EXPR> can read the file but cannot compile it, it +If C can read the file but cannot compile it, it returns L|/undef EXPR> and sets an error message in -L|perlvar/$@>. If L|/do EXPR> cannot read the file, it +L|perlvar/$@>. If C cannot read the file, it returns undef and sets L|perlvar/$!> to the error. Always check L|perlvar/$@> first, as compilation could fail in a way that also sets L|perlvar/$!>. If the file is successfully compiled, -L|/do EXPR> returns the value of the last expression evaluated. +C returns the value of the last expression evaluated. Inclusion of library modules is better done with the L|/use Module VERSION LIST> and L|/require VERSION> operators, which also do automatic error checking and raise an exception if there's a problem. -You might like to use L|/do EXPR> to read in a program +You might like to use C to read in a program configuration file. Manual error checking can be done this way: # Read in config files: system first, then user. @@ -2120,7 +2120,7 @@ as C. Unlike most named operators, this has the same precedence as assignment. It is also exempt from the looks-like-a-function rule, so C will cause "bar" to be part of the argument to -L|/dump LABEL>. +C. Portability issues: L. @@ -2150,7 +2150,7 @@ that the most recent key returned by C or L|/keys HASH> may be deleted without changing the order. So long as a given hash is unmodified you may rely on L|/keys HASH>, L|/values HASH> and -L|/each HASH> to repeatedly return the same order +C to repeatedly return the same order as each other. See L for details on why hash order is randomized. Aside from the guarantees provided here, the exact details of Perl's hash algorithm and the hash @@ -2284,22 +2284,22 @@ interactive context.) Do not read from a terminal file (or call C on it) after end-of-file is reached. File types such as terminals may lose the end-of-file condition if you do. -An L|/eof FILEHANDLE> without an argument uses the last file -read. Using L|/eof FILEHANDLE> with empty parentheses is +An C without an argument uses the last file +read. Using C with empty parentheses is different. It refers to the pseudo file formed from the files listed on the command line and accessed via the C<< <> >> operator. Since C<< <> >> isn't explicitly opened, as a normal filehandle is, an -L|/eof FILEHANDLE> before C<< <> >> has been used will cause +C before C<< <> >> has been used will cause L|perlvar/@ARGV> to be examined to determine if input is -available. Similarly, an L|/eof FILEHANDLE> after C<< <> >> +available. Similarly, an C after C<< <> >> has returned end-of-file will assume you are processing another L|perlvar/@ARGV> list, and if you haven't set L|perlvar/@ARGV>, will read input from C; see L. -In a C<< while (<>) >> loop, L|/eof FILEHANDLE> or C +In a C<< while (<>) >> loop, C or C can be used to detect the end of each file, whereas -L|/eof FILEHANDLE> will detect the end of the very last file +C will detect the end of the very last file only. Examples: # reset line numbering on each input file @@ -2319,7 +2319,7 @@ only. Examples: last if eof(); # needed if we're reading from a terminal } -Practical hint: you almost never need to use L|/eof FILEHANDLE> +Practical hint: you almost never need to use C in Perl, because the input operators typically return L|/undef EXPR> when they run out of data or encounter an error. @@ -2601,7 +2601,7 @@ C and C within the string have their usual effect. Source filters activated within the evaluated code apply to the code itself. -L|/evalbytes EXPR> is available starting in Perl v5.16. To +C is available starting in Perl v5.16. To access it, you must say C, but you can omit the C if the L feature|feature/The 'unicode_eval' and 'evalbytes' features> @@ -2615,18 +2615,18 @@ X X =for Pod::Functions abandon this program to run another -The L|/exec LIST> function executes a system command I; use L|/system LIST> instead of L|/exec LIST> +The C function executes a system command I; use L|/system LIST> instead of C if you want it to return. It fails and returns false only if the command does not exist I it is executed directly instead of via your system's command shell (see below). -Since it's a common mistake to use L|/exec LIST> instead of -L|/system LIST>, Perl warns you if L|/exec LIST> is +Since it's a common mistake to use C instead of +L|/system LIST>, Perl warns you if C is called in void context and if there is a following statement that isn't L|/die LIST>, L|/warn LIST>, or L|/exit EXPR> (if L are enabled--but you always do that, right?). If you -I want to follow an L|/exec LIST> with some other +I want to follow an C with some other statement, you can use one of these styles to avoid the warning: exec ('foo') or print STDERR "couldn't exec foo: $!"; @@ -2661,7 +2661,7 @@ When the arguments get executed via the system shell, results are subject to its quirks and capabilities. See L for details. -Using an indirect object with L|/exec LIST> or +Using an indirect object with C or L|/system LIST> is also more secure. This usage (which also works fine with L|/system LIST>) forces interpretation of the arguments as a multivalued list, even if the @@ -2690,7 +2690,7 @@ To be safe, you may need to set L>|perlvar/$E> L|IO::Handle/METHODS> on any open handles to avoid lost output. -Note that L|/exec LIST> will not call your C blocks, nor +Note that C will not call your C blocks, nor will it invoke C methods on your objects. Portability issues: L. @@ -2712,7 +2712,7 @@ exists may also be called on array elements, but its behavior is much less obvious and is strongly tied to the use of L|/delete EXPR> on arrays. -B Calling L|/exists EXPR> on array values is +B Calling C on array values is strongly discouraged. The notion of deleting or checking the existence of Perl array elements is not conceptually coherent, and can lead to surprising behavior. @@ -2757,7 +2757,7 @@ This happens anywhere the arrow operator is used, including even here: print $ref; # prints HASH(0x80d3d5c) Use of a subroutine call, rather than a subroutine name, as an argument -to L|/exists EXPR> is an error. +to C is an error. exists ⊂ # OK exists &sub(); # Error @@ -2782,12 +2782,12 @@ environment in which the Perl program is running. For example, exiting 69 (EX_UNAVAILABLE) from a I incoming-mail filter will cause the mailer to return the item undelivered, but that's not true everywhere. -Don't use L|/exit EXPR> to abort a subroutine if there's any +Don't use C to abort a subroutine if there's any chance that someone might want to trap whatever error happened. Use L|/die LIST> instead, which can be trapped by an L|/eval EXPR>. -The L|/exit EXPR> function does not always exit immediately. It +The C function does not always exit immediately. It calls any defined C routines first, but these C routines may not themselves abort the exit. Likewise any object destructors that need to be called are called before the real exit. C routines and @@ -2851,7 +2851,7 @@ If EXPR is omitted, uses L|perlvar/$_>. This function behaves the same way under various pragmas, such as within L>|feature/The 'unicode_strings' feature>, as L|/lc EXPR> does, with the single exception of -L|/fc EXPR> of I (U+1E9E) within the +C of I (U+1E9E) within the scope of L>|locale>. The foldcase of this character would normally be C<"ss">, but as explained in the L|/lc EXPR> section, case @@ -2866,7 +2866,7 @@ one for Turkic languages and one that never maps one character into multiple characters, these are not provided by the Perl core. However, the CPAN module L|Unicode::Casing> may be used to provide an implementation. -L|/fc EXPR> is available only if the +C is available only if the L feature|feature/The 'fc' feature> is enabled or if it is prefixed with C. The L feature|feature/The 'fc' feature> is enabled automatically @@ -2890,7 +2890,7 @@ FILEHANDLE,FUNCTION,SCALAR> below. For example: or die "Can't fcntl F_GETFL: $!"; You don't have to check for L|/defined EXPR> on the return -from L|/fcntl FILEHANDLE,FUNCTION,SCALAR>. Like +from C. Like L|/ioctl FILEHANDLE,FUNCTION,SCALAR>, it maps a C<0> return from the system call into C<"0 but true"> in Perl. This string is true in boolean context and C<0> in numeric context. It is also exempt from @@ -2898,7 +2898,7 @@ the normal L|perldiag/Argument "%s" isn't numeric%s> L on improper numeric conversions. -Note that L|/fcntl FILEHANDLE,FUNCTION,SCALAR> raises an +Note that C raises an exception if used on a machine that doesn't implement L. See the L module or your L manpage to learn what functions are available on your system. @@ -2968,9 +2968,9 @@ same underlying descriptor: "not have a real file descriptor\n"; } -The behavior of L|/fileno FILEHANDLE> on a directory handle +The behavior of C on a directory handle depends on the operating system. On a system with L or -similar, L|/fileno FILEHANDLE> on a directory +similar, C on a directory handle returns the underlying file descriptor associated with the handle; on systems with no such support, it returns the undefined value, and sets L|perlvar/$!> (errno). @@ -2983,7 +2983,7 @@ X X X Calls L, or an emulation of it, on FILEHANDLE. Returns true for success, false on failure. Produces a fatal error if used on a machine that doesn't implement L, L locking, or -L. L|/flock FILEHANDLE,OPERATION> is Perl's portable +L. C is Perl's portable file-locking interface, although it locks entire files only, not records. @@ -2992,8 +2992,8 @@ FILEHANDLE,OPERATION> semantics are that it waits indefinitely until the lock is granted, and that its locks are B. Such discretionary locks are more flexible, but offer fewer guarantees. This means that programs that do not also use -L|/flock FILEHANDLE,OPERATION> may modify files locked with -L|/flock FILEHANDLE,OPERATION>. See L, +C may modify files locked with +C. See L, your port's specific documentation, and 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 @@ -3007,7 +3007,7 @@ you can use the symbolic names if you import them from the L module, either individually, or as a group using the C<:flock> tag. LOCK_SH requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN releases a previously requested lock. If LOCK_NB is bitwise-or'ed with -LOCK_SH or LOCK_EX, then L|/flock FILEHANDLE,OPERATION> returns +LOCK_SH or LOCK_EX, then C returns immediately rather than blocking waiting for the lock; check the return status to see if you got it. @@ -3024,7 +3024,7 @@ Note that the L emulation of L requires that FILEHANDLE be open with read intent to use LOCK_SH and requires that it be open with write intent to use LOCK_EX. -Note also that some versions of L|/flock FILEHANDLE,OPERATION> +Note also that some versions of C cannot lock things over the network; you would need to use the more system-specific L|/fcntl FILEHANDLE,FUNCTION,SCALAR> for that. If you like you can force Perl to ignore your system's L @@ -3062,7 +3062,7 @@ L|/fork> calls, whereas those that must resort to the more capricious L function lose their locks, making it seriously harder to write servers. -See also L for other L|/flock FILEHANDLE,OPERATION> +See also L for other C examples. Portability issues: L. @@ -3089,7 +3089,7 @@ L>|perlvar/$E> (C<$AUTOFLUSH> in L) or call the C method of L|IO::Handle/METHODS> on any open handles to avoid duplicate output. -If you L|/fork> without ever waiting on your children, you will +If you C without ever waiting on your children, you will accumulate zombies. On some systems, you can avoid this by setting L|perlvar/%SIG> to C<"IGNORE">. See also L for more examples of forking and reaping moribund children. @@ -3101,7 +3101,7 @@ backgrounded job launched from a remote shell) won't think you're done. You should reopen those to F if it's any issue. On some platforms such as Windows, where the L system call is -not available, Perl can be built to emulate L|/fork> in the Perl +not available, Perl can be built to emulate C in the Perl interpreter. The emulation is designed, at the level of the Perl program, to be as compatible as possible with the "Unix" L. However it has limitations that have to be considered in code intended @@ -3134,7 +3134,7 @@ X =for Pod::Functions internal function used for formats -This is an internal function used by L|/format>s, though you +This is an internal function used by Cs, though you may call it, too. It formats (see L) a list of values according to the contents of PICTURE, placing the output into the format output accumulator, L|perlvar/$^A> (or C<$ACCUMULATOR> in @@ -3142,8 +3142,8 @@ L). Eventually, when a L|/write FILEHANDLE> is done, the contents of L|perlvar/$^A> are written to some filehandle. You could also read L|perlvar/$^A> and then set L|perlvar/$^A> back to C<"">. Note that a format typically does -one L|/formline PICTURE,LIST> per line of form, but the -L|/formline PICTURE,LIST> function itself doesn't care how +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 treat the entire PICTURE as a single line. You may therefore need to use multiple formlines to implement a single record @@ -3151,7 +3151,7 @@ format, just like the L|/format> compiler. Be careful if you put double quotes around the picture, because an C<@> character may be taken to mean the beginning of an array name. -L|/formline PICTURE,LIST> always returns true. See +C always returns true. See L for other examples. If you are trying to use this instead of L|/write FILEHANDLE> @@ -3208,7 +3208,7 @@ returns the empty string, use L|/getpwuid UID>. my $login = getlogin || getpwuid($<) || "Kilroy"; -Do not consider L|/getlogin> for authentication: it is not +Do not consider C for authentication: it is not as secure as L|/getpwuid UID>. Portability issues: L. @@ -3489,10 +3489,10 @@ you can write this: $ip_address = inet_ntoa($packed_ip); } -Make sure L|/gethostbyname NAME> is called in SCALAR +Make sure C is called in SCALAR context and that its return value is checked for definedness. -The L|/getprotobynumber NUMBER> function, even +The C function, even though it only takes one argument, has the precedence of a list operator, so beware: @@ -3620,7 +3620,7 @@ C<:nocase> parameter of the L|File::Glob/C> module. my @txt = glob("readme*"); # README readme.txt Readme.md -Note that L|/glob EXPR> splits its arguments on whitespace and +Note that C splits its arguments on whitespace and treats each segment as separate pattern. As such, C matches all files with a F<.c> or F<.h> extension. The expression @@ -3640,7 +3640,7 @@ If you had to get a variable through, you could do this: my @spacies = glob(qq("*${var}e f*")); If non-empty braces are the only wildcard characters used in the -L|/glob EXPR>, no filenames are matched, but potentially many +C, no filenames are matched, but potentially many strings are returned. For example, this produces nine strings, one for each pairing of fruits and colors: @@ -3700,10 +3700,10 @@ subroutine given to L|/sort SUBNAME LIST>. It can be used to go almost anywhere else within the dynamic scope, including out of subroutines, but it's usually better to use some other construct such as L|/last LABEL> or L|/die LIST>. The author of Perl has -never felt the need to use this form of L|/goto LABEL> (in Perl, +never felt the need to use this form of C (in Perl, that is; C is another matter). (The difference is that C does not offer named loops combined with loop control. Perl does, and this replaces -most structured uses of L|/goto LABEL> in other languages.) +most structured uses of C in other languages.) The C form expects to evaluate C to a code reference or a label name. If it evaluates to a code reference, it will be handled @@ -3711,7 +3711,7 @@ like C, below. This is especially useful for implementing tail recursion via C. If the expression evaluates to a label name, its scope will be resolved -dynamically. This allows for computed L|/goto LABEL>s per +dynamically. This allows for computed Cs per FORTRAN, but isn't necessarily recommended if you're optimizing for maintainability: @@ -3736,7 +3736,7 @@ operand.) It also can't be used to go into a construct that is optimized away. The C form is quite different from the other forms of -L|/goto LABEL>. In fact, it isn't a goto in the normal sense at +C. In fact, it isn't a goto in the normal sense at all, and doesn't have the stigma associated with other gotos. Instead, it exits the current subroutine (losing any changes set by L|/local EXPR>) and immediately calls in its place the named @@ -3745,7 +3745,7 @@ by C subroutines that wish to load another subroutine and then pretend that the other subroutine had been called in the first place (except that any modifications to L|perlvar/@_> in the current subroutine are propagated to the other subroutine.) After the -L|/goto LABEL>, not even L|/caller EXPR> will be able +C, not even L|/caller EXPR> 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 @@ -3781,11 +3781,11 @@ it can cause bizarre results if the elements of LIST are not variables. Similarly, grep returns aliases into the original list, much as a for loop's index variable aliases the list elements. That is, modifying an element of a list returned by grep (for example, in a C, -L|/map BLOCK LIST> or another L|/grep BLOCK LIST>) +L|/map BLOCK LIST> or another C) actually modifies the element in the original list. This is usually something to be avoided when writing clear code. -See also L|/map BLOCK LIST> for a list composed of the results of +See also C for a list composed of the results of the BLOCK or EXPR. =item hex EXPR @@ -3819,11 +3819,11 @@ X =for Pod::Functions patch a module's namespace into your own -There is no builtin L|/import LIST> function. It is just an +There is no builtin C function. It is just an ordinary method (subroutine) defined (or inherited) by modules that wish to export names to another module. The L|/use Module VERSION LIST> function calls the -L|/import LIST> method for the package used. See also +C method for the package used. See also L|/use Module VERSION LIST>, L, and L. =item index STR,SUBSTR,POSITION @@ -3840,7 +3840,7 @@ or after POSITION. If POSITION is omitted, starts searching from the beginning of the string. POSITION before the beginning of the string or after its end is treated as if it were the beginning or the end, respectively. POSITION and the return value are based at zero. -If the substring is not found, L|/index STR,SUBSTR,POSITION> +If the substring is not found, C returns -1. Find characters or strings: @@ -3896,15 +3896,15 @@ own, based on your C header files such as F<< >>. may help you in this, but it's nontrivial.) SCALAR will be read and/or written depending on the FUNCTION; a C pointer to the string value of SCALAR will be passed as the third argument of the actual -L|/ioctl FILEHANDLE,FUNCTION,SCALAR> call. (If SCALAR +C call. (If SCALAR has no string value but does have a numeric value, that value will be passed rather than a pointer to the string value. To guarantee this to be true, add a C<0> to the scalar before using it.) The L|/pack TEMPLATE,LIST> and L|/unpack TEMPLATE,EXPR> functions may be needed to manipulate the values of structures used by -L|/ioctl FILEHANDLE,FUNCTION,SCALAR>. +C. -The return value of L|/ioctl FILEHANDLE,FUNCTION,SCALAR> (and +The return value of C (and L|/fcntl FILEHANDLE,FUNCTION,SCALAR>) is as follows: if OS returns: then Perl returns: @@ -3936,7 +3936,7 @@ separated by the value of EXPR, and returns that new string. Example: my $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell); Beware that unlike L|/split EPATTERNE,EXPR,LIMIT>, -L|/join EXPR,LIST> doesn't take a pattern as its first argument. +C doesn't take a pattern as its first argument. Compare L|/split EPATTERNE,EXPR,LIMIT>. =item keys HASH @@ -4064,7 +4064,7 @@ the entire process group specified. That means you usually want to use positive not negative signals. If SIGNAL is either the number 0 or the string C (or C), -no signal is sent to the process, but L|/kill SIGNAL, LIST> +no signal is sent to the process, but C checks whether it's I to send a signal to it (that means, to be brief, that the process is owned by the same user, or we are the super-user). This is useful to check that a child process is still @@ -4106,7 +4106,7 @@ X X =for Pod::Functions exit a block prematurely -The L|/last LABEL> command is like the C statement in C +The C command is like the C statement in C (as used in loops); it immediately exits the loop in question. If the LABEL is omitted, the command refers to the innermost enclosing @@ -4120,24 +4120,24 @@ L|/continue BLOCK> block, if any, is not executed: #... } -L|/last LABEL> cannot return a value from a block that typically +C cannot return a value from a block that typically returns a value, such as C, C, or C. It will perform its flow control behavior, which precludes any return value. It should not be used to exit a L|/grep BLOCK LIST> or L|/map BLOCK LIST> operation. Note that a block by itself is semantically identical to a loop -that executes once. Thus L|/last LABEL> can be used to effect +that executes once. Thus C can be used to effect an early exit out of such a block. See also L|/continue BLOCK> for an illustration of how -L|/last LABEL>, L|/next LABEL>, and +C, L|/next LABEL>, and L|/redo LABEL> work. Unlike most named operators, this has the same precedence as assignment. It is also exempt from the looks-like-a-function rule, so C will cause "bar" to be part of the argument to -L|/last LABEL>. +C. =item lc EXPR X X @@ -4273,7 +4273,7 @@ X =for Pod::Functions create a temporary value for a global variable (dynamic scoping) You really probably want to be using L|/my VARLIST> instead, -because L|/local EXPR> isn't what most people think of as +because C isn't what most people think of as "local". See L for details. A local modifies the listed variables to be local to the enclosing @@ -4282,9 +4282,9 @@ be placed in parentheses. See L for details, including issues with tied arrays and hashes. Like L|/my VARLIST>, L|/state VARLIST>, and -L|/our VARLIST>, L|/local EXPR> can operate on a variable +L|/our VARLIST>, C can operate on a variable anywhere it appears in an expression (aside from interpolation in strings). -Unlike the other declarations, the effect of L|/local EXPR> happens +Unlike the other declarations, the effect of C happens at runtime, and so it will apply to additional uses of the same variable executed after the declaration, even within the same statement. Note that this does not include uses within an expression assigned to the variable @@ -4312,7 +4312,7 @@ X X Converts a time as returned by the time function to a 9-element list with the time analyzed for the local time zone. If EXPR is omitted, -L|/localtime EXPR> uses the current time (as returned by +C uses the current time (as returned by L|/time>). Typically used as follows: @@ -4367,7 +4367,7 @@ To get just the year, you can use either L>: # just the last two digits of the year: my $ar = sprintf("%02d", $year % 100); -In scalar context, L|/localtime EXPR> returns the +In scalar context, C returns the L value: my $now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994" @@ -4388,7 +4388,7 @@ three characters wide. The L and L modules provide a convenient, by-name access mechanism to the L|/gmtime EXPR> and -L|/localtime EXPR> functions, respectively. +C functions, respectively. For a comprehensive date and time representation look at the L module on CPAN. @@ -4413,7 +4413,7 @@ object contained in I until the lock goes out of scope. The value returned is the scalar itself, if the argument is a scalar, or a reference, if the argument is a hash, array or subroutine. -L|/lock THING> is a "weak keyword"; this means that if you've +C is a "weak keyword"; this means that if you've defined a function by this name (before any calls to it), that function will be called instead. If you are not under C this does nothing. @@ -4663,7 +4663,7 @@ X =for Pod::Functions declare and assign a local variable (lexical scoping) -A L|/my VARLIST> declares the listed variables to be local +A C declares the listed variables to be local (lexically) to the enclosing block, file, or L|/eval EXPR>. If more than one variable is listed, the list must be placed in parentheses. @@ -4675,7 +4675,7 @@ values: my ( undef, $min, $hour ) = localtime; Like L|/state VARLIST>, L|/local EXPR>, and -L|/our VARLIST>, L|/my VARLIST> can operate on a variable +L|/our VARLIST>, C can operate on a variable anywhere it appears in an expression (aside from interpolation in strings). The declaration will not apply to additional uses of the same variable until the next statement. This means additional uses of that variable within the @@ -4710,7 +4710,7 @@ X X =for Pod::Functions iterate a block prematurely -The L|/next LABEL> command is like the C statement in +The C command is like the C statement in C; it starts the next iteration of the loop: LINE: while () { @@ -4725,24 +4725,24 @@ refers to the innermost enclosing loop. The C form, available as of Perl 5.18.0, allows a label name to be computed at run time, being otherwise identical to C. -L|/next LABEL> cannot return a value from a block that typically +C cannot return a value from a block that typically returns a value, such as C, C, or C. It will perform its flow control behavior, which precludes any return value. It should not be used to exit a L|/grep BLOCK LIST> or L|/map BLOCK LIST> operation. Note that a block by itself is semantically identical to a loop -that executes once. Thus L|/next LABEL> will exit such a block +that executes once. Thus C will exit such a block early. See also L|/continue BLOCK> for an illustration of how -L|/last LABEL>, L|/next LABEL>, and +L|/last LABEL>, C, and L|/redo LABEL> work. Unlike most named operators, this has the same precedence as assignment. It is also exempt from the looks-like-a-function rule, so C will cause "bar" to be part of the argument to -L|/next LABEL>. +C. =item no MODULE VERSION LIST X @@ -4759,7 +4759,7 @@ X =for Pod::Functions unimport some module symbols or semantics at compile time See the L|/use Module VERSION LIST> function, of which -L|/no MODULE VERSION LIST> is the opposite. +C is the opposite. =item oct EXPR X X X X X X @@ -4787,14 +4787,14 @@ L|/printf FILEHANDLE FORMAT, LIST>: my $dec_perms = (stat("filename"))[2] & 07777; my $oct_perm_str = sprintf "%o", $perms; -The L|/oct EXPR> function is commonly used when a string such as +The C function is commonly used when a string such as C<644> needs to be converted into a file mode, for example. Although Perl automatically converts strings into numbers as needed, this automatic conversion assumes base 10. Leading white space is ignored without warning, as too are any trailing -non-digits, such as a decimal point (L|/oct EXPR> only handles +non-digits, such as a decimal point (C only handles non-negative integers, not negative integers or floating point). =item open FILEHANDLE,MODE,EXPR @@ -4997,7 +4997,7 @@ is C<-|>, the filename is interpreted as a command that pipes output to us. In the two-argument (and one-argument) form, one should replace dash (C<->) with the command. See L for more examples of this. -(You are not allowed to L|/open FILEHANDLE,MODE,EXPR> to a command +(You are not allowed to C to a command that pipes both in I out, but see L, L, and L for alternatives.) @@ -5017,14 +5017,14 @@ alternatives.) In the form of pipe opens taking three or more arguments, if LIST is specified (extra arguments after the command name) then LIST becomes arguments to the command invoked if the platform supports it. The meaning of -L|/open FILEHANDLE,MODE,EXPR> with more than three arguments for +C with more than three arguments for non-pipe modes is not yet defined, but experimental "layers" may give extra LIST arguments meaning. If you open a pipe on the command C<-> (that is, specify either C<|-> or C<-|> with the one- or two-argument forms of -L|/open FILEHANDLE,MODE,EXPR>), an implicit L|/fork> is done, -so L|/open FILEHANDLE,MODE,EXPR> returns twice: in the parent process +C), an implicit L|/fork> is done, +so C returns twice: in the parent process it returns the pid of the child process, and in the child process it returns (a defined) C<0>. Use C or C to determine whether the open was successful. @@ -5173,7 +5173,7 @@ In the one- and two-argument forms of the call, the mode and filename should be concatenated (in that order), preferably separated by white space. You can--but shouldn't--omit the mode in these forms when that mode is C<< < >>. It is safe to use the two-argument form of -L|/open FILEHANDLE,MODE,EXPR> if the filename argument is a known literal. +C if the filename argument is a known literal. open(my $dbase, "+ should I be in effect.) =item Whitespace and special characters in the filename argument The filename passed to the one- and two-argument forms of -L|/open FILEHANDLE,MODE,EXPR> will +C will have leading and trailing whitespace deleted and normal redirection characters honored. This property, known as "magic open", can often be used to good effect. A user could specify a filename of @@ -5283,7 +5283,7 @@ otherwise it's necessary to protect any leading and trailing whitespace: (this may not work on some bizarre filesystems). One should conscientiously choose between the I and I form -of L|/open FILEHANDLE,MODE,EXPR>: +of C: open(my $in, $ARGV[0]) || die "Can't open $ARGV[0]: $!"; @@ -5302,7 +5302,7 @@ produces a filename that can be opened normally.) If you want a "real" C L, then you should use the L|/sysopen FILEHANDLE,FILENAME,MODE> function, which involves no such magic (but uses different filemodes than Perl -L|/open FILEHANDLE,MODE,EXPR>, which corresponds to C L). +C, which corresponds to C L). This is another way to protect your filenames from interpretation. For example: @@ -5371,21 +5371,21 @@ X X =for Pod::Functions +5.6.0 declare and assign a package variable (lexical scoping) -L|/our VARLIST> makes a lexical alias to a package (i.e. global) +C makes a lexical alias to a package (i.e. global) variable of the same name in the current package for use within the current lexical scope. -L|/our VARLIST> has the same scoping rules as +C has the same scoping rules as L|/my VARLIST> or L|/state VARLIST>, meaning that it is only valid within a lexical scope. Unlike L|/my VARLIST> and L|/state VARLIST>, which both declare new (lexical) variables, -L|/our VARLIST> only creates an alias to an existing variable: a +C only creates an alias to an existing variable: a package variable of the same name. This means that when C is in effect, L|/our VARLIST> lets you use a package variable without qualifying it with the package name, but only within the lexical scope of the -L|/our VARLIST> declaration. This applies immediately--even +C declaration. This applies immediately--even within the same statement. package Foo; @@ -5428,7 +5428,7 @@ in parentheses. our($bar, $baz); Like L|/my VARLIST>, L|/state VARLIST>, and -L|/local EXPR>, L|/our VARLIST> can operate on a variable +L|/local EXPR>, C can operate on a variable anywhere it appears in an expression (aside from interpolation in strings). The declaration will not apply to additional uses of the same variable until the next statement. This means additional uses of that variable within the @@ -5442,7 +5442,7 @@ that scope. foo($x, our $x = $x + 1, $x); # foo() receives (2, 3, 2) foo($x, our $z = 5, $z); # foo() receives (3, 5, 5) -An L|/our VARLIST> declaration declares an alias for a package +An C declaration declares an alias for a package variable that will be visible across its entire lexical scope, even across package boundaries. The package in which the variable is entered is determined at the point @@ -5456,13 +5456,13 @@ behavior holds: package Bar; print $bar; # prints 20, as it refers to $Foo::bar -Multiple L|/our VARLIST> declarations with the same name in the +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 L|/my VARLIST> declarations. Unlike a second L|/my VARLIST> declaration, which will bind the name to a -fresh variable, a second L|/our VARLIST> declaration in the same +fresh variable, a second C declaration in the same package, in the same scope, is merely redundant. use warnings; @@ -5477,7 +5477,7 @@ package, in the same scope, is merely redundant. our $bar; # emits warning but has no other effect print $bar; # still prints 30 -An L|/our VARLIST> declaration may also have a list of attributes +An C declaration may also have a list of attributes associated with it. The exact semantics and interface of TYPE and ATTRS are still @@ -5492,7 +5492,7 @@ values: our ( undef, $min, $hour ) = localtime; -L|/our VARLIST> creates a lexically scoped alias to the package +C creates a lexically scoped alias to the package variable of the same name, and as such differs from L|vars>, which allows use of an unqualified name I within the affected package, without consideration for scopes. @@ -5748,7 +5748,7 @@ On unpacking, bits are converted to a string of C<0>s and C<1>s. The C and C formats pack a string that many nybbles (4-bit groups, representable as hexadecimal digits, C<"0".."9"> C<"a".."f">) long. -For each such format, L|/pack TEMPLATE,LIST> generates 4 bits of result. +For each such format, C generates 4 bits of result. With 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 @@ -5758,7 +5758,7 @@ C<"A"> both generate the nybble C<0xA==10>. Use only these specific hex characters with this format. Starting from the beginning of the template to -L|/pack TEMPLATE,LIST>, each pair +C, each pair 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; with format C, it determines the most-significant @@ -5798,13 +5798,13 @@ the packed items themselves. This is useful when the structure you're unpacking has encoded the sizes or repeat counts for some of its fields within the structure itself as separate fields. -For L|/pack TEMPLATE,LIST>, you write +For C, you write ICI, and the I describes how the length value is packed. Formats 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 L|/pack TEMPLATE,LIST>, I may have a repeat +For C, I may have a repeat count, in which case the minimum of that and the number of available items is used as the argument for I. If it has no repeat count or uses a '*', the number @@ -6035,14 +6035,14 @@ is what you want: C3.8E.C2.B1.C3.8F.C2.89 Those examples also illustrate that you should not try to use -L|/pack TEMPLATE,LIST>/L|/unpack TEMPLATE,EXPR> as a +C/L|/unpack TEMPLATE,EXPR> as a substitute for the L module. =item * You must yourself do any alignment or padding by inserting, for example, enough C<"x">es while packing. There is no way for -L|/pack TEMPLATE,LIST> and L|/unpack TEMPLATE,EXPR> +C and L|/unpack TEMPLATE,EXPR> to know where characters are going to or coming from, so they handle their output and input as flat sequences of characters. @@ -6064,7 +6064,7 @@ is the string C<"\0X\0\0YZ">. C and C accept the C modifier to act as alignment commands: they jump forward or back to the closest position aligned at a multiple of C -characters. For example, to L|/pack TEMPLATE,LIST> or +characters. For example, to C or L|/unpack TEMPLATE,EXPR> a C structure like struct { @@ -6098,8 +6098,8 @@ for complicated pattern matches. =item * -If TEMPLATE requires more arguments than L|/pack TEMPLATE,LIST> -is given, L|/pack TEMPLATE,LIST> +If TEMPLATE requires more arguments than C +is given, C assumes additional C<""> arguments. If TEMPLATE requires fewer arguments than given, extra arguments are ignored. @@ -6206,7 +6206,7 @@ operative through the end of the current scope, just like the L|/my VARLIST>, L|/state VARLIST>, and L|/our VARLIST> operators. All unqualified dynamic identifiers in this scope will be in the given namespace, except where overridden by -another L|/package NAMESPACE> declaration or +another C declaration or when they're one of the special identifiers that qualify into C, like C, C, C, and the punctuation variables. @@ -6226,7 +6226,7 @@ package is assumed. That is, C<$::sail> is equivalent to C<$main::sail> (as well as to C<$main'sail>, still seen in ancient code, mostly from Perl 4). -If VERSION is provided, L|/package NAMESPACE> sets the +If VERSION is provided, C sets the C<$VERSION> variable in the given namespace to a L object with the VERSION provided. VERSION must be a "strict" style version number as defined by the L module: a positive @@ -6264,7 +6264,7 @@ class methods, before the instance is fully constructed. } In a basic class, this value will be the same as -L|/__PACKAGE__>. The distinction can be seen when a subclass +C<__PACKAGE__>. The distinction can be seen when a subclass is constructed; it will give the class name of the instance being constructed, rather than just the package name that the actual code belongs to. @@ -6327,7 +6327,7 @@ will operate on the C<@ARGV> array in C, C, C, C blocks. Starting with Perl 5.14, an experimental feature allowed -L|/pop ARRAY> to take a +C to take a scalar expression. This experiment has been deemed unsuccessful, and was removed as of Perl 5.24. @@ -6347,20 +6347,20 @@ L|/undef EXPR> indicates that the search position is reset (usually due to match failure, but can also be because no match has yet been run on the scalar). -L|/pos SCALAR> directly accesses the location used by the regexp -engine to store the offset, so assigning to L|/pos SCALAR> will +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. Both of these effects take place for the next match, so you can't affect the position with -L|/pos SCALAR> during the current match, such as in +C during the current match, such as in C<(?{pos() = 5})> or C. -Setting L|/pos SCALAR> also resets the I also resets the I flag, described under L. Because a failed C match doesn't reset the offset, the return -from L|/pos SCALAR> won't change either in this case. See +from C won't change either in this case. See L and L. =item print FILEHANDLE LIST @@ -6392,7 +6392,7 @@ each LIST item. The current value of L|perlvar/$\> (if any) is printed after the entire LIST has been printed. Because print takes a LIST, anything in the LIST is evaluated in list context, including any subroutines whose return lists you pass to -L|/print FILEHANDLE LIST>. Be careful not to follow the print +C. Be careful not to follow the print keyword with a left parenthesis unless you want the corresponding right parenthesis to terminate the arguments to the print; put parentheses around all arguments @@ -6444,7 +6444,7 @@ L are enabled. Just use L|/print FILEHANDLE LIST> if you want to print the contents of L|perlvar/$_>. Don't fall into the trap of using a -L|/printf FILEHANDLE FORMAT, LIST> when a simple +C when a simple L|/print FILEHANDLE LIST> would do. The L|/print FILEHANDLE LIST> is more efficient and less error prone. @@ -6465,7 +6465,7 @@ L|perlvar/$_> is used. If FUNCTION is a string starting with C, the rest is taken as a name for a Perl builtin. If the builtin's arguments cannot be adequately expressed by a prototype -(such as L|/system LIST>), L|/prototype FUNCTION> +(such as L|/system LIST>), C returns L|/undef EXPR>, because the builtin does not really behave like a Perl function. Otherwise, the string describing the equivalent prototype is returned. @@ -6484,14 +6484,14 @@ Adds one or more items to the B of an array. push(@colors, ("blue", "green")); # ("red", "blue", "green") Returns the number of elements in the array following the completed -L|/push ARRAY,LIST>. +C. my $color_count = push(@colors, ("yellow", "purple")); say "There are $color_count colors in the updated array"; Starting with Perl 5.14, an experimental feature allowed -L|/push ARRAY,LIST> to take a +C to take a scalar expression. This experiment has been deemed unsuccessful, and was removed as of Perl 5.24. @@ -6561,7 +6561,7 @@ Or: Will both leave the sentence as is. Normally, when accepting literal string input from the user, -L|/quotemeta EXPR> or C<\Q> must be used. +C or C<\Q> must be used. Beware that if you put literal backslashes (those not inside interpolated variables) between C<\Q> and C<\E>, double-quotish @@ -6676,7 +6676,7 @@ for crypto safe alternatives. =item B -B|/rand EXPR> is not cryptographically secure. You should not rely +B is not cryptographically secure. You should not rely on it in security-sensitive situations.> As of this writing, a number of third-party CPAN modules offer random number generators intended by their authors to be cryptographically secure, @@ -6755,7 +6755,7 @@ directory. If there are no more entries, returns the undefined value in scalar context and the empty list in list context. If you're planning to filetest the return values out of a -L|/readdir DIRHANDLE>, you'd better prepend the directory in +C, you'd better prepend the directory in question. Otherwise, because we didn't L|/chdir EXPR> there, it would have been testing the wrong file. @@ -6763,7 +6763,7 @@ it would have been testing the wrong file. my @dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh); closedir $dh; -As of Perl 5.12 you can use a bare L|/readdir DIRHANDLE> in a +As of Perl 5.12 you can use a bare C in a C loop, which will set L|perlvar/$_> on every iteration. If either a C expression or an explicit assignment of a C expression to a scalar is used as a C/C condition, @@ -6800,7 +6800,7 @@ L>|perlvar/$E> (or C<$INPUT_RECORD_SEPARATOR> in L). See L. When L>|perlvar/$E> is set to L|/undef EXPR>, -when L|/readline EXPR> is in scalar context (i.e., file +when C is in scalar context (i.e., file slurp mode), and when an empty file is read, it returns C<''> the first time, followed by L|/undef EXPR> subsequently. @@ -6811,11 +6811,11 @@ operator is discussed in more detail in L. my $line = ; my $line = readline(STDIN); # same thing -If L|/readline EXPR> encounters an operating system error, +If C encounters an operating system error, L|perlvar/$!> will be set with the corresponding error message. It can be helpful to check L|perlvar/$!> when you are reading from filehandles you don't trust, such as a tty or a socket. The following -example uses the operator form of L|/readline EXPR> and dies +example uses the operator form of C and dies if the result is not defined. while ( ! eof($fh) ) { @@ -6823,7 +6823,7 @@ if the result is not defined. ... } -Note that you can't handle L|/readline EXPR> errors +Note that you can't handle C errors that way with the C filehandle. In that case, you have to open each element of L|perlvar/@ARGV> yourself since L|/eof FILEHANDLE> handles C differently. @@ -6904,7 +6904,7 @@ X =for Pod::Functions start this loop iteration over again -The L|/redo LABEL> command restarts the loop block without +The C command restarts the loop block without evaluating the conditional again. The L|/continue BLOCK> block, if any, is not executed. If the LABEL is omitted, the command refers to the innermost enclosing @@ -6930,24 +6930,24 @@ normally use this command: print; } -L|/redo LABEL> cannot return a value from a block that typically +C cannot return a value from a block that typically returns a value, such as C, C, or C. It will perform its flow control behavior, which precludes any return value. It should not be used to exit a L|/grep BLOCK LIST> or L|/map BLOCK LIST> operation. Note that a block by itself is semantically identical to a loop -that executes once. Thus L|/redo LABEL> inside such a block +that executes once. Thus C inside such a block will effectively turn it into a looping construct. See also L|/continue BLOCK> for an illustration of how L|/last LABEL>, L|/next LABEL>, and -L|/redo LABEL> work. +C work. Unlike most named operators, this has the same precedence as assignment. It is also exempt from the looks-like-a-function rule, so C will cause "bar" to be part of the argument to -L|/redo LABEL>. +C. =item ref EXPR X X @@ -7058,7 +7058,7 @@ older code. require 5.024_001; # ditto; older syntax compatible with perl 5.6 -Otherwise, L|/require VERSION> demands that a library file be +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 L|/eval EXPR> with the @@ -7132,7 +7132,7 @@ affects the compilation unit within which the feature is used, and using it before requiring a module will not change the behavior of existing modules that do not themselves also use it. -If EXPR is a bareword, L|/require VERSION> assumes a F<.pm> +If EXPR is a bareword, C assumes a F<.pm> extension and replaces C<::> with C in the filename for you, to make it easy to load standard modules. This form of loading of modules does not risk altering your namespace, however it will autovivify @@ -7166,9 +7166,9 @@ or you could do Neither of these forms will autovivify any stashes at compile time and only have run time effects. -Now that you understand how L|/require VERSION> looks for +Now that you understand how C looks for files with a bareword argument, there is a little extra functionality -going on behind the scenes. Before L|/require VERSION> looks +going on behind the scenes. Before C looks for a F<.pm> extension, it will first look for a similar filename with a F<.pmc> extension. If this file is found, it will be loaded in place of any file ending in a F<.pm> extension. This applies to both the explicit @@ -7223,7 +7223,7 @@ C cannot be used to resolve the C method, C is checked first, and C would resolve that. If an empty list, L|/undef EXPR>, or nothing that matches the -first 3 values above is returned, then L|/require VERSION> +first 3 values above is returned, then C looks at the remaining elements of L|perlvar/@INC>. Note that this filehandle must be a real filehandle (strictly a typeglob or reference to a typeglob, whether blessed or unblessed); tied filehandles @@ -7453,14 +7453,14 @@ L|/wantarray>). If no EXPR is given, returns an empty list in list context, the undefined value in scalar context, and (of course) nothing at all in void context. -(In the absence of an explicit L|/return EXPR>, a subroutine, +(In the absence of an explicit C, a subroutine, L|/eval EXPR>, or L|/do EXPR> automatically returns the value of the last expression evaluated.) Unlike most named operators, this is also exempt from the looks-like-a-function rule, so C will -cause C<"bar"> to be part of the argument to L|/return EXPR>. +cause C<"bar"> to be part of the argument to C. =item reverse LIST X X X @@ -7476,7 +7476,7 @@ in the opposite order. print scalar reverse "dlrow ,", "olleH"; # Hello, world -Used without arguments in scalar context, L|/reverse LIST> +Used without arguments in scalar context, C reverses L|perlvar/$_>. $_ = "dlrow ,olleH"; @@ -7556,7 +7556,7 @@ might have. To use FILEHANDLE without a LIST to print the contents of L|perlvar/$_> to it, you must use a bareword filehandle like C, not an indirect one like C<$fh>. -L|/say FILEHANDLE LIST> is available only if the +C is available only if the L feature|feature/The 'say' feature> is enabled or if it is prefixed with C. The L feature|feature/The 'say' feature> is enabled automatically @@ -7578,7 +7578,7 @@ needed. If you really wanted to do so, however, you could use the construction C<@{[ (some expression) ]}>, but usually a simple C<(some expression)> suffices. -Because L|/scalar EXPR> is a unary operator, if you +Because C is a unary operator, if you accidentally use a parenthesized list for the EXPR, this behaves as a scalar comma expression, evaluating all but the last element in void context and returning the final @@ -7613,7 +7613,7 @@ otherwise. Note the emphasis on bytes: even if the filehandle has been set to operate on characters (for example using the C<:encoding(UTF-8)> I/O layer), the -L|/seek FILEHANDLE,POSITION,WHENCE>, +C, L|/tell FILEHANDLE>, and L|/sysseek FILEHANDLE,POSITION,WHENCE> family of functions use byte offsets, not character offsets, @@ -7622,7 +7622,7 @@ because seeking to a character offset would be very slow in a UTF-8 file. If you want to position the file for L|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET> or L|/syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET>, don't use -L|/seek FILEHANDLE,POSITION,WHENCE>, because buffering makes its +C, because buffering makes its effect on the file's read-write position unpredictable and non-portable. Use L|/sysseek FILEHANDLE,POSITION,WHENCE> instead. @@ -7635,8 +7635,8 @@ A WHENCE of C<1> (C) is useful for not moving the file position: This is also useful for applications emulating C. Once you hit EOF on your read and then sleep for a while, you (probably) have to stick in a -dummy L|/seek FILEHANDLE,POSITION,WHENCE> to reset things. The -L|/seek FILEHANDLE,POSITION,WHENCE> doesn't change the position, +dummy C to reset things. The +C doesn't change the position, but it I clear the end-of-file condition on the handle, so that the next C makes Perl try again to read something. (We hope.) @@ -7659,7 +7659,7 @@ X Sets the current position for the L|/readdir DIRHANDLE> routine on DIRHANDLE. POS must be a value returned by -L|/telldir DIRHANDLE>. L|/seekdir DIRHANDLE,POS> +L|/telldir DIRHANDLE>. C also has the same caveats about possible directory compaction as the corresponding system library routine. @@ -7765,7 +7765,7 @@ or to block until something becomes ready just do this select(my $rout = $rin, my $wout = $win, my $eout = $ein, undef); Most systems do not bother to return anything useful in C<$timeleft>, so -calling L|/select RBITS,WBITS,EBITS,TIMEOUT> in scalar context +calling C gets restarted after signals (say, SIGALRM) is implementation-dependent. See also L for notes on the portability of -L|/select RBITS,WBITS,EBITS,TIMEOUT>. +C behaves just like L: it returns C<-1> and sets L|perlvar/$!>. On some Unixes, L may report a socket file descriptor as @@ -7794,13 +7794,13 @@ L and L for further details. The standard L|IO::Select> module provides a user-friendlier interface to -L|/select RBITS,WBITS,EBITS,TIMEOUT>, mostly because it does +C, except as permitted by POSIX, and even then only on POSIX systems. You have to use L|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET> instead. @@ -7888,7 +7888,7 @@ Sets the current process group for the specified PID, C<0> for the current process. Raises an exception when used on a machine that doesn't implement POSIX L or BSD L. If the arguments are omitted, it defaults to C<0,0>. Note that the BSD 4.2 version of -L|/setpgrp PID,PGRP> does not accept any arguments, so only +C does not accept any arguments, so only C is portable. See also L|POSIX/C>. @@ -7955,12 +7955,12 @@ program, and the C<@_> array in subroutines. C will operate on the C<@ARGV> array in C, C, C, C blocks. Starting with Perl 5.14, an experimental feature allowed -L|/shift ARRAY> to take a +C to take a scalar expression. This experiment has been deemed unsuccessful, and was removed as of Perl 5.24. See also L|/unshift ARRAY,LIST>, L|/push ARRAY,LIST>, -and L|/pop ARRAY>. L|/shift ARRAY> and +and L|/pop ARRAY>. C and L|/unshift ARRAY,LIST> do the same thing to the left end of an array that L|/pop ARRAY> and L|/push ARRAY,LIST> do to the right end. @@ -8011,7 +8011,7 @@ detaching from it. When reading, VAR must be a variable that will hold the data read. When writing, if STRING is too long, only SIZE bytes are used; if STRING is too short, nulls are written to fill out SIZE bytes. Return true if successful, false on error. -L|/shmread ID,VAR,POS,SIZE> taints the variable. See also +C taints the variable. See also L and the documentation for L|IPC::SysV> and the L|IPC::Shareable> module from CPAN. @@ -8066,7 +8066,7 @@ Causes the script to sleep for (integer) EXPR seconds, or forever if no argument is given. Returns the integer number of seconds actually slept. EXPR should be a positive integer. If called with a negative integer, -L|/sleep EXPR> does not sleep but instead emits a warning, sets +C does not sleep but instead emits a warning, sets C<$!> (C), and returns zero. If called with a non-integer, the fractional part is ignored. @@ -8085,7 +8085,7 @@ May be interrupted if the process receives a signal such as C. die $@ unless $@ eq "Alarm!\n"; You probably cannot mix L|/alarm SECONDS> and -L|/sleep EXPR> calls, because L|/sleep EXPR> is often +C calls, because C is often implemented using L|/alarm SECONDS>. On some older systems, it may sleep up to a full second less than what @@ -8135,7 +8135,7 @@ be set for the newly opened file descriptors, as determined by the value of L|perlvar/$^F>. See L. Some systems define L|/pipe READHANDLE,WRITEHANDLE> in terms of -L|/socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL>, in +C, in which a call to C is essentially: use Socket; @@ -8159,10 +8159,10 @@ X =for Pod::Functions sort a list of values In list context, this sorts the LIST and returns the sorted list value. -In scalar context, the behaviour of L|/sort SUBNAME LIST> is +In scalar context, the behaviour of C is undefined. -If SUBNAME or BLOCK is omitted, L|/sort SUBNAME LIST>s in +If SUBNAME or BLOCK is omitted, Cs in standard string comparison order. If SUBNAME is specified, it gives the name of a subroutine that returns a numeric value less than, equal to, or greater than C<0>, @@ -8198,9 +8198,9 @@ When L|locale> (but not C) is in effect, C sorts LIST according to the current collation locale. See L. -L|/sort SUBNAME LIST> returns aliases into the original list, +C returns aliases into the original list, much as a for loop's index variable aliases the list elements. That is, -modifying an element of a list returned by L|/sort SUBNAME LIST> +modifying an element of a list returned by C (for example, in a C, L|/map BLOCK LIST> or L|/grep BLOCK LIST>) actually modifies the element in the original list. This is usually @@ -8419,7 +8419,7 @@ The following equivalences hold (assuming C<< $#a >= $i >> ) unshift(@a,$x,$y) splice(@a,0,0,$x,$y) $a[$i] = $y splice(@a,$i,1,$y) -L|/splice ARRAY,OFFSET,LENGTH,LIST> can be used, for example, +C can be used, for example, to implement n-ary queue processing: sub nary_print { @@ -8436,7 +8436,7 @@ to implement n-ary queue processing: # g -- h Starting with Perl 5.14, an experimental feature allowed -L|/splice ARRAY,OFFSET,LENGTH,LIST> to take a +C to take a scalar expression. This experiment has been deemed unsuccessful, and was removed as of Perl 5.24. @@ -8480,7 +8480,7 @@ However, this: uses empty string matches as separators; thus, the empty string may be used to split EXPR into a list of its component characters. -As a special case for L|/split EPATTERNE,EXPR,LIMIT>, +As a special case for CPATTERNE,EXPR,LIMIT>, the empty pattern given in L syntax (C) specifically matches the empty string, which is contrary to its usual @@ -8495,7 +8495,7 @@ Cm> and any of the other pattern modifiers valid for C specified explicitly. As another special case, -L|/split EPATTERNE,EXPR,LIMIT> emulates the default +CPATTERNE,EXPR,LIMIT> emulates the default behavior of the command line tool B when the PATTERN is either omitted or a string composed of a single space character (such as S> or @@ -8632,8 +8632,8 @@ X =for Pod::Functions formatted print into a string Returns a string formatted by the usual -L|/printf FILEHANDLE FORMAT, LIST> conventions of the C -library function L|/sprintf FORMAT, LIST>. See below for +C conventions of the C +library function C. See below for more details and see L or L on your system for an explanation of the general principles. @@ -8645,22 +8645,22 @@ For example: # Round number to 3 digits after decimal point my $rounded = sprintf("%.3f", $number); -Perl does its own L|/sprintf FORMAT, LIST> formatting: it +Perl does its own C formatting: it emulates the C function L, but doesn't use it except for floating-point numbers, and even then only standard modifiers are allowed. Non-standard extensions in your local L are therefore unavailable from Perl. -Unlike L|/printf FILEHANDLE FORMAT, LIST>, -L|/sprintf FORMAT, LIST> does not do what you probably mean +Unlike C, +C does not do what you probably mean when you pass it an array as your first argument. The array is given scalar context, and instead of using the 0th element of the array as the format, Perl will use the count of elements in the array as the format, which is almost never useful. -Perl's L|/sprintf FORMAT, LIST> permits the following +Perl's C permits the following universally-known conversions: %% a percent sign @@ -8955,7 +8955,7 @@ integer or floating-point number", which is the default. =item order of arguments -Normally, L|/sprintf FORMAT, LIST> takes the next unused +Normally, C takes the next unused argument as the value to format for each format specification. If the format specification uses C<*> to require additional arguments, these are consumed from @@ -9022,33 +9022,33 @@ operator. The point of the function is to "seed" the L|/rand EXPR> function so that L|/rand EXPR> can produce a different sequence each time you run your program. When called with a parameter, -L|/srand EXPR> uses that for the seed; otherwise it +C uses that for the seed; otherwise it (semi-)randomly chooses a seed (see below). In either case, starting with Perl 5.14, it returns the seed. To signal that your code will work I on Perls of a recent vintage: use v5.14; # so srand returns the seed -If L|/srand EXPR> is not called explicitly, it is called +If C is not called explicitly, it is called implicitly without a parameter at the first use of the L|/rand EXPR> operator. However, there are a few situations -where programs are likely to want to call L|/srand EXPR>. One +where programs are likely to want to call C. One is for generating predictable results, generally for testing or debugging. There, you use C, with the same C<$seed> each -time. Another case is that you may want to call L|/srand EXPR> +time. Another case is that you may want to call C after a L|/fork> to avoid child processes sharing the same seed value as the parent (and consequently each other). Do B call C (i.e., without an argument) more than once per process. The internal state of the random number generator should contain more entropy than can be provided by any seed, so calling -L|/srand EXPR> again actually I randomness. +C again actually I randomness. -Most implementations of L|/srand EXPR> take an integer and will +Most implementations of C take an integer and will silently truncate decimal numbers. This means C will usually produce the same results as C. To be safe, always pass -L|/srand EXPR> an integer. +C an integer. A typical use of the returned seed is for a test program which has too many combinations to test comprehensively in the time available to it each run. It @@ -9087,7 +9087,7 @@ X X X Returns a 13-element list giving the status info for a file, either the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR. If EXPR is omitted, it stats L|perlvar/$_> (not C<_>!). Returns the empty -list if L|/stat FILEHANDLE> fails. Typically +list if C fails. Typically used as follows: my ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size, @@ -9119,9 +9119,9 @@ meanings of the fields: ctime field is non-portable. In particular, you cannot expect it to be a "creation time"; see L for details. -If L|/stat FILEHANDLE> is passed the special filehandle +If C is passed the special filehandle consisting of an underline, no stat is done, but the current contents of -the stat structure from the last L|/stat FILEHANDLE>, +the stat structure from the last C, L|/lstat FILEHANDLE>, or filetest are returned. Example: if (-x $file && (($d) = stat(_)) && $d < 0) { @@ -9147,7 +9147,7 @@ if you want to see the real permissions. my $mode = (stat($filename))[2]; printf "Permissions are %04o\n", $mode & 07777; -In scalar context, L|/stat FILEHANDLE> returns a boolean value +In scalar context, C returns a boolean value indicating success or failure, and, if successful, sets the information associated with the special filehandle C<_>. @@ -9238,7 +9238,7 @@ X =for Pod::Functions +state declare and assign a persistent lexical variable -L|/state VARLIST> declares a lexically scoped variable, just +C declares a lexically scoped variable, just like L|/my VARLIST>. However, those variables will never be reinitialized, contrary to lexical variables that are reinitialized each time their enclosing block @@ -9252,7 +9252,7 @@ dummy placeholder. However, since initialization of state variables in such lists is currently not possible this would serve no purpose. Like L|/my VARLIST>, L|/local EXPR>, and -L|/our VARLIST>, L|/state VARLIST> can operate on a variable +L|/our VARLIST>, C can operate on a variable anywhere it appears in an expression (aside from interpolation in strings). The declaration will not apply to additional uses of the same variable until the next statement. This means additional uses of that variable within the @@ -9270,7 +9270,7 @@ previous declaration, creating a new instance and preventing access to the previous one. This is usually undesired and, if warnings are enabled, will result in a warning in the C category. -L|/state VARLIST> is available only if the +C is available only if the L feature|feature/The 'state' feature> is enabled or if it is prefixed with C. The L feature|feature/The 'state' feature> is enabled @@ -9351,7 +9351,7 @@ many characters off the end of the string. my $tail = substr $s, -4; # tree my $z = substr $s, -4, 2; # tr -You can use the L|/substr EXPR,OFFSET,LENGTH,REPLACEMENT> +You can use the C function as an lvalue, in which case EXPR must itself be an lvalue. If you assign something shorter than LENGTH, the string will shrink, and if you assign something longer than LENGTH, @@ -9362,7 +9362,7 @@ L|/sprintf FORMAT, LIST>. If OFFSET and LENGTH specify a substring that is partly outside the string, only the part within the string is returned. If the substring is beyond either end of the string, -L|/substr EXPR,OFFSET,LENGTH,REPLACEMENT> returns the undefined +C returns the undefined value and produces a warning. When used as an lvalue, specifying a substring that is entirely outside the string raises an exception. Here's an example showing the behavior for boundary cases: @@ -9374,7 +9374,7 @@ Here's an example showing the behavior for boundary cases: substr($name, 7) = 'gap'; # raises an exception An alternative to using -L|/substr EXPR,OFFSET,LENGTH,REPLACEMENT> as an lvalue is to +C as an lvalue is to specify the REPLACEMENT string as the 4th argument. This allows you to replace parts of the EXPR and return what was there before in one operation, @@ -9386,7 +9386,7 @@ L|/splice ARRAY,OFFSET,LENGTH,LIST>. # $s is now "The black cat jumped from the green tree" Note that the lvalue returned by the three-argument version of -L|/substr EXPR,OFFSET,LENGTH,REPLACEMENT> acts as +C acts as a 'magic bullet'; each time it is assigned to, it remembers which part of the original string is being modified; for example: @@ -9439,7 +9439,7 @@ an int. If not, the pointer to the string value is passed. You are responsible to make sure a string is pre-extended long enough to receive any result that might be written into a string. You can't use a string literal (or other read-only string) as an argument to -L|/syscall NUMBER, LIST> because Perl has to assume that any +C because Perl has to assume that any string pointer might be written through. If your integer arguments are not literals and have never been interpreted in a numeric context, you may need to add C<0> to them to force them to look @@ -9455,12 +9455,12 @@ Note that Perl supports passing of up to only 14 arguments to your syscall, which in practice should (usually) suffice. Syscall returns whatever value returned by the system call it calls. -If the system call fails, L|/syscall NUMBER, LIST> returns +If the system call fails, C returns C<-1> and sets L|perlvar/$!> (errno). Note that some system calls I legitimately return C<-1>. The proper way to handle such calls is to assign C<$! = 0> before the call, then check the value of L|perlvar/$!> if -L|/syscall NUMBER, LIST> returns C<-1>. +C returns C<-1>. There's a problem with C: it returns the file number of the read end of the pipe it creates, but there is no way @@ -9514,7 +9514,7 @@ If the file named by FILENAME does not exist and the L|/open FILEHANDLE,MODE,EXPR> call creates it (typically because MODE includes the C flag), then the value of PERMS specifies the permissions of the newly created file. If you omit -the PERMS argument to L|/sysopen FILEHANDLE,FILENAME,MODE>, +the PERMS argument to C, Perl uses the octal value C<0666>. These permission values need to be in octal, and are modified by your process's current L|/umask EXPR>. @@ -9523,7 +9523,7 @@ X In many systems the C flag is available for opening files in exclusive mode. This is B locking: exclusiveness means here that if the file already exists, -L|/sysopen FILEHANDLE,FILENAME,MODE> fails. C may +C fails. C may not work on network filesystems, and has no effect unless the C flag is set as well. Setting C prevents the file from @@ -9537,7 +9537,7 @@ C with C is undefined. X You should seldom if ever use C<0644> as argument to -L|/sysopen FILEHANDLE,FILENAME,MODE>, because +C, because that takes away the user's option to have a more permissive umask. Better to omit it. See L|/umask EXPR> for more on this. @@ -9549,7 +9549,7 @@ this function can be used with buffered IO just as one opened with L|/open FILEHANDLE,MODE,EXPR> can be used with unbuffered IO. Note that under Perls older than 5.8.0, -L|/sysopen FILEHANDLE,FILENAME,MODE> depends on the +C depends on the L C library function. On many Unix systems, L is known to fail when file descriptors exceed a certain value, typically 255. If you need more file descriptors than that, consider using the @@ -9602,7 +9602,7 @@ bytes before the result of the read is appended. There is no syseof() function, which is ok, since L|/eof FILEHANDLE> doesn't work well on device files (like ttys) -anyway. Use L|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET> and +anyway. Use C and check for a return value of 0 to decide whether you're done. Note that if the filehandle has been marked as C<:utf8>, C will @@ -9626,11 +9626,11 @@ Note the emphasis on bytes: even if the filehandle has been set to operate on characters (for example using the C<:encoding(UTF-8)> I/O layer), the L|/seek FILEHANDLE,POSITION,WHENCE>, L|/tell FILEHANDLE>, and -L|/sysseek FILEHANDLE,POSITION,WHENCE> +C family of functions use byte offsets, not character offsets, because seeking to a character offset would be very slow in a UTF-8 file. -L|/sysseek FILEHANDLE,POSITION,WHENCE> bypasses normal +C bypasses normal buffered IO, so mixing it with reads other than L|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET> (for example L|/readline EXPR> or @@ -9650,7 +9650,7 @@ than relying on 0, 1, and 2. For example to define a "systell" function: Returns the new position, or the undefined value on failure. A position of zero is returned as the string C<"0 but true">; thus -L|/sysseek FILEHANDLE,POSITION,WHENCE> returns +C returns true on success and false on failure, yet you can still easily determine the new position. @@ -9694,15 +9694,15 @@ L. Return value of -1 indicates a failure to start the program or an error of the L system call (inspect L|perlvar/$!> for the reason). -If you'd like to make L|/system LIST> (and many other bits of +If you'd like to make C (and many other bits of Perl) die on error, have a look at the L pragma. -Like L|/exec LIST>, L|/system LIST> allows you to lie +Like L|/exec LIST>, C allows you to lie to a program about its name if you use the C syntax. Again, see L|/exec LIST>. Since C and C are ignored during the execution of -L|/system LIST>, if you expect your program to terminate on +C, if you expect your program to terminate on receipt of these signals you will need to arrange to do so yourself based on the return value. @@ -9710,7 +9710,7 @@ based on the return value. system(@args) == 0 or die "system @args failed: $?"; -If you'd like to manually inspect L|/system LIST>'s failure, +If you'd like to manually inspect C's failure, you can check all possible failure modes by inspecting L|perlvar/$?> like this: @@ -9729,11 +9729,11 @@ Alternatively, you may inspect the value of L|perlvar/${^CHILD_ERROR_NATIVE}> with the L|POSIX/C> calls from the L module. -When L|/system LIST>'s arguments are executed indirectly by +When C's arguments are executed indirectly by the shell, results and return codes are subject to its quirks. See L and L|/exec LIST> for details. -Since L|/system LIST> does a L|/fork> and +Since C does a L|/fork> and L|/wait> it may affect a C handler. See L for details. @@ -9791,25 +9791,25 @@ last read. Note the emphasis on bytes: even if the filehandle has been set to operate on characters (for example using the C<:encoding(UTF-8)> I/O layer), the L|/seek FILEHANDLE,POSITION,WHENCE>, -L|/tell FILEHANDLE>, and +C, and L|/sysseek FILEHANDLE,POSITION,WHENCE> family of functions use byte offsets, not character offsets, because seeking to a character offset would be very slow in a UTF-8 file. -The return value of L|/tell FILEHANDLE> for the standard streams +The return value of C for the standard streams like the STDIN depends on the operating system: it may return -1 or -something else. L|/tell FILEHANDLE> on pipes, fifos, and +something else. C on pipes, fifos, and sockets usually returns -1. There is no C function. Use L|/sysseek FILEHANDLE,POSITION,WHENCE> for that. -Do not use L|/tell FILEHANDLE> (or other buffered I/O +Do not use C (or other buffered I/O operations) on a filehandle that has been manipulated by L|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>, L|/syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET>, or L|/sysseek FILEHANDLE,POSITION,WHENCE>. Those functions -ignore the buffering, while L|/tell FILEHANDLE> does not. +ignore the buffering, while C does not. =item telldir DIRHANDLE X @@ -9819,7 +9819,7 @@ X Returns the current position of the L|/readdir DIRHANDLE> routines on DIRHANDLE. Value may be given to L|/seekdir DIRHANDLE,POS> to access a particular location in -a directory. L|/telldir DIRHANDLE> has the same caveats +a directory. C has the same caveats about possible directory compaction as the corresponding system library routine. @@ -9837,7 +9837,7 @@ method of the class (meaning C, C, C, or C). Typically these are arguments such as might be passed to the L function of C. The object returned by the constructor is also returned by the -L|/tie VARIABLE,CLASSNAME,LIST> function, which would be useful +C function, which would be useful if you want to access other methods in CLASSNAME. Note that functions such as L|/keys HASH> and @@ -9916,11 +9916,11 @@ Not all methods indicated above need be implemented. See L, L, L, L, and L. Unlike L|/dbmopen HASH,DBNAME,MASK>, the -L|/tie VARIABLE,CLASSNAME,LIST> function will not +C function will not L|/use Module VERSION LIST> or L|/require VERSION> a module for you; you need to do that explicitly yourself. See L or the L module for interesting -L|/tie VARIABLE,CLASSNAME,LIST> implementations. +C implementations. For further details see L, L|/tied VARIABLE>. @@ -9967,7 +9967,7 @@ seconds for this process and any exited children of this process. my ($user,$system,$cuser,$csystem) = times; -In scalar context, L|/times> returns C<$user>. +In scalar context, C returns C<$user>. Children's times are only included for terminated children. @@ -10058,7 +10058,7 @@ If EXPR is omitted, merely returns the current umask. The Unix permission C is represented as three sets of three bits, or three octal digits: C<0750> (the leading 0 indicates octal -and isn't one of the digits). The L|/umask EXPR> value is such +and isn't one of the digits). The C value is such a number representing disabled permissions bits. The permission (or "mode") values you pass L|/mkdir FILENAME,MODE> or L|/sysopen FILEHANDLE,FILENAME,MODE> are modified by your @@ -10066,7 +10066,7 @@ umask, so even if you tell L|/sysopen FILEHANDLE,FILENAME,MODE> to create a file with permissions C<0777>, if your umask is C<0022>, then the file will actually be created with permissions C<0755>. If your -L|/umask EXPR> were C<0027> (group can't write; others can't +C were C<0027> (group can't write; others can't read, write, or execute), then passing L|/sysopen FILEHANDLE,FILENAME,MODE> C<0666> would create a file with mode C<0640> (because C<0666 &~ 027> is C<0640>). @@ -10139,7 +10139,7 @@ L|perlvar/$!> (errno): unlink @goners; unlink glob "*.bak"; -On error, L|/unlink LIST> will not tell you which files it +On error, C will not tell you which files it could not remove. If you want to know which files you could not remove, try them one at a time: @@ -10148,15 +10148,15 @@ at a time: unlink $file or warn "Could not unlink $file: $!"; } -Note: L|/unlink LIST> will not attempt to delete directories +Note: C will not attempt to delete directories unless you are superuser and the B<-U> flag is supplied to Perl. Even if these conditions are met, be warned that unlinking a directory can inflict -damage on your filesystem. Finally, using L|/unlink LIST> on +damage on your filesystem. Finally, using C on directories is not supported on many operating systems. Use L|/rmdir FILENAME> instead. -If LIST is omitted, L|/unlink LIST> uses L|perlvar/$_>. +If LIST is omitted, C uses L|perlvar/$_>. =item unpack TEMPLATE,EXPR X @@ -10165,7 +10165,7 @@ X =for Pod::Functions convert binary structure into normal perl variables -L|/unpack TEMPLATE,EXPR> does the reverse of +C does the reverse of L|/pack TEMPLATE,LIST>: it takes a string and expands it out into a list of values. (In scalar context, it returns merely the first value produced.) @@ -10212,14 +10212,14 @@ The following efficiently counts the number of set bits in a bit vector: The C

and C

formats should be used with care. Since Perl has no way of checking whether the value passed to -L|/unpack TEMPLATE,EXPR> +C corresponds to a valid memory location, passing a pointer value that's not known to be valid is likely to have disastrous consequences. If there are more pack codes or if the repeat count of a field or a group is larger than what the remainder of the input string allows, the result is not well defined: the repeat count may be decreased, or -L|/unpack TEMPLATE,EXPR> may produce empty strings or zeros, +C may produce empty strings or zeros, or it may raise an exception. If the input string is longer than one described by the TEMPLATE, the remainder of that input string is ignored. @@ -10252,7 +10252,7 @@ prepended elements stay in the same order. Use L|/reverse LIST> to do the reverse. Starting with Perl 5.14, an experimental feature allowed -L|/unshift ARRAY,LIST> to take +C to take a scalar expression. This experiment has been deemed unsuccessful, and was removed as of Perl 5.24. @@ -10310,7 +10310,7 @@ That is exactly equivalent to BEGIN { require Module } If the VERSION argument is present between Module and LIST, then the -L|/use Module VERSION LIST> will call the C method in +C will call the C method in class Module with the given version as an argument: use Module 12.34; @@ -10355,9 +10355,9 @@ block scope (like L|strict> or L|integer>, unlike ordinary modules, which import symbols into the current package (which are effective through the end of the file). -Because L|/use Module VERSION LIST> takes effect at compile time, +Because C takes effect at compile time, it doesn't respect the ordinary flow control of the code being compiled. -In particular, putting a L|/use Module VERSION LIST> inside the +In particular, putting a C inside the false branch of a conditional doesn't prevent it from being processed. If a module or pragma only needs to be loaded conditionally, this can be done using the L pragma: @@ -10366,7 +10366,7 @@ conditionally, this can be done using the L pragma: use if WANT_WARNINGS, warnings => qw(all); There's a corresponding L|/no MODULE VERSION LIST> declaration -that unimports meanings imported by L|/use Module VERSION LIST>, +that unimports meanings imported by C, i.e., it calls C<< Module->unimport(LIST) >> instead of L|/import LIST>. It behaves just as L|/import LIST> does with VERSION, an omitted or empty LIST, @@ -10378,7 +10378,7 @@ or no unimport method being found. See L for a list of standard modules and pragmas. See L for the C<-M> and C<-m> command-line -options to Perl that give L|/use Module VERSION LIST> +options to Perl that give C functionality from the command-line. =item use VERSION @@ -10437,7 +10437,7 @@ older code. use 5.024_001; # ditto; older syntax compatible with perl 5.6 This is often useful if you need to check the current Perl version before -L|/use Module VERSION LIST>ing library modules that won't work +Cing library modules that won't work with older versions of Perl. (We try not to do this more than we have to.) @@ -10596,7 +10596,7 @@ C<0x04>, C<0x08>, C<0x10>, C<0x20>, C<0x40>, C<0x80>. For example, breaking the single input byte C into two groups gives a list C<(0x6, 0x3)>; breaking it into 4 groups gives C<(0x2, 0x1, 0x3, 0x0)>. -L|/vec EXPR,OFFSET,BITS> may also be assigned to, in which case +C may also be assigned to, in which case parentheses are needed to give the expression the correct precedence as in @@ -10608,12 +10608,12 @@ extend the string with sufficiently many zero bytes. It is an error to try to write off the beginning of the string (i.e., negative OFFSET). If the string happens to be encoded as UTF-8 internally (and thus has -the UTF8 flag set), L|/vec EXPR,OFFSET,BITS> tries to convert it +the UTF8 flag set), C tries to convert it to use a one-byte-per-character internal representation. However, if the string contains characters with values of 256 or higher, a fatal error will occur. -Strings created with L|/vec EXPR,OFFSET,BITS> can also be +Strings created with C can also be manipulated with the logical operators C<|>, C<&>, C<^>, and C<~>. These operators will assume a bit vector operation is desired when both operands are strings. @@ -10826,7 +10826,7 @@ L|perlvar/${^CHILD_ERROR_NATIVE}>. Note that a return value of C<-1> could mean that child processes are being automatically reaped, as described in L. -If you use L|/wait> in your handler for +If you use C in your handler for L|perlvar/%SIG>, it may accidentally wait for the child created by L|/qxESTRINGE> or L|/system LIST>. See L for details. @@ -10894,7 +10894,7 @@ looking for no value (void context). my @a = complex_calculation(); return wantarray ? @a : "@a"; -L|/wantarray>'s result is unspecified in the top level of a file, +C's result is unspecified in the top level of a file, in a C, C, C, C or C block, or in a C method. @@ -10922,7 +10922,7 @@ as it sees fit (like, for instance, converting it into a L|/die LIST>). Most handlers must therefore arrange to actually display the warnings that they are not prepared to deal with, by calling -L|/warn LIST> +C again in the handler. Note that this is quite safe and will not produce an endless loop, since C<__WARN__> hooks are not called from inside one.