posh.h File Reference

---

Detailed Description

Author:

Brian Hook

Version:

1.3

Header file for POSH, the Portable Open Source Harness project.

NOTE: Unlike most header files, this one is designed to be included multiple times, which is why it does not have the #ifndef/#define preamble.

POSH relies on environment specified preprocessor symbols in order to infer as much as possible about the target OS/architecture and the host compiler capabilities.

NOTE: POSH is simple and focused. It attempts to provide basic functionality and information, but it does NOT attempt to emulate missing functionality. I am also not willing to make POSH dirty and hackish to support truly ancient and/or outmoded and/or bizarre technologies such as non-ANSI compilers, systems with non-IEEE floating point formats, segmented 16-bit operating systems, etc.

Please refer to the accompanying HTML documentation or visit http://www.poshlib.org for more information on how to use POSH.

LICENSE:

Copyright (c) 2004, Brian Hook All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

The names of this package'ss contributors contributors may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Definition in file posh.h.

Go to the source code of this file.

Defines
#define	POSH_COMPILER_STRING   "Unknown compiler"
	string constant describing the compiler
#define	POSH_CPU_STRING   "Unknown" /* this is here for Doxygen's benefit */
	string constant describing the target CPU
#define	POSH_OS_STRING   "Embedded/Unknown"
#define	POSH_CDECL
#define	POSH_STDCALL
#define	POSH_FASTCALL
#define	POSH_DLL
	define this if your library is being built or used as a DLL
#define	POSH_BUILDING_LIB
	define this when actually building a library (as opposed to building an app).
#define	POSH_PUBLIC_API(rtype)   extern POSH_IMPORTEXPORT rtype
	use as a wrapper for all publicly exported functions and data
#define	POSH_ENDIAN_STRING   "big"
	String constant representation of the target's byte ordering.
#define	POSH_BIG_ENDIAN   1
	if defined, target CPU is big endian
#define	POSH_LITTLE_ENDIAN
	if defined, target CPU is little endian
#define	POSH_COMPILE_TIME_ASSERT(name, x)   typedef int _POSH_dummy_ ## name[(x) ? 1 : -1 ]
	Cross-platform compile time assertion macro that will cause a syntax error at compile time if the assertion 'x' is not true.
#define	POSH_64BIT_INTEGER
	indicates presence of compiler supported 64-bit integer types.
#define	POSH_I64_PRINTF_PREFIX
	Constant string suitable for use as a printf modifier, e.g.
#define	POSH_I64(x)
	Macro to make a constant signed 64-bit value.
#define	POSH_U64(x)
	Macro to make a constant unsigned 64-bit value.
#define	POSH_I64_MIN   POSH_I64(0x8000000000000000)
	Minimum value for a 64-bit signed integer.
#define	POSH_I64_MAX   POSH_I64(0x7FFFFFFFFFFFFFFF)
	Maximum value for a 64-bit signed integer.
#define	POSH_U64_MIN   POSH_U64(0)
	Minimum value for a 64-bit unsigned integer.
#define	POSH_U64_MAX   POSH_U64(0xFFFFFFFFFFFFFFFF)
	Maximum value for a 64-bit unsigned integer.
#define	POSH_FALSE   0
	used as a generic FALSE value
#define	POSH_TRUE   1
	used as a generic TRUE value
#define	POSH_BYTE_MIN   0
	Minimum value for a byte.
#define	POSH_BYTE_MAX   255
	Maximum value for an 8-bit unsigned value.
#define	POSH_I16_MIN   ( ( posh_i16_t ) 0x8000 )
	Minimum value for a byte.
#define	POSH_I16_MAX   ( ( posh_i16_t ) 0x7FFF )
	Maximum value for a 16-bit signed value.
#define	POSH_U16_MIN   0
	Minimum value for a 16-bit unsigned value.
#define	POSH_U16_MAX   ( ( posh_u16_t ) 0xFFFF )
	Maximum value for a 16-bit unsigned value.
