X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=67c305ca6bc727253bc0356ea0caa9f30e1e8194;hb=03d70c897754d6af90de9d0ffe2857d000d6f2d7;hp=b97c4a896ea04693530ee7ff98cd0d005306e5b6;hpb=6063ba187760a62f10a97ba9dd6ff5a93107bb51;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index b97c4a8..67c305c 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -398,8 +398,9 @@ on the previous timer. For delays of finer granularity than one second, you may use Perl's four-argument version of select() leaving the first three arguments undefined, or you might be able to use the C interface to -access setitimer(2) if your system supports it. The Time::HiRes module -from CPAN may also prove useful. +access setitimer(2) if your system supports it. The Time::HiRes +module (from CPAN, and starting from Perl 5.8 part of the standard +distribution) may also prove useful. It is usually a mistake to intermix C and C calls. (C may be internally implemented in your system with C) @@ -474,17 +475,17 @@ 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. +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 +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. @@ -2628,15 +2629,18 @@ to be converted into a file mode, for example. (Although perl will 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) 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 should I be in effect.) If EXPR is omitted, the scalar @@ -2646,7 +2650,8 @@ for this purpose; so if you're using C, specify EXPR in your call to open.) See L 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. @@ -2663,7 +2668,8 @@ 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<< '<' >>. +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 @@ -2674,14 +2680,18 @@ that pipes both in I out, but see L, L, and L 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 for more examples of this. (You are not allowed to C to a command that pipes both in I out, but see L, L, -and L for alternatives.) +and L 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 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. @@ -2699,6 +2709,10 @@ and those that don't is their text file formats. Systems like Unix, MacOS, and Plan9, which delimit lines with a single character, and which encode that character in C as C<"\n">, do not need C. The rest need it. +In the three argument form MODE may also contain a list of IO "layers" (see L and +L for more details) to be applied to the handle. This can be used to achieve the +effect of C 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 is frequently used in connection with C. Even if C won't do what you want (say, in a CGI script, @@ -2714,6 +2728,7 @@ being C: opens a filehandle to an anonymous temporary file. + Examples: $ARTICLE = 100; @@ -2797,19 +2812,25 @@ STDERR: print STDOUT "stdout 2\n"; print STDERR "stderr 2\n"; -If you specify C<< '<&=N' >>, where C is a number, then Perl will do an -equivalent of C's C of that file descriptor; this is more -parsimonious of file descriptors. For example: +If you specify C<< '<&=N' >>, where C is a number, then Perl will +do an equivalent of C's C 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. +You can see whether Perl has been compiled with PerlIO or not by +running C and looking for C line. If C +is C, 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 @@ -2934,6 +2955,8 @@ See L for more about Unicode. =item our EXPR +=item our EXPR : ATTRIBUTES + An C declares the listed variables to be valid globals within the enclosing block, file, or C. That is, it has the same scoping rules as a "my" declaration, but does not create a local @@ -2972,6 +2995,28 @@ package, Perl will emit warnings if you have asked for them. our $bar; # emits warning +An C declaration may also have a list of attributes associated +with it. B: 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 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: + + our @EXPORT : shared = qw(foo); + our %EXPORT_TAGS : shared = (bar => [qw(aa bb cc)]); + our $VERSION : shared = "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 attribute does nothing in +all other environments. + =item pack TEMPLATE,LIST Takes a LIST of values and converts it into a string using the rules @@ -3202,7 +3247,7 @@ not support long longs.) The integer formats C, C, C, C, C, and C are inherently non-portable between processors and operating systems because they obey the native byteorder and endianness. For example a -4-byte integer 0x12345678 (305419896 decimal) be ordered natively +4-byte integer 0x12345678 (305419896 decimal) would be ordered natively (arranged in and handled by the CPU registers) into bytes as 0x12 0x34 0x56 0x78 # big-endian @@ -3211,7 +3256,8 @@ because they obey the native byteorder and endianness. For example a Basically, the Intel and VAX CPUs are little-endian, while everybody else, for example Motorola m68k/88k, PPC, Sparc, HP PA, Power, and Cray are big-endian. Alpha and MIPS can be either: Digital/Compaq -used/uses them in little-endian mode; SGI/Cray uses them in big-endian mode. +used/uses them in little-endian mode; SGI/Cray uses them in big-endian +mode. The names `big-endian' and `little-endian' are comic references to the classic "Gulliver's Travels" (via the paper "On Holy Wars and a @@ -3238,7 +3284,7 @@ Byteorders C<'1234'> and C<'12345678'> are little-endian, C<'4321'> and C<'87654321'> are big-endian. If you want portable packed integers use the formats C, C, -C, and C, their byte endianness and size is known. +C, and C, their byte endianness and size are known. See also L. =item * @@ -3506,8 +3552,8 @@ If EXPR is omitted, uses C<$_>. 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, the value C<1> is used. Automatically calls C unless -C has already been called. See also C. +omitted, or a C<0>, the value C<1> is used. Automatically calls C +unless C has already been called. See also C. Apply C to the value returned by C if you want random integers instead of random fractional numbers. For example, @@ -4158,8 +4204,9 @@ busy multitasking system. For delays of finer granularity than one second, you may use Perl's C interface to access setitimer(2) if your system supports -it, or else see L above. The Time::HiRes module from CPAN -may also help. +it, or else see L above. The Time::HiRes module (from CPAN, +and starting from Perl 5.8 part of the standard distribution) may also +help. See also the POSIX module's C function. @@ -4250,6 +4297,12 @@ loop control operators described in L or with C. When C is in effect, C sorts LIST according to the current collation locale. See L. +Perl does B guarantee that sort is stable. (A I 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 @@ -4406,11 +4459,15 @@ splits on whitespace (after skipping any leading whitespace). Anything 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 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 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 @@ -5459,7 +5516,7 @@ Does the opposite of a C. Or the opposite of a 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 to do the @@ -5571,6 +5628,13 @@ command if the files already exist: $now = time; utime $now, $now, @ARGV; +If the first two elements of the list are C, 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