"text" mode. If the DISCIPLINE is omitted, it defaults to C<:raw>.
Returns true on success, C<undef> on failure. To mark FILEHANDLE as
UTF-8, use C<:utf8>, and to mark it as bytes, use C<:bytes>.
+For backward compatibility binmode(FILEHANDLE) also implicitly
+marks the handle as bytes.
The C<:raw> are C<:clrf>, and any other directives of the form
C<:...>, are called I/O I<disciplines>. The C<open> pragma can be
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.
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. Similarly, an C<eof()> after C<< <> >> has returned
+available. Similarly, an C<eof()> after C<< <> >> has returned
end-of-file will assume you are processing another C<@ARGV> list,
and if you haven't set C<@ARGV>, will read input from C<STDIN>;
see L<perlop/"I/O Operators">.
=item lock THING
-This function places an advisory lock on a variable, subroutine,
-or referenced object contained in I<THING> until the lock goes out
-of scope. This is a built-in function only if your version of Perl
-was built with threading enabled, and if you've said C<use Thread>.
-Otherwise a user-defined function by this name will be called.
-See L<Thread>.
+This function places an advisory lock on a shared variable, or referenced
+object contained in I<THING> until the lock goes out of scope.
+
+lock() is a "weak keyword" : this means that if you've defined a function
+by this name (before any calls to it), that function will be called
+instead. (However, if you've said C<use threads>, lock() is always a
+keyword.) See L<threads>.
=item log EXPR
=item my EXPR
-=item my EXPR : ATTRIBUTES
+=item my TYPE EXPR
+
+=item my EXPR : ATTRS
+
+=item my TYPE EXPR : ATTRS
A C<my> declares the listed variables to be local (lexically) to the
-enclosing block, file, or C<eval>. If
-more than one value is listed, the list must be placed in parentheses. See
-L<perlsub/"Private Variables via my()"> for details.
+enclosing block, file, or C<eval>. If more than one value is listed,
+the list must be placed in parentheses.
+
+The exact semantics and interface of TYPE and ATTRS are still
+evolving. TYPE is currently bound to the use of C<fields> pragma,
+and attributes are handled using the C<attributes> pragma, or starting
+from Perl 5.8.0 also via the C<Attribute::Handlers> module. See
+L<perlsub/"Private Variables via my()"> for details, and L<fields>,
+L<attributes>, and L<Attribute::Handlers>.
=item next LABEL
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.)
+using C<my>, specify EXPR in your call to open.)
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
files and binary files, then you should check out L</binmode> for tips
for dealing with this. The key distinction between systems that need
C<binmode> and those that don't is their text file formats. Systems
-like Unix, MacOS, and Plan9, which delimit lines with a single
+like Unix, Mac OS, and Plan 9, 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.
open(FOO, '-|', "cat", '-n', $file);
The last example in each block shows the pipe as "list form", which is
-not yet supported on all platforms.
+not yet supported on all platforms. A good rule of thumb is that if
+your platform has true C<fork()> (in other words, if your platform is
+UNIX) you can use the list form.
See L<perlipc/"Safe Pipe Opens"> for more examples of this.
=item our EXPR
-=item our EXPR : ATTRIBUTES
+=item our EXPR TYPE
+
+=item our EXPR : ATTRS
+
+=item our TYPE EXPR : ATTRS
An C<our> declares the listed variables to be valid globals within
the enclosing block, file, or C<eval>. That is, it has the same
our $bar; # emits warning
An C<our> declaration may also have a list of attributes associated
-with it. B<WARNING>: This is an experimental feature that may be
-changed or removed in future releases of Perl. It should not be
-relied upon.
-
-The only currently recognized attribute is C<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
-have its own copy of the global.) In such an environment, this
-attribute also has the effect of making the global readonly.
-Examples:
+with it.
+
+The exact semantics and interface of TYPE and ATTRS are still
+evolving. TYPE is currently bound to the use of C<fields> pragma,
+and attributes are handled using the C<attributes> pragma, or starting
+from Perl 5.8.0 also via the C<Attribute::Handlers> module. See
+L<perlsub/"Private Variables via my()"> for details, and L<fields>,
+L<attributes>, and L<Attribute::Handlers>.
+
+The only currently recognized C<our()> 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 have its own copy of the global.) Examples:
our @EXPORT : unique = qw(foo);
our %EXPORT_TAGS : unique = (bar => [qw(aa bb cc)]);
our $VERSION : unique = "1.00";
+Note that this attribute also has the effect of making the global
+readonly when the first new interpreter is cloned (for example,
+when the first new thread is created).
+
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<unique> attribute does nothing in
=item sort LIST
-Sorts the LIST and returns the sorted list value. If SUBNAME or BLOCK
-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<< <=> >> 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
-of a SUBNAME, you can provide a BLOCK as an anonymous, in-line sort
-subroutine.
+In list context, this sorts the LIST and returns the sorted list value.
+In scalar context, the behaviour of C<sort()> is undefined.
+
+If SUBNAME or BLOCK 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<<
+<=> >> 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 of a SUBNAME, you can provide a BLOCK as
+an anonymous, in-line sort subroutine.
If the subroutine's prototype is C<($$)>, the elements to be compared
are passed by reference in C<@_>, as for a normal subroutine. This is
need a cryptographically-strong starting point rather than the
generally acceptable default, which is based on time of day,
process ID, and memory allocation, or the F</dev/urandom> device,
-if available.
+if available.
You can call srand($seed) with the same $seed to reproduce the
I<same> sequence from rand(), but this is usually reserved for
print $file, "\n";
}
-=item sub BLOCK
+=item sub NAME BLOCK
+
+=item sub NAME (PROTO) BLOCK
-=item sub NAME
+=item sub NAME : ATTRS BLOCK
-=item sub NAME BLOCK
+=item sub NAME (PROTO) : ATTRS BLOCK
-This is subroutine definition, not a real function I<per se>. With just a
-NAME (and possibly prototypes or attributes), it's just a forward declaration.
-Without a NAME, it's an anonymous function declaration, and does actually
-return a value: the CODE ref of the closure you just created. See L<perlsub>
-and L<perlref> for details.
+This is subroutine definition, not a real function I<per se>.
+Without a BLOCK it's just a forward declaration. Without a NAME,
+it's an anonymous function declaration, and does actually return
+a value: the CODE ref of the closure you just created.
+
+See L<perlsub> and L<perlref> for details about subroutines and
+references, and L<attributes> and L<Attribute::Handlers> for more
+information about attributes.
=item substr EXPR,OFFSET,LENGTH,REPLACEMENT
=item time
Returns the number of non-leap seconds since whatever time the system
-considers to be the epoch (that's 00:00:00, January 1, 1904 for MacOS,
+considers to be the epoch (that's 00:00:00, January 1, 1904 for Mac OS,
and 00:00:00 UTC, January 1, 1970 for most other systems).
Suitable for feeding to C<gmtime> and C<localtime>.
no strict 'refs';
no warnings;
-If no C<unimport> method can be found the call fails with a fatal error.
-
See L<perlmodlib> for a list of standard modules and pragmas. See L<perlrun>
for the C<-M> and C<-m> command-line options to perl that give C<use>
functionality from the command-line.
projects / p5sagit/p5-mst-13.2.git / blobdiff