NAME

Fmt_Convert − Package for converting data from one byte-order/alignment format to another. 

SYNOPSIS

#include <fmt.h>
int
Fmt_Convert(contents, inFormat, inSizePtr, inBuffer, outFormat, outSizePtr, outBuffer)
int
Fmt_Size(contents, inFormat, inSizePtr, outFormat, outSizePtr)

ARGUMENTS

char ∗contents   (in) String describing contents of inBuffer (see below). 

Fmt_Format inFormat   (in) Byte-order/alignment format of data in inBuffer. 

int ∗inSizePtr   (in/out) Points to size of inBuffer.  Upon return ∗inSizePtr is the number of bytes actually used. 

char ∗inBuffer   (in) Data to be converted. 

Fmt_Format outFormat   (in) Byte-order/alignment format of data in outBuffer. 

int ∗outSizePtr   (in/out) Points to size of outBuffer.  Upon return ∗outSizePtr contains the number of bytes actually used. For Fmt_Size this is strictly an out parameter. 

char ∗outBuffer   (in) Converted data. 
 

DESCRIPTION

Fmt_Convert converts data between different byte-order/alignment formats. Typically this is done between different machine types, but it can be used to convert between two compilers that align data differently.  InFormat specifies the byte-order/alignment format of the data in inBuffer, and outFormat specifies the byte-order/alignment format of the data in outBuffer after the conversion.  The data to be converted is read from inBuffer and the converted data is written to outBuffer.  The parameter inSizePtr points to the size of the input buffer.  When Fmt_Convert returns ∗inSizePtr contains the number of bytes that were actually used.  It is possible for less than the entire buffer to be converted depending upon the contents string.  See below for more details on contents.  The parameter outSizePtr points to the size of the output buffer.  When Fmt_Convert returns ∗outSizePtr contains the number of bytes actually used. 

Fmt_Size computes the minimum size output buffer needed converting the data at described by the contents string The result is returned in ∗outSizePtr.  This size can then be passed to Fmt_Convert (assuming that the format and contents parameters remain the same). 
 
The legal values for the format parameters are defined in fmt.h. They are as follows:

FMT_68K_FORMAT
The byte-order/alignment format of code compiled by Gcc for Motorola 680x0 machines. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains the most significant byte. Halfwords, words and doublewords are aligned on even boundaries. The alignment of structures and unions equals the most restrictive alignment of one of their members, such that they are at least aligned on an even boundary. The size of structures and unions is a multiple of their alignment.

FMT_VAX_FORMAT
The byte-order/alignment format of the Vax. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains the least significant byte. Halfwords are aligned on even boundaries. Words and doublewords are aligned on word boundaries. The alignment of structures and unions equals the most restrictive alignment of one of their members. The size of structures and unions is a multiple of their alignment.

FMT_SPUR_FORMAT
The byte-order/alignment format of code compiled by Gcc for the Spur. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains the least significant byte. Halfwords are aligned on even boundaries, words are aligned on quad boundaries, and doublewords are aligned on oct boundaries. The alignment of structures and unions equals the most restrictive alignment of one of their members, such that they are at least aligned on a quad boundary. The size of structures and unions is a multiple of their alignment.

FMT_SPARC_FORMAT
The byte-order/alignment format of code compiled by the SunOS compiler for the Sparc architecture. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains the most significant byte. Halfwords are aligned on even boundaries, words are aligned on quad boundaries, and doublewords are aligned on oct boundaries. The alignment of structures and unions equals the most restrictive alignment of one of their members. The size of structures and unions is a multiple of their alignment.

FMT_MIPS_FORMAT
The byte-order/alignment format of code compiled by the Ultrix compiler for the Mips (DecStation3100) architecture. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains the least significant byte. Halfwords are aligned on even boundaries, words are aligned on quad boundaries, and doublewords are aligned on oct boundaries. The alignment of structures and unions equals the most restrictive alignment of one of their members. The size of structures and unions is a multiple of their alignment.

FMT_MY_FORMAT
This format is set to the format of the machine on which the code is running. This relieves the program that is using the Fmt package from having to decide with format is appropriate for a particular machine. 

The contents parameter is used to describe the data types that comprise the input buffer. The buffer can contain bytes, halfwords (2 bytes), words (4 bytes), doublewords (8 bytes), structures, and unions.  These data types are represented in the contents string using the following characters. 

bOne byte. 

hOne halfword (2 bytes). 

wOne word (4 bytes). 

dOne double word (8 bytes). 

{The start of a structure. 

}The end of a structure. 

(The start of a union. The ’(’ must be followed by a discriminant that indicates which of the components of the union is to be converted.  The discriminant is a decimal number that gives the index of the component, starting at 0. 

)The end of a union. 

0-9∗A decimal number following a data type (byte, halfword, word, doubleword, structure, or union) indicates that the data type is repeated the given number of times. For instance, the string "w5" means that the input contains 5 consecutive words. There is an ambiguity that arises when describing the contents of a union. "w5" can either refer to one component of 5 words, or to 5 components of one word each.  The abiguity is resolved by having "w5" refer to one component of 5 words, and "wwwww" refer to 5 components of one word.  Similarly, "w∗" refers to one component (see next paragraph for description of the ’∗’ character). 

∗A ’∗’ means 1 or more repetitions of the previous data type. The number of repetitions is determined by the amount of data remaining in the input buffer. Care must be taken if the ’∗’ character is anything but the last character in the string. Certain formats place constraints on the sizes of unions and structures that may cause the ’∗’ character to give unwanted results. For example, consider a structure consisting of a word followed by a byte that is defined as "{wb∗}".  In the Spur format "b∗" will refer to 4 bytes, while in the 68K format it will refer to 2 bytes. 
 

The following are examples of input data types and content strings.  Data: intfoo[5]; Content string: "w5" or "w∗" or "wwwww" Data: structflea{ char mite;  int spider;  int worm;  short moth;  short mosquito;  short beetle;  int fly[5];  char gnat[50];  }; Content string: "{bwwh3w5b∗}" Data: struct  foo{ char bar;  int baz;  union {  short quux;  double  cow;  } dog[6];  }; Content string: "{bw(0hd)6}" or "{bw(0hd)∗}"  if "quux" is the component of "dog" to be converted,
or,
"{bw(1hd)6}" or "{bw(1hd)∗}" if "cow" is the component of "dog" to be converted. 
 

RETURN VALUES

The following return codes are defined in fmt.h:

FMT_OK (0)
Procedure completed properly

FMT_CONTENT_ERROR
The contents parameter contained an error. 

FMT_INPUT_TOO_SMALL
The input buffer was smaller than indicated by contents. 

FMT_OUTPUT_TOO_SMALL
The output buffer was too small to hold the converted data. This is only returned by Fmt_Convert. 

FMT_ILLEGAL_FORMAT
One of the format parameters was illegal.

KEYWORDS

byte-order, byte-swap, alignment, data conversion
 

Sprite version 1.0  —  May 07, 1990