summaryrefslogtreecommitdiffstats
path: root/man/man3/endian.3
diff options
context:
space:
mode:
Diffstat (limited to 'man/man3/endian.3')
-rw-r--r--man/man3/endian.3164
1 files changed, 164 insertions, 0 deletions
diff --git a/man/man3/endian.3 b/man/man3/endian.3
new file mode 100644
index 0000000..7ff7053
--- /dev/null
+++ b/man/man3/endian.3
@@ -0,0 +1,164 @@
+.\" 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>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH endian 3 2024-05-02 "Linux man-pages (unreleased)"
+.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 LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <endian.h>
+.P
+.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 );
+.P
+.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 );
+.P
+.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
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.ad l
+.P
+.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
+.ad
+.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.
+.P
+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.
+.P
+The functions with names of the form "htobe\fInn\fP" convert
+from host byte order to big-endian order.
+.P
+The functions with names of the form "htole\fInn\fP" convert
+from host byte order to little-endian order.
+.P
+The functions with names of the form "be\fInn\fPtoh" convert
+from big-endian order to host byte order.
+.P
+The functions with names of the form "le\fInn\fPtoh" convert
+from little-endian order to host byte order.
+.SH VERSIONS
+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 STANDARDS
+None.
+.SH HISTORY
+glibc 2.9.
+.P
+These functions are similar to the older
+.BR byteorder (3)
+family of functions.
+For example,
+.BR be32toh ()
+is identical to
+.BR ntohl ().
+.P
+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 EXAMPLES
+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:
+.P
+.in +4n
+.EX
+$ \fB./a.out\fP
+x.u32 = 0x44332211
+htole32(x.u32) = 0x44332211
+htobe32(x.u32) = 0x11223344
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (endian.c)
+.EX
+#include <endian.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+\&
+int
+main(void)
+{
+ 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 = %#x\en", x.u32);
+ printf("htole32(x.u32) = %#x\en", htole32(x.u32));
+ printf("htobe32(x.u32) = %#x\en", htobe32(x.u32));
+\&
+ exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR bswap (3),
+.BR byteorder (3)