
unpack TEMPLATE,EXPR

Unpack() does the reverse of pack(): it takes a string representing a structure and
     expands it out into a list value, returning the array value. (In scalar context, it returns
     merely the first value produced.) The TEMPLATE has the same format as in the pack()
     function. Here's a subroutine that does substring: 

         sub substr {
             my($what,$where,$howmuch) = @_;
             unpack("x$where a$howmuch", $what);
         }

     and then there's 

         sub ordinal { unpack("c",$_[0]); } # same as ord()


pack TEMPLATE,LIST

     Takes an array or list of values and packs it into a binary structure, returning the string
     containing the structure. The TEMPLATE is a sequence of characters that give the
     order and type of values, as follows: 

         a   A string with arbitrary binary data, will be null padded.
         A   An ascii string, will be space padded.
         Z   A null terminated (asciz) string, will be null padded.

         b   A bit string (ascending bit order, like vec()).
         B   A bit string (descending bit order).
         h   A hex string (low nybble first).
         H   A hex string (high nybble first).

         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" (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.)

         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.
                Causes a fatal error otherwise.)

         f   A single-precision float in the native format.
         d   A double-precision float in the native format.

         p   A pointer to a null-terminated string.
         P   A pointer to a structure (fixed-length string).

         u   A uuencoded string.

         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.
         @   Null fill to absolute position.

     The following rules apply: 

          Each letter may optionally be followed by a number giving a repeat count. With
          all types except "a", "A", "Z", "b", "B", "h", "H", and "P" the pack function will
          gobble up that many values from the LIST. A * for the repeat count means to
          use however many items are left. 

          The "a", "A", and "Z" types gobble just one value, but pack it as a string of
          length count, padding with nulls or spaces as necessary. When unpacking, "A"
          strips trailing spaces and nulls, "Z" strips everything after the first null, and "a"
          returns data verbatim. 

          Likewise, the "b" and "B" fields pack a string that many bits long. 

          The "h" and "H" fields pack a string that many nybbles long. 

          The "p" type packs a pointer to a null-terminated string. You are responsible for
          ensuring the string is not a temporary value (which can potentially get deallocated
          before you get around to using the packed result). The "P" type packs a pointer
          to a structure of the size indicated by the length. A NULL pointer is created if
          the corresponding value for "p" or "P" is undef. 

          The integer formats "s", "S", "i", "I", "l", and "L" are inherently non-portable
          between processors and operating systems because they obey the native
          byteorder and endianness. For example a 4-byte integer 0x87654321
          (2271560481 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 and
          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 in little-endian mode, SGI uses it in big-endian mode. 

          The names `big-endian' and `little-endian' are joking 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 lilliputs. Some systems may even have weird 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", $_ }
                                      unpack("C*",pack("L",0x12345678))), "\n";

          The byteorder on the platform where Perl was built is also available via Config: 

                  use Config;
                  print $Config{byteorder}, "\n";

          Byteorders '1234' and '12345678' are little-endian, '4321' and
          '87654321' are big-endian. 

          If you want portable packed integers use the formats "n", "N", "v", and "V",
          their byte endianness and size is known. 

          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 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). 

          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.,
          unpack("f", pack("f", $foo)) will not in general equal $foo). 

     Examples: 

         $foo = pack("CCCC",65,66,67,68);
         # foo eq "ABCD"
         $foo = pack("C4",65,66,67,68);
         # same thing

         $foo = pack("ccxxcc",65,66,67,68);
         # foo eq "AB\0\0CD"

         $foo = pack("s2",1,2);
         # "\1\0\2\0" on little-endian
         # "\0\1\0\2" on big-endian

         $foo = pack("a4","abcd","x","y","z");
         # "abcd"

         $foo = pack("aaaa","abcd","x","y","z");
         # "axyz"

         $foo = pack("a14","abcdefg");
         # "abcdefg\0\0\0\0\0\0\0"

         $foo = pack("i9pl", gmtime);
         # a real struct tm (on my system anyway)

         $utmp_template = "Z8 Z8 Z16 L";
         $utmp = pack($utmp_template, @utmp1);
         # a struct utmp (BSDish)


         @utmp2 = unpack($utmp_template, $utmp);
         # "@utmp1" eq "@utmp2"

         sub bintodec {
             unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
         }

     The same template may generally also be used in unpack(). 

