"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
=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
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
print $file, "\n";
}
-=item sub BLOCK
+=item sub NAME BLOCK
-=item sub NAME
+=item sub NAME (PROTO) BLOCK
-=item sub NAME BLOCK
+=item sub NAME : ATTRS BLOCK
+
+=item sub NAME (PROTO) : ATTRS BLOCK
+
+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.
-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.
+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>.
projects / p5sagit/p5-mst-13.2.git / blobdiff