#define	POSH_I32_MIN   ( ( posh_i32_t ) 0x80000000 )
	Minimum value for a 32-bit signed value.
#define	POSH_I32_MAX   ( ( posh_i32_t ) 0x7FFFFFFF )
	Maximum value for a 32-bit signed value.
#define	POSH_U32_MIN   0
	Minimum value for a 32-bit unsigned value.
#define	POSH_U32_MAX   ( ( posh_u32_t ) 0xFFFFFFFF )
	Maximum value for a 32-bit unsigned value.
#define	POSH_64BIT_POINTER
	Indicates the presence of 64-bit pointers.
#define	POSH_NO_FLOAT
	define this if you want to disable floating point support
#define	POSH_LittleU16(x)   (x)
	Convert native to 16-bit unsigned little-endian.
#define	POSH_LittleU32(x)   (x)
	Convert native to 32-bit unsigned little-endian.
#define	POSH_LittleI16(x)   (x)
	Convert native to 16-bit signed little-endian.
#define	POSH_LittleI32(x)   (x)
	Convert native to 32-bit signed little-endian.
#define	POSH_LittleU64(x)   (x)
	Convert native to 64-bit unsigned little-endian.
#define	POSH_LittleI64(x)   (x)
	Convert native to 64-bit signed little-endian.
#define	POSH_BigU16(x)   POSH_SwapU16(x)
	Convert native to 16-bit unsigned big-endian.
#define	POSH_BigU32(x)   POSH_SwapU32(x)
	Convert native to 32-bit unsigned big-endian.
#define	POSH_BigI16(x)   POSH_SwapI16(x)
	Convert native to 16-bit signed big-endian.
#define	POSH_BigI32(x)   POSH_SwapI32(x)
	Convert native to 32-bit signed big-endian.
#define	POSH_BigU64(x)   POSH_SwapU64(x)
	Convert native to 64-bit unsigned big-endian.
#define	POSH_BigI64(x)   POSH_SwapI64(x)
	Convert native to 64-bit signed big-endian.
Typedefs
typedef long long	posh_i64_t
	signed 64-bit integer
typedef unsigned long	posh_u64_t
	unsigned 64-bit integer
typedef int	posh_bool_t
	generic boolean value
typedef unsigned char	posh_byte_t
	native byte, possibly > 8-bits
typedef unsigned char	posh_u8_t
	unsigned 8-bit integer
typedef signed char	posh_i8_t
	signed 8-bit integer
typedef unsigned short	posh_u16_t
	unsigned 16-bit integer
typedef short	posh_i16_t
	signed 16-bit integer
typedef unsigned	posh_u32_t
	unsigned 32-bit integer
typedef int	posh_i32_t
	signed 32-bit integer
Functions
const char *	POSH_GetArchString (void)
	Returns a string describing this platform's basic attributes.
posh_u32_t	POSH_LittleFloatBits (float f)
posh_u32_t	POSH_BigFloatBits (float f)
	Extracts raw big-endian bits from a 32-bit floating point value.
float	POSH_FloatFromLittleBits (posh_u32_t bits)
	Creates a floating point number from little endian bits.
float	POSH_FloatFromBigBits (posh_u32_t bits)
	Creates a floating point number from big-endian bits.
void	POSH_DoubleBits (double d, posh_byte_t dst[8])
	Extracts raw, little-endian bit representation from a 64-bit double.
double	POSH_DoubleFromBits (const posh_byte_t src[8])
	Creates a double-precision, 64-bit floating point value from a set of raw, little-endian bits.
posh_u16_t	POSH_SwapU16 (posh_u16_t u)
	Byte swaps a 16-bit unsigned value.
posh_i16_t	POSH_SwapI16 (posh_i16_t u)
	Byte swaps a 16-bit signed value.
