Endianness.h File Reference

Provides definitions of the ENDIANNESS of the target machine. The symbols ENDIANNESS_IS_LITTLE and ENDIANNESS_IS_BIG should be used in preprocessing directives to determine the endianness of the machine, while the symbol ENDIANNESS can be more easily used in 'C' code. More...

Defines
#define	ENDIANNESS_K_UNKNOWN   0
	Value of ENDIANNESS the endianness of the target is undefined.
#define	ENDIANNESS_K_LITTLE   1
	Value of ENDIANNESS if the target is a little endian machine.
#define	ENDIANNESS_K_BIG   2
	Value of ENDIANNESS if the target is a big endian machine machine.
#define	ENDIANNESS   ENDIANNESS_K_UNKNOWN
	ENDINANESS assumes one of the values,
#define	ENDIANNESS_IS_LITTLE   ENDIANNESS_K_UNKNOWN
	Defined and set to a non-zero value, ENDIANNESS_K_LITTLE, if the target is a little endian machine.
#define	ENDIANNESS_IS_BIG   ENDIANNESS_K_UNKNOWN
	Defined and set to a non-zero value, ENDIANNESS_BIG, if the target is a big endian machine.

---

Detailed Description

Provides definitions of the ENDIANNESS of the target machine. The symbols ENDIANNESS_IS_LITTLE and ENDIANNESS_IS_BIG should be used in preprocessing directives to determine the endianness of the machine, while the symbol ENDIANNESS can be more easily used in 'C' code.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: Endianness.h,v 1.5 2011/03/24 20:50:58 apw Exp $

SYNOPSIS

One of two symbols are defined

• ENDIANNESS_IS_LITTLE
• ENDIANNESS_IS_BIG.

As a convenience to the programmer, an overall symbol, ENDIANNESS is also defined. It will take on one of the three values.

• ENDIANNESS_K_UNKNOWN
• ENDIANNESS_K_LITTLE
• ENDIANNESS_K_BIG

USAGE

One should use this as follows

    #if   ENDIANNESS_IS_LITTLE

      / * Do little endian kind of things * /

    #elif ENDIANNESS_IS_BIG

      / * Do big endian kind of things * /

    #else

    #error _FILE_ Endianness not determined in this file

    #endif

It is recommended that both BIG and LITTLE conditions are tested for. This can save one from embarrassing typographical errors. For example, consider the consequences of the following

    #if ENDIANESS_IS_LITTLE

       / * Do little endian kind of things * /

    #else

       / * Do big endian kind of things * /

    #endif

It takes a keen eye to note the misspelling of ENDIANNESS_IS_LITTLE as ENDIANESS_IS_LITTLE. Since there is no such symbol as ENDIANESS_IS_LITTLE, the 'big' endian kind of things will always be done.

It is also recommended that one use #if preprocessor directive over the #ifdef form. Either works with the current implementation, but future implementations reserves the right to support only the #if form.

TARGET PLATFORMS

All FSW supported platforms.

---

Define Documentation

#define ENDIANNESS   ENDIANNESS_K_UNKNOWN

ENDINANESS assumes one of the values,

• ENDIANNESS_K_LITTLE
• ENDIANNESS_K_BIG
• ENDIANNESS_K_UNKNOWN.

Note:

Since DOXYGEN does not have access to the full set of compile time preprocessor symbols, ENDIANNESS will appear to be defined as ENDIANNESS_K_UNKNOWN.

Warning:

It is not recommended that this symbol be used in preprocessor directives to determine the endianness of the machine. Use ENDIANNESS_IS_LITTLE or ENDIANNESS_IS_BIG. Why? To do this correctly one must use the following long-winded style:

   if   defined (ENDIANNESS) && (ENDIANNESS == ENDIANNESS_K_LITTLE)
   {
      .
      .
   }
   elif defined (ENDIANNESS) && (ENDIANNESS == ENDIANNESS_K_BIG)
   {
      .
      .
   }
   else
   {
      .
      / * Endianness unknown * /
   }

The check for ENDIANNESS being defined is mandatory for robustness. If the user forgets to include <PBI/Endiannness.h>, all the ENDIANNESS symbols are, in fact, undefined. Without the check that ENDIANNESS is defined, the simple check of (ENDIANNESS == ENDIANNESS_K_LITTLE) will always succeed, causing the big endian if clause to always be taken. If the code is developed on a big endian machine, it is only when the code is ported to a little endian machine will the problem show up as malfunctioning code which the poor developer will eventually trace to the ill-constructed endianness determination.