D.1.1 Platform-specific types, macros and functions

It’s sometimes necessary to provide nonstandard, platform-specific features to developers. The C library is traditionally the lowest library layer, so it makes sense for it to provide these low-level features. However, including these features in the C library may be a disadvantage if another package provides them as well as there will be two conflicting versions of them. Also, the features won’t be available to projects that do not use the GNU C Library but use other GNU tools, like GCC.

The current guidelines are:

• If the header file provides features that only make sense on a particular machine architecture and have nothing to do with an operating system, then the features should ultimately be provided as GCC built-in functions. Until then, the GNU C Library may provide them in the header file. When the GCC built-in functions become available, those provided in the header file should be made conditionally available prior to the GCC version in which the built-in function was made available.
• If the header file provides features that are specific to an operating system, both GCC and the GNU C Library could provide it, but the GNU C Library is preferred as it already has a lot of information about the operating system.
• If the header file provides features that are specific to an operating system but used by the GNU C Library, then the GNU C Library should provide them.

The general solution for providing low-level features is to export them as follows:

• A nonstandard, low-level header file that defines macros and inline functions should be called sys/platform/name.h.
• Each header file’s name should include the platform name, to avoid users thinking there is anything in common between different the header files for different platforms. For example, a sys/platform/arch.h name such as sys/platform/ppc.h is better than sys/platform.h.
• A platform-specific header file provided by the GNU C Library should coordinate with GCC such that compiler built-in versions of the functions and macros are preferred if available. This means that user programs will only ever need to include sys/platform/arch.h, keeping the same names of types, macros, and functions for convenience and portability.
• Each included symbol must have the prefix __arch_, such as __ppc_get_timebase.

The easiest way to provide a header file is to add it to the sysdep_headers variable. For example, the combination of Linux-specific header files on PowerPC could be provided like this:

sysdep_headers += sys/platform/ppc.h

Then ensure that you have added a sys/platform/ppc.h header file in the machine-specific directory, e.g., sysdeps/powerpc/sys/platform/ppc.h.