platforms the external representation of C<\n> is made up of more than
one character.
-Mac OS, all variants of Unix, and Stream_LF files on VMS use a single
-character to end each line in the external representation of text (even
+Mac OS, all variants of Unix, and Stream_LF files on VMS use a single
+character to end each line in the external representation of text (even
though that single character is CARRIAGE RETURN on Mac OS and LINE FEED
-on Unix and most VMS files). Consequently binmode() has no effect on
-these operating systems. In other systems like OS/2, DOS and the various
-flavors of MS-Windows your program sees a C<\n> as a simple C<\cJ>, but
-what's stored in text files are the two characters C<\cM\cJ>. That means
-that, if you don't use binmode() on these systems, C<\cM\cJ> sequences on
-disk will be converted to C<\n> on input, and any C<\n> in your program
+on Unix and most VMS files). Consequently binmode() has no effect on
+these operating systems. In other systems like OS/2, DOS and the various
+flavors of MS-Windows your program sees a C<\n> as a simple C<\cJ>, but
+what's stored in text files are the two characters C<\cM\cJ>. That means
+that, if you don't use binmode() on these systems, C<\cM\cJ> sequences on
+disk will be converted to C<\n> on input, and any C<\n> in your program
will be converted back to C<\cM\cJ> on output. This is what you want for
text files, but it can be disastrous for binary files.
Returns the character represented by that NUMBER in the character set.
For example, C<chr(65)> is C<"A"> in either ASCII or Unicode, and
-chr(0x263a) is a Unicode smiley face. Within the scope of C<use utf8>,
-characters higher than 127 are encoded in Unicode; if you don't want
-this, temporarily C<use bytes> or use C<pack("C*",...)>
+chr(0x263a) is a Unicode smiley face. Note that characters from
+127 to 255 (inclusive) are not encoded in Unicode for backward
+compatibility reasons.
For the reverse, use L</ord>.
See L<utf8> for more about Unicode.
=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<use locale> in force. See L<perllocale>
-and L<utf8>.
+implementing the C<\L> escape in double-quoted strings. Respects
+current LC_CTYPE locale if C<use locale> in force. See L<perllocale>
+and L<perlunicode>.
If EXPR is omitted, uses C<$_>.
=item lcfirst
-Returns the value of EXPR with the first character lowercased. This is
-the internal function implementing the C<\l> escape in double-quoted strings.
-Respects current LC_CTYPE locale if C<use locale> in force. See L<perllocale>.
+Returns the value of EXPR with the first character lowercased. This
+is the internal function implementing the C<\l> escape in
+double-quoted strings. Respects current LC_CTYPE locale if C<use
+locale> in force. See L<perllocale> and L<perlunicode>.
If EXPR is omitted, uses C<$_>.
automatically convert strings into numbers as needed, this automatic
conversion assumes base 10.)
-=item open FILEHANDLE,MODE,LIST
-
=item open FILEHANDLE,EXPR
+=item open FILEHANDLE,MODE,EXPR
+
+=item open FILEHANDLE,MODE,EXPR,LIST
+
=item open FILEHANDLE
Opens the file whose filename is given by EXPR, and associates it with
-FILEHANDLE. If FILEHANDLE is an expression, its value is used as the
-name of the real filehandle wanted. (This is considered a symbolic
+FILEHANDLE. 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 EXPR is omitted, the scalar
to open.) See L<perlopentut> for a kinder, gentler explanation of opening
files.
-If MODE is C<< '<' >> or nothing, the file is opened for input.
+If three or more arguments are specified then the mode of opening and the file name
+are separate. If MODE is C<< '<' >> or nothing, the file is opened for input.
If MODE is C<< '>' >>, the file is truncated and opened for
output, being created if necessary. If MODE is C<<< '>>' >>>,
the file is opened for appending, again being created if necessary.
In the 2-arguments (and 1-argument) form of the call the mode and
filename should be concatenated (in this order), possibly separated by
-spaces. It is possible to omit the mode if the mode is C<< '<' >>.
+spaces. It is possible to omit the mode in these forms if the mode is
+C<< '<' >>.
If the filename begins with C<'|'>, the filename is interpreted as a
command to which output is to be piped, and if the filename ends with a
and L<perlipc/"Bidirectional Communication with Another Process">
for alternatives.)
-If MODE is C<'|-'>, the filename is interpreted as a
+For three or more arguments if MODE is C<'|-'>, the filename is interpreted as a
command to which output is to be piped, and if MODE is
C<'-|'>, the filename is interpreted as a command which pipes output to
us. In the 2-arguments (and 1-argument) form one should replace dash
(C<'-'>) with the command. See L<perlipc/"Using open() for IPC">
for more examples of this. (You are not allowed to C<open> to a command
that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>,
-and L<perlipc/"Bidirectional Communication"> for alternatives.)
+and L<perlipc/"Bidirectional Communication"> for alternatives.) In 3+ arg form of
+pipe opens then if LIST is specified (extra arguments after the command name) then
+LIST becomes arguments to the command invoked if the platform supports it.
+The meaning of C<open> with more than three arguments for non-pipe modes
+is not yet specified. Experimental "layers" may give extra LIST arguments meaning.
In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN
and opening C<< '>-' >> opens STDOUT.
Plan9, which delimit lines with a single character, and which encode that
character in C as C<"\n">, do not need C<binmode>. The rest need it.
+In the three argument form MODE may also contain a list of IO "layers" (see L<open> and
+L<PerlIO> for more details) to be applied to the handle. This can be used to achieve the
+effect of C<binmode> as well as more complex behaviours.
+
When opening a file, it's usually a bad idea to continue normal execution
if the request failed, so C<open> is frequently used in connection with
C<die>. Even if C<die> won't do what you want (say, in a CGI script,
opens a filehandle to an anonymous temporary file.
+
Examples:
$ARTICLE = 100;
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<< '<&=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:
open(FILEHANDLE, "<&=$fd")
+
or
+
open(FILEHANDLE, "<&=", $fd)
-Note that if perl is using the standard C libaries fdopen() then on many UNIX systems,
-fdopen() is known to fail when file descriptors
+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
descriptors than that, consider rebuilding Perl to use the C<PerlIO>.
+You can see whether Perl has been compiled with PerlIO or not by
+running C<perl -V> and looking for C<useperlio=> line. If C<useperlio>
+is C<define>, you have PerlIO, otherwise you don't.
+
If you open a pipe on the command C<'-'>, i.e., either C<'|-'> or C<'-|'>
with 2-arguments (or 1-argument) form of open(), then
there is an implicit fork done, and the return value of open is the pid
changed or removed in future releases of Perl. It should not be
relied upon.
-The only currently recognized attribute is C<shared> which indicates
+The only currently recognized attribute is C<unique> 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
attribute also has the effect of making the global readonly.
Examples:
- our @EXPORT : shared = qw(foo);
- our %EXPORT_TAGS : shared = (bar => [qw(aa bb cc)]);
- our $VERSION : shared = "1.00";
+ 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<shared> attribute does nothing in
+multi-threaded application. The C<unique> attribute does nothing in
all other environments.
=item pack TEMPLATE,LIST
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<use utf8> 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
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<use strict>, 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<perlmod/"Packages"> for more information about packages, modules,
and classes. See L<perlsub> for other scoping issues.
Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that C<$\>
(the output record separator) is not appended. The first argument
-of the list will be interpreted as the C<printf> format. 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>.
+of the list will be interpreted as the C<printf> format. See C<sprintf>
+for an explanation of the format argument. 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>.
Don't fall into the trap of using a C<printf> when a simple
C<print> would do. The C<print> is more efficient and less
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>
+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>.
Apply C<int()> to the value returned by C<rand()> if you want random
=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<pack("sss", $semnum, $semop, $semflag)>. The number of semaphore
+C<pack("s!3", $semnum, $semop, $semflag)>. 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
When C<use locale> is in effect, C<sort LIST> sorts LIST according to the
current collation locale. See L<perllocale>.
+Perl does B<not> guarantee that sort is stable. (A I<stable> 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
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<pop> 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<pop> 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
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
#...
}
+As with regular pattern matching, any capturing parentheses that are not
+matched in a C<split()> will be set to C<undef> when returned:
+
+ @fields = split /(A)|B/, "1A2B3";
+ # @fields is (1, 'A', 2, undef, 3)
=item sprintf FORMAT, LIST
($user,$system,$cuser,$csystem) = times;
+In scalar context, C<times> returns C<$user>.
+
=item tr///
The transliteration operator. Same as C<y///>. See L<perlop>.
=item uc
Returns an uppercased version of EXPR. This is the internal function
-implementing the C<\U> escape in double-quoted strings.
-Respects current LC_CTYPE locale if C<use locale> in force. See L<perllocale>.
-Under Unicode (C<use utf8>) it uses the standard Unicode uppercase mappings. (It
-does not attempt to do titlecase mapping on initial letters. See C<ucfirst> for that.)
+implementing the C<\U> escape in double-quoted strings. Respects
+current LC_CTYPE locale if C<use locale> in force. See L<perllocale>
+and L<perlunicode>. Under Unicode it uses the standard Unicode
+uppercase mappings. (It does not attempt to do titlecase mapping on
+initial letters. See C<ucfirst> for that.)
If EXPR is omitted, uses C<$_>.
=item ucfirst
-Returns the value of EXPR with the first character
-in uppercase (titlecase in Unicode). This is
-the internal function implementing the C<\u> escape in double-quoted strings.
-Respects current LC_CTYPE locale if C<use locale> in force. See L<perllocale>
-and L<utf8>.
+Returns the value of EXPR with the first character in uppercase
+(titlecase in Unicode). This is the internal function implementing
+the C<\u> escape in double-quoted strings. Respects current LC_CTYPE
+locale if C<use locale> in force. See L<perllocale> and L<perlunicode>.
If EXPR is omitted, uses C<$_>.
depending on how you look at it. Prepends list to the front of the
array, and returns the new number of elements in the array.
- unshift(ARGV, '-e') unless $ARGV[0] =~ /^-/;
+ unshift(@ARGV, '-e') unless $ARGV[0] =~ /^-/;
Note the LIST is prepended whole, not one element at a time, so the
prepended elements stay in the same order. Use C<reverse> to do the
$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.)
+
+ utime undef, undef, @ARGV;
+
=item values HASH
Returns a list consisting of all the values of the named hash. (In a