X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=8722105c2b6fa9beffc50b5e9ca9b9b71f1f974a;hb=1b1f1335be81080356b687a63b64fde210a3b697;hp=0d620d90dc9fc95fbd397b580130faa24888ca3c;hpb=847a5fae45dac396d0f9e1bb61d5b4ff9d94cdcd;p=p5sagit%2Fp5-mst-13.2.git
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 0d620d9..8722105 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -96,9 +96,8 @@ than one place.
=item Functions for SCALARs or strings
C, C, C, C, C, C, C, C,
-C, C, C, C, C, C, C,
-C, C, C, C, C
, C, C,
-C
+C, C, C, C, C, C, C,
+C, C, C, C
, C, C, C
=item Regular expressions and pattern matching
@@ -173,7 +172,7 @@ C, C.
-See L for more about Unicode.
+For the reverse, use L.
+See L and L for more about Unicode.
If NUMBER is omitted, uses C<$_>.
@@ -730,9 +719,9 @@ counter (C<$.>), while the implicit close done by C does not.
If the file handle came from a piped open C will additionally
return false if one of the other system calls involved fails or if the
program exits with non-zero status. (If the only problem was that the
-program exited non-zero C<$!> will be set to C<0>.) Closing a pipe
+program exited non-zero C<$!> will be set to C<0>.) Closing a pipe
also waits for the process executing on the pipe to complete, in case you
-want to look at the output of the pipe afterwards, and
+want to look at the output of the pipe afterwards, and
implicitly puts the exit status value of that command into C<$?>.
Prematurely closing the read end of a pipe (i.e. before the process
@@ -818,17 +807,29 @@ extirpated as a potential munition). This can prove useful for checking
the password file for lousy passwords, amongst other things. Only the
guys wearing white hats should do this.
-Note that C is intended to be a one-way function, much like breaking
-eggs to make an omelette. There is no (known) corresponding decrypt
-function. As a result, this function isn't all that useful for
+Note that C is intended to be a one-way function, much like
+breaking eggs to make an omelette. There is no (known) corresponding
+decrypt function (in other words, the crypt() is a one-way hash
+function). As a result, this function isn't all that useful for
cryptography. (For that, see your nearby CPAN mirror.)
-When verifying an existing encrypted string you should use the encrypted
-text as the salt (like C). This
-allows your code to work with the standard C and with more
-exotic implementations. When choosing a new salt create a random two
-character string whose characters come from the set C<[./0-9A-Za-z]>
-(like C).
+When verifying an existing encrypted string you should use the
+encrypted text as the salt (like C). This allows your code to work with the standard C
+and with more exotic implementations. In other words, do not assume
+anything about the returned string itself, or how many bytes in
+the encrypted string matter.
+
+Traditionally the result is a string of 13 bytes: two first bytes of
+the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only
+the first eight bytes of the encrypted string mattered, but
+alternative hashing schemes (like MD5), higher level security schemes
+(like C2), and implementations on non-UNIX platforms may produce
+different strings.
+
+When choosing a new salt create a random two character string whose
+characters come from the set C<[./0-9A-Za-z]> (like C).
Here's an example that makes sure that whoever runs this program knows
their own password:
@@ -856,6 +857,11 @@ back. Look at the F and F directories
on your favorite CPAN mirror for a slew of potentially useful
modules.
+If using crypt() on an Unicode string (which potentially has
+characters with codepoints above 255), Perl tries to make sense of
+the situation by using only the low eight bits of the characters when
+calling crypt().
+
=item dbmclose HASH
[This function has been largely superseded by the C function.]
@@ -972,7 +978,7 @@ See also L, L, L.
Given an expression that specifies a hash element, array element, hash slice,
or array slice, deletes the specified element(s) from the hash or array.
In the case of an array, if the array elements happen to be at the end,
-the size of the array will shrink to the highest element that tests
+the size of the array will shrink to the highest element that tests
true for exists() (or 0 if no such element exists).
Returns each element so deleted or the undefined value if there was no such
@@ -1102,7 +1108,7 @@ nothing in such situations, put
as the first line of the handler (see L). Because
this promotes strange action at a distance, this counterintuitive
-behavior may be fixed in a future release.
+behavior may be fixed in a future release.
=item do BLOCK
@@ -1129,7 +1135,7 @@ from a Perl subroutine library.
is just like
- scalar eval `cat stat.pl`;
+ eval `cat stat.pl`;
except that it's more efficient and concise, keeps track of the current
filename for error messages, searches the @INC libraries, and updates
@@ -1152,9 +1158,9 @@ and raise an exception if there's a problem.
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
+ # read in config files: system first, then user
for $file ("/share/prog/defaults.rc",
- "$ENV{HOME}/.someprogrc")
+ "$ENV{HOME}/.someprogrc")
{
unless ($return = do $file) {
warn "couldn't parse $file: $@" if $@;
@@ -1179,7 +1185,7 @@ If C.) If EXPR is omitted, uses C<$_>.
print hex 'aF'; # same
Hex strings may only represent integers. Strings that would cause
-integer overflow trigger a warning.
+integer overflow trigger a warning. Leading whitespace is not stripped,
+unlike oct().
=item import
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 C, L, and L.
+for the package used. See also L, L, and L.
=item index STR,SUBSTR,POSITION
@@ -2175,7 +2186,7 @@ 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 C and C
functions may be needed to manipulate the values of structures used by
-C.
+C.
The return value of C (and C) is as follows:
@@ -2230,7 +2241,7 @@ Here is yet another way to print your environment:
@keys = keys %ENV;
@values = values %ENV;
- while (@keys) {
+ while (@keys) {
print pop(@keys), '=', pop(@values), "\n";
}
@@ -2317,9 +2328,9 @@ C work.
=item lc
Returns an lowercased version of EXPR. This is the internal function
-implementing the C<\L> escape in double-quoted strings.
-Respects current LC_CTYPE locale if C.
-See L for more about Unicode.
+Returns the numeric (the native 8-bit encoding, like ASCII or EBCDIC,
+or Unicode) value of the first character of EXPR. If EXPR is omitted,
+uses C<$_>.
+
+For the reverse, see L.
+See L and L for more about Unicode.
=item our EXPR
+=item our EXPR : ATTRIBUTES
+
An C declares the listed variables to be valid globals within
the enclosing block, file, or C. That is, it has the same
scoping rules as a "my" declaration, but does not create a local
@@ -2966,6 +3019,28 @@ package, Perl will emit warnings if you have asked for them.
our $bar; # emits warning
+An C declaration may also have a list of attributes associated
+with it. B: This is an experimental feature that may be
+changed or removed in future releases of Perl. It should not be
+relied upon.
+
+The only currently recognized attribute is C which indicates
+that a single copy of the global is to be used by all interpreters
+should the program happen to be running in a multi-interpreter
+environment. (The default behaviour would be for each interpreter to
+have its own copy of the global.) In such an environment, this
+attribute also has the effect of making the global readonly.
+Examples:
+
+ our @EXPORT : unique = qw(foo);
+ our %EXPORT_TAGS : unique = (bar => [qw(aa bb cc)]);
+ our $VERSION : unique = "1.00";
+
+Multi-interpreter environments can come to being either through the
+fork() emulation on Windows platforms, or by embedding perl in a
+multi-threaded application. The C attribute does nothing in
+all other environments.
+
=item pack TEMPLATE,LIST
Takes a LIST of values and converts it into a string using the rules
@@ -2979,8 +3054,8 @@ sequence of characters that give the order and type of values, as
follows:
a A string with arbitrary binary data, will be null padded.
- A An ASCII string, will be space padded.
- Z A null terminated (asciz) string, will be null padded.
+ A A text (ASCII) string, will be space padded.
+ Z A null terminated (ASCIZ) string, will be null padded.
b A bit string (ascending bit order inside each byte, like vec()).
B A bit string (descending bit order inside each byte).
@@ -3029,8 +3104,8 @@ follows:
P A pointer to a structure (fixed-length string).
u A uuencoded string.
- U A Unicode character number. Encodes to UTF-8 internally.
- Works even if C is not in effect.
+ U A Unicode character number. Encodes to UTF-8 internally
+ (or UTF-EBCDIC in EBCDIC platforms).
w A BER compressed integer. Its bytes represent an unsigned
integer in base 128, most significant digit first, with as
@@ -3189,14 +3264,14 @@ L:
print $Config{longlongsize}, "\n";
(The C<$Config{longlongsize}> will be undefine if your system does
-not support long longs.)
+not support long longs.)
=item *
The integer formats C, C, C, C, C, and C
are inherently non-portable between processors and operating systems
because they obey the native byteorder and endianness. For example a
-4-byte integer 0x12345678 (305419896 decimal) be ordered natively
+4-byte integer 0x12345678 (305419896 decimal) would be ordered natively
(arranged in and handled by the CPU registers) into bytes as
0x12 0x34 0x56 0x78 # big-endian
@@ -3205,7 +3280,8 @@ because they obey the native byteorder and endianness. For example a
Basically, the Intel and VAX CPUs are little-endian, while everybody
else, for example Motorola m68k/88k, PPC, Sparc, HP PA, Power, and
Cray are big-endian. Alpha and MIPS can be either: Digital/Compaq
-used/uses them in little-endian mode; SGI/Cray uses them in big-endian mode.
+used/uses them in little-endian mode; SGI/Cray uses them in big-endian
+mode.
The names `big-endian' and `little-endian' are comic references to
the classic "Gulliver's Travels" (via the paper "On Holy Wars and a
@@ -3232,7 +3308,7 @@ Byteorders C<'1234'> and C<'12345678'> are little-endian, C<'4321'>
and C<'87654321'> are big-endian.
If you want portable packed integers use the formats C, C,
-C, and C, their byte endianness and size is known.
+C, and C, their byte endianness and size are known.
See also L.
=item *
@@ -3333,7 +3409,7 @@ The same template may generally also be used in unpack().
=item package NAMESPACE
-=item package
+=item package
Declares the compilation unit as being in the given namespace. The scope
of the package declaration is from the declaration itself through the end
@@ -3352,8 +3428,10 @@ C<$::sail> is equivalent to C<$main::sail> (as well as to C<$main'sail>,
still seen in older code).
If NAMESPACE is omitted, then there is no current package, and all
-identifiers must be fully qualified or lexicals. This is stricter
-than C, since it also extends to function names.
+identifiers must be fully qualified or lexicals. However, you are
+strongly advised not to make use of this feature. Its use can cause
+unexpected behaviour, even crashing some versions of Perl. It is
+deprecated, and will be removed from a future release.
See L for more information about packages, modules,
and classes. See L for other scoping issues.
@@ -3436,9 +3514,10 @@ you will have to use a block returning its value instead:
Equivalent to C, except that C<$\>
(the output record separator) is not appended. The first argument
-of the list will be interpreted as the C format. If C is
-in effect, the character used for the decimal point in formatted real numbers
-is affected by the LC_NUMERIC locale. See L.
+of the list will be interpreted as the C format. See C
+for an explanation of the format argument. If C is in effect,
+the character used for the decimal point in formatted real numbers is
+affected by the LC_NUMERIC locale. See L.
Don't fall into the trap of using a C when a simple
C would do. The C is more efficient and less
@@ -3475,12 +3554,10 @@ but is more efficient. Returns the new number of elements in the array.
=item qr/STRING/
-=item qu/STRING/
+=item qx/STRING/
=item qw/STRING/
-=item qx/STRING/
-
Generalized quotes. See L.
=item quotemeta EXPR
@@ -3502,8 +3579,15 @@ If EXPR is omitted, uses C<$_>.
Returns a random fractional number greater than or equal to C<0> and less
than the value of EXPR. (EXPR should be positive.) If EXPR is
-omitted, the value C<1> is used. Automatically calls C unless
-C has already been called. See also C.
+omitted, or a C<0>, the value C<1> is used. Automatically calls C
+unless C has already been called. See also C.
+
+Apply C to the value returned by C if you want random
+integers instead of random fractional numbers. For example,
+
+ int(rand(10))
+
+returns a random integer between C<0> and C<9>, inclusive.
(Note: If your rand function consistently returns numbers that are too
large or too small, then your version of Perl was probably compiled
@@ -3654,7 +3738,7 @@ name is returned instead. You can think of C as a C operator.
}
if (UNIVERSAL::isa($r, "HASH")) { # for subclassing
print "r is a reference to something that isa hash.\n";
- }
+ }
See also L.
@@ -3676,19 +3760,23 @@ rename(2) manpage or equivalent system documentation for details.
=item require
-Demands some semantics specified by EXPR, or by C<$_> if EXPR is not
-supplied.
+Demands a version of Perl specified by VERSION, or demands some semantics
+specified by EXPR or by C<$_> if EXPR is not supplied.
-If a VERSION is specified as a literal of the form v5.6.1,
-demands that the current version of Perl (C<$^V> or $PERL_VERSION) be
-at least as recent as that version, at run time. (For compatibility
-with older versions of Perl, a numeric argument will also be interpreted
-as VERSION.) Compare with L, which can do a similar check at
-compile time.
+VERSION may be either a numeric argument such as 5.006, which will be
+compared to C<$]>, or a literal of the form v5.6.1, which will be compared
+to C<$^V> (aka $PERL_VERSION). A fatal error is produced at run time if
+VERSION is greater than the version of the current Perl interpreter.
+Compare with L, which can do a similar check at compile time.
+
+Specifying VERSION as a literal of the form v5.6.1 should generally be
+avoided, because it leads to misleading error messages under earlier
+versions of Perl which do not support this syntax. The equivalent numeric
+version should be used instead.
require v5.6.1; # run time version check
require 5.6.1; # ditto
- require 5.005_03; # float version allowed for compatibility
+ require 5.006_001; # ditto; preferred for backwards compatibility
Otherwise, demands that a library file be included if it hasn't already
been included. The file is included via the do-FILE mechanism, which is
@@ -3730,9 +3818,9 @@ modules does not risk altering your namespace.
In other words, if you try this:
- require Foo::Bar; # a splendid bareword
+ require Foo::Bar; # a splendid bareword
-The require function will actually look for the "F" file in the
+The require function will actually look for the "F" file in the
directories specified in the C<@INC> array.
But if you try this:
@@ -3742,11 +3830,65 @@ But if you try this:
#or
require "Foo::Bar"; # not a bareword because of the ""
-The require function will look for the "F" file in the @INC array and
+The require function will look for the "F" file in the @INC array and
will complain about not finding "F" there. In this case you can do:
eval "require $class";
+You can also insert hooks into the import facility, by putting directly
+Perl code into the @INC array. There are three forms of hooks: subroutine
+references, array references and blessed objects.
+
+Subroutine references are the simplest case. When the inclusion system
+walks through @INC and encounters a subroutine, this subroutine gets
+called with two parameters, the first being a reference to itself, and the
+second the name of the file to be included (e.g. "F"). The
+subroutine should return C or a filehandle, from which the file to
+include will be read. If C is returned, C will look at
+the remaining elements of @INC.
+
+If the hook is an array reference, its first element must be a subroutine
+reference. This subroutine is called as above, but the first parameter is
+the array reference. This enables to pass indirectly some arguments to
+the subroutine.
+
+In other words, you can write:
+
+ push @INC, \&my_sub;
+ sub my_sub {
+ my ($coderef, $filename) = @_; # $coderef is \&my_sub
+ ...
+ }
+
+or:
+
+ push @INC, [ \&my_sub, $x, $y, ... ];
+ sub my_sub {
+ my ($arrayref, $filename) = @_;
+ # Retrieve $x, $y, ...
+ my @parameters = @$arrayref[1..$#$arrayref];
+ ...
+ }
+
+If the hook is an object, it must provide an INC method, that will be
+called as above, the first parameter being the object itself. (Note that
+you must fully qualify the sub's name, as it is always forced into package
+C.) Here is a typical code layout:
+
+ # In Foo.pm
+ package Foo;
+ sub new { ... }
+ sub Foo::INC {
+ my ($self, $filename) = @_;
+ ...
+ }
+
+ # In the main program
+ push @INC, new Foo(...);
+
+Note that these hooks are also permitted to set the %INC entry
+corresponding to the files they have loaded. See L.
+
For a yet-more-powerful import facility, see L and L.
=item reset EXPR
@@ -3776,7 +3918,7 @@ See L.
=item return
-Returns from a subroutine, C, or C with the value
+Returns from a subroutine, C, or C with the value
given in EXPR. Evaluation of EXPR may be in list, scalar, or void
context, depending on how the return value will be used, and the context
may vary from one execution to the next (see C). If no EXPR
@@ -3973,7 +4115,7 @@ calling select() in scalar context just returns $nfound.
Any of the bit masks can also be undef. The timeout, if specified, is
in seconds, which may be fractional. Note: not all implementations are
-capable of returning the$timeleft. If not, they always return
+capable of returning the $timeleft. If not, they always return
$timeleft equal to the supplied $timeout.
You can effect a sleep of 250 milliseconds this way:
@@ -4009,14 +4151,14 @@ documentation.
=item semop KEY,OPSTRING
Calls the System V IPC function semop to perform semaphore operations
-such as signaling and waiting. OPSTRING must be a packed array of
+such as signalling and waiting. OPSTRING must be a packed array of
semop structures. Each semop structure can be generated with
-C. The number of semaphore
+C. The number of semaphore
operations is implied by the length of OPSTRING. Returns true if
successful, or false if there is an error. As an example, the
following code waits on semaphore $semnum of semaphore id $semid:
- $semop = pack("sss", $semnum, -1, 0);
+ $semop = pack("s!3", $semnum, -1, 0);
die "Semaphore trouble: $!\n" unless semop($semid, $semop);
To signal the semaphore, replace C<-1> with C<1>. See also
@@ -4113,7 +4255,7 @@ has the same interpretation as in the system call of the same name.
This is useful with sockets when you want to tell the other
side you're done writing but not done reading, or vice versa.
-It's also a more insistent form of close because it also
+It's also a more insistent form of close because it also
disables the file descriptor in any forked copies in other
processes.
@@ -4147,11 +4289,32 @@ busy multitasking system.
For delays of finer granularity than one second, you may use Perl's
C interface to access setitimer(2) if your system supports
-it, or else see L above. The Time::HiRes module from CPAN
-may also help.
+it, or else see L above. The Time::HiRes module (from CPAN,
+and starting from Perl 5.8 part of the standard distribution) may also
+help.
See also the POSIX module's C function.
+=item sockatmark SOCKET
+
+Returns true if the socket is positioned at the out-of-band mark
+(also known as the urgent data mark), false otherwise. Use right
+after reading from the socket.
+
+Not available directly, one has to import the function from
+the IO::Socket extension
+
+ use IO::Socket 'sockatmark';
+
+Even this doesn't guarantee that sockatmark() really is available,
+though, because sockatmark() is a relatively recent addition to
+the family of socket functions. If it is unavailable, attempt to
+use it will fail
+
+ IO::Socket::atmark not implemented on this architecture ...
+
+See also L.
+
=item socket SOCKET,DOMAIN,TYPE,PROTOCOL
Opens a socket of the specified kind and attaches it to filehandle
@@ -4219,6 +4382,12 @@ loop control operators described in L or with C.
When C is in effect, C sorts LIST according to the
current collation locale. See L.
+Perl does B guarantee that sort is stable. (A I sort
+preserves the input order of elements that compare equal.) 5.7 and
+5.8 happen to use a stable mergesort, but 5.6 and earlier used quicksort,
+which is not stable. Do not assume that future perls will continue to
+use a stable sort.
+
Examples:
# sort lexically
@@ -4375,11 +4544,15 @@ splits on whitespace (after skipping any leading whitespace). Anything
matching PATTERN is taken to be a delimiter separating the fields. (Note
that the delimiter may be longer than one character.)
-If LIMIT is specified and positive, splits into no more than that
-many fields (though it may split into fewer). If LIMIT is unspecified
-or zero, trailing null fields are stripped (which potential users
-of C would do well to remember). If LIMIT is negative, it is
-treated as if an arbitrarily large LIMIT had been specified.
+If LIMIT is specified and positive, it represents the maximum number
+of fields the EXPR will be split into, though the actual number of
+fields returned depends on the number of times PATTERN matches within
+EXPR. If LIMIT is unspecified or zero, trailing null fields are
+stripped (which potential users of C would do well to remember).
+If LIMIT is negative, it is treated as if an arbitrarily large LIMIT
+had been specified. Note that splitting an EXPR that evaluates to the
+empty string always returns the empty list, regardless of the LIMIT
+specified.
A pattern matching the null string (not to be confused with
a null pattern C/>, which is just one member of the set of patterns
@@ -4390,6 +4563,10 @@ characters at each point it matches that way. For example:
produces the output 'h:i:t:h:e:r:e'.
+Using the empty pattern C/> specifically matches the null string, and is
+not be confused with the use of C/> to mean "the last successful pattern
+match".
+
Empty leading (or trailing) fields are produced when there positive width
matches at the beginning (or end) of the string; a zero-width match at the
beginning (or end) of the string does not produce an empty field. For
@@ -4443,13 +4620,17 @@ Example:
open(PASSWD, '/etc/passwd');
while () {
- ($login, $passwd, $uid, $gid,
+ chomp;
+ ($login, $passwd, $uid, $gid,
$gcos, $home, $shell) = split(/:/);
#...
}
-(Note that $shell above will still have a newline on it. See L,
-L, and L.)
+As with regular pattern matching, any capturing parentheses that are not
+matched in a C will be set to C when returned:
+
+ @fields = split /(A)|B/, "1A2B3";
+ # @fields is (1, 'A', 2, undef, 3)
=item sprintf FORMAT, LIST
@@ -4499,7 +4680,7 @@ In addition, Perl permits the following widely-supported conversions:
%b an unsigned integer, in binary
%p a pointer (outputs the Perl value's address in hexadecimal)
%n special: *stores* the number of characters output so far
- into the next variable in the parameter list
+ into the next variable in the parameter list
Finally, for backward (and we do mean "backward") compatibility, Perl
permits these unnecessary but widely-supported conversions:
@@ -4628,19 +4809,42 @@ loaded the standard Math::Complex module.
=item srand
-Sets the random number seed for the C operator. If EXPR is
-omitted, uses a semi-random value supplied by the kernel (if it supports
-the F device) or based on the current time and process
-ID, among other things. In versions of Perl prior to 5.004 the default
-seed was just the current C