README.md

   1 # Description
   2
   3 A one-file public-domain library to determine endianness at compile time.
   4 Just drop a copy of the header in your source tree, use it and forget about all
   5 the platform-specific differences to get that endianess definition!
   6
   7 The usual conversion functions are also provided.
   8
   9 # Rationale
  10
  11 If someone needs to know the endianess at compile time, there are 2 different
  12 use cases:
  13
  14 - in some rare cases one needs to know the endianess to lay out structs and the
  15   like, for example an RGB union; or directly in the code.
  16
  17 - in 99% of the cases, just a conversion from one endian to the other is needed,
  18   e.g. when a protocol defines that a value is stored in a specific endianness.
  19
  20 # Use case 1 - compile time endianness detecion macro
  21
  22 The header tries its best to determine the endianess from a number of possible
  23 sources, and if successful, defines both `ENDIANNESS_LE` and `ENDIANNESS_BE`
  24 macros to 0 or 1.
  25
  26 ```C
  27 #include "endianness.h"
  28 #if ENDIANNESS_LE +0 == 1
  29 /* Little Endian code here */
  30 #elif ENDIANNESS_BE +0 == 1
  31 /* Big Endian code here */
  32 #endif
  33 ```
  34
  35 or if the macro is to be used directly from the code, you can even use the nicer
  36 form (taking advantage of dead code elimination done by the compiler):
  37
  38 ```C
  39 if (ENDIANNESS_LE) {
  40     ...
  41 } else {
  42     ...
  43 }
  44 ```
  45
  46 Note that on very exotic platforms, the detection may fail. The header then
  47 throws an error and tells the user to define the macros by hand (and report the
  48 system here so we can get it fixed).
  49 However, if your use case is just conversion, there's a way to avoid erroring
  50 out. Read on!
  51
  52 # Use case 2 - endian conversion
  53
  54 In the majority of use cases, one wants just to convert from little to big
  55 endian, and vice versa (or actually to and from host endianness!).
  56
  57 The provided endian conversion functions/macros start with the `end_` prefix.
  58
  59 ```
  60 end_htobe16(x)  // Host to Big Endian 16
  61 end_be16toh(x)
  62 end_htobe32(x)
  63 end_be32toh(x)  // Big Endian 32 to Host
  64 end_htobe64(x)
  65 end_be64toh(x)
  66 end_htole16(x)
  67 end_le16toh(x)
  68 end_htole32(x)  // Host to Little Endian 32
  69 end_le32toh(x)
  70 end_htole64(x)
  71 end_le64toh(x)  // Little Endian 64 to Host
  72 ```
  73
  74 For conversion of network byte order (big endian) to host order:
  75 ```
  76 end_ntoh16(x)  // equivalent of ntohs(x) from <netinet/in.h>
  77 end_hton16(x)  //               htons(x)
  78 end_ntoh32(x)  //               ntohl(x)
  79 end_hton32(x)  //               htonl(x)
  80 end_ntoh64(x)
  81 end_hton64(x)
  82 ```
  83
  84 General purpose byteswap functions:
  85 ```
  86 end_bswap16(x)
  87 end_bswap32(x)
  88 end_bswap64(x)
  89 ```
  90
  91 In case the endianness detection failed and you need only those conversions,
  92 you can avoid erroring out by defining `ENDIANNESS_PORTABLE_CONVERSION` prior to
  93 including the header:
  94
  95 ```C
  96 #define ENDIANNESS_PORTABLE_CONVERSION
  97 #include "endianness.h"
  98 ```
  99
 100 That way, the code will fallback to a slightly slower, but portable version of
 101 the conversion functions. On modern compilers like GCC 8.0 these compile into
 102 a single move and a byteswap instruction.
 103
 104 However, if `ENDIANNESS_PORTABLE_CONVERSION` is in use, there's no guarantee
 105 that the macros for use case 1 will be defined!
 106
 107 # License
 108
 109 This file is published under the public domain. In case the concept of
 110 public domain does not exist under your jurisdiction, you can consider it
 111 to be dual licensed under the [MIT](https://opensource.org/licenses/MIT),
 112 [Apache](https://www.apache.org/licenses/LICENSE-2.0) and
 113 [WTFPL](http://www.wtfpl.net/about/) licenses.
 114
 115 # Contribution
 116
 117 If you notice an issue on a platform you're using, feel free to open a PR or
 118 issue on the Github repository https://github.com/rofl0r/endianness.h .
 119
 120 # Appendix A: Methodology used to detect endianness
 121
 122 The header first tries to use the macro `__BYTE_ORDER__` which is built into
 123 all GCC versions >= 4.6 and all clang versions >= 3.1. Recent ICC versions
 124 also support it.
 125 As GCC 4.6.0 was released in 2011, this should already cover the vast majority
 126 of available toolchains for UNIX platforms and other platforms targetted by
 127 GCC/Clang, such as mingw.
 128
 129 If that fails, a number of CPU-specific macros is tested.
 130 The list was assembled carefully by looking at built-in macros for compilers
 131 targeting all platforms supported by musl libc (which includes e.g.
 132 `powerpc`, `mips`, `arm`, `aarch64`, `microblaze` and many others), but also
 133 by looking at predefined macros for compilers like MSVC and others.
 134 For architectures that support both little and big endian configuration, we
 135 only test for them when a macro to detect the subarch, e.g. `mipsel` exists,
 136 in order to not produce wrong results.
 137 Older compilers targeting one such architecture, `avr`, don't provide a macro
 138 that could be used to determine the endianness, and even though 99% of users
 139 use avr in little-endian configuration, we do not hardcode that avr equals
 140 little endian.
 141
 142 If even this does not yield detection, we next try to open the header `endian.h`
 143 which is unfortunately not standardized and available in different locations
 144 in different Operating Systems. Here we use a list of OS detection macros to
 145 derive the correct location of endian.h and then use the macros it provides.
 146 Note that getting at this point requires that either a really old or a really
 147 exotic compiler is used, and that one targetting a really exotic architecture.
 148 If even this pass fails, we're dealing with an exotic compiler, an exotic
 149 architecture, and an exotic OS - most likely a bare-metal toolchain for
 150 embedded development.