The C<-T> and C<-B> switches work as follows. The first block or so of the
file is examined for odd characters such as strange control codes or
-characters with the high bit set. If too many strange characters (E<gt>30%)
+characters with the high bit set. If too many strange characters (>30%)
are found, it's a C<-B> file, otherwise it's a C<-T> file. Also, any file
containing null in the first block is considered a binary file. If C<-T>
or C<-B> is used on a filehandle, the current stdio buffer is examined
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
-Arranges for FILEHANDLE to be read or written in "binary" mode on
-systems whose run-time libraries force the programmer to guess
-between binary and text files. If FILEHANDLE is an expression, the
-value is taken as the name of the filehandle. binmode() should be
-called after the C<open> but before any I/O is done on the filehandle.
-The only way to reset binary mode on a filehandle is to reopen the
-file.
+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. DISCIPLINE can be either of C<":raw"> for
+binary mode or C<":crlf"> for "text" mode. If the DISCIPLINE is
+omitted, it defaults to C<":raw">.
+
+binmode() should be called after open() but before any I/O is done on
+the filehandle.
+
+On many systems binmode() currently has no effect, but in future, it
+will be extended to support user-defined input and output disciplines.
+On some 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.
+
+In other words: Regardless of platform, use binmode() on binary
+files, and do not use binmode() on text files.
+
+The C<open> pragma can be used to establish default disciplines.
+See L<open>.
The operating system, device drivers, C libraries, and Perl run-time
-system all conspire to let the programmer conveniently treat a
-simple, one-byte C<\n> as the line terminator, irrespective of its
-external representation. On Unix and its brethren, the native file
-representation exactly matches the internal representation, making
-everyone's lives unbelievably simpler. Consequently, L<binmode>
-has no effect under Unix, Plan9, or Mac OS, all of which use C<\n>
-to end each line. (Unix and Plan9 think C<\n> means C<\cJ> and
-C<\r> means C<\cM>, whereas the Mac goes the other way--it uses
-C<\cM> for c<\n> and C<\cJ> to mean C<\r>. But that's ok, because
-it's only one byte, and the internal and external representations
-match.)
-
-In legacy systems like MS-DOS and its embellishments, your program
-sees a C<\n> as a simple C<\cJ> (just as in Unix), but oddly enough,
-that's not what's physically stored on disk. What's worse, these
-systems refuse to help you with this; it's up to you to remember
-what to do. And you mustn't go applying binmode() with wild abandon,
-either, because if your system does care about binmode(), then using
-it when you shouldn't is just as perilous as failing to use it when
-you should.
-
-That means that on any version of Microsoft WinXX that you might
-care to name (or not), binmode() causes C<\cM\cJ> sequences on disk
-to be converted to C<\n> when read into your program, and causes
-any C<\n> in your program to be converted back to C<\cM\cJ> on
-output to disk. This sad discrepancy leads to no end of
-problems in not just the readline operator, but also when using
-seek(), tell(), and read() calls. See L<perlport> for other painful
-details. See the C<$/> and C<$\> variables in L<perlvar> for how
-to manually set your input and output line-termination sequences.
+system all work together to let the programmer treat a single
+character (C<\n>) as the line terminator, irrespective of the external
+representation. On many operating systems, the native text file
+representation matches the internal representation, but on some
+platforms the external representation of C<\n> is made up of more than
+one character.
+
+Mac OS and all variants of Unix use a single character to end each line
+in the external representation of text (even though that single
+character is not necessarily the same across these platforms).
+Consequently binmode() has no effect on these operating systems. In
+other systems like VMS, MS-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.
+
+Another consequence of using binmode() (on some systems) is that
+special end-of-file markers will be seen as part of the data stream.
+For systems from the Microsoft family this means that if your binary
+data contains C<\cZ>, the I/O subsystem will ragard it as the end of
+the file, unless you use binmode().
+
+binmode() is not only important for readline() and print() operations,
+but also when using read(), seek(), sysread(), syswrite() and tell()
+(see L<perlport> for more details). See the C<$/> and C<$\> variables
+in L<perlvar> for how to manually set your input and output
+line-termination sequences.
=item bless REF,CLASSNAME
Be aware that the optimizer might have optimized call frames away before
C<caller> had a chance to get the information. That means that C<caller(N)>
might not return information about the call frame you expect it do, for
-C<N E<gt> 1>. In particular, C<@DB::args> might have information from the
+C<< N > 1 >>. In particular, C<@DB::args> might have information from the
previous time C<caller> was called.
=item chdir EXPR
Outside an C<eval>, prints the value of LIST to C<STDERR> and
exits with the current value of C<$!> (errno). If C<$!> is C<0>,
-exits with the value of C<($? E<gt>E<gt> 8)> (backtick `command`
-status). If C<($? E<gt>E<gt> 8)> is C<0>, exits with C<255>. Inside
+exits with the value of C<<< ($? >> 8) >>> (backtick `command`
+status). If C<<< ($? >> 8) >>> is C<0>, exits with C<255>. Inside
an C<eval(),> the error message is stuffed into C<$@> and the
C<eval> is terminated with the undefined value. This makes
C<die> the way to raise an exception.
An C<eof> without an argument uses the last file read. Using C<eof()>
with empty parentheses is very different. It refers to the pseudo file
formed from the files listed on the command line and accessed via the
-C<E<lt>E<gt>> operator. Since C<E<lt>E<gt>> isn't explicitly opened,
-as a normal filehandle is, an C<eof()> before C<E<lt>E<gt>> has been
+C<< <> >> operator. Since C<< <> >> isn't explicitly opened,
+as a normal filehandle is, an C<eof()> before C<< <> >> has been
used will cause C<@ARGV> to be examined to determine if input is
available.
-In a C<while (E<lt>E<gt>)> loop, C<eof> or C<eof(ARGV)> can be used to
+In a C<< while (<>) >> loop, C<eof> or C<eof(ARGV)> can be used to
detect the end of each file, C<eof()> will only detect the end of the
last file. Examples:
didn't--it tried to run a program literally called I<"echo surprise">,
didn't find it, and set C<$?> to a non-zero value indicating failure.
+Beginning with v5.6.0, Perl will attempt to flush all files opened for
+output before the exec, but this may not be supported on some platforms
+(see L<perlport>). To be safe, you may need to set C<$|> ($AUTOFLUSH
+in English) or call the C<autoflush()> method of C<IO::Handle> on any
+open handles in order to avoid lost output.
+
Note that C<exec> will not call your C<END> blocks, nor will it call
any C<DESTROY> methods in your objects.
Although the deepest nested array or hash will not spring into existence
just because its existence was tested, any intervening ones will.
-Thus C<$ref-E<gt>{"A"}> and C<$ref-E<gt>{"A"}-E<gt>{"B"}> will spring
+Thus C<< $ref->{"A"} >> and C<< $ref->{"A"}->{"B"} >> will spring
into existence due to the existence test for the $key element above.
This happens anywhere the arrow operator is used, including even:
second--glance appear to be an lvalue context may be fixed in a future
release.
-See L<perlref/"Pseudo-hashes"> for specifics on how exists() acts when
-used on a pseudo-hash.
+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.
example, using copy-on-write technology on data pages), making it the
dominant paradigm for multitasking over the last few decades.
-All files opened for output are flushed before forking the child process.
+Beginning with v5.6.0, Perl will attempt to flush all files opened for
+output before forking the child process, but this may not be supported
+on some platforms (see L<perlport>). To be safe, you may need to set
+C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
+C<IO::Handle> on any open handles in order to avoid duplicate output.
If you C<fork> without ever waiting on your children, you will
accumulate zombies. On some systems, you can avoid this by setting
(If the entry doesn't exist you get a null list.)
+The exact meaning of the $gcos field varies but it usually contains
+the real name of the user (as opposed to the login name) and other
+information pertaining to the user. Beware, however, that in many
+system users are able to change this information and therefore it
+cannot be trusted and therefore the $gcos is is tainted (see
+L<perlsec>). The $passwd and $shell, user's encrypted password and
+login shell, are also tainted, because of the same reason.
+
In scalar context, you get the name, unless the function was a
lookup by name, in which case you get the other thing, whatever it is.
(If the entry doesn't exist you get the undefined value.) For example:
$name = getgrent();
#etc.
-In I<getpw*()> the fields $quota, $comment, and $expire are
-special cases in the sense that in many systems they are unsupported.
-If the $quota is unsupported, it is an empty scalar. If it is
-supported, it usually encodes the disk quota. If the $comment
-field is unsupported, it is an empty scalar. If it is supported it
-usually encodes some administrative comment about the user. In some
-systems the $quota field may be $change or $age, fields that have
-to do with password aging. In some systems the $comment field may
-be $class. The $expire field, if present, encodes the expiration
-period of the account or the password. For the availability and the
-exact meaning of these fields in your system, please consult your
-getpwnam(3) documentation and your F<pwd.h> file. You can also find
-out from within Perl what your $quota and $comment fields mean
-and whether you have the $expire field by using the C<Config> module
-and the values C<d_pwquota>, C<d_pwage>, C<d_pwchange>, C<d_pwcomment>,
-and C<d_pwexpire>. Shadow password files are only supported if your
-vendor has implemented them in the intuitive fashion that calling the
-regular C library routines gets the shadow versions if you're running
-under privilege. Those that incorrectly implement a separate library
-call are not supported.
+In I<getpw*()> the fields $quota, $comment, and $expire are special
+cases in the sense that in many systems they are unsupported. If the
+$quota is unsupported, it is an empty scalar. If it is supported, it
+usually encodes the disk quota. If the $comment field is unsupported,
+it is an empty scalar. If it is supported it usually encodes some
+administrative comment about the user. In some systems the $quota
+field may be $change or $age, fields that have to do with password
+aging. In some systems the $comment field may be $class. The $expire
+field, if present, encodes the expiration period of the account or the
+password. For the availability and the exact meaning of these fields
+in your system, please consult your getpwnam(3) documentation and your
+F<pwd.h> file. You can also find out from within Perl what your
+$quota and $comment fields mean and whether you have the $expire field
+by using the C<Config> module and the values C<d_pwquota>, C<d_pwage>,
+C<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>. Shadow password
+files are only supported if your vendor has implemented them in the
+intuitive fashion that calling the regular C library routines gets the
+shadow versions if you're running under privilege. Those that
+incorrectly implement a separate library call are not supported.
The $members value returned by I<getgr*()> is a space separated list of
the login names of the members of the group.
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<E<lt>*.cE<gt>> operator, but you can use it directly.
-If EXPR is omitted, C<$_> is used. The C<E<lt>*.cE<gt>> operator is
+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 gmtime EXPR
-Converts a time as returned by the time function to a 9-element list
+Converts a time as returned by the time function to a 8-element list
with the time localized for the standard Greenwich time zone.
Typically used as follows:
- # 0 1 2 3 4 5 6 7 8
- ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
+ # 0 1 2 3 4 5 6 7
+ ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday) =
gmtime(time);
-All list elements are numeric, and come straight out of a struct tm.
-In particular this means that $mon has the range C<0..11> and $wday
-has the range C<0..6> with sunday as day C<0>. Also, $year is the
-number of years since 1900, that is, $year is C<123> in year 2023,
-I<not> simply the last two digits of the year. If you assume it is,
-then you create non-Y2K-compliant programs--and you wouldn't want to do
-that, would you?
+All list elements are numeric, and come straight out of the C `struct
+tm'. $sec, $min, and $hour are the seconds, minutes, and hours of the
+specified time. $mday is the day of the month, and $mon is the month
+itself, in the range C<0..11> with 0 indicating January and 11
+indicating December. $year is the number of years since 1900. That
+is, $year is C<123> in year 2023. $wday is the day of the week, with
+0 indicating Sunday and 3 indicating Wednesday. $yday is the day of
+the year, in the range C<0..364> (or C<0..365> in leap years.)
+
+Note that the $year element is I<not> simply the last two digits of
+the year. If you assume it is, then you create non-Y2K-compliant
+programs--and you wouldn't want to do that, would you?
The proper way to get a complete 4-digit year is simply:
$year = sprintf("%02d", $year % 100);
-If EXPR is omitted, does C<gmtime(time())>.
+If EXPR is omitted, C<gmtime()> uses the current time (C<gmtime(time)>).
-In scalar context, returns the ctime(3) value:
+In scalar context, C<gmtime()> returns the ctime(3) value:
$now_string = gmtime; # e.g., "Thu Oct 13 04:54:34 1994"
to get the correct function definitions. If F<ioctl.ph> doesn't
exist or doesn't have the correct definitions you'll have to roll your
-own, based on your C header files such as F<E<lt>sys/ioctl.hE<gt>>.
+own, based on your C header files such as F<< <sys/ioctl.h> >>.
(There is a Perl script called B<h2ph> that comes with the Perl kit that
may help you in this, but it's nontrivial.) SCALAR will be read and/or
written depending on the FUNCTION--a pointer to the string value of SCALAR
($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
localtime(time);
-All list elements are numeric, and come straight out of a struct tm.
-In particular this means that $mon has the range C<0..11> and $wday
-has the range C<0..6> with sunday as day C<0>. Also, $year is the
-number of years since 1900, that is, $year is C<123> in year 2023,
-and I<not> simply the last two digits of the year. If you assume it is,
-then you create non-Y2K-compliant programs--and you wouldn't want to do
-that, would you?
+All list elements are numeric, and come straight out of the C `struct
+tm'. $sec, $min, and $hour are the seconds, minutes, and hours of the
+specified time. $mday is the day of the month, and $mon is the month
+itself, in the range C<0..11> with 0 indicating January and 11
+indicating December. $year is the number of years since 1900. That
+is, $year is C<123> in year 2023. $wday is the day of the week, with
+0 indicating Sunday and 3 indicating Wednesday. $yday is the day of
+the year, in the range C<0..364> (or C<0..365> in leap years.) $isdst
+is true if the specified time occurs during daylight savings time,
+false otherwise.
+
+Note that the $year element is I<not> simply the last two digits of
+the year. If you assume it is, then you create non-Y2K-compliant
+programs--and you wouldn't want to do that, would you?
The proper way to get a complete 4-digit year is simply:
$year = sprintf("%02d", $year % 100);
-If EXPR is omitted, uses the current time (C<localtime(time)>).
+If EXPR is omitted, C<localtime()> uses the current time (C<localtime(time)>).
-In scalar context, returns the ctime(3) value:
+In scalar context, C<localtime()> returns the ctime(3) value:
$now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
id, or the undefined value if there is an error. See also C<IPC::SysV>
and C<IPC::Msg> documentation.
-=item msgsnd ID,MSG,FLAGS
-
-Calls the System V IPC function msgsnd to send the message MSG to the
-message queue ID. MSG must begin with the long integer message type,
-which may be created with C<pack("l", $type)>. Returns true if
-successful, or false if there is an error. See also C<IPC::SysV>
-and C<IPC::SysV::Msg> documentation.
-
=item msgrcv ID,VAR,SIZE,TYPE,FLAGS
Calls the System V IPC function msgrcv to receive a message from
message queue ID into variable VAR with a maximum message size of
-SIZE. Note that if a message is received, the message type will be
-the first thing in VAR, and the maximum length of VAR is SIZE plus the
-size of the message type. Returns true if successful, or false if
-there is an error. See also C<IPC::SysV> and C<IPC::SysV::Msg> documentation.
+SIZE. Note that when a message is received, the message type as a
+native long integer will be the first thing in VAR, followed by the
+actual message. This packing may be opened with C<unpack("l! a*")>.
+Taints the variable. Returns true if successful, or false if there is
+an error. See also C<IPC::SysV> and C<IPC::SysV::Msg> documentation.
+
+=item msgsnd ID,MSG,FLAGS
+
+Calls the System V IPC function msgsnd to send the message MSG to the
+message queue ID. MSG must begin with the native long integer message
+type, and be followed by the length of the actual message, and finally
+the message itself. This kind of packing can be achieved with
+C<pack("l! a*", $type, $message)>. Returns true if successful,
+or false if there is an error. See also C<IPC::SysV>
+and C<IPC::SysV::Msg> documentation.
=item my EXPR
automatically convert strings into numbers as needed, this automatic
conversion assumes base 10.)
-=item open FILEHANDLE,MODE,EXPR
+=item open FILEHANDLE,MODE,LIST
=item open FILEHANDLE,EXPR
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. If EXPR is omitted, the scalar
+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 declared with C<my>--will not work
for this purpose; so if you're using C<my>, specify EXPR in your call
to open.) See L<perlopentut> for a kinder, gentler explanation of opening
files.
-If MODE is C<'E<lt>'> or nothing, the file is opened for input.
-If MODE is C<'E<gt>'>, the file is truncated and opened for
-output, being created if necessary. If MODE is C<'E<gt>E<gt>'>,
+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.
-You can put a C<'+'> in front of the C<'E<gt>'> or C<'E<lt>'> to indicate that
-you want both read and write access to the file; thus C<'+E<lt>'> is almost
-always preferred for read/write updates--the C<'+E<gt>'> mode would clobber the
+You can put a C<'+'> in front of the C<< '>' >> or C<< '<' >> to indicate that
+you want both read and write access to the file; thus C<< '+<' >> is almost
+always preferred for read/write updates--the C<< '+>' >> mode would clobber the
file first. You can't usually use either read-write mode for updating
textfiles, since they have variable length records. See the B<-i>
switch in L<perlrun> for a better approach. The file is created with
permissions of C<0666> modified by the process' C<umask> value.
-These various prefixes correspond to the fopen(3) modes of C<'r'>, C<'r+'>, C<'w'>,
-C<'w+'>, C<'a'>, and C<'a+'>.
+These various prefixes correspond to the fopen(3) modes of C<'r'>, C<'r+'>,
+C<'w'>, C<'w+'>, C<'a'>, and C<'a+'>.
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<'E<lt>'>.
+spaces. It is possible to omit the mode 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
us. 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 with Another Process">
+for alternatives.)
If MODE is C<'|-'>, the filename is interpreted as a
command to which output is to be piped, and if MODE is
and L<perlipc/"Bidirectional Communication"> for alternatives.)
In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN
-and opening C<'E<gt>-'> opens STDOUT.
+and opening C<< '>-' >> opens STDOUT.
Open returns
nonzero upon success, the undefined value otherwise. If the C<open>
}
You may also, in the Bourne shell tradition, specify an EXPR beginning
-with C<'E<gt>&'>, in which case the rest of the string is interpreted as the
+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<E<gt>>, C<E<gt>E<gt>>,
-C<E<lt>>, C<+E<gt>>, C<+E<gt>E<gt>>, and C<+E<lt>>. The
+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
stdio buffers.) Duping file handles is not yet supported for 3-argument
print STDOUT "stdout 2\n";
print STDERR "stderr 2\n";
-If you specify C<'E<lt>&=N'>, where C<N> is a number, then Perl will do an
+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:
See L<perlipc/"Safe Pipe Opens"> for more examples of this.
-NOTE: On any operation that may do a fork, all files opened for output
-are flushed before the fork is attempted. On systems that support a
+Beginning with v5.6.0, Perl will attempt to flush all files opened for
+output before any operation that may do a fork, but this may not be
+supported on some platforms (see L<perlport>). To be safe, you may need
+to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
+of C<IO::Handle> on any open handles.
+
+On systems that support a
close-on-exec flag on files, the flag will be set for the newly opened
file descriptor as determined by the value of $^F. See L<perlvar/$^F>.
because they obey the native byteorder and endianness. For example a
4-byte integer 0x12345678 (305419896 decimal) be ordered natively
(arranged in and handled by the CPU registers) into bytes as
-
+
0x12 0x34 0x56 0x78 # little-endian
0x78 0x56 0x34 0x12 # big-endian
-
+
Basically, the Intel, Alpha, and VAX CPUs are little-endian, while
everybody else, for example Motorola m68k/88k, PPC, Sparc, HP PA,
Power, and Cray are big-endian. MIPS can be either: Digital used it
the classic "Gulliver's Travels" (via the paper "On Holy Wars and a
Plea for Peace" by Danny Cohen, USC/ISI IEN 137, April 1, 1980) and
the egg-eating habits of the Lilliputians.
-
+
Some systems may have even weirder byte orders such as
-
+
0x56 0x78 0x12 0x34
0x34 0x12 0x78 0x56
-
+
You can see your system's preference with
print join(" ", map { sprintf "%#02x", $_ }
context (i.e. file slurp mode), and when an empty file is read, it
returns C<''> the first time, followed by C<undef> subsequently.
-This is the internal function implementing the C<E<lt>EXPRE<gt>>
-operator, but you can use it directly. The C<E<lt>EXPRE<gt>>
+This is the internal function implementing the C<< <EXPR> >>
+operator, but you can use it directly. The C<< <EXPR> >>
operator is discussed in more detail in L<perlop/"I/O Operators">.
$line = <STDIN>;
=item require
Demands some semantics specified by EXPR, or by C<$_> if EXPR is not
-supplied. If a version number or tuple is specified, or if EXPR is
-numeric, demands that the current version of Perl
-(C<$^V> or C<$]> or $PERL_VERSION) be equal or greater than EXPR.
+supplied.
+
+If a VERSION is specified as a literal of the form v5.6.1,
+demands that the current version of Perl (C<$^V> or $PERL_VERSION) be
+at least as recent as that version, at run time. (For compatibility
+with older versions of Perl, a numeric argument will also be interpreted
+as VERSION.) Compare with L</use>, which can do a similar check at
+compile time.
+
+ require v5.6.1; # run time version check
+ require 5.6.1; # ditto
+ require 5.005_03; # float version allowed for compatibility
Otherwise, demands that a library file be included if it hasn't already
been included. The file is included via the do-FILE mechanism, which is
EOF on your read, and then sleep for a while, you might have to stick in a
seek() to reset things. The C<seek> doesn't change the current position,
but it I<does> clear the end-of-file condition on the handle, so that the
-next C<E<lt>FILEE<gt>> makes Perl try again to read something. We hope.
+next C<< <FILE> >> makes Perl try again to read something. We hope.
If that doesn't work (some stdios are particularly cantankerous), then
you may need something more like this:
select(undef, undef, undef, 0.25);
B<WARNING>: One should not attempt to mix buffered I/O (like C<read>
-or E<lt>FHE<gt>) with C<select>, except as permitted by POSIX, and even
+or <FH>) with C<select>, except as permitted by POSIX, and even
then only on POSIX systems. You have to use C<sysread> instead.
=item semctl ID,SEMNUM,CMD,ARG
first to get the correct constant definitions. If CMD is IPC_STAT or
GETALL, then ARG must be a variable which will hold the returned
-semid_ds structure or semaphore value array. Returns like C<ioctl>: the
-undefined value for error, "C<0 but true>" for zero, or the actual return
-value otherwise. See also C<IPC::SysV> and C<IPC::Semaphore> documentation.
+semid_ds structure or semaphore value array. Returns like C<ioctl>:
+the undefined value for error, "C<0 but true>" for zero, or the actual
+return value otherwise. The ARG must consist of a vector of native
+short integers, which may may be created with C<pack("s!",(0)x$nsem)>.
+See also C<IPC::SysV> and C<IPC::Semaphore> documentation.
=item semget KEY,NSEMS,FLAGS
hold the data read. When writing, if STRING is too long, only SIZE
bytes are used; if STRING is too short, nulls are written to fill out
SIZE bytes. Return true if successful, or false if there is an error.
-See also C<IPC::SysV> documentation and the C<IPC::Shareable> module
-from CPAN.
+shmread() taints the variable. See also C<IPC::SysV> documentation and
+the C<IPC::Shareable> module from CPAN.
=item shutdown SOCKET,HOW
is omitted, C<sort>s in standard string comparison order. If SUBNAME is
specified, it gives the name of a subroutine that returns an integer
less than, equal to, or greater than C<0>, depending on how the elements
-of the list are to be ordered. (The C<E<lt>=E<gt>> and C<cmp>
+of the list are to be ordered. (The C<< <=> >> and C<cmp>
operators are extremely useful in such routines.) SUBNAME may be a
scalar variable name (unsubscripted), in which case the value provides
the name of (or a reference to) the actual subroutine to use. In place
subroutine.
If the subroutine's prototype is C<($$)>, the elements to be compared
-are passed by reference in C<@_>, as for a normal subroutine. If not,
-the normal calling code for subroutines is bypassed in the interests of
-efficiency, and the elements to be compared are passed into the subroutine
+are passed by reference in C<@_>, as for a normal subroutine. This is
+slower than unprototyped subroutines, where the elements to be
+compared are passed into the subroutine
as the package global variables $a and $b (see example below). Note that
in the latter case, it is usually counter-productive to declare $a and
$b as lexicals.
||
$a->[2] cmp $b->[2]
} map { [$_, /=(\d+)/, uc($_)] } @old;
-
+
# using a prototype allows you to use any comparison subroutine
# as a sort subroutine (including other package's subroutines)
package other;
%n special: *stores* the number of characters output so far
into the next variable in the parameter list
-And the following Perl-specific conversion:
-
- %v a string, output as a tuple of integers ("Perl" is 80.101.114.108)
-
Finally, for backward (and we do mean "backward") compatibility, Perl
permits these unnecessary but widely-supported conversions:
h interpret integer as C type "short" or "unsigned short"
If no flags, interpret integer as C type "int" or "unsigned"
-There is also one Perl-specific flag:
+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 C<*>
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
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:
+
+ 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
+
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>.
You can find out whether your Perl supports quads via L<Config>:
use Config;
- ($Config{use64bits} eq 'define' || $Config{longsize} == 8) &&
+ ($Config{use64bitint} eq 'define' || $Config{longsize} == 8) &&
print "quads\n";
If Perl understands "long doubles" (this requires that the platform
ID, among other things. In versions of Perl prior to 5.004 the default
seed was just the current C<time>. This isn't a particularly good seed,
so many old programs supply their own seed value (often C<time ^ $$> or
-C<time ^ ($$ + ($$ E<lt>E<lt> 15))>), but that isn't necessary any more.
+C<time ^ ($$ + ($$ << 15))>), but that isn't necessary any more.
In fact, it's usually not necessary to call C<srand> at all, because if
it is not called explicitly, it is called implicitly at the first use of
S_IRWXU S_IRUSR S_IWUSR S_IXUSR
S_IRWXG S_IRGRP S_IWGRP S_IXGRP
S_IRWXO S_IROTH S_IWOTH S_IXOTH
-
+
# Setuid/Setgid/Stickiness.
S_ISUID S_ISGID S_ISVTX S_ISTXT
it is split into words and passed directly to C<execvp>, which is
more efficient.
-All files opened for output are flushed before attempting the exec().
+Beginning with v5.6.0, Perl will attempt to flush all files opened for
+output before any operation that may do a fork, but this may not be
+supported on some platforms (see L<perlport>). To be safe, you may need
+to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
+of C<IO::Handle> on any open handles.
The return value is the exit status of the program as
returned by the C<wait> call. To get the actual exit value divide by
sub ordinal { unpack("c",$_[0]); } # same as ord()
In addition to fields allowed in pack(), you may prefix a field with
-a %E<lt>numberE<gt> to indicate that
-you want a E<lt>numberE<gt>-bit checksum of the items instead of the items
+a %<number> to indicate that
+you want a <number>-bit checksum of the items instead of the items
themselves. Default is a 16-bit checksum. Checksum is calculated by
summing numeric values of expanded values (for string fields the sum of
C<ord($char)> is taken, for bit fields the sum of zeroes and ones).
prepended elements stay in the same order. Use C<reverse> to do the
reverse.
+=item use Module VERSION LIST
+
+=item use Module VERSION
+
=item use Module LIST
=item use Module
-=item use Module VERSION LIST
-
=item use VERSION
Imports some semantics into the current package from the named module,
except that Module I<must> be a bareword.
-If the first argument to C<use> is a number or a version tuple, it is
-treated as a version instead of a module name. If the version
-of the Perl interpreter is less than VERSION, then an error message
-is printed and Perl exits immediately.
+VERSION, which can be specified as a literal of the form v5.6.1, demands
+that the current version of Perl (C<$^V> or $PERL_VERSION) be at least
+as recent as that version. (For compatibility with older versions of Perl,
+a numeric literal will also be interpreted as VERSION.) If the version
+of the running Perl interpreter is less than VERSION, then an error
+message is printed and Perl exits immediately without attempting to
+parse the rest of the file. Compare with L</require>, which can do a
+similar check at run time.
- use 5.005_03; # version number
- use v5.6.0; # version tuple
+ use v5.6.1; # compile time version check
+ use 5.6.1; # ditto
+ use 5.005_03; # float version allowed for compatibility
This is often useful if you need to check the current Perl version before
C<use>ing library modules that have changed in incompatible ways from
If the VERSION argument is present between Module and LIST, then the
C<use> will call the VERSION method in class Module with the given
version as an argument. The default VERSION method, inherited from
-the Universal class, croaks if the given version is larger than the
-value of the variable C<$Module::VERSION>. (Note that there is not a
-comma after VERSION!)
+the UNIVERSAL class, croaks if the given version is larger than the
+value of the variable C<$Module::VERSION>.
+
+Again, there is a distinction between omitting LIST (C<import> called
+with no arguments) and an explicit empty LIST C<()> (C<import> not
+called). Note that there is no comma after VERSION!
Because this is a wide-open interface, pragmas (compiler directives)
are also implemented this way. Currently implemented pragmas are:
https://perl5.git.perl.org / perl5.git / blobdiff