Debian Codegraph @

upstream/debian-unstable/man3/endian.3

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