man3/endian.3

   1 .\" Copyright (C) 2009, Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\" a few pieces remain from an earlier version
   4 .\" Copyright (C) 2008, Nanno Langstraat <nal@ii.nl>
   5 .\"
   6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   7 .\"
   8 .TH endian 3 (date) "Linux man-pages (unreleased)"
   9 .SH NAME
  10 htobe16, htole16, be16toh, le16toh, htobe32, htole32, be32toh, le32toh,
  11 htobe64, htole64, be64toh, le64toh \-
  12 convert values between host and big-/little-endian byte order
  13 .SH LIBRARY
  14 Standard C library
  15 .RI ( libc ", " \-lc )
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <endian.h>
  19 .P
  20 .BI "uint16_t htobe16(uint16_t " host_16bits );
  21 .BI "uint16_t htole16(uint16_t " host_16bits );
  22 .BI "uint16_t be16toh(uint16_t " big_endian_16bits );
  23 .BI "uint16_t le16toh(uint16_t " little_endian_16bits );
  24 .P
  25 .BI "uint32_t htobe32(uint32_t " host_32bits );
  26 .BI "uint32_t htole32(uint32_t " host_32bits );
  27 .BI "uint32_t be32toh(uint32_t " big_endian_32bits );
  28 .BI "uint32_t le32toh(uint32_t " little_endian_32bits );
  29 .P
  30 .BI "uint64_t htobe64(uint64_t " host_64bits );
  31 .BI "uint64_t htole64(uint64_t " host_64bits );
  32 .BI "uint64_t be64toh(uint64_t " big_endian_64bits );
  33 .BI "uint64_t le64toh(uint64_t " little_endian_64bits );
  34 .fi
  35 .P
  36 .RS -4
  37 Feature Test Macro Requirements for glibc (see
  38 .BR feature_test_macros (7)):
  39 .RE
  40 .ad l
  41 .P
  42 .BR htobe16 (),
  43 .BR htole16 (),
  44 .BR be16toh (),
  45 .BR le16toh (),
  46 .BR htobe32 (),
  47 .BR htole32 (),
  48 .BR be32toh (),
  49 .BR le32toh (),
  50 .BR htobe64 (),
  51 .BR htole64 (),
  52 .BR be64toh (),
  53 .BR le64toh ():
  54 .nf
  55     Since glibc 2.19:
  56         _DEFAULT_SOURCE
  57     In glibc up to and including 2.19:
  58         _BSD_SOURCE
  59 .fi
  60 .ad
  61 .SH DESCRIPTION
  62 These functions convert the byte encoding of integer values from
  63 the byte order that the current CPU (the "host") uses,
  64 to and from little-endian and big-endian byte order.
  65 .P
  66 The number,
  67 .IR nn ,
  68 in the name of each function indicates the size of
  69 integer handled by the function, either 16, 32, or 64 bits.
  70 .P
  71 The functions with names of the form "htobe\fInn\fP" convert
  72 from host byte order to big-endian order.
  73 .P
  74 The functions with names of the form "htole\fInn\fP" convert
  75 from host byte order to little-endian order.
  76 .P
  77 The functions with names of the form "be\fInn\fPtoh" convert
  78 from big-endian order to host byte order.
  79 .P
  80 The functions with names of the form "le\fInn\fPtoh" convert
  81 from little-endian order to host byte order.
  82 .SH VERSIONS
  83 Similar functions are present on the BSDs,
  84 where the required header file is
  85 .I <sys/endian.h>
  86 instead of
  87 .IR <endian.h> .
  88 Unfortunately,
  89 NetBSD, FreeBSD, and glibc haven't followed the original
  90 OpenBSD naming convention for these functions,
  91 whereby the
  92 .I nn
  93 component always appears at the end of the function name
  94 (thus, for example, in NetBSD, FreeBSD, and glibc,
  95 the equivalent of OpenBSDs "betoh32" is "be32toh").
  96 .SH STANDARDS
  97 None.
  98 .SH HISTORY
  99 glibc 2.9.
 100 .P
 101 These functions are similar to the older
 102 .BR byteorder (3)
 103 family of functions.
 104 For example,
 105 .BR be32toh ()
 106 is identical to
 107 .BR ntohl ().
 108 .P
 109 The advantage of the
 110 .BR byteorder (3)
 111 functions is that they are standard functions available
 112 on all UNIX systems.
 113 On the other hand, the fact that they were designed
 114 for use in the context of TCP/IP means that
 115 they lack the 64-bit and little-endian variants described in this page.
 116 .SH EXAMPLES
 117 The program below display the results of converting an integer
 118 from host byte order to both little-endian and big-endian byte order.
 119 Since host byte order is either little-endian or big-endian,
 120 only one of these conversions will have an effect.
 121 When we run this program on a little-endian system such as x86-32,
 122 we see the following:
 123 .P
 124 .in +4n
 125 .EX
 126 $ \fB./a.out\fP
 127 x.u32 = 0x44332211
 128 htole32(x.u32) = 0x44332211
 129 htobe32(x.u32) = 0x11223344
 130 .EE
 131 .in
 132 .SS Program source
 133 \&
 134 .\" SRC BEGIN (endian.c)
 135 .EX
 136 #include <endian.h>
 137 #include <stdint.h>
 138 #include <stdio.h>
 139 #include <stdlib.h>
 140 \&
 141 int
 142 main(void)
 143 {
 144     union {
 145         uint32_t u32;
 146         uint8_t arr[4];
 147     } x;
 148 \&
 149     x.arr[0] = 0x11;    /* Lowest\-address byte */
 150     x.arr[1] = 0x22;
 151     x.arr[2] = 0x33;
 152     x.arr[3] = 0x44;    /* Highest\-address byte */
 153 \&
 154     printf("x.u32 = %#x\en", x.u32);
 155     printf("htole32(x.u32) = %#x\en", htole32(x.u32));
 156     printf("htobe32(x.u32) = %#x\en", htobe32(x.u32));
 157 \&
 158     exit(EXIT_SUCCESS);
 159 }
 160 .EE
 161 .\" SRC END
 162 .SH SEE ALSO
 163 .BR bswap (3),
 164 .BR byteorder (3)