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.