X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=913f6f8fbddf29125a4e7368a2cdb27ff9678ab5;hb=dd2afc7eca335b517bec81ce70a8a5a1c86b9c11;hp=84a794adb25fb702f11e643dd98e698c9a57cb98;hpb=4a6725af9146bd7faaa10aa5429ff009d393fd6d;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 84a794a..913f6f8 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -108,7 +108,7 @@ delete, each, exists, keys, values binmode, close, closedir, dbmclose, dbmopen, die, eof, fileno, flock, format, getc, print, printf, read, readdir, -rewinddir, seek, seekdir, select, syscall, sysread, +rewinddir, seek, seekdir, select, syscall, sysread, sysseek, syswrite, tell, telldir, truncate, warn, write =item Functions for fixed length data or records @@ -1231,7 +1231,7 @@ example: See L for many details and examples. -=item formline PICTURE, LIST +=item formline PICTURE,LIST This is an internal function used by Cs, though you may call it too. It formats (see L) a list of values according to the @@ -2096,17 +2096,29 @@ follows: c A signed char value. C An unsigned char value. + s A signed short value. S An unsigned short value. + (This 'short' is _exactly_ 16 bits, which may differ from + what a local C compiler calls 'short'.) + i A signed integer value. I An unsigned integer value. + (This 'integer' is _at_least_ 32 bits wide. Its exact size + depends on what a local C compiler calls 'int', and may + even be larger than the 'long' described in the next item.) + l A signed long value. L An unsigned long value. + (This 'long' is _exactly_ 32 bits, which may differ from + what a local C compiler calls 'long'.) - n A short in "network" order. - N A long in "network" order. + n A short in "network" (big-endian) order. + N A long in "network" (big-endian) order. v A short in "VAX" (little-endian) order. V A long in "VAX" (little-endian) order. + (These 'shorts' and 'longs' are _exactly_ 16 bits and + _exactly_ 32 bits, respectively.) f A single-precision float in the native format. d A double-precision float in the native format. @@ -2116,10 +2128,10 @@ follows: u A uuencoded string. - w A BER compressed integer. Bytes give an unsigned integer base - 128, most significant digit first, with as few digits as - possible, and with the bit 8 of each byte except the last set - to "1." + w A BER compressed integer. Its bytes represent an unsigned + integer in base 128, most significant digit first, with as few + digits as possible. Bit eight (the high bit) is set on each + byte except the last. x A null byte. X Back up a byte. @@ -2577,26 +2589,30 @@ C<(some expression)> suffices. =item seek FILEHANDLE,POSITION,WHENCE -Randomly positions the file pointer for FILEHANDLE, just like the fseek() -call of stdio. FILEHANDLE may be an expression whose value gives the name -of the filehandle. The values for WHENCE are 0 to set the file pointer to -POSITION, 1 to set the it to current plus POSITION, and 2 to set it to EOF -plus offset. You may use the values SEEK_SET, SEEK_CUR, and SEEK_END for -this from the POSIX module. Returns 1 upon success, 0 otherwise. +Sets FILEHANDLE's position, just like the fseek() call of stdio. +FILEHANDLE may be an expression whose value gives the name of the +filehandle. The values for WHENCE are 0 to set the new position to +POSITION, 1 to set it to the current position plus POSITION, and 2 to +set it to EOF plus POSITION (typically negative). For WHENCE you may +use the constants SEEK_SET, SEEK_CUR, and SEEK_END from either the +IO::Seekable or the POSIX module. Returns 1 upon success, 0 otherwise. + +If you want to position file for sysread() or syswrite(), don't use +seek() -- buffering makes its effect on the file's system position +unpredictable and non-portable. Use sysseek() instead. On some systems you have to do a seek whenever you switch between reading and writing. Amongst other things, this may have the effect of calling -stdio's clearerr(3). A "whence" of 1 (SEEK_CUR) is useful for not moving -the file pointer: +stdio's clearerr(3). A WHENCE of 1 (SEEK_CUR) is useful for not moving +the file position: seek(TEST,0,1); 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. First the simple trick listed above to clear the -filepointer. The seek() 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. +seek() to reset things. The seek() 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. If that doesn't work (some stdios are particularly cantankerous), then you may need something more like this: @@ -3074,15 +3090,77 @@ L, and L.) =item sprintf FORMAT, LIST -Returns a string formatted by the usual printf conventions of the C -language. See L or L on your system for details. -(The * character for an indirectly specified length is not -supported, but you can get the same effect by interpolating a variable -into the pattern.) If C is -in effect, the character used for the decimal point in formatted real numbers -is affected by the LC_NUMERIC locale. See L. -Some C libraries' implementations of sprintf() can -dump core when fed ludicrous arguments. +Returns a string formatted by the usual printf conventions of the +C library function sprintf(). See L or L +on your system for an explanation of the general principles. + +Perl does all of its own sprintf() formatting -- it emulates the C +function sprintf(), but it doesn't use it (except for floating-point +numbers, and even then only the standard modifiers are allowed). As a +result, any non-standard extensions in your local sprintf() are not +available from Perl. + +Perl's sprintf() permits the following universally-known conversions: + + %% a percent sign + %c a character with the given number + %s a string + %d a signed integer, in decimal + %u an unsigned integer, in decimal + %o an unsigned integer, in octal + %x an unsigned integer, in hexadecimal + %e a floating-point number, in scientific notation + %f a floating-point number, in fixed decimal notation + %g a floating-point number, in %e or %f notation + +In addition, Perl permits the following ANSI-invented conversions: + + %i a synonym for %d + %X like %x, but using upper-case letters + %E like %e, but using an upper-case "E" + %G like %g, but with an upper-case "E" (if applicable) + %p a pointer (outputs the Perl value's address in hexadecimal) + %n special: B into the next variable in the parameter + list the number of characters printed so far + +Finally, for backward (and we do mean "backward") compatibility, +Perl permits these nonstandard but unaccountably popular conversions: + + %D a synonym for %ld + %U a synonym for %lu + %O a synonym for %lo + %F a synonym for %f + +Perl permits the following universally-known flags between the C<%> +and the conversion letter: + + space prefix positive number with a space + + prefix positive number with a plus sign + - left-justify within the field + 0 use zeros, not spaces, to right-justify + number minimum field width + .number "precision": digits after decimal point for floating-point, + max length for string, minimum length for integer + l interpret integer as C type "long" or "unsigned long" + +In addition, Perl permits the following ANSI-invented flags: + + # prefix octal with "0", hex with "0x" + h interpret integer as C type "short" or "unsigned short" + +Finally, there is one Perl-specific flag: + + V interpret integer as Perl's standard integer type + +Where a number would appear in the flags, an asterisk ("*") may be +used instead, in which case Perl uses the next item in the parameter +list as the given number (that is, as the field width or precision). +If a field width obtained through "*" is negative, it has the same +effect as the '-' flag: left-justification. + +If C is in effect, the character used for the decimal +point in formatted real numbers is affected by the LC_NUMERIC locale. +See L. =item sqrt EXPR @@ -3325,11 +3403,12 @@ into that kind of thing. =item sysread FILEHANDLE,SCALAR,LENGTH Attempts to read LENGTH bytes of data into variable SCALAR from the -specified FILEHANDLE, using the system call read(2). It bypasses -stdio, so mixing this with other kinds of reads may cause confusion. -Returns the number of bytes actually read, or undef if there was an -error. SCALAR will be grown or shrunk so that the last byte actually -read is the last byte of the scalar after the read. +specified FILEHANDLE, using the system call read(2). It bypasses stdio, +so mixing this with other kinds of reads, print(), write(), seek(), or +tell() can cause confusion. Returns the number of bytes actually read, +or undef if there was an error. SCALAR will be grown or shrunk so that +the last byte actually read is the last byte of the scalar after the +read. An OFFSET may be specified to place the read data at some place in the string other than the beginning. A negative OFFSET specifies @@ -3338,6 +3417,23 @@ string. A positive OFFSET greater than the length of SCALAR results in the string being padded to the required size with "\0" bytes before the result of the read is appended. +=item sysseek FILEHANDLE,POSITION,WHENCE + +Sets FILEHANDLE's system position using the system call lseek(2). It +bypasses stdio, so mixing this with reads (other than sysread()), +print(), write(), seek(), or tell() may cause confusion. FILEHANDLE may +be an expression whose value gives the name of the filehandle. The +values for WHENCE are 0 to set the new position to POSITION, 1 to set +the it to the current position plus POSITION, and 2 to set it to EOF +plus POSITION (typically negative). For WHENCE, you may use the +constants SEEK_SET, SEEK_CUR, and SEEK_END from either the IO::Seekable +or the POSIX module. + +Returns the new position, or the undefined value on failure. A position +of zero is returned as the string "0 but true"; thus sysseek() returns +TRUE on success and FALSE on failure, yet you can still easily determine +the new position. + =item system LIST Does exactly the same thing as "exec LIST" except that a fork is done @@ -3388,10 +3484,11 @@ signals and core dumps. Attempts to write LENGTH bytes of data from variable SCALAR to the specified FILEHANDLE, using the system call write(2). It bypasses -stdio, so mixing this with prints may cause confusion. Returns the -number of bytes actually written, or undef if there was an error. -If the length is greater than the available data, only as much data as -is available will be written. +stdio, so mixing this with reads (other than sysread()), print(), +write(), seek(), or tell() may cause confusion. Returns the number of +bytes actually written, or undef if there was an error. If the length +is greater than the available data, only as much data as is available +will be written. An OFFSET may be specified to write the data from some part of the string other than the beginning. A negative OFFSET specifies writing @@ -3401,7 +3498,7 @@ that many bytes counting backwards from the end of the string. =item tell -Returns the current file position for FILEHANDLE. FILEHANDLE may be an +Returns the current position for FILEHANDLE. FILEHANDLE may be an expression whose value gives the name of the actual filehandle. If FILEHANDLE is omitted, assumes the file last read.