posh_u32_t	POSH_SwapU32 (posh_u32_t u)
	Byte swaps a 32-bit unsigned value.
posh_i32_t	POSH_SwapI32 (posh_i32_t u)
	Byte swaps a 32-bit signed value.
posh_u64_t	POSH_SwapU64 (posh_u64_t u)
	Byte swaps a 64-bit unsigned value.
posh_i64_t	POSH_SwapI64 (posh_i64_t u)
	Byte swaps a 64-bit signed value.
posh_u16_t *	POSH_WriteU16ToLittle (void *dst, posh_u16_t value)
	Writes an unsigned 16-bit value to a little endian buffer.
posh_i16_t *	POSH_WriteI16ToLittle (void *dst, posh_i16_t value)
	Writes a signed 16-bit value to a little endian buffer.
posh_u32_t *	POSH_WriteU32ToLittle (void *dst, posh_u32_t value)
	Writes an unsigned 32-bit value to a little endian buffer.
posh_i32_t *	POSH_WriteI32ToLittle (void *dst, posh_i32_t value)
	Writes a signed 32-bit value to a little endian buffer.
posh_u16_t *	POSH_WriteU16ToBig (void *dst, posh_u16_t value)
	Writes an unsigned 16-bit value to a big endian buffer.
posh_i16_t *	POSH_WriteI16ToBig (void *dst, posh_i16_t value)
	Writes a signed 16-bit value to a big endian buffer.
posh_u32_t *	POSH_WriteU32ToBig (void *dst, posh_u32_t value)
	Writes an unsigned 32-bit value to a big endian buffer.
posh_i32_t *	POSH_WriteI32ToBig (void *dst, posh_i32_t value)
	Writes a signed 32-bit value to a big endian buffer.
posh_u16_t	POSH_ReadU16FromLittle (const void *src)
	Reads an unsigned 16-bit value from a little-endian buffer.
posh_i16_t	POSH_ReadI16FromLittle (const void *src)
	Reads a signed 16-bit value from a little-endian buffer.
posh_u32_t	POSH_ReadU32FromLittle (const void *src)
	Reads an unsigned 32-bit value from a little-endian buffer.
posh_i32_t	POSH_ReadI32FromLittle (const void *src)
	Reads a signed 32-bit value from a little-endian buffer.
posh_u16_t	POSH_ReadU16FromBig (const void *src)
	Reads an unsigned 16-bit value from a big-endian buffer.
posh_i16_t	POSH_ReadI16FromBig (const void *src)
	Reads a signed 16-bit value from a big-endian buffer.
posh_u32_t	POSH_ReadU32FromBig (const void *src)
	Reads an unsigned 32-bit value from a big-endian buffer.
posh_i32_t	POSH_ReadI32FromBig (const void *src)
	Reads a signed 32-bit value from a big-endian buffer.
posh_u64_t *	POSH_WriteU64ToLittle (void *dst, posh_u64_t value)
	Writes an unsigned 64-bit value to a little-endian buffer.
posh_i64_t *	POSH_WriteI64ToLittle (void *dst, posh_i64_t value)
	Writes a signed 64-bit value to a little-endian buffer.
posh_u64_t *	POSH_WriteU64ToBig (void *dst, posh_u64_t value)
	Writes an unsigned 64-bit value to a big-endian buffer.
posh_i64_t *	POSH_WriteI64ToBig (void *dst, posh_i64_t value)
	Writes a signed 64-bit value to a big-endian buffer.
posh_u64_t	POSH_ReadU64FromLittle (const void *src)
	Reads an unsigned 64-bit value from a little-endian buffer.
posh_i64_t	POSH_ReadI64FromLittle (const void *src)
	Reads a signed 64-bit value from a little-endian buffer.
posh_u64_t	POSH_ReadU64FromBig (const void *src)
	Reads an unsigned 64-bit value from a big-endian buffer.
posh_i64_t	POSH_ReadI64FromBig (const void *src)
	Reads an signed 64-bit value from a big-endian buffer.

