Swap — C Library Procedures

NAME

Swap_Buffer − Do byte-swapping and alignment of data buffers
Swap_BufSize − Calculate the necessary buffer size to hold swapped and aligned data

SYNOPSIS

#include <swapBuffer.h> void Swap_Buffer(inBuf, inSize, inType, outType, format, outBuf, outSizePtr) void Swap_BufSize(inBuf, inSize, inType, outType, format, outSizePtr)

ARGUMENTS

char ∗inBuf (in) In-coming data buffer

int inSize (in) Size in bytes of inBuf

int inType (in) Type of byte-order and alignment of data in inBuf

int outType (in) Type of byte-order and alignment of data in outBuf

char ∗format (in) String describing format of data in inBuf (see below for more details)

char ∗outBuf (out) Buffer in which to put out-going swapped and aligned data

int ∗outSizePtr (in/out) outSizePtr is an in/out parameter for Swap_Buffer(), but just an out parameter for Swap_BufSize(). See below for its use in Swap_Buffer() and Swap_BufSize().

DESCRIPTION

These routines are obsolete. See Fmt instead.

Swap_Buffer() takes a buffer of data (inBuf) from one machine byte-order and alignment type (inType) and produces an output buffer (outBuf) of the same data swapped and aligned to conform to a different machine byte-order and alignment type (outType). The parameter outSizePtr is an in/out parameter to Swap_Buffer(). In a call to Swap_Buffer(), ∗outSizePtr should contain the size in bytes of the buffer parameter outBuf. As Swap_Buffer() returns, ∗outSizePtr contains the actual size of the swapped and aligned data. If the return value of ∗outSizePtr is larger than its input value, then Swap_Buffer() needed more buffer space for the out-going data than outBuf provided. In this case, Swap_Buffer() stops swapping the data and instead calculates the amount of space in bytes that it needs. It returns that value in ∗outSizePtr. If ∗outSizePtr returns with a 0 value, then an error occurred, such as the format argument contained unrecognizable characters or contained a ’∗’ character in a position other than the last character (see description of format string, below), or the sizes of the format string or inBuf weren’t compatible. In the case of an error, if Swap_Buffer() is called from a user process, it will panic with an error string explaining the problem. If called in the kernel, it will print a warning-level system error message and return.

Swap_BufSize() calculates the size required for the outBuf parameter to Swap_Buffer() given the same input data (inBuf), byte-ordering types (inType and outType), and the same data format (format). It returns this calculated value in ∗outSizePtr. If ∗outSizePtr returns with a zero, then an error occurred. (See the errors listed above for Swap_Buffer() for details.) Different machines have different alignment (and thus padding) requirements, and this is why the size of the out-going data may be different from the size of the in-coming data.

The format string (format) must describe the configuration of the data in the input buffer, inBuf. The data can contain bytes, half-words (4 bytes), words (8 bytes) and double-words (16 bytes).

The format string describes these data types as follows:

’b’The character ’b’ stands for a byte value (1 byte).

’h’The character ’h’ stands for a half-word (2 bytes).

’w’The character ’w’ stands for a word (4 bytes).

’d’The character ’d’ stands for a double-word (8 bytes and not yet implemented).

’0’-’9’∗A number in ascii means that the previous value type (’b, ’h’, ’w’, or ’d’) is repeated the given number of times. For instance, the string "w88" means that inBuf contains 88 word values in a row.

´∗’A ’∗’ character means 1 or more occurrences of the previous value type. A ’∗’ can only appear at the end of a format string, since otherwise there’s no way to determine the actual number of repetitions of the previous value.

An example format string, "bwwh3w5b∗", would describe a buffer containing the structure struct flea { char mite; int spider; int worm; short moth; short mosquito; short beetle; int fly[5]; char gnat[50]; };

The machine byte-order and alignment types are defined in swapBuffer.h. Their names may change since complaints have been registered about the current names, but currently the types are as follows:

SWAP_SUN_TYPE
The byte-ordering and alignment of 68020’s. Looking at an integer as if it were an array of 4 bytes (char buf[4]), buf[0] contains the low byte, buf[3] contains the high byte, and half-words and words are aligned to half-word boundaries.

SWAP_VAX_TYPE
The byte-ordering and alignment of Vaxen. Looking at an integer as if it were an array of 4 bytes (char buf[4]), buf[0] contains the high byte, buf[3] contains the low byte, and half-words and words are aligned to half-word boundaries.

SWAP_SPUR_TYPE
The byte-ordering and alignment of the Spur machine. Looking at an integer as if it were an array of 4 bytes (char buf[4]), buf[0] contains the high byte, buf[3] contains the low byte. Half-words are half-word aligned and words are word aligned.

KEYWORDS

byte-order, byte-swap, padding, alignment