X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfunc.pod;h=833e89182579e65ecc26db20897d3843f6617e29;hb=9b5c3821be1f2a9a84772171c8bbadbf9cfc4a53;hp=96dabbbdc512d70465397631d53051f6fe10041b;hpb=b2e26e6edc035b06037b6eca4ef7db0cd8e603a6;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 96dabbb..833e891 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -614,7 +614,7 @@ false otherwise. See the example under C. Changes the permissions of a list of files. The first element of the list must be the numerical mode, which should probably be an octal -number, and which definitely should I a string of octal digits: +number, and which definitely should I be a string of octal digits: C<0644> is okay, C<'0644'> is not. Returns the number of files successfully changed. See also L, if all you have is a string. @@ -2097,7 +2097,34 @@ IPs that the connection might have come in on. =item getsockopt SOCKET,LEVEL,OPTNAME -Returns the socket option requested, or undef if there is an error. +Queries the option named OPTNAME associated with SOCKET at a given LEVEL. +Options may exist at multiple protocol levels depending on the socket +type, but at least the uppermost socket level SOL_SOCKET (defined in the +C module) will exist. To query options at another level the +protocol number of the appropriate protocol controlling the option +should be supplied. For example, to indicate that an option is to be +interpreted by the TCP protocol, LEVEL should be set to the protocol +number of TCP, which you can get using getprotobyname. + +The call returns a packed string representing the requested socket option, +or C if there is an error (the error reason will be in $!). What +exactly is in the packed string depends in the LEVEL and OPTNAME, consult +your system documentation for details. A very common case however is that +the option is an integer, in which case the result will be an packed +integer which you can decode using unpack with the C (or C) format. + +An example testing if Nagle's algorithm is turned on on a socket: + + use Socket; + + defined(my $tcp = getprotobyname("tcp")) + or die "Could not determine the protocol number for tcp"; + # my $tcp = Socket::IPPROTO_TCP; # Alternative + my $packed = getsockopt($socket, $tcp, Socket::TCP_NODELAY) + or die "Could not query TCP_NODELAY SOCKEt option: $!"; + my $nodelay = unpack("I", $packed); + print "Nagle's algorithm is turned ", $nodelay ? "off\n" : "on\n"; + =item glob EXPR @@ -2151,22 +2178,13 @@ In scalar context, C returns the ctime(3) value: $now_string = gmtime; # e.g., "Thu Oct 13 04:54:34 1994" -Also see the C function provided by the C module, -and the strftime(3) function available via the POSIX module. +If you need local time instead of GMT use the L builtin. +See also the C function provided by the C module, +and the strftime(3) and mktime(3) functions available via the L module. -This scalar value is B locale dependent (see L), but -is instead a Perl builtin. Also see the C module, and the -strftime(3) and mktime(3) functions available via the POSIX module. To -get somewhat similar but locale dependent date strings, set up your -locale environment variables appropriately (please see L) -and try for example: - - use POSIX qw(strftime); - $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime; - -Note that the C<%a> and C<%b> escapes, which represent the short forms -of the day of the week and the month of the year, may not necessarily -be three characters wide in all locales. +This scalar value is B locale dependent (see L), but is +instead a Perl builtin. To get somewhat similar but locale dependent date +strings, see the example in L. =item goto LABEL @@ -2501,36 +2519,44 @@ for details, including issues with tied arrays and hashes. =item localtime EXPR +=item localtime + Converts a time as returned by the time function to a 9-element list with the time analyzed for the local time zone. Typically used as follows: # 0 1 2 3 4 5 6 7 8 ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = - localtime(time); + localtime(time); All list elements are numeric, and come straight out of the C `struct -tm'. $sec, $min, and $hour are the seconds, minutes, and hours of the -specified time. $mday is the day of the month, and $mon is the month -itself, in the range C<0..11> with 0 indicating January and 11 -indicating December. $year is the number of years since 1900. That -is, $year is C<123> in year 2023. $wday is the day of the week, with -0 indicating Sunday and 3 indicating Wednesday. $yday is the day of -the year, in the range C<0..364> (or C<0..365> in leap years.) $isdst -is true if the specified time occurs during daylight savings time, -false otherwise. +tm'. C<$sec>, C<$min>, and C<$hour> are the seconds, minutes, and hours +of the specified time. -Note that the $year element is I simply the last two digits of -the year. If you assume it is, then you create non-Y2K-compliant -programs--and you wouldn't want to do that, would you? +C<$mday> is the day of the month, and C<$mon> is the month itself, in +the range C<0..11> with 0 indicating January and 11 indicating December. +This makes it easy to get a month name from a list: -The proper way to get a complete 4-digit year is simply: + my @abbr = qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ); + print "$abbr[$mon] $mday"; + # $mon=9, $mday=18 gives "Oct 18" - $year += 1900; +C<$year> is the number of years since 1900, not just the last two digits +of the year. That is, C<$year> is C<123> in year 2023. The proper way +to get a complete 4-digit year is simply: -And to get the last two digits of the year (e.g., '01' in 2001) do: + $year += 1900; - $year = sprintf("%02d", $year % 100); +To get the last two digits of the year (e.g., '01' in 2001) do: + + $year = sprintf("%02d", $year % 100); + +C<$wday> is the day of the week, with 0 indicating Sunday and 3 indicating +Wednesday. C<$yday> is the day of the year, in the range C<0..364> +(or C<0..365> in leap years.) + +C<$isdst> is true if the specified time occurs during Daylight Saving +Time, false otherwise. If EXPR is omitted, C uses the current time (C). @@ -2538,17 +2564,20 @@ In scalar context, C returns the ctime(3) value: $now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994" -This scalar value is B locale dependent, see L, but -instead a Perl builtin. Also see the C module -(to convert the second, minutes, hours, ... back to seconds since the -stroke of midnight the 1st of January 1970, the value returned by -time()), and the strftime(3) and mktime(3) functions available via the -POSIX module. To get somewhat similar but locale dependent date -strings, set up your locale environment variables appropriately -(please see L) and try for example: +This scalar value is B locale dependent but is a Perl builtin. For GMT +instead of local time use the L builtin. See also the +C module (to convert the second, minutes, hours, ... back to +the integer value returned by time()), and the L module's strftime(3) +and mktime(3) functions. + +To get somewhat similar but locale dependent date strings, set up your +locale environment variables appropriately (please see L) and +try for example: use POSIX qw(strftime); $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime; + # or for GMT formatted appropriately for your locale: + $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime; Note that the C<%a> and C<%b>, the short forms of the day of the week and the month of the year, may not necessarily be three characters wide. @@ -2914,7 +2943,9 @@ works for symmetry, but you really should consider writing something to the temporary file first. You will need to seek() to do the reading. -File handles can be opened to "in memory" files held in Perl scalars via: +Since v5.8.0, perl has built using PerlIO by default. Unless you've +changed this (ie Configure -Uuseperlio), you can open file handles to +"in memory" files held in Perl scalars via: open($fh, '>', \$variable) || .. @@ -2977,6 +3008,8 @@ Examples: } } +See L for detailed info on PerlIO. + You may also, in the Bourne shell tradition, specify an EXPR beginning 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 @@ -3278,34 +3311,14 @@ of values, as follows: h A hex string (low nybble first). H A hex string (high nybble first). - c A signed char value. + c A signed char (8-bit) value. C An unsigned char value. Only does bytes. See U for Unicode. - s A signed short value. + s A signed short (16-bit) value. S An unsigned short value. - (This 'short' is _exactly_ 16 bits, which may differ from - what a local C compiler calls 'short'. If you want - native-length shorts, use the '!' suffix.) - - 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 A signed long (32-bit) value. L An unsigned long value. - (This 'long' is _exactly_ 32 bits, which may differ from - what a local C compiler calls 'long'. If you want - native-length longs, use the '!' suffix.) - - n An unsigned short in "network" (big-endian) order. - N An unsigned long in "network" (big-endian) order. - v An unsigned short in "VAX" (little-endian) order. - V An unsigned long in "VAX" (little-endian) order. - (These 'shorts' and 'longs' are _exactly_ 16 bits and - _exactly_ 32 bits, respectively.) q A signed quad (64-bit) value. Q An unsigned quad value. @@ -3313,14 +3326,23 @@ of values, as follows: integer values _and_ if Perl has been compiled to support those. Causes a fatal error otherwise.) - j A signed integer value (a Perl internal integer, IV). - J An unsigned integer value (a Perl internal unsigned integer, UV). + i A signed integer value. + I A unsigned integer value. + (This 'integer' is _at_least_ 32 bits wide. Its exact + size depends on what a local C compiler calls 'int'.) + + n An unsigned short (16-bit) in "network" (big-endian) order. + N An unsigned long (32-bit) in "network" (big-endian) order. + v An unsigned short (16-bit) in "VAX" (little-endian) order. + V An unsigned long (32-bit) in "VAX" (little-endian) order. + + j A Perl internal signed integer value (IV). + J A Perl internal unsigned integer value (UV). f A single-precision float in the native format. d A double-precision float in the native format. - F A floating point value in the native native format - (a Perl internal floating point value, NV). + F A Perl internal floating point value (NV) in the native format D A long double-precision float in the native format. (Long doubles are available only if your system supports long double values _and_ if Perl has been compiled to support those. @@ -3344,6 +3366,27 @@ of values, as follows: the innermost ()-group. ( Start of a ()-group. +Some letters in the TEMPLATE may optionally be followed by one or +more of these modifiers (the second column lists the letters for +which the modifier is valid): + + ! sSlLiI Forces native (short, long, int) sizes instead + of fixed (16-/32-bit) sizes. + + xX Make x and X act as alignment commands. + + nNvV Treat integers as signed instead of unsigned. + + > sSiIlLqQ Force big-endian byte-order on the type. + jJfFdDpP (The "big end" touches the construct.) + + < sSiIlLqQ Force little-endian byte-order on the type. + jJfFdDpP (The "little end" touches the construct.) + +The C> and C> modifiers can also be used on C<()>-groups, +in which case they force a certain byte-order on all components of +that group, including subgroups. + The following rules apply: =over 8 @@ -3448,6 +3491,11 @@ The C

type packs a pointer to a structure of the size indicated by the length. A NULL pointer is created if the corresponding value for C

or C

is C, similarly for unpack(). +If your system has a strange pointer size (i.e. a pointer is neither as +big as an int nor as big as a long), it may not be possible to pack or +unpack pointers in big- or little-endian byte order. Attempting to do +so will result in a fatal error. + =item * The C template character allows packing and unpacking of strings where @@ -3479,7 +3527,7 @@ which Perl does not regard as legal in numeric strings. =item * The integer types C, C, C, and C may be -immediately followed by a C suffix to signify native shorts or +followed by a C modifier to signify native shorts or longs--as you can see from above for example a bare C does mean exactly 32 bits, the native C (as seen by the local C compiler) may be larger. This is an issue mainly in 64-bit platforms. You can @@ -3545,12 +3593,45 @@ via L: 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 are known. +If you want portable packed integers you can either use the formats +C, C, C, and C, or you can use the C> and C> +modifiers. These modifiers are only available as of perl 5.9.2. See also L. =item * +All integer and floating point formats as well as C

and C

and +C<()>-groups may be followed by the C> or C> modifiers +to force big- or little- endian byte-order, respectively. +This is especially useful, since C, C, C and C don't cover +signed integers, 64-bit integers and floating point values. However, +there are some things to keep in mind. + +Exchanging signed integers between different platforms only works +if all platforms store them in the same format. Most platforms store +signed integers in two's complement, so usually this is not an issue. + +The C> or C> modifiers can only be used on floating point +formats on big- or little-endian machines. Otherwise, attempting to +do so will result in a fatal error. + +Forcing big- or little-endian byte-order on floating point values for +data exchange can only work if all platforms are using the same +binary representation (e.g. IEEE floating point format). Even if all +platforms are using IEEE, there may be subtle differences. Being able +to use C> or C> on floating point values can be very useful, +but also very dangerous if you don't know exactly what you're doing. +It is definetely not a general way to portably store floating point +values. + +When using C> or C> on an C<()>-group, this will affect +all types inside the group that accept the byte-order modifiers, +including all subgroups. It will silently be ignored for all other +types. You are not allowed to override the byte-order within a group +that already has a byte-order modifier suffix. + +=item * + Real numbers (floats and doubles) are in the native machine format only; due to the multiplicity of floating formats around, and the lack of a standard "network" representation, no facility for interchange has been @@ -3559,10 +3640,13 @@ may not be readable on another - even if both use IEEE floating point arithmetic (as the endian-ness of the memory representation is not part of the IEEE spec). See also L. -Note that Perl uses doubles internally for all numeric calculation, and -converting from double into float and thence back to double again will -lose precision (i.e., C) will not in general -equal $foo). +If you know exactly what you're doing, you can use the C> or C> +modifiers to force big- or little-endian byte-order on floating point values. + +Note that Perl uses doubles (or long doubles, if configured) internally for +all numeric calculation, and converting from double into float and thence back +to double again will lose precision (i.e., C) +will not in general equal $foo). =item * @@ -3608,9 +3692,17 @@ both result in no-ops. =item * +C, C, C and C accept the C modifier. In this case they +will represent signed 16-/32-bit integers in big-/little-endian order. +This is only portable if all platforms sharing the packed data use the +same binary representation for signed integers (e.g. all platforms are +using two's complement representation). + +=item * + A comment in a TEMPLATE starts with C<#> and goes to the end of line. White space may be used to separate pack codes from each other, but -a C modifier and a repeat count must follow immediately. +modifiers and a repeat count must follow immediately. =item * @@ -3670,6 +3762,15 @@ Examples: # short 12, zero fill to position 4, long 34 # $foo eq $bar + $foo = pack('nN', 42, 4711); + # pack big-endian 16- and 32-bit unsigned integers + $foo = pack('S>L>', 42, 4711); + # exactly the same + $foo = pack('s. =item pos Returns the offset of where the last C search left off for the variable -in question (C<$_> is used when the variable is not specified). May be -modified to change that offset. Such modification will also influence -the C<\G> zero-width assertion in regular expressions. See L and +in question (C<$_> is used when the variable is not specified). Note that +0 is a valid match offset, while C indicates that the search position +is reset (usually due to match failure, but can also be because no match has +yet been performed on the scalar). C directly accesses the location used +by the regexp engine to store the offset, so assigning to C will change +that offset, and so will also influence the C<\G> zero-width assertion in +regular expressions. Because a failed C match doesn't reset the offset, +the return from C won't change either in this case. See L and L. =item print FILEHANDLE LIST @@ -4457,7 +4563,8 @@ You can effect a sleep of 250 milliseconds this way: select(undef, undef, undef, 0.25); Note that whether C. B: One should not attempt to mix buffered I/O (like C or ) with C