---

1.5.4 Other portability assumptions made by Gnulib

Gnulib code makes the following assumptions that go beyond what C and POSIX require:

• Standard internal types like ptrdiff_t and size_t are no wider than long. The GNU coding standards allow code to make this assumption, POSIX requires implementations to support at least one programming environment where this is true, and such environments are recommended for Gnulib-using applications. When it is easy to port to non-POSIX platforms like MinGW where these types are wider than long, new Gnulib code should do so, e.g., by using ptrdiff_t instead of long. However, it is not always that easy, and no effort has been made to check that all Gnulib modules work on MinGW-like environments.
• int and unsigned int are at least 32 bits wide. POSIX and the GNU coding standards both require this.
• Signed integer arithmetic is two’s complement.

  Previously, Gnulib code sometimes also assumed that signed integer arithmetic wraps around, but modern compiler optimizations sometimes do not guarantee this, and Gnulib code with this assumption is now considered to be questionable. See Integer Properties.

  Although some Gnulib modules contain explicit support for ones’ complement and signed magnitude integer representations, which are allowed by C17 and earlier, these modules are the exception rather than the rule. All practical Gnulib targets use two’s complement, which is required by C23.

• There are no “holes” in integer values: all the bits of an integer contribute to its value in the usual way. In particular, an unsigned type and its signed counterpart have the same number of bits when you count the latter’s sign bit. (As an exception, Gnulib code is portable to CHERI platforms even though this assumption is false for CHERI.)
• Objects with all bits zero are treated as zero or as null pointers. For example, memset (A, 0, sizeof A) initializes an array A of pointers to null pointers.
• The types intptr_t and uintptr_t exist, and pointers can be converted to and from these types without loss of information.
• Addresses and sizes behave as if objects reside in a flat address space. In particular:
  • If two nonoverlapping objects have sizes S and T represented as ptrdiff_t or size_t values, then S + T cannot overflow.
  • A pointer P points within an object O if and only if (char *) &O <= (char *) P && (char *) P < (char *) (&O + 1).
  • Arithmetic on a valid pointer is equivalent to the same arithmetic on the pointer converted to uintptr_t, except that offsets are multiplied by the size of the pointed-to objects. For example, if P + I is a valid expression involving a pointer P and an integer I, then (uintptr_t) (P + I) == (uintptr_t) ((uintptr_t) P + I * sizeof *P). Similar arithmetic can be done with intptr_t, although more care must be taken in case of integer overflow or negative integers.
  • A pointer P has alignment A if and only if (uintptr_t) P % A is zero, and similarly for intptr_t.
  • If an existing object has size S, and if T is sufficiently small (e.g., 8 KiB), then S + T cannot overflow. Overflow in this case would mean that the rest of your program fits into T bytes, which can’t happen in realistic flat-address-space hosts.
  • Adding zero to a null pointer does not change the pointer. For example, 0 + (char *) NULL == (char *) NULL.

Some system platforms violate these assumptions and are therefore not Gnulib porting targets. See Unsupported Platforms.