X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=2f342900a1de184bb6a806d3b58e37c716490747;hb=16fe6d5906f6eff9da00cb861a7054a440d1f6eb;hp=de7abdc01d5b9e1196dbad4bc5b1185b02918952;hpb=3a4b19e44cf4e74b7a6a58fed36ba3ca9cafc864;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index de7abdc..2f34290 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -335,7 +335,7 @@ following a minus are interpreted as file tests. 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 (E30%) +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 @@ -439,23 +439,32 @@ does. Returns true if it succeeded, false otherwise. NAME should be a packed address of the appropriate type for the socket. See the examples in L. +=item binmode FILEHANDLE, DISCIPLINE + =item binmode FILEHANDLE -Arranges for FILEHANDLE to be read or written in "binary" mode on -systems where the run-time libraries distinguish between binary and +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. binmode() should be called after 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. +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() has no effect, and on some systems it 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. +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 pragma can be used to establish default disciplines. +See L. + The operating system, device drivers, C libraries, and Perl run-time system all work together to let the programmer treat a single character (C<\n>) as the line terminator, irrespective of the external @@ -544,7 +553,7 @@ arguments with which the subroutine was invoked. Be aware that the optimizer might have optimized call frames away before C had a chance to get the information. That means that C might not return information about the call frame you expect it do, for -C 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 was called. =item chdir EXPR @@ -1002,8 +1011,8 @@ lookup: Outside an C, prints the value of LIST to C and exits with the current value of C<$!> (errno). If C<$!> is C<0>, -exits with the value of C<($? EE 8)> (backtick `command` -status). If C<($? EE 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 the error message is stuffed into C<$@> and the C is terminated with the undefined value. This makes C the way to raise an exception. @@ -1217,12 +1226,12 @@ as terminals may lose the end-of-file condition if you do. An C without an argument uses the last file read. Using C 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 -CE> operator. Since CE> isn't explicitly opened, -as a normal filehandle is, an C before CE> has been +C<< <> >> operator. Since C<< <> >> isn't explicitly opened, +as a normal filehandle is, an C before C<< <> >> has been used will cause C<@ARGV> to be examined to determine if input is available. -In a CE)> loop, C or C can be used to +In a C<< while (<>) >> loop, C or C can be used to detect the end of each file, C will only detect the end of the last file. Examples: @@ -1465,7 +1474,7 @@ operation is a hash or array key lookup or subroutine name: 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{"A"}> and C<$ref-E{"A"}-E{"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: @@ -1477,8 +1486,8 @@ This surprising autovivification in what does not at first--or even second--glance appear to be an lvalue context may be fixed in a future release. -See L for specifics on how exists() acts when -used on a pseudo-hash. +See L 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. @@ -1933,8 +1942,8 @@ Returns the socket option requested, or undef if there is an error. Returns the value of EXPR with filename expansions such as the standard Unix shell F would do. This is the internal function -implementing the C*.cE> operator, but you can use it directly. -If EXPR is omitted, C<$_> is used. The C*.cE> 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. Beginning with v5.6.0, this operator is implemented using the standard @@ -2109,7 +2118,7 @@ Implements the ioctl(2) function. You'll probably first have to say to get the correct function definitions. If F 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 Fsys/ioctl.hE>. +own, based on your C header files such as F<< >>. (There is a Perl script called B 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 @@ -2462,10 +2471,10 @@ and C 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. Returns true if -successful, or false if there is an error. See also C -and C documentation. +message queue ID. MSG must begin with the native long integer message +type, which may be created with C. Returns true if +successful, or false if there is an error. See also C and +C documentation. =item msgrcv ID,VAR,SIZE,TYPE,FLAGS @@ -2538,7 +2547,7 @@ 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,EXPR +=item open FILEHANDLE,MODE,LIST =item open FILEHANDLE,EXPR @@ -2553,24 +2562,24 @@ 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<'E'> or nothing, the file is opened for input. -If MODE is C<'E'>, the file is truncated and opened for -output, being created if necessary. If MODE is C<'EE'>, +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'> or C<'E'> to indicate that -you want both read and write access to the file; thus C<'+E'> is almost -always preferred for read/write updates--the C<'+E'> 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 for a better approach. The file is created with permissions of C<0666> modified by the process' C 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'>. +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 @@ -2590,7 +2599,7 @@ that pipes both in I out, but see L, L, and L for alternatives.) In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN -and opening C<'E-'> opens STDOUT. +and opening C<< '>-' >> opens STDOUT. Open returns nonzero upon success, the undefined value otherwise. If the C @@ -2662,10 +2671,10 @@ Examples: } You may also, in the Bourne shell tradition, specify an EXPR beginning -with C<'E&'>, 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>, CE>, -C>, C<+E>, C<+EE>, and C<+E>. 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 @@ -2696,7 +2705,7 @@ STDERR: print STDOUT "stdout 2\n"; print STDERR "stderr 2\n"; -If you specify C<'E&=N'>, where C is a number, then Perl will do an +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: @@ -3092,10 +3101,10 @@ 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 (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 @@ -3105,12 +3114,12 @@ The names `big-endian' and `little-endian' are comic references to 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", $_ } @@ -3432,8 +3441,8 @@ When C<$/> is set to C, when readline() is in scalar context (i.e. file slurp mode), and when an empty file is read, it returns C<''> the first time, followed by C subsequently. -This is the internal function implementing the CEXPRE> -operator, but you can use it directly. The CEXPRE> +This is the internal function implementing the C<< >> +operator, but you can use it directly. The C<< >> operator is discussed in more detail in L. $line = ; @@ -3769,7 +3778,7 @@ This is also useful for applications emulating C. Once you hit EOF on your read, and then sleep for a while, you might have to stick in a seek() to reset things. The C doesn't change the current position, but it I clear the end-of-file condition on the handle, so that the -next CFILEE> makes Perl try again to read something. We hope. +next C<< >> 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: @@ -3863,7 +3872,7 @@ You can effect a sleep of 250 milliseconds this way: select(undef, undef, undef, 0.25); B: One should not attempt to mix buffered I/O (like C -or EFHE) with C, except as permitted by POSIX, and even then only on POSIX systems. You have to use C instead. =item semctl ID,SEMNUM,CMD,ARG @@ -3874,9 +3883,11 @@ Calls the System V IPC function C. You'll probably have to say 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: the -undefined value for error, "C<0 but true>" for zero, or the actual return -value otherwise. See also C and C documentation. +semid_ds structure or semaphore value array. Returns like C: +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. +See also C and C documentation. =item semget KEY,NSEMS,FLAGS @@ -4072,7 +4083,7 @@ Sorts the LIST and returns the sorted list value. If SUBNAME or BLOCK is omitted, Cs 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> and C +of the list are to be ordered. (The C<< <=> >> and C 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 @@ -4168,7 +4179,7 @@ Examples: || $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; @@ -4465,7 +4476,7 @@ the F device) or based on the current time and process ID, among other things. In versions of Perl prior to 5.004 the default seed was just the current C