X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=67c305ca6bc727253bc0356ea0caa9f30e1e8194;hb=03d70c897754d6af90de9d0ffe2857d000d6f2d7;hp=e959cd3da086c2aec0f7d17adc60ae76d75be183;hpb=e833de1e92fbc1dd83d6239be4b7391e4fa4f8ce;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index e959cd3..67c305c 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -475,15 +475,15 @@ 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, 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. @@ -2629,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 @@ -2647,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. @@ -2664,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 @@ -2675,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. @@ -2700,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, @@ -2715,6 +2728,7 @@ being C: opens a filehandle to an anonymous temporary file. + Examples: $ARTICLE = 100; @@ -2798,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 @@ -3532,7 +3552,7 @@ 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, or a C<0>, the value C<1> is used. Automatically calls 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 @@ -4277,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 @@ -5490,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 @@ -5602,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