X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=7c69ff60282074f3d0799f70a8f8bd93c9f611c3;hb=a3bcc51ebd4e201d85a37d8410b7a375b8d94244;hp=c617e94db547739b7bf2cc96b001ff220537bae1;hpb=d9a9d4576ee524be82c47fd4efcdec0a4cc327e4;p=p5sagit%2Fp5-mst-13.2.git
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index c617e94..7c69ff6 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -224,8 +224,8 @@ by this are:
C<-X>, C, C, C, C, C,
C, C, C, C, C,
C, C, C, C, C,
-C, C, C, C, C, C,
-C, C, C, C,
+C, C, C, C, C, C,
+C, C, C, C, C,
C, C, C, C,
C, C, C, C,
C, C, C, C, C,
@@ -246,11 +246,11 @@ L and other available platform-specific documentation.
=over 8
-=item I<-X> FILEHANDLE
+=item -X FILEHANDLE
-=item I<-X> EXPR
+=item -X EXPR
-=item I<-X>
+=item -X
A file test, where X is one of the letters listed below. This unary
operator takes one argument, either a filename or a filehandle, and
@@ -429,6 +429,8 @@ modulo the caveats given in L.
# didn't
}
+For more information see L.
+
=item atan2 Y,X
Returns the arctangent of Y/X in the range -PI to PI.
@@ -445,7 +447,7 @@ does. Returns true if it succeeded, false otherwise. NAME should be a
packed address of the appropriate type for the socket. See the examples in
L.
-=item binmode FILEHANDLE, DISCIPLINE
+=item binmode FILEHANDLE, LAYER
=item binmode FILEHANDLE
@@ -453,46 +455,52 @@ Arranges for FILEHANDLE to be read or written in "binary" or "text"
mode on systems where the run-time libraries distinguish between
binary and text files. If FILEHANDLE is an expression, the value is
taken as the name of the filehandle. Returns true on success,
-C on failure.
-
-If DISCIPLINE is omitted or specified as C<:raw> the filehandle is made
-suitable for passing binary data. This includes turning off possible CRLF
-translation and marking it as bytes (as opposed to Unicode characters).
-Note that as desipite what may be implied in I<"Programming Perl">
-(the Camel) or elsewhere C<:raw> is I the simply inverse of C<:crlf>
-- other disciplines which would affect binary nature of the stream are
-I disabled. See L, L and the discussion about the
-PERLIO environment variable.
+otherwise it returns C and sets C<$!> (errno).
On some systems (in general, DOS and Windows-based systems) binmode()
is necessary when you're not working with a text file. For the sake
of portability it is a good idea to always use it when appropriate,
-and to never use it when it isn't appropriate.
+and to never use it when it isn't appropriate. Also, people can
+set their I/O to be by default UTF-8 encoded Unicode, not bytes.
-In other words: regardless of platform, use binmode() on binary files
-(like for example images).
+In other words: regardless of platform, use binmode() on binary data,
+like for example images.
-If DISCIPLINE is present it is a single string, but may contain
-multiple directives. The directives alter the behaviour of the
-file handle. When DISCIPLINE is present using binmode on text
-file makes sense.
+If LAYER is present it is a single string, but may contain multiple
+directives. The directives alter the behaviour of the file handle.
+When LAYER is present using binmode on text file makes sense.
-To mark FILEHANDLE as UTF-8, use C<:utf8>.
+If LAYER is omitted or specified as C<:raw> the filehandle is made
+suitable for passing binary data. This includes turning off possible CRLF
+translation and marking it as bytes (as opposed to Unicode characters).
+Note that, despite what may be implied in I<"Programming Perl"> (the
+Camel) or elsewhere, C<:raw> is I the simply inverse of C<:crlf>
+-- other layers which would affect binary nature of the stream are
+I disabled. See L, L and the discussion about the
+PERLIO environment variable.
The C<:bytes>, C<:crlf>, and C<:utf8>, and any other directives of the
-form C<:...>, are called I/O I. The normal implementation
-of disciplines in Perl 5.8 and later is in terms of I. See
-L. (There is typically a one-to-one correspondence between
-layers and disiplines.) The C pragma can be used to establish
-default I/O disciplines. See L.
+form C<:...>, are called I/O I. The C pragma can be used to
+establish default I/O layers. See L.
+
+I
+
+To mark FILEHANDLE as UTF-8, use C<:utf8>.
In general, binmode() should be called after open() but before any I/O
is done on the filehandle. Calling binmode() will normally flush any
pending buffered output data (and perhaps pending input data) on the
-handle. An exception to this is the C<:encoding> discipline that
+handle. An exception to this is the C<:encoding> layer that
changes the default character encoding of the handle, see L.
-The C<:encoding> discipline sometimes needs to be called in
-mid-stream, and it doesn't flush the stream.
+The C<:encoding> layer sometimes needs to be called in
+mid-stream, and it doesn't flush the stream. The C<:encoding>
+also implicitly pushes on top of itself the C<:utf8> layer because
+internally Perl will operate on UTF-8 encoded Unicode characters.
The operating system, device drivers, C libraries, and Perl run-time
system all work together to let the programmer treat a single
@@ -653,6 +661,13 @@ You can actually chomp anything that's an lvalue, including an assignment:
If you chomp a list, each element is chomped, and the total number of
characters removed is returned.
+Note that parentheses are necessary when you're chomping anything
+that is not a simple variable. This is because C
+is interpreted as C<(chomp $cwd) = `pwd`;>, rather than as
+C which you might expect. Similarly,
+C is interpreted as C rather than
+as C.
+
=item chop VARIABLE
=item chop( LIST )
@@ -672,6 +687,8 @@ last C is returned.
Note that C returns the last character. To return all but the last
character, use C.
+See also L.
+
=item chown LIST
Changes the owner (and group) of a list of files. The first two
@@ -711,14 +728,18 @@ On POSIX systems, you can detect this condition this way:
Returns the character represented by that NUMBER in the character set.
For example, C is C<"A"> in either ASCII or Unicode, and
-chr(0x263a) is a Unicode smiley face. Note that characters from 127
-to 255 (inclusive) are by default not encoded in Unicode for backward
-compatibility reasons (but see L).
+chr(0x263a) is a Unicode smiley face. Note that characters from 128
+to 255 (inclusive) are by default not encoded in UTF-8 Unicode for
+backward compatibility reasons (but see L).
+
+If NUMBER is omitted, uses C<$_>.
For the reverse, use L.
-See L and L for more about Unicode.
-If NUMBER is omitted, uses C<$_>.
+Note that under the C pragma the NUMBER is masked to
+the low eight bits.
+
+See L and L for more about Unicode.
=item chroot FILENAME
@@ -777,9 +798,6 @@ filehandle, usually the real filehandle name.
Closes a directory opened by C and returns the success of that
system call.
-DIRHANDLE may be an expression whose value can be used as an indirect
-dirhandle, usually the real dirhandle name.
-
=item connect SOCKET,NAME
Attempts to connect to a remote socket, just as the connect system call
@@ -836,7 +854,7 @@ 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
+Note that L is intended to be a one-way function, much like
breaking eggs to make an omelette. There is no (known) corresponding
decrypt function (in other words, the crypt() is a one-way hash
function). As a result, this function isn't all that useful for
@@ -844,7 +862,7 @@ 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
+$crypted>). This allows your code to work with the standard L
and with more exotic implementations. In other words, do not assume
anything about the returned string itself, or how many bytes in
the encrypted string matter.
@@ -858,7 +876,10 @@ 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).
+'/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>). 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 C accepts.
Here's an example that makes sure that whoever runs this program knows
their own password:
@@ -880,7 +901,7 @@ their own password:
Of course, typing in your own password to whoever asks you
for it is unwise.
-The L function is unsuitable for encrypting large quantities
+The L function is unsuitable for encrypting large quantities
of data, not least of all because you can't get the information
back. Look at the F and F directories
on your favorite CPAN mirror for a slew of potentially useful
@@ -961,7 +982,7 @@ element to return happens to be C.
You may also use C to check whether subroutine C<&func>
has ever been defined. The return value is unaffected by any forward
-declarations of C<&foo>. Note that a subroutine which is not defined
+declarations of C<&func>. Note that a subroutine which is not defined
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.
@@ -1104,7 +1125,7 @@ This is useful for propagating exceptions:
If LIST is empty and C<$@> contains an object reference that has a
C method, that method will be called with additional file
and line number parameters. The return value replaces the value in
-C<$@>. ie. as if C<<$@ = eval { $@->PROPAGATE(__FILE__, __LINE__) };>>
+C<$@>. ie. as if C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >>
were called.
If C<$@> is empty then the string C<"Died"> is used.
@@ -1246,9 +1267,11 @@ it. When called in scalar context, returns only the key for the next
element in the hash.
Entries are returned in an apparently random order. The actual random
-order is subject to change in future versions of perl, but it is guaranteed
-to be in the same order as either the C or C function
-would produce on the same (unmodified) hash.
+order is subject to change in future versions of perl, but it is
+guaranteed to be in the same order as either the C or C
+function would produce on the same (unmodified) hash. Since Perl
+5.8.1 the ordering is different even between different runs of Perl
+for security reasons (see L).
When the hash is entirely read, a null array is returned in list context
(which when assigned produces a false (C<0>) value), and C in
@@ -1314,12 +1337,11 @@ last file. Examples:
# insert dashes just before last line of last file
while (<>) {
- if (eof()) { # check for end of current file
+ if (eof()) { # check for end of last file
print "--------------\n";
- close(ARGV); # close or last; is needed if we
- # are reading from the terminal
}
print;
+ last if eof(); # needed if we're reading from a terminal
}
Practical hint: you almost never need to use C in Perl, because the
@@ -1436,6 +1458,11 @@ in case 6.
C does I count as a loop, so the loop control statements
C, C, or C cannot be used to leave or restart the block.
+Note that as a very special case, an C executed within the C
+package doesn't see the usual surrounding lexical scope, but rather the
+scope of the first non-DB piece of code that called it. You don't normally
+need to worry about this unless you are writing a Perl debugger.
+
=item exec LIST
=item exec PROGRAM LIST
@@ -1565,9 +1592,6 @@ This surprising autovivification in what does not at first--or even
second--glance appear to be an lvalue context may be fixed in a future
release.
-See L for specifics
-on how exists() acts when used on a pseudo-hash.
-
Use of a subroutine call, rather than a subroutine name, as an argument
to exists() is an error.
@@ -1620,7 +1644,7 @@ For example:
fcntl($filehandle, F_GETFL, $packed_return_buffer)
or die "can't fcntl F_GETFL: $!";
-You don't have to check for C on the return from C.
+You don't have to check for C on the return from C.
Like C, 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 the normal B<-w> warnings
@@ -1630,6 +1654,18 @@ Note that C will produce a fatal error if used on a machine that
doesn't implement fcntl(2). See the Fcntl module or your fcntl(2)
manpage to learn what functions are available on your system.
+Here's an example of setting a filehandle named C to be
+non-blocking at the system level. You'll have to negotiate C<$|>
+on your own, though.
+
+ use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
+
+ $flags = fcntl(REMOTE, F_GETFL, 0)
+ or die "Can't get flags for the socket: $!\n";
+
+ $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
+ or die "Can't set flags for the socket: $!\n";
+
=item fileno FILEHANDLE
Returns the file descriptor for a filehandle, or undefined if the
@@ -1795,11 +1831,11 @@ C always returns true. See L for other examples.
=item getc
Returns the next character from the input file attached to FILEHANDLE,
-or the undefined value at end of file, or if there was an error.
-If FILEHANDLE is omitted, reads from STDIN. This is not particularly
-efficient. However, it cannot be used by itself to fetch single
-characters without waiting for the user to hit enter. For that, try
-something more like:
+or the undefined value at end of file, or if there was an error (in
+the latter case C<$!> is set). If FILEHANDLE is omitted, reads from
+STDIN. This is not particularly efficient. However, it cannot be
+used by itself to fetch single characters without waiting for the user
+to hit enter. For that, try something more like:
if ($BSD_STYLE) {
system "stty cbreak /dev/tty 2>&1";
@@ -1860,6 +1896,13 @@ does not accept a PID argument, so only C is truly portable.
Returns the process id of the parent process.
+Note for Linux users: on Linux, the C functions C and
+C return different values from different threads. In order to
+be portable, this behavior is not reflected by the perl-level function
+C, that returns a consistent value across threads. If you want
+to call the underlying C, you may use the CPAN module
+C.
+
=item getpriority WHICH,WHO
Returns the current priority for a process, a process group, or a user.
@@ -1956,7 +1999,7 @@ lookup by name, in which case you get the other thing, whatever it is.
$name = getpwuid($num);
$name = getpwent();
$gid = getgrnam($name);
- $name = getgrgid($num;
+ $name = getgrgid($num);
$name = getgrent();
#etc.
@@ -2255,21 +2298,9 @@ system:
$retval = ioctl(...) || -1;
printf "System returned %d\n", $retval;
-The special string "C<0> but true" is exempt from B<-w> complaints
+The special string C<"0 but true"> is exempt from B<-w> complaints
about improper numeric conversions.
-Here's an example of setting a filehandle named C to be
-non-blocking at the system level. You'll have to negotiate C<$|>
-on your own, though.
-
- use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
-
- $flags = fcntl(REMOTE, F_GETFL, 0)
- or die "Can't get flags for the socket: $!\n";
-
- $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
- or die "Can't set flags for the socket: $!\n";
-
=item join EXPR,LIST
Joins the separate strings of LIST into a single string with fields
@@ -2282,13 +2313,20 @@ first argument. Compare L.
=item keys HASH
-Returns a list consisting of all the keys of the named hash. (In
-scalar context, returns the number of keys.) The keys are returned in
-an apparently random order. The actual random order is subject to
-change in future versions of perl, but it is guaranteed to be the same
-order as either the C or C function produces (given
-that the hash has not been modified). As a side effect, it resets
-HASH's iterator.
+Returns a list consisting of all the keys of the named hash.
+(In scalar context, returns the number of keys.)
+
+The keys are returned in an apparently random order. The actual
+random order is subject to change in future versions of perl, but it
+is guaranteed to be the same order as either the C or C
+function produces (given that the hash has not been modified). Since
+Perl 5.8.1 the ordering is different even between different runs of
+Perl for security reasons (see L).
+
+As a side effect, calling keys() resets the HASH's internal iterator,
+see L. (In particular, calling keys() in void context resets
+the iterator with no other overhead.)
Here is yet another way to print your environment:
@@ -2341,7 +2379,7 @@ same as the number actually killed).
kill 9, @goners;
If SIGNAL is zero, no signal is sent to the process. This is a
-useful way to check that the process is alive and hasn't changed
+useful way to check that a child process is alive and hasn't changed
its UID. See L for notes on the portability of this
construct.
@@ -2349,7 +2387,9 @@ Unlike in the shell, if SIGNAL is negative, it kills
process groups instead of processes. (On System V, a negative I
number will also kill process groups, but that's not portable.) That
means you usually want to use positive not negative signals. You may also
-use a signal name in quotes. See L for details.
+use a signal name in quotes.
+
+See L for more details.
=item last LABEL
@@ -2403,11 +2443,15 @@ If EXPR is omitted, uses C<$_>.
=item length
-Returns the length in characters of the value of EXPR. If EXPR is
+Returns the length in I of the value of EXPR. If EXPR is
omitted, returns length of C<$_>. Note that this cannot be used on
an entire array or hash to find out how many elements these have.
For that, use C and C respectively.
+Note the I: if the EXPR is in Unicode, you will get the
+number of characters, not the number of bytes. To get the length
+in bytes, use C, see L.
+
=item link OLDFILE,NEWFILE
Creates a new filename linked to the old filename. Returns true for
@@ -2517,7 +2561,8 @@ See also L for the inverse operation.
Does the same thing as the C function (including setting the
special C<_> filehandle) but stats a symbolic link instead of the file
the symbolic link points to. If symbolic links are unimplemented on
-your system, a normal C is done.
+your system, a normal C is done. For much more detailed
+information, please see the documentation for C.
If EXPR is omitted, stats C<$_>.
@@ -2692,7 +2737,7 @@ C work.
=item no Module
-See the L function, which C is the opposite of.
+See the C, and the C
-pragma, L), the I/O will operate on characters, not bytes.
+C, C, C, or C can cause confusion because the
+perlio or stdio layers usually buffers data. Returns the number of
+bytes actually read, C<0> at end of file, or undef if there was an
+error (in the latter case C<$!> is also set). SCALAR will be grown or
+shrunk so that the last byte actually read is the last byte of the
+scalar after the read.
An OFFSET may be specified to place the read data at some place in the
string other than the beginning. A negative OFFSET specifies
@@ -5411,9 +5675,15 @@ There is no syseof() function, which is ok, since eof() doesn't work
very well on device files (like ttys) anyway. Use sysread() and check
for a return value for 0 to decide whether you're done.
+Note that if the filehandle has been marked as C<:utf8> Unicode
+characters are read instead of bytes (the LENGTH, OFFSET, and the
+return value of sysread() are in Unicode characters).
+The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
+See L, L, and the C pragma, L.
+
=item sysseek FILEHANDLE,POSITION,WHENCE
-Sets FILEHANDLE's system position I using the system call
+Sets FILEHANDLE's system position in bytes using the system call
lseek(2). FILEHANDLE may be an expression whose value gives the name
of the filehandle. The values for WHENCE are C<0> to set the new
position to POSITION, C<1> to set the it to the current position plus
@@ -5421,11 +5691,11 @@ POSITION, and C<2> to set it to EOF plus POSITION (typically
negative).
Note the I: even if the filehandle has been set to operate
-on characters (for example by using the C<:utf8> discipline), tell()
+on characters (for example by using the C<:utf8> I/O layer), tell()
will return byte offsets, not character offsets (because implementing
that would render sysseek() very slow).
-sysseek() bypasses normal buffered io, so mixing this with reads (other
+sysseek() bypasses normal buffered IO, so mixing this with reads (other
than C, for example >< or read()) C, C,
C, C, or C may cause confusion.
@@ -5434,7 +5704,7 @@ and C (start of the file, current position, end of the file)
from the Fcntl module. Use of the constants is also more portable
than relying on 0, 1, and 2. For example to define a "systell" function:
- use Fnctl 'SEEK_CUR';
+ use Fcntl 'SEEK_CUR';
sub systell { sysseek($_[0], 0, SEEK_CUR) }
Returns the new position, or the undefined value on failure. A position
@@ -5487,9 +5757,17 @@ your program.
You can check all the failure possibilities by inspecting
C<$?> like this:
- $exit_value = $? >> 8;
- $signal_num = $? & 127;
- $dumped_core = $? & 128;
+ if ($? == -1) {
+ print "failed to execute: $!\n";
+ }
+ elsif ($? & 127) {
+ printf "child died with signal %d, %s coredump\n",
+ ($? & 127), ($? & 128) ? 'with' : 'without';
+ }
+ else {
+ printf "child exited with value %d\n", $? >> 8;
+ }
+
or more portably by using the W*() calls of the POSIX extension;
see L for more information.
@@ -5504,13 +5782,14 @@ See L and L for details.
=item syswrite FILEHANDLE,SCALAR
-Attempts to write LENGTH characters of data from variable SCALAR to
-the specified FILEHANDLE, using the system call write(2). If LENGTH
-is not specified, writes whole SCALAR. It bypasses buffered IO, so
+Attempts to write LENGTH bytes of data from variable SCALAR to the
+specified FILEHANDLE, using the system call write(2). If LENGTH is
+not specified, writes whole SCALAR. It bypasses buffered IO, so
mixing this with reads (other than C, C, C,
-C, C, or C may cause confusion because stdio usually
-buffers data. Returns the number of characters actually written, or
-C if there was an error. If the LENGTH is greater than the
+C, C, or C may cause confusion because the perlio and
+stdio layers usually buffers data. Returns the number of bytes
+actually written, or C if there was an error (in this case the
+errno variable C<$!> is also set). If the LENGTH is greater than the
available data in the SCALAR after the OFFSET, only as much data as is
available will be written.
@@ -5519,11 +5798,11 @@ string other than the beginning. A negative OFFSET specifies writing
that many characters counting backwards from the end of the string.
In the case the SCALAR is empty you can use OFFSET but only zero offset.
-Note the I: depending on the status of the filehandle,
-either (8-bit) bytes or characters are written. By default all
-filehandles operate on bytes, but for example if the filehandle has
-been opened with the C<:utf8> discipline (see L, and the open
-pragma, L), the I/O will operate on characters, not bytes.
+Note that if the filehandle has been marked as C<:utf8>, Unicode
+characters are written instead of bytes (the LENGTH, OFFSET, and the
+return value of syswrite() are in UTF-8 encoded Unicode characters).
+The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
+See L, L, and the C pragma, L.
=item tell FILEHANDLE
@@ -5536,7 +5815,7 @@ last read.
Note the I: even if the filehandle has been set to
operate on characters (for example by using the C<:utf8> open
-discipline), tell() will return byte offsets, not character offsets
+layer), tell() will return byte offsets, not character offsets
(because that would render seek() and tell() rather slow).
The return value of tell() for the standard streams like the STDIN
@@ -5592,6 +5871,7 @@ A class implementing a hash should have the following methods:
EXISTS this, key
FIRSTKEY this
NEXTKEY this, lastkey
+ SCALAR this
DESTROY this
UNTIE this
@@ -5663,9 +5943,10 @@ and 00:00:00 UTC, January 1, 1970 for most other systems).
Suitable for feeding to C and C.
For measuring time in better granularity than one second,
-you may use either the Time::HiRes module from CPAN, or
-if you have gettimeofday(2), you may be able to use the
-C interface of Perl, see L for details.
+you may use either the Time::HiRes module (from CPAN, and starting from
+Perl 5.8 part of the standard distribution), or if you have
+gettimeofday(2), you may be able to use the C interface of Perl.
+See L for details.
=item times
@@ -5760,7 +6041,7 @@ string of octal digits. See also L, if all you have is a string.
Undefines the value of EXPR, which must be an lvalue. Use only on a
scalar value, an array (using C<@>), a hash (using C<%>), a subroutine
-(using C<&>), or a typeglob (using <*>). (Saying C
+(using C<&>), or a typeglob (using C<*>). (Saying C
will probably not do what you expect on most predefined variables or
DBM list values, so don't do that; see L.) Always returns the
undefined value. You can omit the EXPR, in which case nothing is
@@ -5800,10 +6081,14 @@ If LIST is omitted, uses C<$_>.
=item unpack TEMPLATE,EXPR
+=item unpack TEMPLATE
+
C does the reverse of C: it takes a string
and expands it out into a list of values.
(In scalar context, it returns merely the first value produced.)
+If EXPR is omitted, unpacks the C<$_> string.
+
The string is broken into chunks described by the TEMPLATE. Each chunk
is converted separately to a value. Typically, either the string is a result
of C, or the bytes of the string represent a C structure of some
@@ -5845,15 +6130,19 @@ has no way of checking whether the value passed to 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 the repeat count of a field is larger than what the remainder of
-the input string allows, repeat count is decreased. If the input string
-is longer than one described by the TEMPLATE, the rest is ignored.
+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: in some cases, the repeat count is decreased, or
+C will produce null strings or zeroes, or terminate with an
+error. If the input string is longer than one described by the TEMPLATE,
+the rest is ignored.
See L for more examples and notes.
=item untie VARIABLE
Breaks the binding between a variable and a package. (See C.)
+Has no effect if the variable is not tied.
=item unshift ARRAY,LIST
@@ -5913,7 +6202,8 @@ features back into the current package. The module can implement its
C method any way it likes, though most modules just choose to
derive their C method via inheritance from the C class that
is defined in the C module. See L. If no C
-method can be found then the call is skipped.
+method can be found then the call is skipped, even if there is an AUTOLOAD
+method.
If you do not want to call the package's C method (for instance,
to stop your namespace from being altered), explicitly supply the empty list:
@@ -5953,6 +6243,8 @@ through the end of the file).
There's a corresponding C command that unimports meanings imported
by C, i.e., it calls C instead of C.
+It behaves exactly as C does with respect to VERSION, an
+omitted LIST, empty LIST, or no unimport method being found.
no integer;
no strict 'refs';
@@ -5968,28 +6260,47 @@ Changes the access and modification times on each file of a list of
files. The first two elements of the list must be the NUMERICAL access
and modification times, in that order. Returns the number of files
successfully changed. The inode change time of each file is set
-to the current time. This code has the same effect as the C
-command if the files already exist:
+to the current time. For example, this code has the same effect as the
+Unix touch(1) command when the files I.
#!/usr/bin/perl
- $now = time;
- utime $now, $now, @ARGV;
+ $atime = $mtime = time;
+ utime $atime, $mtime, @ARGV;
-If the first two elements of the list are C, then the utime(2)
-function in the C library will be called with a null second argument.
-On most systems, this will set the file's access and modification
-times to the current time. (i.e. equivalent to the example above.)
+Since perl 5.7.2, if the first two elements of the list are C, then
+the utime(2) function in the C library will be called with a null second
+argument. On most systems, this will set the file's access and
+modification times to the current time (i.e. equivalent to the example
+above.)
utime undef, undef, @ARGV;
+Under NFS this will use the time of the NFS server, not the time of
+the local machine. If there is a time synchronization problem, the
+NFS server and local machine will have different times. The Unix
+touch(1) command will in fact normally use this form instead of the
+one shown in the first example.
+
+Note that only passing one of the first two elements as C will
+be equivalent of passing it as 0 and will not have the same effect as
+described when they are both C. This case will also trigger an
+uninitialized warning.
+
=item values HASH
-Returns a list consisting of all the values of the named hash. (In a
-scalar context, returns the number of values.) The values are
-returned in an apparently random order. The actual random order is
-subject to change in future versions of perl, but it is guaranteed to
-be the same order as either the C or C function would
-produce on the same (unmodified) hash.
+Returns a list consisting of all the values of the named hash.
+(In a scalar context, returns the number of values.)
+
+The values are returned in an apparently random order. The actual
+random order is subject to change in future versions of perl, but it
+is guaranteed to be the same order as either the C or C
+function would produce on the same (unmodified) hash. Since Perl
+5.8.1 the ordering is different even between different runs of Perl
+for security reasons (see L).
+
+As a side effect, calling values() resets the HASH's internal iterator,
+see L. (In particular, calling values() in void context resets
+the iterator with no other overhead.)
Note that the values are not copied, which means modifying them will
modify the contents of the hash:
@@ -5997,7 +6308,6 @@ modify the contents of the hash:
for (values %hash) { s/foo/bar/g } # modifies %hash values
for (@hash{keys %hash}) { s/foo/bar/g } # same
-As a side effect, calling values() resets the HASH's internal iterator.
See also C, C, and C.
=item vec EXPR,OFFSET,BITS
@@ -6034,10 +6344,10 @@ 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).
The string should not contain any character with the value > 255 (which
-can only happen if you're using UTF8 encoding). If it does, it will be
-treated as something which is not UTF8 encoded. When the C was
+can only happen if you're using UTF-8 encoding). If it does, it will be
+treated as something which is not UTF-8 encoded. When the C was
assigned to, other parts of your program will also no longer consider the
-string to be UTF8 encoded. In other words, if you do have such characters
+string to be UTF-8 encoded. In other words, if you do have such characters
in your string, vec() will operate on the actual byte string, and not the
conceptual character string.