--- name: "VistaIOPackData" section: "3" platform: "linux" package: "libvistaio-dev" version: "1.2.19-3+b2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/VistaIOPackData" --- # VistaIOPackData(3) pack or unpack a vector of values ## 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 \** **Adaption to vistaio: Gert Wollny \**