C<-X>, C<binmode>, C<chmod>, C<chown>, C<chroot>, C<crypt>,
C<dbmclose>, C<dbmopen>, C<dump>, C<endgrent>, C<endhostent>,
C<endnetent>, C<endprotoent>, C<endpwent>, C<endservent>, C<exec>,
-C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostent>,
-C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
+C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostbyname>,
+C<gethostent>, C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
C<getppid>, C<getprgp>, C<getpriority>, C<getprotobynumber>,
C<getprotoent>, C<getpwent>, C<getpwnam>, C<getpwuid>,
C<getservbyport>, C<getservent>, C<getsockopt>, C<glob>, C<ioctl>,
=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
# didn't
}
+For more information see L<perlipc>.
+
=item atan2 Y,X
Returns the arctangent of Y/X in the range -PI to PI.
packed address of the appropriate type for the socket. See the examples in
L<perlipc/"Sockets: Client/Server Communication">.
-=item binmode FILEHANDLE, DISCIPLINE
+=item binmode FILEHANDLE, LAYER
=item binmode FILEHANDLE
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<undef> on failure.
-
-If DISCIPLINE is ommited the filehandle is made suitable for
-passing binary data. This includes turning off CRLF translation
-and marking it as bytes.
+otherwise it returns C<undef> 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 as despite what may be implied in I<"Programming Perl">
+(the Camel) or elsewhere C<:raw> is I<not> the simply inverse of C<:crlf>
+-- other layers which would affect binary nature of the stream are
+I<also> disabled. See L<PerlIO>, L<perlrun> 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<disciplines>. The normal implementation
-of disciplines in perl5.8 and later is in terms of I<layers>. See
-L<PerlIO>. (There is typically a one-to-one correspondence between
-layers and disiplines.) The C<open> pragma can be used to establish
-default I/O disciplines. See L<open>.
+form C<:...>, are called I/O I<layers>. The C<open> pragma can be used to
+establish default I/O layers. See L<open>.
-The C<:raw> discipline is deprecated. (As opposed to what Camel III
-said, it is not the inverse of C<:crlf>.) See L<PerlIO>, L<perlrun>
-and the discussion about the PERLIO environment variable.
+I<The LAYER parameter of the binmode() 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 from "discipline" to "layer". All documentation
+of this version of Perl therefore refers to "layers" rather than to
+"disciplines". Now back to the regularly scheduled documentation...>
+
+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<open>.
-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
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<chomp $cwd = `pwd`;>
+is interpreted as C<(chomp $cwd) = `pwd`;>, rather than as
+C<chomp( $cwd = `pwd` )> which you might expect. Similarly,
+C<chomp $a, $b> is interpreted as C<chomp($a), $b> rather than
+as C<chomp($a, $b)>.
+
=item chop VARIABLE
=item chop( LIST )
Note that C<chop> returns the last character. To return all but the last
character, use C<substr($string, 0, -1)>.
+See also L</chomp>.
+
=item chown LIST
Changes the owner (and group) of a list of files. The first two
to 255 (inclusive) are by default not encoded in Unicode for backward
compatibility reasons (but see L<encoding>).
+If NUMBER is omitted, uses C<$_>.
+
For the reverse, use L</ord>.
-See L<perlunicode> and L<encoding> for more about Unicode.
-If NUMBER is omitted, uses C<$_>.
+Note that under the C<bytes> pragma the NUMBER is masked to
+the low eight bits.
+
+See L<perlunicode> and L<encoding> for more about Unicode.
=item chroot FILENAME
Closes a directory opened by C<opendir> 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
the password file for lousy passwords, amongst other things. Only the
guys wearing white hats should do this.
-Note that C<crypt> is intended to be a one-way function, much like
+Note that L<crypt|/crypt> 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
When verifying an existing encrypted string you should use the
encrypted text as the salt (like C<crypt($plain, $crypted) eq
-$crypted>). This allows your code to work with the standard C<crypt>
+$crypted>). This allows your code to work with the standard L<crypt|/crypt>
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.
When choosing a new salt create a random two character string whose
characters come from the set C<[./0-9A-Za-z]> (like C<join '', ('.',
-'/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>).
+'/', 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<crypt()> accepts.
Here's an example that makes sure that whoever runs this program knows
their own password:
Of course, typing in your own password to whoever asks you
for it is unwise.
-The L<crypt> function is unsuitable for encrypting large quantities
+The L<crypt|/crypt> 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<by-module/Crypt> and F<by-module/PGP> directories
on your favorite CPAN mirror for a slew of potentially useful
You may also use C<defined(&func)> 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<AUTOLOAD> method that
makes it spring into existence the first time that it is called -- see
L<perlsub>.
If LIST is empty and C<$@> contains an object reference that has a
C<PROPAGATE> 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.
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<keys> or C<values> 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<keys> or C<values>
+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<perlsec/"Algorithmic Complexity Attacks">).
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<undef> in
# 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<eof> in Perl, because the
C<eval BLOCK> does I<not> count as a loop, so the loop control statements
C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
+Note that as a very special case, an C<eval ''> executed within the C<DB>
+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
second--glance appear to be an lvalue context may be fixed in a future
release.
-See L<perlref/"Pseudo-hashes: Using an array as a hash"> 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.
fcntl($filehandle, F_GETFL, $packed_return_buffer)
or die "can't fcntl F_GETFL: $!";
-You don't have to check for C<defined> on the return from C<fnctl>.
+You don't have to check for C<defined> on the return from C<fcntl>.
Like C<ioctl>, 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
=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 >/dev/tty 2>&1";
Returns the process id of the parent process.
+Note for Linux users: on Linux, the C functions C<getpid()> and
+C<getppid()> return different values from different threads. In order to
+be portable, this behavior is not reflected by the perl-level function
+C<getppid()>, that returns a consistent value across threads. If you want
+to call the underlying C<getppid()>, you may use the CPAN module
+C<Linux::Pid>.
+
=item getpriority WHICH,WHO
Returns the current priority for a process, a process group, or a user.
$name = getpwuid($num);
$name = getpwent();
$gid = getgrnam($name);
- $name = getgrgid($num;
+ $name = getgrgid($num);
$name = getgrent();
#etc.
=item glob
-Returns the value of EXPR with filename expansions such as the
-standard Unix shell F</bin/csh> would do. This is the internal function
-implementing the C<< <*.c> >> operator, but you can use it directly.
-If EXPR is omitted, C<$_> is used. The C<< <*.c> >> operator is
-discussed in more detail in L<perlop/"I/O Operators">.
+In list context, returns a (possibly empty) list of filename expansions on
+the value of EXPR such as the standard Unix shell F</bin/csh> would do. In
+scalar context, glob iterates through such filename expansions, returning
+undef when the list is exhausted. This is the internal function
+implementing the C<< <*.c> >> operator, but you can use it directly. If
+EXPR is omitted, C<$_> is used. The C<< <*.c> >> operator is discussed in
+more detail in L<perlop/"I/O Operators">.
Beginning with v5.6.0, this operator is implemented using the standard
C<File::Glob> extension. See L<File::Glob> for details.
=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<values> or C<each> 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<values> or C<each>
+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<perlsec/"Algorithmic Complexity
+Attacks">).
+
+As a side effect, calling keys() resets the HASH's internal iterator,
+see L</each>.
Here is yet another way to print your environment:
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<perlport> for notes on the portability of this
construct.
process groups instead of processes. (On System V, a negative I<PROCESS>
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<perlipc/"Signals"> for details.
+use a signal name in quotes.
+
+See L<perlipc/"Signals"> for more details.
=item last LABEL
=item length
-Returns the length in characters of the value of EXPR. If EXPR is
+Returns the length in I<characters> 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<scalar @array> and C<scalar keys %hash> respectively.
+Note the I<characters>: 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<do { use bytes; length(EXPR) }>, see L<bytes>.
+
=item link OLDFILE,NEWFILE
Creates a new filename linked to the old filename. Returns true for
Does the same thing as the C<stat> 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<stat> is done.
+your system, a normal C<stat> is done. For much more detailed
+information, please see the documentation for C<stat>.
If EXPR is omitted, stats C<$_>.
=item no Module
-See the L</use> function, which C<no> is the opposite of.
+See the C<use> function, of which C<no> is the opposite.
=item oct EXPR
(The following is a comprehensive reference to open(): for a gentler
introduction you may consider L<perlopentut>.)
-If FILEHANDLE is an undefined lexical (C<my>) variable the variable is
-assigned a reference to a new anonymous filehandle, otherwise if
-FILEHANDLE is an expression, its value is used as the name of the real
-filehandle wanted. (This is considered a symbolic reference, so C<use
-strict 'refs'> should I<not> be in effect.)
+If FILEHANDLE is an undefined scalar variable (or array or hash element)
+the variable is assigned a reference to a new anonymous filehandle,
+otherwise if FILEHANDLE is an expression, its value is used as the name of
+the real filehandle wanted. (This is considered a symbolic reference, so
+C<use strict 'refs'> should I<not> be in effect.)
If EXPR is omitted, the scalar variable of the same name as the
FILEHANDLE contains the filename. (Note that lexical variables--those
In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN
and opening C<< '>-' >> opens STDOUT.
-You may use the three-argument form of open to specify
-I<I/O disciplines> or IO "layers" to be applied to the handle that affect how the input and output
-are processed: (see L<open> and L<PerlIO> for more details).
-For example
+You may use the three-argument form of open to specify IO "layers"
+(sometimes also referred to as "disciplines") to be applied to the handle
+that affect how the input and output are processed (see L<open> and
+L<PerlIO> for more details). For example
open(FH, "<:utf8", "file")
will open the UTF-8 encoded file containing Unicode characters,
-see L<perluniintro>. (Note that if disciplines are specified in the
-three-arg form then default disciplines set by the C<open> pragma are
+see L<perluniintro>. (Note that if layers are specified in the
+three-arg form then default layers set by the C<open> pragma are
ignored.)
Open returns nonzero upon success, the undefined value otherwise. If
open(TMP, "+>", undef) or die ...
-opens a filehandle to an anonymous temporary file.
+opens a filehandle to an anonymous temporary file. Also using "+<"
+works for symmetry, but you really should consider writing something
+to the temporary file first. You will need to seek() to do the
+reading.
File handles can be opened to "in memory" files held in Perl scalars via:
}
You may also, in the Bourne shell tradition, specify an EXPR beginning
-with C<< '>&' >>, in which case the rest of the string is interpreted as the
-name of a filehandle (or file descriptor, if numeric) to be
-duped and opened. You may use C<&> after C<< > >>, C<<< >> >>>,
-C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>. The
-mode you specify should match the mode of the original filehandle.
-(Duping a filehandle does not take into account any existing contents of
-IO buffers.) If you use the 3 arg form then you can pass either a number,
-the name of a filehandle or the normal "reference to a glob".
+with C<< '>&' >>, in which case the rest of the string is interpreted
+as the name of a filehandle (or file descriptor, if numeric) to be
+duped (as L<dup(2)>) and opened. You may use C<&> after C<< > >>,
+C<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>.
+The mode you specify should match the mode of the original filehandle.
+(Duping a filehandle does not take into account any existing contents
+of IO buffers.) If you use the 3 arg form then you can pass either a
+number, the name of a filehandle or the normal "reference to a glob".
Here is a script that saves, redirects, and restores C<STDOUT> and
C<STDERR> using various methods:
print STDOUT "stdout 2\n";
print STDERR "stderr 2\n";
-If you specify C<< '<&=N' >>, where C<N> is a number, then Perl will
-do an equivalent of C's C<fdopen> of that file descriptor; this is
-more parsimonious of file descriptors. For example:
+If you specify C<< '<&=X' >>, where C<X> is a number or a filehandle,
+then Perl will do an equivalent of C's C<fdopen> of that file
+descriptor (and not call L<dup(2)>); this is more parsimonious
+of file descriptors. For example:
+ # open for input, reusing the fileno of $fd
open(FILEHANDLE, "<&=$fd")
or
open(FILEHANDLE, "<&=", $fd)
+or
+
+ # open for append, using the fileno of OLDFH
+ open(FH, ">>&=", OLDFH)
+
+or
+
+ open(FH, ">>&=OLDFH")
+
+Being parsimonious on filehandles is useful (besides being
+parsimonious) also for example when something is dependent
+on the file descriptors, like for example locking using flock().
+If you do just a C<< open(A, '>>&B') >>, the filehandle A will not
+have the file descriptor as B has, and therefore flock(A) will
+not flock(B), and vice versa. But with C<< open(A, '>>&=B') >>
+the filehandles will share the same file descriptor.
+
Note that if Perl is using the standard C libraries' fdopen() then on
many UNIX systems, fdopen() is known to fail when file descriptors
exceed a certain value, typically 255. If you need more file
Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
C<seekdir>, C<rewinddir>, and C<closedir>. Returns true if successful.
+DIRHANDLE may be an expression whose value can be used as an indirect
+dirhandle, usually the real dirhandle name. If DIRHANDLE is an undefined
+scalar variable (or array or hash element), the variable is assigned a
+reference to a new anonymous dirhandle.
DIRHANDLEs have their own namespace separate from FILEHANDLEs.
=item ord EXPR
x A null byte.
X Back up a byte.
- @ Null fill to absolute position.
+ @ Null fill to absolute position, counted from the start of
+ the innermost ()-group.
( Start of a ()-group.
The following rules apply:
integer-packing ones like C<n> (for Java strings), C<w> (for ASN.1 or
SNMP) and C<N> (for Sun XDR).
-The I<string-item> must, at present, be C<"A*">, C<"a*"> or C<"Z*">.
-For C<unpack> the length of the string is obtained from the I<length-item>,
-but if you put in the '*' it will be ignored.
+For C<pack>, the I<string-item> must, at present, be C<"A*">, C<"a*"> or
+C<"Z*">. For C<unpack> the length of the string is obtained from the
+I<length-item>, but if you put in the '*' it will be ignored. For all other
+codes, C<unpack> applies the length value to the next item, which must not
+have a repeat count.
unpack 'C/a', "\04Gurusamy"; gives 'Guru'
unpack 'a3/A* A*', '007 Bond J '; gives (' Bond','J')
print $Config{longsize}, "\n";
print $Config{longlongsize}, "\n";
-(The C<$Config{longlongsize}> will be undefine if your system does
+(The C<$Config{longlongsize}> will be undefined if your system does
not support long longs.)
=item *
=item *
A ()-group is a sub-TEMPLATE enclosed in parentheses. A group may
-take a repeat count, both as postfix, and via the C</> template
-character.
+take a repeat count, both as postfix, and for unpack() also via the C</>
+template character. Within each repetition of a group, positioning with
+C<@> starts again at 0. Therefore, the result of
+
+ pack( '@1A((@2A)@3A)', 'a', 'b', 'c' )
+
+is the string "\0a\0\0bc".
+
=item *
=item *
A comment in a TEMPLATE starts with C<#> and goes to the end of line.
+White space may be used to separate pack codes from each other, but
+a C<!> modifier and a repeat count must follow immediately.
=item *
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, or a C<0>, the value C<1> is used. Automatically calls C<srand>
-unless C<srand> has already been called. See also C<srand>.
+omitted, the value C<1> is used. Currently EXPR with the value C<0> is
+also special-cased as C<1> - this has not been documented before perl 5.8.0
+and is subject to change in future versions of perl. Automatically calls
+C<srand> unless C<srand> has already been called. See also C<srand>.
Apply C<int()> to the value returned by C<rand()> if you want random
integers instead of random fractional numbers. For example,
Attempts to read LENGTH I<characters> of data into variable SCALAR
from the specified FILEHANDLE. Returns the number of characters
-actually read, C<0> at end of file, or undef if there was an error.
-SCALAR will be grown or shrunk to the length actually read. If SCALAR
-needs growing, the new bytes will be zero bytes. An OFFSET may be
-specified to place the read data into some other place in SCALAR than
-the beginning. The call is actually implemented in terms of either
-Perl's or system's fread() call. To get a true read(2) system call,
-see C<sysread>.
+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 character actually read is the last character 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
+placement at that many characters counting backwards from the end of
+the string. A positive OFFSET greater than the length of SCALAR
+results in the string being padded to the required size with C<"\0">
+bytes before the result of the read is appended.
+
+The call is actually implemented in terms of either Perl's or system's
+fread() call. To get a true read(2) system call, see C<sysread>.
Note the I<characters>: depending on the status of the filehandle,
either (8-bit) bytes or characters are read. By default all
filehandles operate on bytes, but for example if the filehandle has
-been opened with the C<:utf8> discipline (see L</open>, and the C<open>
-pragma, L<open>), the I/O will operate on characters, not bytes.
+been opened with the C<:utf8> I/O layer (see L</open>, and the C<open>
+pragma, L<open>), the I/O will operate on UTF-8 encoded Unicode
+characters, not bytes. Similarly for the C<:encoding> pragma:
+in that case pretty much any characters can be read.
=item readdir DIRHANDLE
$line = <STDIN>;
$line = readline(*STDIN); # same thing
+If readline encounters an operating system error, C<$!> will be set with the
+corresponding error message. It can be helpful to check C<$!> 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 C<readline>, and takes the necessary
+steps to ensure that C<readline> was successful.
+
+ for (;;) {
+ undef $!;
+ unless (defined( $line = <> )) {
+ die $! if $!;
+ last; # reached EOF
+ }
+ # ...
+ }
+
=item readlink EXPR
=item readlink
Note the I<characters>: depending on the status of the socket, either
(8-bit) bytes or characters are received. By default all sockets
operate on bytes, but for example if the socket has been changed using
-binmode() to operate with the C<:utf8> discipline (see the C<open>
-pragma, L<open>), the I/O will operate on characters, not bytes.
+binmode() to operate with the C<:utf8> I/O layer (see the C<open>
+pragma, L<open>), the I/O will operate on UTF-8 encoded Unicode
+characters, not bytes. Similarly for the C<:encoding> pragma:
+in that case pretty much any characters can be read.
=item redo LABEL
eval "require $class";
+Now that you understand how C<require> looks for files in the case of
+a bareword argument, there is a little extra functionality going on
+behind the scenes. Before C<require> looks for a "F<.pm>" extension,
+it will first look for a filename with a "F<.pmc>" extension. A file
+with this extension is assumed to be Perl bytecode generated by
+L<B::Bytecode|B::Bytecode>. If this file is found, and it's modification
+time is newer than a coinciding "F<.pm>" non-compiled file, it will be
+loaded in place of that non-compiled file ending in a "F<.pm>" extension.
+
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.
=item rmdir
-Deletes the directory specified by FILENAME if that directory is empty. If it
-succeeds it returns true, otherwise it returns false and sets C<$!> (errno). If
-FILENAME is omitted, uses C<$_>.
+Deletes the directory specified by FILENAME if that directory is
+empty. If it succeeds it returns true, otherwise it returns false and
+sets C<$!> (errno). If FILENAME is omitted, uses C<$_>.
=item s///
Note the I<in bytes>: 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 implementing that would render seek() and tell() rather slow).
If you want to position file for C<sysread> or C<syswrite>, don't use
Note the I<characters>: depending on the status of the socket, either
(8-bit) bytes or characters are sent. By default all sockets operate
on bytes, but for example if the socket has been changed using
-binmode() to operate with the C<:utf8> discipline (see L</open>, or
-the C<open> pragma, L<open>), the I/O will operate on characters, not
-bytes.
+binmode() to operate with the C<:utf8> I/O layer (see L</open>, or the
+C<open> pragma, L<open>), the I/O will operate on UTF-8 encoded
+Unicode characters, not bytes. Similarly for the C<:encoding> pragma:
+in that case pretty much any characters can be sent.
=item setpgrp PID,PGRP
limited control of the sort. Its rather blunt control of the
underlying algorithm may not persist into future perls, but the
ability to characterize the input or output in implementation
-independent ways quite probably will. See L</use>.
+independent ways quite probably will. See L<sort>.
Examples:
sometimes saying the opposite, for example) the results are not
well-defined.
+Because C<< <=> >> returns C<undef> when either operand is C<NaN>
+(not-a-number), and because C<sort> will trigger a fatal error unless the
+result of a comparison is defined, when sorting with a comparison function
+like C<< $a <=> $b >>, be careful about lists that might contain a C<NaN>.
+The following example takes advantage of the fact that C<NaN != NaN> to
+eliminate any C<NaN>s from the input.
+
+ @result = sort { $a <=> $b } grep { $_ == $_ } @input;
+
=item splice ARRAY,OFFSET,LENGTH,LIST
=item splice ARRAY,OFFSET,LENGTH
past the end of the array, perl issues a warning, and splices at the
end of the array.
-The following equivalences hold (assuming C<$[ == 0>):
+The following equivalences hold (assuming C<< $[ == 0 and $#a >= $i >> )
push(@a,$x,$y) splice(@a,@a,0,$x,$y)
pop(@a) splice(@a,-1)
shift(@a) splice(@a,0,1)
unshift(@a,$x,$y) splice(@a,0,0,$x,$y)
- $a[$x] = $y splice(@a,$x,1,$y)
+ $a[$i] = $y splice(@a,$i,1,$y)
Example, assuming array lengths are passed before arrays:
($login, $passwd, $remainder) = split(/:/, $_, 3);
-When assigning to a list, if LIMIT is omitted, Perl supplies a LIMIT
-one larger than the number of variables in the list, to avoid
+When assigning to a list, if LIMIT is omitted, or zero, Perl supplies
+a LIMIT one larger than the number of variables in the list, to avoid
unnecessary work. For the list above LIMIT would have been 4 by
default. In time critical applications it behooves you not to split
into more fields than you really need.
patterns that vary at runtime. (To do runtime compilation only once,
use C</$variable/o>.)
-As a special case, specifying a PATTERN of space (C<' '>) will split on
-white space just as C<split> with no arguments does. Thus, C<split(' ')> can
-be used to emulate B<awk>'s default behavior, whereas C<split(/ /)>
+As a special case, specifying a PATTERN of space (S<C<' '>>) will split on
+white space just as C<split> with no arguments does. Thus, S<C<split(' ')>> can
+be used to emulate B<awk>'s default behavior, whereas S<C<split(/ /)>>
will give you as many null initial fields as there are leading spaces.
-A C<split> on C</\s+/> is like a C<split(' ')> except that any leading
+A C<split> on C</\s+/> is like a S<C<split(' ')>> except that any leading
whitespace produces a null first field. A C<split> with no arguments
-really does a C<split(' ', $_)> internally.
+really does a S<C<split(' ', $_)>> internally.
A PATTERN of C</^/> is treated as if it were C</^/m>, since it isn't
much use otherwise.
%O a synonym for %lo
%F a synonym for %f
-Note that the number of exponent digits in the scientific notation by
-C<%e>, C<%E>, C<%g> and C<%G> for numbers with the modulus of the
+Note that the number of exponent digits in the scientific notation produced
+by C<%e>, C<%E>, C<%g> and C<%G> for numbers with the modulus of the
exponent less than 100 is system-dependent: it may be three or less
(zero-padded as necessary). In other words, 1.23 times ten to the
99th may be either "1.23e99" or "1.23e099".
-Perl permits the following universally-known flags between the C<%>
-and the conversion letter:
+Between the C<%> and the format letter, you may specify a number of
+additional attributes controlling the interpretation of the format.
+In order, these are:
+=over 4
+
+=item format parameter index
+
+An explicit format parameter index, such as C<2$>. By default sprintf
+will format the next unused argument in the list, but this allows you
+to take the arguments out of order. Eg:
+
+ printf '%2$d %1$d', 12, 34; # prints "34 12"
+ printf '%3$d %d %1$d', 1, 2, 3; # prints "3 1 1"
+
+=item flags
+
+one or more of:
space prefix positive number with a space
+ prefix positive number with a plus sign
- left-justify within the field
0 use zeros, not spaces, to right-justify
- # prefix non-zero octal with "0", non-zero hex with "0x"
- number minimum field width
- .number "precision": digits after decimal point for
- floating-point, max length for string, minimum length
- for integer
- l interpret integer as C type "long" or "unsigned long"
- h interpret integer as C type "short" or "unsigned short"
- If no flags, interpret integer as C type "int" or "unsigned"
-
-Perl supports parameter ordering, in other words, fetching the
-parameters in some explicitly specified "random" ordering as opposed
-to the default implicit sequential ordering. The syntax is, instead
-of the C<%> and C<*>, to use C<%>I<digits>C<$> and C<*>I<digits>C<$>,
-where the I<digits> is the wanted index, from one upwards. For example:
-
- printf "%2\$d %1\$d\n", 12, 34; # will print "34 12\n"
- printf "%*2\$d\n", 12, 3; # will print " 12\n"
-
-Note that using the reordering syntax does not interfere with the usual
-implicit sequential fetching of the parameters:
-
- printf "%2\$d %d\n", 12, 34; # will print "34 12\n"
- printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n"
- printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n"
- printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n"
- printf "%*3\$2\$d %d\n", 12, 34, 3; # will print " 34 12\n"
-
-There are also two Perl-specific flags:
-
- V interpret integer as Perl's standard integer type
- v interpret string as a vector of integers, output as
- numbers separated either by dots, or by an arbitrary
- string received from the argument list when the flag
- is preceded by "*"
-
-Where a number would appear in the flags, an asterisk (C<*>) may be
-used instead, in which case Perl uses the next item in the parameter
-list as the given number (that is, as the field width or precision).
+ # prefix non-zero octal with "0", non-zero hex with "0x",
+ non-zero binary with "0b"
+
+For example:
+
+ printf '<% d>', 12; # prints "< 12>"
+ printf '<%+d>', 12; # prints "<+12>"
+ printf '<%6s>', 12; # prints "< 12>"
+ printf '<%-6s>', 12; # prints "<12 >"
+ printf '<%06s>', 12; # prints "<000012>"
+ printf '<%#x>', 12; # prints "<0xc>"
+
+=item vector flag
+
+The vector flag C<v>, optionally specifying the join string to use.
+This flag tells perl to interpret the supplied string as a vector
+of integers, one for each character in the string, separated by
+a given string (a dot C<.> by default). This can be useful for
+displaying ordinal values of characters in arbitrary strings:
+
+ printf "version is v%vd\n", $^V; # Perl's version
+
+Put an asterisk C<*> before the C<v> to override the string to
+use to separate the numbers:
+
+ printf "address is %*vX\n", ":", $addr; # IPv6 address
+ printf "bits are %0*v8b\n", " ", $bits; # random bitstring
+
+You can also explicitly specify the argument number to use for
+the join string using eg C<*2$v>:
+
+ printf '%*4$vX %*4$vX %*4$vX', @addr[1..3], ":"; # 3 IPv6 addresses
+
+=item (minimum) width
+
+Arguments are usually formatted to be only as wide as required to
+display the given value. You can override the width by putting
+a number here, or get the width from the next argument (with C<*>)
+or from a specified argument (with eg C<*2$>):
+
+ printf '<%s>', "a"; # prints "<a>"
+ printf '<%6s>', "a"; # prints "< a>"
+ printf '<%*s>', 6, "a"; # prints "< a>"
+ printf '<%*2$s>', "a", 6; # prints "< a>"
+ printf '<%2s>', "long"; # prints "<long>" (does not truncate)
+
If a field width obtained through C<*> is negative, it has the same
effect as the C<-> flag: left-justification.
-The C<v> flag is useful for displaying ordinal values of characters
-in arbitrary strings:
+=item precision, or maximum width
- printf "version is v%vd\n", $^V; # Perl's version
- printf "address is %*vX\n", ":", $addr; # IPv6 address
- printf "bits are %*vb\n", " ", $bits; # random bitstring
+You can specify a precision (for numeric conversions) or a maximum
+width (for string conversions) by specifying a C<.> followed by a number.
+For floating point formats, with the exception of 'g' and 'G', this specifies
+the number of decimal places to show (the default being 6), eg:
-If C<use locale> is in effect, the character used for the decimal
-point in formatted real numbers is affected by the LC_NUMERIC locale.
-See L<perllocale>.
+ # these examples are subject to system-specific variation
+ printf '<%f>', 1; # prints "<1.000000>"
+ printf '<%.1f>', 1; # prints "<1.0>"
+ printf '<%.0f>', 1; # prints "<1>"
+ printf '<%e>', 10; # prints "<1.000000e+01>"
+ printf '<%.1e>', 10; # prints "<1.0e+01>"
-If Perl understands "quads" (64-bit integers) (this requires
-either that the platform natively support quads or that Perl
-be specifically compiled to support quads), the characters
+For 'g' and 'G', this specifies the maximum number of digits to show,
+including prior to the decimal point as well as after it, eg:
- d u o x X b i D U O
+ # these examples are subject to system-specific variation
+ printf '<%g>', 1; # prints "<1>"
+ printf '<%.10g>', 1; # prints "<1>"
+ printf '<%g>', 100; # prints "<100>"
+ printf '<%.1g>', 100; # prints "<1e+02>"
+ printf '<%.2g>', 100.01; # prints "<1e+02>"
+ printf '<%.5g>', 100.01; # prints "<100.01>"
+ printf '<%.4g>', 100.01; # prints "<100>"
-print quads, and they may optionally be preceded by
+For integer conversions, specifying a precision implies that the
+output of the number itself should be zero-padded to this width:
- ll L q
+ printf '<%.6x>', 1; # prints "<000001>"
+ printf '<%#.6x>', 1; # prints "<0x000001>"
+ printf '<%-10.6x>', 1; # prints "<000001 >"
-For example
+For string conversions, specifying a precision truncates the string
+to fit in the specified width:
- %lld %16LX %qo
+ printf '<%.5s>', "truncated"; # prints "<trunc>"
+ printf '<%10.5s>', "truncated"; # prints "< trunc>"
-You can find out whether your Perl supports quads via L<Config>:
+You can also get the precision from the next argument using C<.*>:
- use Config;
- ($Config{use64bitint} eq 'define' || $Config{longsize} == 8) &&
- print "quads\n";
+ printf '<%.6x>', 1; # prints "<000001>"
+ printf '<%.*x>', 6, 1; # prints "<000001>"
-If Perl understands "long doubles" (this requires that the platform
-support long doubles), the flags
+You cannot currently get the precision from a specified number,
+but it is intended that this will be possible in the future using
+eg C<.*2$>:
- e f g E F G
+ printf '<%.*2$x>', 1, 6; # INVALID, but in future will print "<000001>"
-may optionally be preceded by
+=item size
- ll L
+For numeric conversions, you can specify the size to interpret the
+number as using C<l>, C<h>, C<V>, C<q>, C<L>, or C<ll>. For integer
+conversions (C<d u o x X b i D U O>), numbers are usually assumed to be
+whatever the default integer size is on your platform (usually 32 or 64
+bits), but you can override this to use instead one of the standard C types,
+as supported by the compiler used to build Perl:
-For example
+ l interpret integer as C type "long" or "unsigned long"
+ h interpret integer as C type "short" or "unsigned short"
+ q, L or ll interpret integer as C type "long long", "unsigned long long".
+ or "quads" (typically 64-bit integers)
- %llf %Lg
+The last will produce errors if Perl does not understand "quads" in your
+installation. (This requires that either the platform natively supports quads
+or Perl was specifically compiled to support quads.) You can find out
+whether your Perl supports quads via L<Config>:
+
+ use Config;
+ ($Config{use64bitint} eq 'define' || $Config{longsize} >= 8) &&
+ print "quads\n";
-You can find out whether your Perl supports long doubles via L<Config>:
+For floating point conversions (C<e f g E F G>), numbers are usually assumed
+to be the default floating point size on your platform (double or long double),
+but you can force 'long double' with C<q>, C<L>, or C<ll> if your
+platform supports them. You can find out whether your Perl supports long
+doubles via L<Config>:
use Config;
$Config{d_longdbl} eq 'define' && print "long doubles\n";
+You can find out whether Perl considers 'long double' to be the default
+floating point size to use on your platform via L<Config>:
+
+ use Config;
+ ($Config{uselongdouble} eq 'define') &&
+ print "long doubles by default\n";
+
+It can also be the case that long doubles and doubles are the same thing:
+
+ use Config;
+ ($Config{doublesize} == $Config{longdblsize}) &&
+ print "doubles are long doubles\n";
+
+The size specifier C<V> has no effect for Perl code, but it is supported
+for compatibility with XS code; it means 'use the standard size for
+a Perl integer (or floating-point number)', which is already the
+default for Perl code.
+
+=item order of arguments
+
+Normally, sprintf 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
+the argument list in the order in which they appear in the format
+specification I<before> the value to format. Where an argument is
+specified using an explicit index, this does not affect the normal
+order for the arguments (even when the explicitly specified index
+would have been the next argument in any case).
+
+So:
+
+ printf '<%*.*s>', $a, $b, $c;
+
+would use C<$a> for the width, C<$b> for the precision and C<$c>
+as the value to format, while:
+
+ print '<%*1$.*s>', $a, $b;
+
+would use C<$a> for the width and the precision, and C<$b> as the
+value to format.
+
+Here are some more examples - beware that when using an explicit
+index, the C<$> may need to be escaped:
+
+ printf "%2\$d %d\n", 12, 34; # will print "34 12\n"
+ printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n"
+ printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n"
+ printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n"
+
+=back
+
+If C<use locale> is in effect, the character used for the decimal
+point in formatted real numbers is affected by the LC_NUMERIC locale.
+See L<perllocale>.
+
=item sqrt EXPR
=item sqrt
7 size total size of file, in bytes
8 atime last access time in seconds since the epoch
9 mtime last modify time in seconds since the epoch
- 10 ctime inode change time (NOT creation time!) in seconds since the epoch
+ 10 ctime inode change time in seconds since the epoch (*)
11 blksize preferred block size for file system I/O
12 blocks actual number of blocks allocated
(The epoch was at 00:00 January 1, 1970 GMT.)
+(*) The ctime field is non-portable, in particular you cannot expect
+it to be a "creation time", see L<perlport/"Files and Filesystems">
+for details.
+
If stat is passed the special filehandle consisting of an underline, no
stat is done, but the current contents of the stat structure from the
last stat or filetest are returned. Example:
$group_read = ($mode & S_IRGRP) >> 3;
$other_execute = $mode & S_IXOTH;
- printf "Permissions are %04o\n", S_ISMODE($mode), "\n";
+ printf "Permissions are %04o\n", S_IMODE($mode), "\n";
$is_setuid = $mode & S_ISUID;
$is_setgid = S_ISDIR($mode);
S_IRWXG S_IRGRP S_IWGRP S_IXGRP
S_IRWXO S_IROTH S_IWOTH S_IXOTH
- # Setuid/Setgid/Stickiness.
+ # Setuid/Setgid/Stickiness/SaveText.
+ # Note that the exact meaning of these is system dependent.
S_ISUID S_ISGID S_ISVTX S_ISTXT
and the S_IF* functions are
- S_IFMODE($mode) the part of $mode containing the permission bits
+ S_IMODE($mode) the part of $mode containing the permission bits
and the setuid/setgid/sticky bits
S_IFMT($mode) the part of $mode containing the file type
S_ISENFMT($mode) S_ISWHT($mode)
See your native chmod(2) and stat(2) documentation for more details
-about the S_* constants.
+about the S_* constants. To get status info for a symbolic link
+instead of the target file behind the link, use the C<lstat> function.
=item study SCALAR
parts of the EXPR and return what was there before in one operation,
just as you can with splice().
+If the lvalue returned by substr is used after the EXPR is changed in
+any way, the behaviour may not be as expected and is subject to change.
+This caveat includes code such as C<print(substr($foo,$a,$b)=$bar)> or
+C<(substr($foo,$a,$b)=$bar)=$fud> (where $foo is changed via the
+substring assignment, and then the substr is used again), or where a
+substr() is aliased via a C<foreach> loop or passed as a parameter or
+a reference to it is taken and then the alias, parameter, or deref'd
+reference either is used after the original EXPR has been changed or
+is assigned to and then used a second time.
+
=item symlink OLDFILE,NEWFILE
Creates a new filename symbolically linked to the old filename.
$symlink_exists = eval { symlink("",""); 1 };
-=item syscall LIST
+=item syscall NUMBER, LIST
Calls the system call specified as the first element of the list,
passing the remaining elements as arguments to the system call. If
=item sysread FILEHANDLE,SCALAR,LENGTH
-Attempts to read LENGTH I<characters> of data into variable SCALAR from
-the specified FILEHANDLE, using the system call read(2). It bypasses
+Attempts to read LENGTH bytes of data into variable SCALAR from the
+specified FILEHANDLE, using the system call read(2). It bypasses
buffered IO, so mixing this with other kinds of reads, C<print>,
-C<write>, C<seek>, C<tell>, or C<eof> can cause confusion because
-stdio usually buffers data. Returns the number of characters actually
-read, C<0> at end of file, or undef if there was an error. SCALAR
-will be grown or shrunk so that the last byte actually read is the
-last byte of the scalar after the read.
-
-Note the I<characters>: depending on the status of the filehandle,
-either (8-bit) bytes or characters are read. By default all
-filehandles operate on bytes, but for example if the filehandle has
-been opened with the C<:utf8> discipline (see L</open>, and the C<open>
-pragma, L<open>), the I/O will operate on characters, not bytes.
+C<write>, C<seek>, C<tell>, or C<eof> 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
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</binmode>, L</open>, and the C<open> pragma, L<open>.
+
=item sysseek FILEHANDLE,POSITION,WHENCE
-Sets FILEHANDLE's system position I<in bytes> 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
negative).
Note the I<in bytes>: 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<sysread>, for example >< or read()) C<print>, C<write>,
C<seek>, C<tell>, or C<eof> may cause confusion.
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
=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<sysread())>, C<print>, C<write>,
-C<seek>, C<tell>, or C<eof> may cause confusion because stdio usually
-buffers data. Returns the number of characters actually written, or
-C<undef> if there was an error. If the LENGTH is greater than the
+C<seek>, C<tell>, or C<eof> may cause confusion because the perlio and
+stdio layers usually buffers data. Returns the number of bytes
+actually written, or C<undef> 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.
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<characters>: 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</open>, and the open
-pragma, L<open>), 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</binmode>, L</open>, and the C<open> pragma, L<open>.
=item tell FILEHANDLE
Note the I<in bytes>: 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
Suitable for feeding to C<gmtime> and C<localtime>.
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<syscall> interface of Perl, see L<perlfaq8> 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<syscall> interface of Perl.
+See L<perlfaq8> for details.
=item times
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<undef $hash{$key}>
+(using C<&>), or a typeglob (using C<*>). (Saying C<undef $hash{$key}>
will probably not do what you expect on most predefined variables or
DBM list values, so don't do that; see L<delete>.) Always returns the
undefined value. You can omit the EXPR, in which case nothing is
=item unpack TEMPLATE,EXPR
+=item unpack TEMPLATE
+
C<unpack> does the reverse of C<pack>: 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<pack>, or the bytes of the string represent a C structure of some
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<unpack()> 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</pack> for more examples and notes.
=item untie VARIABLE
Breaks the binding between a variable and a package. (See C<tie>.)
+Has no effect if the variable is not tied.
=item unshift ARRAY,LIST
C<import> method any way it likes, though most modules just choose to
derive their C<import> method via inheritance from the C<Exporter> class that
is defined in the C<Exporter> module. See L<Exporter>. If no C<import>
-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<import> method (for instance,
to stop your namespace from being altered), explicitly supply the empty list:
There's a corresponding C<no> command that unimports meanings imported
by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import>.
+It behaves exactly as C<import> does with respect to VERSION, an
+omitted LIST, empty LIST, or no unimport method being found.
no integer;
no strict 'refs';
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<touch>
-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<already exist>.
#!/usr/bin/perl
$now = time;
utime $now, $now, @ARGV;
-If the first two elements of the list are C<undef>, 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.)
+B<Note:> Under NFS, touch(1) uses 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.
+
+Since perl 5.7.2, if the first two elements of the list are C<undef>, 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;
=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<keys> or C<each> 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<keys> or C<each>
+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<perlsec/"Algorithmic Complexity Attacks">).
+
+As a side effect, calling values() resets the HASH's internal iterator,
+see L</each>.
Note that the values are not copied, which means modifying them will
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<keys>, C<each>, and C<sort>.
=item vec EXPR,OFFSET,BITS
https://perl5.git.perl.org / perl5.git / blobdiff