---

Define Documentation

#define POSH_64BIT_INTEGER

indicates presence of compiler supported 64-bit integer types. POSH defines this symbol if the underlying compiler supports 64-bit integer types. However, it does not indicate whether the actual hardware supports 64-bit integer operations natively, so this should not be used as a performance hint.

#define POSH_64BIT_POINTER

Indicates the presence of 64-bit pointers. POSH defines this symbol if the target platform supports 64-bit pointer types and, implicitly, 64-bit addressing. Note: Just because a pointer is 64-bits does NOT mean that you have a a full 64-bit address space. In practice on most platforms this may be true, but on some platforms, such as the Cray vector processors, this is not the case. Similarly, 32-bit pointers do not necessarily mean 32-bit address spaces, such as on early 68K processors that had a 24-bit address space.

---

Typedef Documentation

posh_i64_t

signed 64-bit integer This is a compiler specific type definition for a 64-bit signed integer type. On some platforms this may map to long, long long, __int64 or, in some cases, nothing at all. You can test for the presence of this type by seeing if POSH_64BIT_INTEGER is defined. Definition at line 702 of file posh.h. Referenced by POSH_ReadI64FromBig(), POSH_ReadI64FromLittle(), POSH_SwapI64(), POSH_WriteI64ToBig(), and POSH_WriteI64ToLittle().

posh_u64_t

unsigned 64-bit integer This is a compiler specific type definition for a 64-bit unsigned integer type. On some platforms this may map to unsigned long, unsigned long long, unsigned __int64 or, in some cases, nothing at all. You can test for the presence of this type by seeing if POSH_64BIT_INTEGER is defined. Definition at line 703 of file posh.h. Referenced by POSH_ReadU64FromBig(), POSH_ReadU64FromLittle(), POSH_SwapI64(), POSH_SwapU64(), POSH_WriteI64ToBig(), POSH_WriteI64ToLittle(), POSH_WriteU64ToBig(), and POSH_WriteU64ToLittle().

---

Function Documentation

const char* POSH_GetArchString (  void   )

Returns a string describing this platform's basic attributes. POSH_GetArchString() reports on an architecture's statically determined attributes. In addition, it will perform run-time verification checks to make sure the various platform specific functions work. If an error occurs, please contact me at poshlib@poshlib.org so we can try to resolve what the specific failure case is. Returns: a string describing this platform on success, or a string in the form "*ERROR: [text]" on failure. You can simply check to see if the first character returned is '*' to verify an error condition. Definition at line 237 of file posh.c.

posh_i64_t POSH_ReadI64FromBig (  const void *  src  )

Reads an signed 64-bit value from a big-endian buffer. Parameters: src  [in] source buffer Returns: host-endian signed 32-bit value Definition at line 818 of file posh.c. References posh_i64_t, and POSH_ReadU64FromBig().

posh_i64_t POSH_ReadI64FromLittle (  const void *  src  )

Reads a signed 64-bit value from a little-endian buffer. Parameters: src  [in] source buffer Returns: host-endian signed 32-bit value Definition at line 787 of file posh.c. References posh_i64_t, and POSH_ReadU64FromLittle().

posh_u64_t POSH_ReadU64FromBig (  const void *  src  )

Reads an unsigned 64-bit value from a big-endian buffer. Parameters: src  [in] source buffer Returns: host-endian unsigned 32-bit value Definition at line 798 of file posh.c. References posh_byte_t, and posh_u64_t. Referenced by POSH_ReadI64FromBig().

posh_u64_t POSH_ReadU64FromLittle (  const void *  src  )

Reads an unsigned 64-bit value from a little-endian buffer. Parameters: src  [in] source buffer Returns: host-endian unsigned 32-bit value Definition at line 767 of file posh.c. References posh_byte_t, and posh_u64_t. Referenced by POSH_ReadI64FromLittle().

---