diff options
Diffstat (limited to 'man3/endian.3')
| -rw-r--r-- | man3/endian.3 | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/man3/endian.3 b/man3/endian.3 new file mode 100644 index 0000000..fa7b9fd --- /dev/null +++ b/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 2023-05-03 "Linux man-pages 6.05.01" +.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> +.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 +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.ad l +.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 +.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. +.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 +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. +.PP +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 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: +.PP +.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) |