Internal compatibility utilities

There are several sets of compatibility utilities within Cahute, playing different roles, and offering a different set of possibilities:

  • <cahute/cdefs.h> defines portability utilities that are also used in the public headers to the library. They must be usable by any compiler using the already compiled library, even if the library has been compiled using a different compiler (or the same compiler using different settings).

    Therefore, it can’t use macros only defined at compile time by CMake, e.g. to determine the size of a type, since it may vary later when using a different compiler.

  • <compat.h> defines portability utilities that are only used within the library or the command-line utilities.

    Since in a given build setup, CMake should only use one compiler, this part is allowed to use macros defined at compile time by CMake.

  • lib/internals.h also contain portability utilities, including the endianness-related functions, that are only used within the library (and not within the command-line utilities).

This file references the internal macros and types defined for compatibility here. For the public ones, see <cahute/cdefs.h> – Basic definitions for Cahute.

Macro definitions

CAHUTE_LOCAL(TYPE)

Macro to use in Cahute function definitions, surrounding the return type, as opposed to CAHUTE_EXTERN. For example:

CAHUTE_LOCAL(int) my_local_utility(int arg1, char const *arg2);

For now, this only produces the following output:

static int my_local_utility(int arg1, char const *arg2);
CAHUTE_INLINE(TYPE)

Macro to use in inlinable local Cahute function definitions, surrounding the return type. This macro extends on CAHUTE_LOCAL’s meaning, by making the function inlinable if the compiler is so inclined.

For example:

CAHUTE_INLINE(int) my_tiny_utility(int arg1, char const *arg2);

This can then use compiler-specific functions, such as GCC’s always_inline attribute; see GCC function attributes for more information.

CAHUTE_LOCAL_DATA(TYPE)

Macro to use in local data in Cahute source files, surrounding the variable type, for example:

CAHUTE_LOCAL_DATA(char const *) my_string = "hello, world";

For now, this only produces the following output:

static char const * my_string = "hello, world";
CAHUTE_SSIZE_MAX

Maximum value for cahute_ssize, i.e. portable version of SSIZE_MAX for platforms that do not explicitely define an ssize_t type.

CAHUTE_UINTPTR_MAX

Maximum value for cahute_uintptr, i.e. portable version of UINTPTR_MAX for platforms that do not explicitely define an uintptr_t type.

CAHUTE_PRIu16

printf specifier for displaying cahute_u16 in decimal form, e.g. hu.

CAHUTE_PRIu32

printf specifier for displaying cahute_u32 in decimal form, e.g. u.

CAHUTE_PRIuSIZE

printf specifier for displaying size_t in decimal form, e.g. zu.

CAHUTE_PRIx16

printf specifier for displaying cahute_u16 in lowercase hexadecimal form, e.g. hx.

CAHUTE_PRIx32

printf specifier for displaying cahute_u32 in lowercase hexadecimal form, e.g. x.

CAHUTE_PRIxSIZE

printf specifier for displaying size_t in lowercase hexadecimal form, e.g. zx.

CAHUTE_PRIX16

printf specifier for displaying cahute_u16 in uppercase hexadecimal form, e.g. hX.

CAHUTE_PRIX32

printf specifier for displaying cahute_u32 in uppercase hexadecimal form, e.g. X.

CAHUTE_PRIXSIZE

printf specifier for displaying size_t in uppercase hexadecimal form, e.g. zX.

Type definitions

type cahute_uintptr

Portable definition of uintptr_t.

This type is required since uintptr_t may not be defined on all platforms, e.g. on Windows where UINT_PTR is defined in a specific header.

Due to namespace constraints, the name of this type cannot include a _t suffix; see Namespace for more information.

type cahute_ssize

Portable definition of ssize_t.

This type is required since ssize_t may not be defined on all platforms, e.g. on Windows where SSIZE_T is defined in a specific header.

Due to namespace constraints, the name of this type cannot include a _t suffix; see Namespace for more information.

type cahute_i8

Signed 8-bit integer type.

type cahute_u16

Unsigned 16-bit integer type.

Available printf specifiers for this type are CAHUTE_PRIu16, CAHUTE_PRIx16 and CAHUTE_PRIX16.

type cahute_i16

Signed 16-bit integer type.

type cahute_u32

Unsigned 32-bit integer type.

Available printf specifiers for this type are CAHUTE_PRIu32, CAHUTE_PRIx32 and CAHUTE_PRIX32.

type cahute_i32

Signed 32-bit integer type.

Function declarations

Warning

These utilities are only available to the library, and not to the command-line utilities.

cahute_u16 cahute_be16toh(cahute_u16 value)

Convert a 16-bit unsigned integer from big endian to host endianness.

Parameters:

  • value – 16-bit unsigned integer in big endian.

Returns:

16-bit unsigned integer in host endianness.

cahute_u16 cahute_le16toh(cahute_u16 value)

Convert a 16-bit unsigned integer from little endian to host endianness.

Parameters:

  • value – 16-bit unsigned integer in little endian.

Returns:

16-bit unsigned integer in host endianness.

cahute_u32 cahute_be32toh(cahute_u32 value)

Convert a 32-bit unsigned integer from big endian to host endianness.

Parameters:

  • value – 32-bit unsigned integer in big endian.

Returns:

32-bit unsigned integer in host endianness.

cahute_u32 cahute_le32toh(cahute_u32 value)

Convert a 32-bit unsigned integer from little endian to host endianness.

Parameters:

  • value – 32-bit unsigned integer in little endian.

Returns:

32-bit unsigned integer in host endianness.

cahute_u16 cahute_htobe16(cahute_u16 value)

Convert a 16-bit unsigned integer from host endianness to big endian.

Parameters:

  • value – 16-bit unsigned integer in host endianness.

Returns:

16-bit unsigned integer in big endian.

cahute_u16 cahute_htole16(cahute_u16 value)

Convert a 16-bit unsigned integer from host endianness to little endian.

Parameters:

  • value – 16-bit unsigned integer in host endianness.

Returns:

16-bit unsigned integer in little endian.

cahute_u32 cahute_htobe32(cahute_u32 value)

Convert a 32-bit unsigned integer from host endianness to big endian.

Parameters:

  • value – 32-bit unsigned integer in host endianness.

Returns:

32-bit unsigned integer in big endian.

cahute_u32 cahute_htole32(cahute_u32 value)

Convert a 32-bit unsigned integer from host endianness to little endian.

Parameters:

  • value – 32-bit unsigned integer in host endianness.

Returns:

32-bit unsigned integer in little endian.