From: Jarkko Hietaniemi Date: Wed, 28 Jul 1999 20:17:37 +0000 (+0000) Subject: Enhance pack() doc. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=851646ae28fbfbd94e25648bf14d782e717e6d3c;p=p5sagit%2Fp5-mst-13.2.git Enhance pack() doc. p4raw-id: //depot/cfgperl@3822 --- diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 7072d72..edcb969 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -2719,7 +2719,8 @@ follows: 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'.) + 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. @@ -2731,7 +2732,8 @@ follows: 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'.) + what a local C compiler calls 'long'. If you want + native-length longs, use the '!' suffix.) n A short in "network" (big-endian) order. N A long in "network" (big-endian) order. @@ -2742,8 +2744,8 @@ follows: q A signed quad (64-bit) value. Q An unsigned quad value. - (Available only if your system supports 64-bit integer values - _and_ if Perl has been compiled to support those. + (Quads are available only if your system supports 64-bit + integer values _and_ if Perl has been compiled to support those. Causes a fatal error otherwise.) f A single-precision float in the native format. @@ -2790,7 +2792,8 @@ Likewise, the C<"b"> and C<"B"> fields pack a string that many bits long. =item * -The C<"h"> and C<"H"> fields pack a string that many nybbles long. +The C<"h"> and C<"H"> fields pack a string that many nybbles (4-bit groups, +representable as hexadecimal digits, 0-9a-f) long. =item * @@ -2833,11 +2836,11 @@ which Perl does not regard as legal in numeric strings. =item * The integer types C<"s">, C<"S">, C<"l">, and C<"L"> may be -immediately followed by a C<"!"> to signify native shorts or longs--as -you can see from above for example a bare C<"l"> 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 see -whether using C<"!"> makes any difference by +immediately followed by a C<"!"> suffix to signify native shorts or +longs--as you can see from above for example a bare C<"l"> 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 +see whether using C<"!"> makes any difference by print length(pack("s")), " ", length(pack("s!")), "\n"; print length(pack("l")), " ", length(pack("l!")), "\n"; @@ -2845,9 +2848,6 @@ whether using C<"!"> makes any difference by C<"i!"> and C<"I!"> also work but only because of completeness; they are identical to C<"i"> and C<"I">. -The actual sizes (in bytes) of native shorts, ints, and longs on -the platform where Perl was built are also available via L: - The actual sizes (in bytes) of native shorts, ints, longs, and long longs on the platform where Perl was built are also available via L: @@ -2858,6 +2858,9 @@ L: print $Config{longsize}, "\n"; print $Config{longlongsize}, "\n"; +(The C<$Config{longlongsize}> will be empty if your system does +not support long longs.) + =item * The integer formats C<"s">, C<"S">, C<"i">, C<"I">, C<"l">, and C<"L"> @@ -2900,6 +2903,7 @@ and C<'87654321'> are big-endian. If you want portable packed integers use the formats C<"n">, C<"N">, C<"v">, and C<"V">, their byte endianness and size is known. +See also L. =item * @@ -2909,13 +2913,22 @@ standard "network" representation, no facility for interchange has been made. This means that packed floating point data written on one machine 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). +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). +=item * + +You must yourself do any alignment or padding by inserting for example +enough C<'x'>es while packing. There is no way to they could know +from where the bytes are coming from, they might be coming from a +completely different system than the one your script is running in. +Therefore C (and C) handle their output and input as +flat sequences of bytes. + =back Examples: @@ -2957,6 +2970,12 @@ Examples: unpack("N", pack("B32", substr("0" x 32 . shift, -32))); } + $foo = pack('sx2l', 12, 34); + # short 12, two zero bytes padding, long 34 + $bar = pack('s@4l', 12, 34); + # short 12, zero fill to position 4, long 34 + # $foo eq $bar + The same template may generally also be used in unpack(). =item package @@ -4779,7 +4798,7 @@ has no way of checking whether the value passed to C corresponds to a valid memory location, passing a pointer value that's not known to be valid is likely to have disastrous consequences. -See L for more examples. +See L for more examples and notes. =item untie VARIABLE