| .\" Copyright (C) 2009, Linux Foundation, written by Michael Kerrisk |
| .\" <mtk.manpages@gmail.com> |
| .\" a few pieces remain from an earlier version |
| .\" Copyright (C) 2008, Nanno Langstraat <nal@ii.nl> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH ENDIAN 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| htobe16, htole16, be16toh, le16toh, htobe32, htole32, be32toh, le32toh, |
| htobe64, htole64, be64toh, le64toh \- |
| convert values between host and big-/little-endian byte order |
| .SH SYNOPSIS |
| .nf |
| .B #include <endian.h> |
| .PP |
| .BI "uint16_t htobe16(uint16_t " host_16bits ); |
| .BI "uint16_t htole16(uint16_t " host_16bits ); |
| .BI "uint16_t be16toh(uint16_t " big_endian_16bits ); |
| .BI "uint16_t le16toh(uint16_t " little_endian_16bits ); |
| .PP |
| .BI "uint32_t htobe32(uint32_t " host_32bits ); |
| .BI "uint32_t htole32(uint32_t " host_32bits ); |
| .BI "uint32_t be32toh(uint32_t " big_endian_32bits ); |
| .BI "uint32_t le32toh(uint32_t " little_endian_32bits ); |
| .PP |
| .BI "uint64_t htobe64(uint64_t " host_64bits ); |
| .BI "uint64_t htole64(uint64_t " host_64bits ); |
| .BI "uint64_t be64toh(uint64_t " big_endian_64bits ); |
| .BI "uint64_t le64toh(uint64_t " little_endian_64bits ); |
| .fi |
| .PP |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .BR htobe16 (), |
| .BR htole16 (), |
| .BR be16toh (), |
| .BR le16toh (), |
| .BR htobe32 (), |
| .BR htole32 (), |
| .BR be32toh (), |
| .BR le32toh (), |
| .BR htobe64 (), |
| .BR htole64 (), |
| .BR be64toh (), |
| .BR le64toh (): |
| .nf |
| Since glibc 2.19: |
| _DEFAULT_SOURCE |
| In glibc up to and including 2.19: |
| _BSD_SOURCE |
| .fi |
| .SH DESCRIPTION |
| These functions convert the byte encoding of integer values from |
| the byte order that the current CPU (the "host") uses, |
| to and from little-endian and big-endian byte order. |
| .PP |
| The number, |
| .IR nn , |
| in the name of each function indicates the size of |
| integer handled by the function, either 16, 32, or 64 bits. |
| .PP |
| The functions with names of the form "htobe\fInn\fP" convert |
| from host byte order to big-endian order. |
| .PP |
| The functions with names of the form "htole\fInn\fP" convert |
| from host byte order to little-endian order. |
| .PP |
| The functions with names of the form "be\fInn\fPtoh" convert |
| from big-endian order to host byte order. |
| .PP |
| The functions with names of the form "le\fInn\fPtoh" convert |
| from little-endian order to host byte order. |
| .SH VERSIONS |
| These functions were added to glibc in version 2.9. |
| .SH CONFORMING TO |
| These functions are nonstandard. |
| Similar functions are present on the BSDs, |
| where the required header file is |
| .I <sys/endian.h> |
| instead of |
| .IR <endian.h> . |
| Unfortunately, |
| NetBSD, FreeBSD, and glibc haven't followed the original |
| OpenBSD naming convention for these functions, |
| whereby the |
| .I nn |
| component always appears at the end of the function name |
| (thus, for example, in NetBSD, FreeBSD, and glibc, |
| the equivalent of OpenBSDs "betoh32" is "be32toh"). |
| .SH NOTES |
| These functions are similar to the older |
| .BR byteorder (3) |
| family of functions. |
| For example, |
| .BR be32toh () |
| is identical to |
| .BR ntohl (). |
| .PP |
| The advantage of the |
| .BR byteorder (3) |
| functions is that they are standard functions available |
| on all UNIX systems. |
| On the other hand, the fact that they were designed |
| for use in the context of TCP/IP means that |
| they lack the 64-bit and little-endian variants described in this page. |
| .SH EXAMPLE |
| The program below display the results of converting an integer |
| from host byte order to both little-endian and big-endian byte order. |
| Since host byte order is either little-endian or big-endian, |
| only one of these conversions will have an effect. |
| When we run this program on a little-endian system such as x86-32, |
| we see the following: |
| .PP |
| .in +4n |
| .EX |
| $ \fB./a.out\fP |
| x.u32 = 0x44332211 |
| htole32(x.u32) = 0x44332211 |
| htobe32(x.u32) = 0x11223344 |
| .EE |
| .in |
| .SS Program source |
| \& |
| .EX |
| #include <endian.h> |
| #include <stdint.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| |
| int |
| main(int argc, char *argv[]) |
| { |
| union { |
| uint32_t u32; |
| uint8_t arr[4]; |
| } x; |
| |
| x.arr[0] = 0x11; /* Lowest-address byte */ |
| x.arr[1] = 0x22; |
| x.arr[2] = 0x33; |
| x.arr[3] = 0x44; /* Highest-address byte */ |
| |
| printf("x.u32 = 0x%x\\n", x.u32); |
| printf("htole32(x.u32) = 0x%x\\n", htole32(x.u32)); |
| printf("htobe32(x.u32) = 0x%x\\n", htobe32(x.u32)); |
| |
| exit(EXIT_SUCCESS); |
| } |
| .EE |
| .SH SEE ALSO |
| .BR bswap (3), |
| .BR byteorder (3) |