]>
Commit | Line | Data |
---|---|---|
d35a6673 MK |
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 | .\" | |
93015253 | 6 | .\" %%%LICENSE_START(VERBATIM) |
d35a6673 MK |
7 | .\" Permission is granted to make and distribute verbatim copies of this |
8 | .\" manual provided the copyright notice and this permission notice are | |
9 | .\" preserved on all copies. | |
10 | .\" | |
11 | .\" Permission is granted to copy and distribute modified versions of this | |
12 | .\" manual under the conditions for verbatim copying, provided that the | |
13 | .\" entire resulting derived work is distributed under the terms of a | |
14 | .\" permission notice identical to this one. | |
15 | .\" | |
16 | .\" Since the Linux kernel and libraries are constantly changing, this | |
17 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
18 | .\" responsibility for errors or omissions, or for damages resulting from | |
19 | .\" the use of the information contained herein. The author(s) may not | |
20 | .\" have taken the same level of care in the production of this manual, | |
21 | .\" which is licensed free of charge, as they might when working | |
22 | .\" professionally. | |
23 | .\" | |
24 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
25 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 26 | .\" %%%LICENSE_END |
d35a6673 | 27 | .\" |
4b8c67d9 | 28 | .TH ENDIAN 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
d35a6673 MK |
29 | .SH NAME |
30 | htobe16, htole16, be16toh, le16toh, htobe32, htole32, be32toh, le32toh, | |
31 | htobe64, htole64, be64toh, le64toh \- | |
32 | convert values between host and big-/little-endian byte order | |
33 | .SH SYNOPSIS | |
34 | .nf | |
d35a6673 | 35 | .B #include <endian.h> |
dbfe9c70 | 36 | .PP |
d35a6673 MK |
37 | .BI "uint16_t htobe16(uint16_t " host_16bits ); |
38 | .BI "uint16_t htole16(uint16_t " host_16bits ); | |
39 | .BI "uint16_t be16toh(uint16_t " big_endian_16bits ); | |
40 | .BI "uint16_t le16toh(uint16_t " little_endian_16bits ); | |
dbfe9c70 | 41 | .PP |
d35a6673 MK |
42 | .BI "uint32_t htobe32(uint32_t " host_32bits ); |
43 | .BI "uint32_t htole32(uint32_t " host_32bits ); | |
44 | .BI "uint32_t be32toh(uint32_t " big_endian_32bits ); | |
45 | .BI "uint32_t le32toh(uint32_t " little_endian_32bits ); | |
dbfe9c70 | 46 | .PP |
d35a6673 MK |
47 | .BI "uint64_t htobe64(uint64_t " host_64bits ); |
48 | .BI "uint64_t htole64(uint64_t " host_64bits ); | |
49 | .BI "uint64_t be64toh(uint64_t " big_endian_64bits ); | |
50 | .BI "uint64_t le64toh(uint64_t " little_endian_64bits ); | |
51 | .fi | |
68e4db0a | 52 | .PP |
7f0ec8ee MK |
53 | .in -4n |
54 | Feature Test Macro Requirements for glibc (see | |
55 | .BR feature_test_macros (7)): | |
56 | .in | |
68e4db0a | 57 | .PP |
7f0ec8ee MK |
58 | .BR htobe16 (), |
59 | .BR htole16 (), | |
60 | .BR be16toh (), | |
61 | .BR le16toh (), | |
62 | .BR htobe32 (), | |
63 | .BR htole32 (), | |
64 | .BR be32toh (), | |
65 | .BR le32toh (), | |
66 | .BR htobe64 (), | |
67 | .BR htole64 (), | |
68 | .BR be64toh (), | |
69 | .BR le64toh (): | |
70 | .nf | |
71 | Since glibc 2.19: | |
72 | _DEFAULT_SOURCE | |
73 | In glibc up to and including 2.19: | |
74 | _BSD_SOURCE | |
75 | .fi | |
d35a6673 MK |
76 | .SH DESCRIPTION |
77 | These functions convert the byte encoding of integer values from | |
78 | the byte order that the current CPU (the "host") uses, | |
79 | to and from little-endian and big-endian byte order. | |
847e0d88 | 80 | .PP |
d35a6673 MK |
81 | The number, |
82 | .IR nn , | |
83 | in the name of each function indicates the size of | |
84 | integer handled by the function, either 16, 32, or 64 bits. | |
847e0d88 | 85 | .PP |
d35a6673 MK |
86 | The functions with names of the form "htobe\fInn\fP" convert |
87 | from host byte order to big-endian order. | |
847e0d88 | 88 | .PP |
d35a6673 MK |
89 | The functions with names of the form "htole\fInn\fP" convert |
90 | from host byte order to little-endian order. | |
847e0d88 | 91 | .PP |
d35a6673 MK |
92 | The functions with names of the form "be\fInn\fPtoh" convert |
93 | from big-endian order to host byte order. | |
847e0d88 | 94 | .PP |
d35a6673 MK |
95 | The functions with names of the form "le\fInn\fPtoh" convert |
96 | from little-endian order to host byte order. | |
97 | .SH VERSIONS | |
d95470fe | 98 | These functions were added to glibc in version 2.9. |
47297adb | 99 | .SH CONFORMING TO |
c8f2dd47 | 100 | These functions are nonstandard. |
373d0736 | 101 | Similar functions are present on the BSDs, |
d35a6673 MK |
102 | where the required header file is |
103 | .I <sys/endian.h> | |
104 | instead of | |
105 | .IR <endian.h> . | |
373d0736 MK |
106 | Unfortunately, |
107 | NetBSD, FreeBSD, and glibc haven't followed the original | |
108 | OpenBSD naming convention for these functions, | |
109 | whereby the | |
110 | .I nn | |
111 | component always appears at the end of the function name | |
112 | (thus, for example, in NetBSD, FreeBSD, and glibc, | |
113 | the equivalent of OpenBSDs "betoh32" is "be32toh"). | |
d35a6673 MK |
114 | .SH NOTES |
115 | These functions are similar to the older | |
116 | .BR byteorder (3) | |
117 | family of functions. | |
118 | For example, | |
119 | .BR be32toh () | |
120 | is identical to | |
f781a5b1 | 121 | .BR ntohl (). |
847e0d88 | 122 | .PP |
d35a6673 MK |
123 | The advantage of the |
124 | .BR byteorder (3) | |
125 | functions is that they are standard functions available | |
008f1ecc | 126 | on all UNIX systems. |
d35a6673 MK |
127 | On the other hand, the fact that they were designed |
128 | for use in the context of TCP/IP means that | |
129 | they lack the 64-bit and little-endian variants described in this page. | |
130 | .SH EXAMPLE | |
131 | The program below display the results of converting an integer | |
132 | from host byte order to both little-endian and big-endian byte order. | |
133 | Since host byte order is either little-endian or big-endian, | |
134 | only one of these conversions will have an effect. | |
135 | When we run this program on a little-endian system such as x86-32, | |
136 | we see the following: | |
e646a1ba | 137 | .PP |
d35a6673 | 138 | .in +4n |
e646a1ba | 139 | .EX |
d35a6673 MK |
140 | $ \fB./a.out\fP |
141 | x.u32 = 0x44332211 | |
142 | htole32(x.u32) = 0x44332211 | |
143 | htobe32(x.u32) = 0x11223344 | |
b8302363 | 144 | .EE |
d35a6673 MK |
145 | .in |
146 | .SS Program source | |
147 | \& | |
e7d0bb47 | 148 | .EX |
d35a6673 MK |
149 | #include <endian.h> |
150 | #include <stdint.h> | |
151 | #include <stdio.h> | |
152 | #include <stdlib.h> | |
153 | ||
154 | int | |
155 | main(int argc, char *argv[]) | |
156 | { | |
157 | union { | |
5a6194a4 MK |
158 | uint32_t u32; |
159 | uint8_t arr[4]; | |
d35a6673 MK |
160 | } x; |
161 | ||
162 | x.arr[0] = 0x11; /* Lowest-address byte */ | |
163 | x.arr[1] = 0x22; | |
164 | x.arr[2] = 0x33; | |
165 | x.arr[3] = 0x44; /* Highest-address byte */ | |
166 | ||
167 | printf("x.u32 = 0x%x\\n", x.u32); | |
168 | printf("htole32(x.u32) = 0x%x\\n", htole32(x.u32)); | |
169 | printf("htobe32(x.u32) = 0x%x\\n", htobe32(x.u32)); | |
170 | ||
171 | exit(EXIT_SUCCESS); | |
172 | } | |
e7d0bb47 | 173 | .EE |
47297adb | 174 | .SH SEE ALSO |
cdff989b | 175 | .BR bswap (3), |
d35a6673 | 176 | .BR byteorder (3) |