X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=355ada86f7cea94f1c185be47f618413bf4a4f43;hb=bea985324a3cd895f8e0a0c38e90ab3d09433415;hp=564f3b6ae3871e32eca7892c1b7f33d6618d3706;hpb=6a30edae98bf8af3a005d1111ac077997dd26f35;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 564f3b6..355ada8 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -453,7 +453,7 @@ 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. Returns true on success, -C on failure. +otherwise it returns C and sets C<$!> (errno). If LAYER is omitted or specified as C<:raw> the filehandle is made suitable for passing binary data. This includes turning off possible CRLF @@ -1449,6 +1449,11 @@ in case 6. C does I count as a loop, so the loop control statements C, C, or C cannot be used to leave or restart the block. +Note that as a very special case, an C executed within the C +package doesn't see the usual surrounding lexical scope, but rather the +scope of the first non-DB piece of code that called it. You don't normally +need to worry about this unless you are writing a Perl debugger. + =item exec LIST =item exec PROGRAM LIST @@ -1578,9 +1583,6 @@ 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. - Use of a subroutine call, rather than a subroutine name, as an argument to exists() is an error. @@ -1808,11 +1810,11 @@ C always returns true. See L for other examples. =item getc Returns the next character from the input file attached to FILEHANDLE, -or the undefined value at end of file, or if there was an error. -If FILEHANDLE is omitted, reads from STDIN. This is not particularly -efficient. However, it cannot be used by itself to fetch single -characters without waiting for the user to hit enter. For that, try -something more like: +or the undefined value at end of file, or if there was an error (in +the latter case C<$!> is set). If FILEHANDLE is omitted, reads from +STDIN. This is not particularly efficient. However, it cannot be +used by itself to fetch single characters without waiting for the user +to hit enter. For that, try something more like: if ($BSD_STYLE) { system "stty cbreak /dev/tty 2>&1"; @@ -1873,6 +1875,13 @@ does not accept a PID argument, so only C is truly portable. Returns the process id of the parent process. +Note for Linux users: on Linux, the C functions C and +C return different values from different threads. In order to +be portable, this behavior is not reflected by the perl-level function +C, that returns a consistent value across threads. If you want +to call the underlying C, you may use the CPAN module +C. + =item getpriority WHICH,WHO Returns the current priority for a process, a process group, or a user. @@ -1969,7 +1978,7 @@ lookup by name, in which case you get the other thing, whatever it is. $name = getpwuid($num); $name = getpwent(); $gid = getgrnam($name); - $name = getgrgid($num; + $name = getgrgid($num); $name = getgrent(); #etc. @@ -2530,7 +2539,8 @@ See also L for the inverse operation. Does the same thing as the C function (including setting the special C<_> filehandle) but stats a symbolic link instead of the file the symbolic link points to. If symbolic links are unimplemented on -your system, a normal C is done. +your system, a normal C is done. For much more detailed +information, please see the documentation for C. If EXPR is omitted, stats C<$_>. @@ -3763,13 +3773,13 @@ with the wrong number of RANDBITS.) Attempts to read LENGTH I of data into variable SCALAR from the specified FILEHANDLE. Returns the number of characters -actually read, C<0> at end of file, or undef if there was an error. -SCALAR will be grown or shrunk to the length actually read. If SCALAR -needs growing, the new bytes will be zero bytes. An OFFSET may be -specified to place the read data into some other place in SCALAR than -the beginning. The call is actually implemented in terms of either -Perl's or system's fread() call. To get a true read(2) system call, -see C. +actually read, C<0> at end of file, or undef if there was an error (in +the latter case C<$!> is also set). SCALAR will be grown or shrunk to +the length actually read. If SCALAR needs growing, the new bytes will +be zero bytes. An OFFSET may be specified to place the read data into +some other place in SCALAR than the beginning. The call is actually +implemented in terms of either Perl's or system's fread() call. To +get a true read(2) system call, see C. Note the I: depending on the status of the filehandle, either (8-bit) bytes or characters are read. By default all @@ -4802,13 +4812,13 @@ The pattern C may be replaced with an expression to specify patterns that vary at runtime. (To do runtime compilation only once, use C.) -As a special case, specifying a PATTERN of space (C<' '>) will split on -white space just as C with no arguments does. Thus, C can -be used to emulate B's default behavior, whereas C +As a special case, specifying a PATTERN of space (S>) will split on +white space just as C with no arguments does. Thus, S> can +be used to emulate B's default behavior, whereas S> will give you as many null initial fields as there are leading spaces. -A C on C is like a C except that any leading +A C on C is like a S> except that any leading whitespace produces a null first field. A C with no arguments -really does a C internally. +really does a S> internally. A PATTERN of C is treated as if it were C, since it isn't much use otherwise. @@ -4969,8 +4979,8 @@ effect as the C<-> flag: left-justification. You can specify a precision (for numeric conversions) or a maximum width (for string conversions) by specifying a C<.> followed by a number. -For floating point formats, this specifies the number of decimal places -to show (the default being 6), eg: +For floating point formats, with the exception of 'g' and 'G', this specifies +the number of decimal places to show (the default being 6), eg: # these examples are subject to system-specific variation printf '<%f>', 1; # prints "<1.000000>" @@ -4979,6 +4989,18 @@ to show (the default being 6), eg: printf '<%e>', 10; # prints "<1.000000e+01>" printf '<%.1e>', 10; # prints "<1.0e+01>" +For 'g' and 'G', this specifies the maximum number of digits to show, +including prior to the decimal point as well as after it, eg: + + # these examples are subject to system-specific variation + printf '<%g>', 1; # prints "<1>" + printf '<%.10g>', 1; # prints "<1>" + printf '<%g>', 100; # prints "<100>" + printf '<%.1g>', 100; # prints "<1e+02>" + printf '<%.2g>', 100.01; # prints "<1e+02>" + printf '<%.5g>', 100.01; # prints "<100.01>" + printf '<%.4g>', 100.01; # prints "<100>" + For integer conversions, specifying a precision implies that the output of the number itself should be zero-padded to this width: @@ -5006,23 +5028,49 @@ eg C<.*2$>: =item size For numeric conversions, you can specify the size to interpret the -number as using C, C, C, C, C or C. For integer -conversions, numbers are usually assumed to be whatever the default -integer size is on your platform (usually 32 or 64 bits), but you -can override this to use instead one of the standard C types, as -supported by the compiler used to build Perl: +number as using C, C, C, C, C, or C. For integer +conversions (C), numbers are usually assumed to be +whatever the default integer size is on your platform (usually 32 or 64 +bits), but you can override this to use instead one of the standard C types, +as supported by the compiler used to build Perl: l interpret integer as C type "long" or "unsigned long" h interpret integer as C type "short" or "unsigned short" - q, L or ll interpret integer as C type "long long" or "unsigned long long" - (if your platform supports such a type, else it is an error) + q, L or ll interpret integer as C type "long long", "unsigned long long". + or "quads" (typically 64-bit integers) + +The last will produce errors if Perl does not understand "quads" in your +installation. (This requires that either the platform natively supports quads +or Perl was specifically compiled to support quads.) You can find out +whether your Perl supports quads via L: + + use Config; + ($Config{use64bitint} eq 'define' || $Config{longsize} >= 8) && + print "quads\n"; -For floating point conversions, numbers are usually assumed to be -the default floating point size on your platform (double or long double), -but you can force 'long double' with C, C or C if your -platform supports them. +For floating point conversions (C), numbers are usually assumed +to be the default floating point size on your platform (double or long double), +but you can force 'long double' with C, C, or C if your +platform supports them. You can find out whether your Perl supports long +doubles via L: -The size specifier 'V' has no effect for Perl code, but it supported + use Config; + $Config{d_longdbl} eq 'define' && print "long doubles\n"; + +You can find out whether Perl considers 'long double' to be the default +floating point size to use on your platform via L: + + use Config; + ($Config{uselongdouble} eq 'define') && + print "long doubles by default\n"; + +It can also be the case that long doubles and doubles are the same thing: + + use Config; + ($Config{doublesize} == $Config{longdblsize}) && + print "doubles are long doubles\n"; + +The size specifier C has no effect for Perl code, but it is supported for compatibility with XS code; it means 'use the standard size for a Perl integer (or floating-point number)', which is already the default for Perl code. @@ -5064,44 +5112,6 @@ 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. -If Perl understands "quads" (64-bit integers) (this requires -either that the platform natively support quads or that Perl -be specifically compiled to support quads), the characters - - d u o x X b i D U O - -print quads, and they may optionally be preceded by - - ll L q - -For example - - %lld %16LX %qo - -You can find out whether your Perl supports quads via L: - - use Config; - ($Config{use64bitint} eq 'define' || $Config{longsize} == 8) && - print "quads\n"; - -If Perl understands "long doubles" (this requires that the platform -support long doubles), the flags - - e f g E F G - -may optionally be preceded by - - ll L - -For example - - %llf %Lg - -You can find out whether your Perl supports long doubles via L: - - use Config; - $Config{d_longdbl} eq 'define' && print "long doubles\n"; - =item sqrt EXPR =item sqrt @@ -5253,7 +5263,7 @@ You can import symbolic mode constants (C) and functions $group_read = ($mode & S_IRGRP) >> 3; $other_execute = $mode & S_IXOTH; - printf "Permissions are %04o\n", S_ISMODE($mode), "\n"; + printf "Permissions are %04o\n", S_IMODE($mode), "\n"; $is_setuid = $mode & S_ISUID; $is_setgid = S_ISDIR($mode); @@ -5267,7 +5277,8 @@ The commonly available S_IF* constants are S_IRWXG S_IRGRP S_IWGRP S_IXGRP S_IRWXO S_IROTH S_IWOTH S_IXOTH - # Setuid/Setgid/Stickiness. + # Setuid/Setgid/Stickiness/SaveText. + # Note that the exact meaning of these is system dependent. S_ISUID S_ISGID S_ISVTX S_ISTXT @@ -5281,7 +5292,7 @@ The commonly available S_IF* constants are and the S_IF* functions are - S_IFMODE($mode) the part of $mode containing the permission bits + S_IMODE($mode) the part of $mode containing the permission bits and the setuid/setgid/sticky bits S_IFMT($mode) the part of $mode containing the file type @@ -5300,7 +5311,8 @@ and the S_IF* functions are S_ISENFMT($mode) S_ISWHT($mode) See your native chmod(2) and stat(2) documentation for more details -about the S_* constants. +about the S_* constants. To get status info for a symbolic link +instead of the target file behind the link, use the C function. =item study SCALAR @@ -5515,14 +5527,15 @@ See L for a kinder, gentler explanation of opening files. =item sysread FILEHANDLE,SCALAR,LENGTH -Attempts to read LENGTH I of data into variable SCALAR from -the specified FILEHANDLE, using the system call read(2). It bypasses -buffered IO, so mixing this with other kinds of reads, C, -C, C, C, or C can cause confusion because -stdio usually buffers data. Returns the number of characters actually -read, C<0> at end of file, 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. +Attempts to read LENGTH I of data into variable SCALAR +from the specified FILEHANDLE, using the system call read(2). It +bypasses buffered IO, so mixing this with other kinds of reads, +C, C, C, C, or C can cause confusion +because stdio usually buffers data. Returns the number of characters +actually read, C<0> at end of file, or undef if there was an error (in +the latter case C<$!> is also set). SCALAR will be grown or shrunk so +that the last byte actually read is the last byte of the scalar after +the read. Note the I: depending on the status of the filehandle, either (8-bit) bytes or characters are read. By default all @@ -5640,9 +5653,10 @@ is not specified, writes whole SCALAR. It bypasses buffered IO, so mixing this with reads (other than C, C, C, C, C, or C may cause confusion because stdio usually buffers data. Returns the number of characters actually written, or -C if there was an error. If the LENGTH is greater than the -available data in the SCALAR after the OFFSET, only as much data as is -available will be written. +C if there was an error (in this case the errno variable C<$!> +is also set). If the LENGTH is greater than the available data in the +SCALAR after the OFFSET, 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