bionic (3) VistaIOPackData.3.gz
NAME
VistaIOPackData, VistaIOUnpackData - pack or unpack a vector of values
SYNOPSIS
typedef enum { VistaIOLsbFirst, VistaIOMsbFirst } VistaIOPackOrder;
void VistaIOPackData (repn, nels, unpacked, order, plength, ppacked, palloced)
VistaIORepnKind repn;
size_t nels, *plength;
VistaIOPointer unpacked, *ppacked;
VistaIOPackOrder order;
VistaIOBoolean *palloced;
void VistaIOUnpackData (repn, nels, packed, order, plength, punpacked, palloced)
VistaIORepnKind repn;
size_t nels, *plength;
VistaIOPointer packed, *punpacked;
VistaIOPackOrder order;
VistaIOBoolean *palloced;
ARGUMENTS
repn Specifies the representation of the values to be packed or unpacked.
nels Specifies the number of values to be packed or unpacked.
unpacked Specifies the location of the values to be packed.
packed Specifies the location of the values to be unpacked.
order Specifies the order in which values smaller than a byte are packed into a single byte, or
values larger than a byte are split among multiple bytes.
plength Specifies and returns the length of the (un)packed data, in bytes. The length is rounded up to
the next whole byte.
ppacked Specifies or returns the location of the packed data.
punpacked Specifies or returns the location of the unpacked data.
palloced If NULL, specifies that a buffer is being supplied to contain the results of (un)packing.
Otherwise, returns TRUE if memory was allocated by the routine to contain the results, and
FALSE otherwise.
DESCRIPTION
VistaIOPackData packs a vector of values into a block of contiguous bytes. Typically, it is used when
preparing to output a series of values to a Vista data file. VistaIOUnpackData performs the inverse,
unpacking a vector of values from a block of contiguous bytes. It is used when decoding a series of
values read from a Vista data file.
Unpacked values reside in memory in a form dependent upon machine architecture. Packed values, on the
other hand, are represented in a machine-independent manner using the fewest bits possible. If the values
are of type VistaIOBit, for example, they might occupy one byte each in unpacked form, but in packed form
each occupies a single bit. The types of values that can be (un)packed, and their form when packed, is as
follows:
VistaIOBit is packed as a single bit.
VistaIOUByte
is packed as an unsigned integer in a single 8-bit byte.
VistaIOSByte
is packed as a two's-complement integer in a single 8-bit byte.
VistaIOShort
is packed as a two's-complement integer in two 8-bit bytes.
VistaIOLong is packed as a two's-complement integer in four 8-bit bytes.
VistaIOFloat
is packed as an IEEE-format floating-point number in four 8-bit bytes.
VistaIODouble
is packed as an IEEE-format floating-point number in eight 8-bit bytes.
VistaIOBoolean
is packed as a single bit.
The values to be (un)packed must all have one of these types, as specified by the repn argument.
The order argument specifies the order with which bits are packed into a byte, or multi-byte, packed
values are separated into bytes. If the packed values each require a single bit, order specifies whether
successive values are to be packed into a byte from least-significant bit to most significant
(VistaIOLsbFirst), or vice versa (VistaIOMsbFirst). If the packed values each require multiple bytes,
order specifies whether those bytes are to be packed from least-significant byte to most significant
(VistaIOLsbFirst), or vice versa (VistaIOMsbFirst). Data in Vista data files is packed with
order = VistaIOMsbFirst.
For a call to VistaIOPackData, nels specifies the number of values to be packed and unpacked points to a
vector containing them. You can specify where to place the packed values in either of two ways:
• You can supply your own buffer for the packed values by passing NULL in palloced, passing a pointer
to the address of your buffer in ppacked, and passing a pointer to the length of your buffer in
plength. On return, the actual length of the packed values will have been stored at *plength.
• You can let VistaIOPackData determine the location of the packed values by passing in palloced a
pointer to a VistaIOBoolean variable. VistaIOPackData then returns, via ppacked and plength, the
location and length of the packed data. Depending on the type of values to be packed, their
arrangement in memory, and order, actual packing may or may not be needed. That is, the packed and
unpacked forms of the value may actually be identical. In this case, the returned location and length
refer to the unpacked data, and palloced returns FALSE to indicate that no separate buffer for the
packed data was allocated. If, however, the packed form differs from the unpacked form,
VistaIOPackData will allocate memory for the packed data. The location and length of this memory are
returned instead, and palloced returns TRUE to indicate that this memory should be freed when the
packed values are no longer needed.
VistaIOUnpackData is called in an analogous manner. The nels argument specifies the number of values to
be unpacked and packed points to a vector containing them. As for VistaIOPackData, you can specify where
to place the unpacked values in either of two ways indicated by palloced.
RETURN VALUES
Both routines return TRUE if successful, and FALSE otherwise. In addition, they may set *plength,
*ppacked, *punpacked, and *palloced as described above.
EXAMPLES
Here we pack a vector of bits, write the packed bits to a file, and free any storage used to represent
the packed bits:
size_t nbits, length;
VistaIOBit *bits;
VistaIOPointer packed;
VistaIOBoolean alloced;
FILE *file;
...
VistaIOPackData (VistaIOBitRepn, nbits, bits, VistaIOMsbFirst, & length, & packed, & alloced);
fwrite ((char *) packed, 1, length, file);
if (alloced)
VistaIOFree (packed);
NOTES
Packing or unpacking can be done in place. For example, in a call to VistaIOPackData, unpacked and
*ppacked can point to the same storage.
LIMITATIONS
The present implementation cannot pack values of type VistaIOUByte, VistaIOSByte, VistaIOShort,
VistaIOLong, VistaIOFloat, or VistaIODouble if their packed and unpacked sizes differ.
DIAGNOSTICS
``Byte order not recognized.''
The routines trie to automatically detect whether the present machine stores multi-byte values
from most-to-least significant byte, or vice versa. If this message is issued it means that a port
to a new machine architecture was unsuccessful, in which case some additional programming is
needed to support the new architecture.
``Insufficient space for (un)packed data.''
A buffer was supplied for the results of (un)packing, but the buffer is too small.
``(Un)packing type from mbits to nbits bits is not supported.''
The present implementation cannot (un)pack values of type VistaIOUByte, VistaIOSByte,
VistaIOShort, VistaIOLong, VistaIOFloat, or VistaIODouble if their packed and unpacked sizes
differ. If asked to do so the routine will abort the program with this message.
AUTHOR
Art Pope <pope@cs.ubc.ca> Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>