PAD(3,L) AIX Technical Reference PAD(3,L)
-------------------------------------------------------------------------------
pad: sflip, sflipa, lflip, lflipa, get_howflip, PAD, PADOPEN, PADCLOSE
PURPOSE
Facilitate the exchange of binary data between processes in a heterogeneous
network.
LIBRARY
Standard C Library (libc.a)
SYNTAX
#include <sys/types.h>
#include <sys/param.h>
short sflip(s, howflip);
short s;
int howflip;
void sflipa(as, howflip, numshort);
short as[];
int howflip;
int numshort;
long lflip(l, howflip);
long l;
int howflip;
void lflipa(al, howflip, numlong);
long al[]
int howflip;
int numlong;
int get_howflip(CPU_code);
short CPU_code;
(The following padding routines are macros, NOT functions.)
PAD(decl, uname)
PADOPEN(stag)
PADCLOSE(stag, sname, uname)
DESCRIPTION
These macros and procedures facilitate the exchange of binary data between
processes in a heterogeneous network. They provide a framework which
application programs may use to allow non-ASCII data written by one process to
Processed November 7, 1990 PAD(3,L) 1
PAD(3,L) AIX Technical Reference PAD(3,L)
be read by another process, even if the two processes are not executing on the
same type of machine.
The need for this mechanism is several-fold. First, different C compilers may
have different alignment constraints for fields within a structure. For
instance, a C compiler for one CPU type may require that 32-bit fields begin on
a 32-bit boundary, while a C compiler for another type of CPU might allow a
32-bit field to begin on an 8-bit boundary. Such a difference could lead to
different structure sizes and field offsets for the same structure definition.
Programs can avoid these differences by defining the format of their data
structures more explicitly. One way is to define their structures using the
padding macros defined below. These macros will add padding characters between
fields where necessary so that the alignment constraint of all C compilers is
satisfied.
Second, different types of CPUs may have different byte orderings. That is,
the order in which 8-bit bytes are layed out inside 16- and 32-bit words varies
according to each machine's architecture. Processes which read binary data may
use the byte flipping routines declared above to reorder the bytes in 16- and
32-bit values to agree with the byte ordering of its own CPU.
Third, in addition to the unpadded structures described above, certain data
types may refer to different size objects when the same definitions are
compiled for different machines. This list includes 'int's', pointer types and
procedures. Therefore, a structure that includes any of these data types is
not portable and should not be used when writing data which is to be read by a
process on a different type of CPU.
Finally, floating point values do not have the same representation on all types
of CPUs. While it may be possible to write routines to convert between these
different formats, no such library routines are provided at this time.
PADDING MACROS
The following padding macros should be used inside all structure definitions
which define the format of non-character data written by one process which is
to be read by another process. If all of data being written is character data
(including 8-bit numeric data), no padding is necessary. If some of the data
is 16-bit or 32-bit data, all 8-bit and 16-bit data should be padded, and it is
recommended that 32-bit data also be padded.
There are two ways to pad fields within a structure. The first uses the
PADOPEN and PADCLOSE macros to surround a collection of like-size fields (each
8, 16, or 32 bits). The second uses the PAD macro to pad a single field.
The PADOPEN/PADCLOSE method has the advantage of providing a name for the
collection of like size fields (for use by the byte flipping routines) and,
therefore, it is easy to add a new field at a later time without modification
of those byte flipping routines.
Processed November 7, 1990 PAD(3,L) 2
PAD(3,L) AIX Technical Reference PAD(3,L)
The PAD macro has the advantage that the size of an object may easily be
changed (from 8 bits to 16 bits, for example) since there is no requirement
that like size fields appear together.
For example, if you wanted to write the following structure:
struct abc {
long along;
long blong;
short ashort;
short bshort[5];
short cshort;
char achar;
char bchar[6];
};
You could instead use the PADOPEN/PADCLOSE macros as follows to generate an
equivalent structure with the same field names. Note that the PADOPEN and
PADCLOSE are not followed by semicolons. Also, NUM_LABC, NUM_SABC and NUM_CABC
compute the number of long, shorts and chars, respectively. These values will
be used by the flipping routines.
struct abc {
PADOPEN(Labc)
long _along;
long _blong;
PADCLOSE(Labc, L1abc, L2abc)
#define along L2abc.L1abc._along
#define blong L2abc.L1abc._blong
#define NUM_LABC (sizeof (struct Labc) / sizeof (long))
PADOPEN(Sabc)
short _ashort;
short _bshort[5];
short _cshort;
PADCLOSE(Sabc, S1abc, S2abc)
#define ashort S2abc.S1abc._ashort
#define bshort S2abc.S1abc._bshort
#define cshort S2abc.S1abc._cshort
#define NUM_SABC (sizeof (struct Sabc) / sizeof (short))
PADOPEN(Cabc)
char _achar;
char _bchar[6];
PADCLOSE(Cabc, C1abc, C2abc)
#define achar C2abc.C1abc._achar
#define bchar C2abc.C1abc._bchar
#define NUM_CABC (sizeof (struct Cabc) / sizeof (char))
};
Processed November 7, 1990 PAD(3,L) 3
PAD(3,L) AIX Technical Reference PAD(3,L)
Alternatively, if you had a simpler structure where each field was no bigger
than 32 bits:
struct xyz {
short ashort;
char achar;
long along;
};
You could use the PAD macro and instead write the following. Again, note that
the PAD macro is not followed by a semicolon.
struct xyz {
PAD(short _ashort, xyz1)
PAD(char _achar, xyz2)
PAD(long _along, xyz3)
};
#define ashort xyz1._ashort
#define achar xyz2._achar
#define along xyz3._along
Below are the actual declarations for the padding arrays.
Processed November 7, 1990 PAD(3,L) 4
PAD(3,L) AIX Technical Reference PAD(3,L)
#define ALIGN_SZ (sizeof(align_t))
#define ALIGN_ROUND (ALIGN_SZ - 1)
/* PADOPEN -- begin a padded range of structure fields using tag
* 'stag'. */
#define PADOPEN(stag) \\
union { struct stag {
/* PADCLOSE -- end a padded range of structure fields.
* 'stag' should be the same tag used in the preceding PADOPEN.
* 'sname' and 'uname' should be unique names.
*/
#define PADCLOSE(stag, sname, uname) \\
} sname; \\
PADARRAY((struct stag), PADNAME) } uname;
/* PADARRAY -- generate an array declaration of a size such that
* the union of 'padobj' and this array will meet the heterogeneous
* structure size criterion.
*/
#define PADARRAY(padobj, arrayname) \\
align_t arrayname[(sizeof padobj + ALIGN_ROUND) / ALIGN_SZ];
/* PAD -- Surround declaration 'decl' with a union that also includes
* an align_t for padding.
*/
#define PAD(decl, uname) \\
union { decl; align_t PADNAME; } uname;
BYTE FLIPPING ROUTINES
The byte flipping routines should be used by a process that is reading binary
data, if that binary data may have been written by a process running on a
different type of CPU.
Character data (including 8-bit numeric data) need not be byte flipped. Only
16-bit (short) and 32-bit (long) values need to be flipped to convert from the
byte ordering of the writing site to the byte ordering of the reading site.
There are four flipping routines provided:
lflip Flips a long value, returning the result after flipping its argument.
Processed November 7, 1990 PAD(3,L) 5
PAD(3,L) AIX Technical Reference PAD(3,L)
sflip Flips a short value, returning the result after flipping its argument.
lflipa Flips in place an array of longs (or a structure, all of whose elements
are longs).
sflipa Flips in place an array of shorts (or a structure, all of whose elements
are shorts).
Each of these flipping routines takes a parameter howflip which indicates how
the bytes are to be reordered. This value may be obtained from the routine
get_howflip, to which the reading process must provide the CPU type code of the
site from which the data was written.
Note: It is assumed in the following that the reader is able to determine the
CPU type code for the CPU from which the data was written. This
information is needed so that the flipping routines know the byte
ordering of the writing site, and therefore how the bytes must be
reordered to conform to the byte ordering of the local site. Possible
ways that the CPU type code may be determined include:
o Explicitly recording this in the text of the application program.
o Deriving it from a site number or site name using one of the
routines described in sf. The site number or site name might, in
turn, be determined from the path name used to open the file or from
the site on which the file is stored.
Using the same examples as above, consider a process reading files whose
formats are described by the structures abc and xyz. The structure abc
was declared using the PADOPEN and PADCLOSE macros, while the structure
xyz was declared using the PAD macro. The reading process could look
like this:
struct abc abcbuf;
struct xyz xyzbuf;
read(fildes1, &abcbuf, sizeof abcbuf);
flipabc(&abcbuf);
read(fildes2, &xyzbuf, sizeof xyzbuf);
flipxyz(&xyzbuf);
Where the byte flipping routines flipabc and flipxyz might then be
defined:
Processed November 7, 1990 PAD(3,L) 6
PAD(3,L) AIX Technical Reference PAD(3,L)
flipabc(buf, writer)
struct abc *buf;
siteno_t writer;
{
short xcode = sfnum(writer)->sf_xcode;
int howflip = get_howflip(xcode);
lflipa((long *) &(buf->L2abc), howflip, NUM_LABC);
sflipa((short *) &(buf->S2abc), howflip, NUM_SABC);
}
flipxyz(buf)
struct xyz *buf;
short xcode;
{
int howflip = get_howflip(xcode);
buf->ashort = sflip(buf->ashort, howflip);
buf->along = lflip(buf->along, howflip);
}
RELATED INFORMATION
In this book: "getut: getutent, getutid, getutline, pututline, setutent,
endutent, utmpname."
Processed November 7, 1990 PAD(3,L) 7