Print this page
9842 man page typos and spelling
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man5/byteorder.5
+++ new/usr/src/man/man5/byteorder.5
1 1 .\"
2 2 .\" This file and its contents are supplied under the terms of the
3 3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 4 .\" You may only use this file in accordance with the terms of version
5 5 .\" 1.0 of the CDDL.
6 6 .\"
7 7 .\" A full copy of the text of the CDDL should have accompanied this
8 8 .\" source. A copy of the CDDL is also available via the Internet at
9 9 .\" http://www.illumos.org/license/CDDL.
10 10 .\"
11 11 .\"
12 12 .\" Copyright 2016 Joyent, Inc.
13 13 .\"
14 14 .Dd August 2, 2018
15 15 .Dt BYTEORDER 5
16 16 .Os
17 17 .Sh NAME
18 18 .Nm byteorder ,
19 19 .Nm endian
20 20 .Nd byte order and endianness
21 21 .Sh DESCRIPTION
22 22 Integer values which occupy more than 1 byte in memory can be laid out
23 23 in different ways on different platforms.
24 24 In particular, there is a major split between those which place the least
25 25 significant byte of an integer at the lowest address, and those which place the
26 26 most significant byte there instead.
27 27 As this difference relates to which end of the integer is found in memory first,
28 28 the term
29 29 .Em endian
30 30 is used to refer to a particular byte order.
31 31 .Pp
32 32 A platform is referred to as using a
33 33 .Em big-endian
34 34 byte order when it places the most significant byte at the lowest
35 35 address, and
36 36 .Em little-endian
37 37 when it places the least significant byte first.
38 38 Some platforms may also switch between big- and little-endian mode and run code
39 39 compiled for either.
40 40 .Pp
41 41 Historically, there have also been some systems that utilized
42 42 .Em middle-endian
43 43 byte orders for integers larger than 2 bytes.
44 44 Such orderings are not in common use today.
45 45 .Pp
46 46 Endianness is also of particular importance when dealing with values
47 47 that are being read into memory from an external source.
48 48 For example, network protocols such as IP conventionally define the fields in a
49 49 packet as being always stored in big-endian byte order.
50 50 This means that a little-endian machine will have to perform transformations on
51 51 these fields in order to process them.
52 52 .Ss Examples
53 53 To illustrate endianness in memory, let us consider the decimal integer
54 54 2864434397.
55 55 This number fits in 32 bits of storage (4 bytes).
56 56 .Pp
57 57 On a big-endian system, this integer would be written into memory as
58 58 the bytes 0xAA, 0xBB, 0xCC, 0xDD, in order from lowest memory address to
59 59 highest.
60 60 .Pp
61 61 On a little-endian system, it would be written instead as the bytes
62 62 0xDD, 0xCC, 0xBB, 0xAA, in that order.
63 63 .Pp
64 64 If both the big- and little-endian systems were asked to store this
65 65 integer at address 0x100, we would see the following in each of their
66 66 memory:
67 67 .Bd -literal
68 68
69 69 Big-Endian
70 70
71 71 ++------++------++------++------++
72 72 || 0xAA || 0xBB || 0xCC || 0xDD ||
73 73 ++------++------++------++------++
74 74 ^^ ^^ ^^ ^^
75 75 0x100 0x101 0x102 0x103
76 76 vv vv vv vv
77 77 ++------++------++------++------++
78 78 || 0xDD || 0xCC || 0xBB || 0xAA ||
79 79 ++------++------++------++------++
80 80
81 81 Little-Endian
82 82 .Ed
83 83 .Pp
84 84 It is particularly important to note that even though the byte order is
85 85 different between these two machines, the bit ordering within each byte,
86 86 by convention, is still the same.
87 87 .Pp
88 88 For example, take the decimal integer 4660, which occupies in 16 bits (2
89 89 bytes).
90 90 .Pp
91 91 On a big-endian system, this would be written into memory as 0x12, then
92 92 0x34.
93 93 .Pp
94 94 On a little-endian system, it would be written as 0x34, then 0x12.
95 95 Note that this is not at all the same as seeing 0x43 then 0x21 in memory --
96 96 only the bytes are re-ordered, not any bits (or nybbles) within them.
97 97 .Pp
98 98 As before, storing this at address 0x100:
99 99 .Bd -literal
100 100 Big-Endian
101 101
102 102 ++------++------++
103 103 || 0x12 || 0x34 ||
104 104 ++------++------++
105 105 ^^ ^^
106 106 0x100 0x101
107 107 vv vv
108 108 ++------++------++
109 109 || 0x34 || 0x12 ||
110 110 ++------++------++
111 111
112 112 Little-Endian
113 113 .Ed
114 114 .Pp
115 115 This example shows how an eight byte number, 0xBADCAFEDEADBEEF is stored
116 116 in both big and little-endian:
117 117 .Bd -literal
118 118 Big-Endian
119 119
120 120 +------+------+------+------+------+------+------+------+
121 121 | 0xBA | 0xDC | 0xAF | 0xFE | 0xDE | 0xAD | 0xBE | 0xEF |
122 122 +------+------+------+------+------+------+------+------+
123 123 ^^ ^^ ^^ ^^ ^^ ^^ ^^ ^^
124 124 0x100 0x101 0x102 0x103 0x104 0x105 0x106 0x107
125 125 vv vv vv vv vv vv vv vv
126 126 +------+------+------+------+------+------+------+------+
127 127 | 0xEF | 0xBE | 0xAD | 0xDE | 0xFE | 0xAF | 0xDC | 0xBA |
128 128 +------+------+------+------+------+------+------+------+
129 129
130 130 Little-Endian
131 131
132 132 .Ed
133 133 .Pp
134 134 The treatment of different endian values would not be complete without
135 135 discussing
136 136 .Em PDP-endian ,
137 137 which is also known as
138 138 .Em middle-endian .
139 139 While the PDP-11 was a 16-bit little-endian system, it laid out 32-bit
140 140 values in a different way from current little-endian systems.
141 141 First, it would divide a 32-bit number into two 16-bit numbers.
142 142 Each 16-bit number would be stored in little-endian; however, the two 16-bit
143 143 words would be stored with the larger 16-bit word appearing first in memory,
144 144 followed by the latter.
145 145 .Pp
146 146 The following image illustrates PDP-endian and compares it against
147 147 little-endian values.
148 148 Here, we'll start with the value 0xAABBCCDD and show how the four bytes for it
149 149 will be laid out, starting at 0x100.
150 150 .Bd -literal
151 151 PDP-Endian
152 152
153 153 ++------++------++------++------++
154 154 || 0xBB || 0xAA || 0xDD || 0xCC ||
155 155 ++------++------++------++------++
156 156 ^^ ^^ ^^ ^^
157 157 0x100 0x101 0x102 0x103
158 158 vv vv vv vv
159 159 ++------++------++------++------++
160 160 || 0xDD || 0xCC || 0xBB || 0xAA ||
161 161 ++------++------++------++------++
162 162
163 163 Little-Endian
164 164
165 165 .Ed
166 166 .Ss Network Byte Order
167 167 The term 'network byte order' refers to big-endian ordering, and
168 168 originates from the IEEE.
169 169 Early disagreements over which byte ordering to use for network traffic prompted
170 170 RFC1700 to define that all IETF-specified network protocols use big-endian
171 171 ordering unless noted explicitly otherwise.
172 172 The Internet protocol family (IP, and thus TCP and UDP etc) particularly adhere
173 173 to this convention.
174 174 .Ss Determining the System's Byte Order
175 175 The operating system supports both big-endian and little-endian CPUs.
176 176 To make it easier for programs to determine the endianness of the platform they
177 177 are being compiled for, functions and macro constants are provided in the system
178 178 header files.
179 179 .Pp
180 180 The endianness of the system can be obtained by including the header
181 181 .In sys/types.h
182 182 and using the pre-processor macros
183 183 .Sy _LITTLE_ENDIAN
184 184 and
185 185 .Sy _BIG_ENDIAN .
186 186 See
187 187 .Xr types.h 3HEAD
188 188 for more information.
189 189 .Pp
190 190 Additionally, the header
191 191 .In endian.h
192 192 defines an alternative means for determining the endianness of the
193 193 current system.
194 194 See
195 195 .Xr endian.h 3HEAD
196 196 for more information.
197 197 .Pp
198 198 illumos runs on both big- and little-endian systems.
199 199 When writing software for which the endianness is important, one must always
200 200 check the byte order and convert it appropriately.
201 201 .Ss Converting Between Byte Orders
202 202 The system provides two different sets of functions to convert values
203 203 between big-endian and little-endian.
204 204 They are defined in
205 205 .Xr byteorder 3C
206 206 and
207 207 .Xr endian 3C .
208 208 .Pp
209 209 The
210 210 .Xr byteorder 3C
211 211 family of functions convert data between the host's native byte order
212 212 and big- or little-endian.
213 213 The functions operate on either 16-bit, 32-bit, or 64-bit values.
214 214 Functions that convert from network byte order to the host's byte order
215 215 start with the string
216 216 .Sy ntoh ,
217 217 while functions which convert from the host's byte order to network byte
218 218 order, begin with
219 219 .Sy hton .
220 220 For example, to convert a 32-bit value, a long, from network byte order
221 221 to the host's, one would use the function
222 222 .Xr ntohl 3C .
223 223 .Pp
224 224 These functions have been standardized by POSIX.
225 225 However, the 64-bit variants,
226 226 .Xr ntohll 3C
227 227 and
228 228 .Xr htonll 3C
229 229 are not standardized and may not be found on other systems.
230 230 For more information on these functions, see
231 231 .Xr byteorder 3C .
232 232 .Pp
233 233 The second family of functions,
234 234 .Xr endian 3C ,
235 235 provide a means to convert between the host's byte order
236 236 and big-endian and little-endian specifically.
237 237 While these functions are similar to those in
238 238 .Xr byteorder 3C ,
239 239 they more explicitly cover different data conversions.
240 240 Like them, these functions operate on either 16-bit, 32-bit, or 64-bit values.
241 241 When converting from big-endian, to the host's endianness, the functions
242 242 begin with
243 243 .Sy betoh .
244 244 If instead, one is converting data from the host's native endianness to
245 245 another, then it starts with
|
↓ open down ↓ |
245 lines elided |
↑ open up ↑ |
246 246 .Sy htobe .
247 247 When working with little-endian data, the prefixes
248 248 .Sy letoh
249 249 and
250 250 .Sy htole
251 251 convert little-endian data to the host's endianness and from the host's
252 252 to little-endian respectively.
253 253 .Pp
254 254 These functions are not standardized and the header they appear in varies
255 255 between the BSDs and GNU/Linux.
256 -Applications that wish to be portable, shoulda instead use the
256 +Applications that wish to be portable, should instead use the
257 257 .Xr byteorder 3C
258 258 functions.
259 259 .Pp
260 260 All of these functions in both families simply return their input when
261 261 the host's native byte order is the same as the desired order.
262 262 For example, when calling
263 263 .Xr htonl 3C
264 264 on a big-endian system the original data is returned with no conversion
265 265 or modification.
266 266 .Sh SEE ALSO
267 267 .Xr byteorder 3C ,
268 268 .Xr endian 3C ,
269 269 .Xr endian.h 3HEAD ,
270 270 .Xr inet 3HEAD
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX