1 <!-- ##### SECTION Title ##### --> 2 Byte Order Macros 3 4 <!-- ##### SECTION Short_Description ##### --> 5 a portable way to convert between different byte orders 6 7 <!-- ##### SECTION Long_Description ##### --> 8 <para> 9 These macros provide a portable way to determine the host byte order 10 and to convert values between different byte orders. 11 </para> 12 <para> 13 The byte order is the order in which bytes are stored to create larger 14 data types such as the #gint and #glong values. 15 The host byte order is the byte order used on the current machine. 16 </para> 17 <para> 18 Some processors store the most significant bytes (i.e. the bytes that 19 hold the largest part of the value) first. These are known as big-endian 20 processors. 21 </para> 22 <para> 23 Other processors (notably the x86 family) store the most significant byte 24 last. These are known as little-endian processors. 25 </para> 26 <para> 27 Finally, to complicate matters, some other processors store the bytes in 28 a rather curious order known as PDP-endian. For a 4-byte word, the 3rd 29 most significant byte is stored first, then the 4th, then the 1st and finally 30 the 2nd. 31 </para> 32 <para> 33 Obviously there is a problem when these different processors communicate 34 with each other, for example over networks or by using binary file formats. 35 This is where these macros come in. 36 They are typically used to convert values into a byte order 37 which has been agreed on for use when communicating between different 38 processors. The Internet uses what is known as 'network byte order' 39 as the standard byte order (which is in fact the big-endian byte order). 40 </para> 41 <para> 42 Note that the byte order conversion macros may evaluate their arguments 43 multiple times, thus you should not use them with arguments which have 44 side-effects. 45 </para> 46 47 <!-- ##### SECTION See_Also ##### --> 48 <para> 49 50 </para> 51 52 <!-- ##### SECTION Stability_Level ##### --> 53 54 55 <!-- ##### MACRO G_BYTE_ORDER ##### --> 56 <para> 57 The host byte order. 58 This can be either #G_LITTLE_ENDIAN or #G_BIG_ENDIAN (support for 59 #G_PDP_ENDIAN may be added in future.) 60 </para> 61 62 63 64 <!-- ##### MACRO G_LITTLE_ENDIAN ##### --> 65 <para> 66 Specifies one of the possible types of byte order. 67 See #G_BYTE_ORDER. 68 </para> 69 70 71 72 <!-- ##### MACRO G_BIG_ENDIAN ##### --> 73 <para> 74 Specifies one of the possible types of byte order. 75 See #G_BYTE_ORDER. 76 </para> 77 78 79 80 <!-- ##### MACRO G_PDP_ENDIAN ##### --> 81 <para> 82 Specifies one of the possible types of byte order (currently unused). 83 See #G_BYTE_ORDER. 84 </para> 85 86 87 88 <!-- ##### MACRO g_htonl ##### --> 89 <para> 90 Converts a 32-bit integer value from host to network byte order. 91 </para> 92 93 @val: a 32-bit integer value in host byte order. 94 @Returns: @val converted to network byte order. 95 96 97 <!-- ##### MACRO g_htons ##### --> 98 <para> 99 Converts a 16-bit integer value from host to network byte order. 100 </para> 101 102 @val: a 16-bit integer value in host byte order. 103 @Returns: @val converted to network byte order. 104 105 106 <!-- ##### MACRO g_ntohl ##### --> 107 <para> 108 Converts a 32-bit integer value from network to host byte order. 109 </para> 110 111 @val: a 32-bit integer value in network byte order. 112 @Returns: @val converted to host byte order. 113 114 115 <!-- ##### MACRO g_ntohs ##### --> 116 <para> 117 Converts a 16-bit integer value from network to host byte order. 118 </para> 119 120 @val: a 16-bit integer value in network byte order. 121 @Returns: @val converted to host byte order. 122 123 124 <!-- ##### MACRO GINT_FROM_BE ##### --> 125 <para> 126 Converts a #gint value from big-endian to host byte order. 127 </para> 128 129 @val: a #gint value in big-endian byte order. 130 @Returns: @val converted to host byte order. 131 132 133 <!-- ##### MACRO GINT_FROM_LE ##### --> 134 <para> 135 Converts a #gint value from little-endian to host byte order. 136 </para> 137 138 @val: a #gint value in little-endian byte order. 139 @Returns: @val converted to host byte order. 140 141 142 <!-- ##### MACRO GINT_TO_BE ##### --> 143 <para> 144 Converts a #gint value from host byte order to big-endian. 145 </para> 146 147 @val: a #gint value in host byte order. 148 @Returns: @val converted to big-endian byte order. 149 150 151 <!-- ##### MACRO GINT_TO_LE ##### --> 152 <para> 153 Converts a #gint value from host byte order to little-endian. 154 </para> 155 156 @val: a #gint value in host byte order. 157 @Returns: @val converted to little-endian byte order. 158 159 160 <!-- ##### MACRO GUINT_FROM_BE ##### --> 161 <para> 162 Converts a #guint value from big-endian to host byte order. 163 </para> 164 165 @val: a #guint value in big-endian byte order. 166 @Returns: @val converted to host byte order. 167 168 169 <!-- ##### MACRO GUINT_FROM_LE ##### --> 170 <para> 171 Converts a #guint value from little-endian to host byte order. 172 </para> 173 174 @val: a #guint value in little-endian byte order. 175 @Returns: @val converted to host byte order. 176 177 178 <!-- ##### MACRO GUINT_TO_BE ##### --> 179 <para> 180 Converts a #guint value from host byte order to big-endian. 181 </para> 182 183 @val: a #guint value in host byte order. 184 @Returns: @val converted to big-endian byte order. 185 186 187 <!-- ##### MACRO GUINT_TO_LE ##### --> 188 <para> 189 Converts a #guint value from host byte order to little-endian. 190 </para> 191 192 @val: a #guint value in host byte order. 193 @Returns: @val converted to little-endian byte order. 194 195 196 <!-- ##### MACRO GLONG_FROM_BE ##### --> 197 <para> 198 Converts a #glong value from big-endian to the host byte order. 199 </para> 200 201 @val: a #glong value in big-endian byte order. 202 @Returns: @val converted to host byte order. 203 204 205 <!-- ##### MACRO GLONG_FROM_LE ##### --> 206 <para> 207 Converts a #glong value from little-endian to host byte order. 208 </para> 209 210 @val: a #glong value in little-endian byte order. 211 @Returns: @val converted to host byte order. 212 213 214 <!-- ##### MACRO GLONG_TO_BE ##### --> 215 <para> 216 Converts a #glong value from host byte order to big-endian. 217 </para> 218 219 @val: a #glong value in host byte order. 220 @Returns: @val converted to big-endian byte order. 221 222 223 <!-- ##### MACRO GLONG_TO_LE ##### --> 224 <para> 225 Converts a #glong value from host byte order to little-endian. 226 </para> 227 228 @val: a #glong value in host byte order. 229 @Returns: @val converted to little-endian. 230 231 232 <!-- ##### MACRO GULONG_FROM_BE ##### --> 233 <para> 234 Converts a #gulong value from big-endian to host byte order. 235 </para> 236 237 @val: a #gulong value in big-endian byte order. 238 @Returns: @val converted to host byte order. 239 240 241 <!-- ##### MACRO GULONG_FROM_LE ##### --> 242 <para> 243 Converts a #gulong value from little-endian to host byte order. 244 </para> 245 246 @val: a #gulong value in little-endian byte order. 247 @Returns: @val converted to host byte order. 248 249 250 <!-- ##### MACRO GULONG_TO_BE ##### --> 251 <para> 252 Converts a #gulong value from host byte order to big-endian. 253 </para> 254 255 @val: a #gulong value in host byte order. 256 @Returns: @val converted to big-endian. 257 258 259 <!-- ##### MACRO GULONG_TO_LE ##### --> 260 <para> 261 Converts a #gulong value from host byte order to little-endian. 262 </para> 263 264 @val: a #gulong value in host byte order. 265 @Returns: @val converted to little-endian. 266 267 268 <!-- ##### MACRO GINT16_FROM_BE ##### --> 269 <para> 270 Converts a #gint16 value from big-endian to host byte order. 271 </para> 272 273 @val: a #gint16 value in big-endian byte order. 274 @Returns: @val converted to host byte order. 275 276 277 <!-- ##### MACRO GINT16_FROM_LE ##### --> 278 <para> 279 Converts a #gint16 value from little-endian to host byte order. 280 </para> 281 282 @val: a #gint16 value in little-endian byte order. 283 @Returns: @val converted to host byte order. 284 285 286 <!-- ##### MACRO GINT16_TO_BE ##### --> 287 <para> 288 Converts a #gint16 value from host byte order to big-endian. 289 </para> 290 291 @val: a #gint16 value in host byte order. 292 @Returns: @val converted to big-endian. 293 294 295 <!-- ##### MACRO GINT16_TO_LE ##### --> 296 <para> 297 Converts a #gint16 value from host byte order to little-endian. 298 </para> 299 300 @val: a #gint16 value in host byte order. 301 @Returns: @val converted to little-endian. 302 303 304 <!-- ##### MACRO GUINT16_FROM_BE ##### --> 305 <para> 306 Converts a #guint16 value from big-endian to host byte order. 307 </para> 308 309 @val: a #guint16 value in big-endian byte order. 310 @Returns: @val converted to host byte order. 311 312 313 <!-- ##### MACRO GUINT16_FROM_LE ##### --> 314 <para> 315 Converts a #guint16 value from little-endian to host byte order. 316 </para> 317 318 @val: a #guint16 value in little-endian byte order. 319 @Returns: @val converted to host byte order. 320 321 322 <!-- ##### MACRO GUINT16_TO_BE ##### --> 323 <para> 324 Converts a #guint16 value from host byte order to big-endian. 325 </para> 326 327 @val: a #guint16 value in host byte order. 328 @Returns: @val converted to big-endian. 329 330 331 <!-- ##### MACRO GUINT16_TO_LE ##### --> 332 <para> 333 Converts a #guint16 value from host byte order to little-endian. 334 </para> 335 336 @val: a #guint16 value in host byte order. 337 @Returns: @val converted to little-endian. 338 339 340 <!-- ##### MACRO GINT32_FROM_BE ##### --> 341 <para> 342 Converts a #gint32 value from big-endian to host byte order. 343 </para> 344 345 @val: a #gint32 value in big-endian byte order. 346 @Returns: @val converted to host byte order. 347 348 349 <!-- ##### MACRO GINT32_FROM_LE ##### --> 350 <para> 351 Converts a #gint32 value from little-endian to host byte order. 352 </para> 353 354 @val: a #gint32 value in little-endian byte order. 355 @Returns: @val converted to host byte order. 356 357 358 <!-- ##### MACRO GINT32_TO_BE ##### --> 359 <para> 360 Converts a #gint32 value from host byte order to big-endian. 361 </para> 362 363 @val: a #gint32 value in host byte order. 364 @Returns: @val converted to big-endian. 365 366 367 <!-- ##### MACRO GINT32_TO_LE ##### --> 368 <para> 369 Converts a #gint32 value from host byte order to little-endian. 370 </para> 371 372 @val: a #gint32 value in host byte order. 373 @Returns: @val converted to little-endian. 374 375 376 <!-- ##### MACRO GUINT32_FROM_BE ##### --> 377 <para> 378 Converts a #guint32 value from big-endian to host byte order. 379 </para> 380 381 @val: a #guint32 value in big-endian byte order. 382 @Returns: @val converted to host byte order. 383 384 385 <!-- ##### MACRO GUINT32_FROM_LE ##### --> 386 <para> 387 Converts a #guint32 value from little-endian to host byte order. 388 </para> 389 390 @val: a #guint32 value in little-endian byte order. 391 @Returns: @val converted to host byte order. 392 393 394 <!-- ##### MACRO GUINT32_TO_BE ##### --> 395 <para> 396 Converts a #guint32 value from host byte order to big-endian. 397 </para> 398 399 @val: a #guint32 value in host byte order. 400 @Returns: @val converted to big-endian. 401 402 403 <!-- ##### MACRO GUINT32_TO_LE ##### --> 404 <para> 405 Converts a #guint32 value from host byte order to little-endian. 406 </para> 407 408 @val: a #guint32 value in host byte order. 409 @Returns: @val converted to little-endian. 410 411 412 <!-- ##### MACRO GINT64_FROM_BE ##### --> 413 <para> 414 Converts a #gint64 value from big-endian to host byte order. 415 </para> 416 417 @val: a #gint64 value in big-endian byte order. 418 @Returns: @val converted to host byte order. 419 420 421 <!-- ##### MACRO GINT64_FROM_LE ##### --> 422 <para> 423 Converts a #gint64 value from little-endian to host byte order. 424 </para> 425 426 @val: a #gint64 value in little-endian byte order. 427 @Returns: @val converted to host byte order. 428 429 430 <!-- ##### MACRO GINT64_TO_BE ##### --> 431 <para> 432 Converts a #gint64 value from host byte order to big-endian. 433 </para> 434 435 @val: a #gint64 value in host byte order. 436 @Returns: @val converted to big-endian. 437 438 439 <!-- ##### MACRO GINT64_TO_LE ##### --> 440 <para> 441 Converts a #gint64 value from host byte order to little-endian. 442 </para> 443 444 @val: a #gint64 value in host byte order. 445 @Returns: @val converted to little-endian. 446 447 448 <!-- ##### MACRO GUINT64_FROM_BE ##### --> 449 <para> 450 Converts a #guint64 value from big-endian to host byte order. 451 </para> 452 453 @val: a #guint64 value in big-endian byte order. 454 @Returns: @val converted to host byte order. 455 456 457 <!-- ##### MACRO GUINT64_FROM_LE ##### --> 458 <para> 459 Converts a #guint64 value from little-endian to host byte order. 460 </para> 461 462 @val: a #guint64 value in little-endian byte order. 463 @Returns: @val converted to host byte order. 464 465 466 <!-- ##### MACRO GUINT64_TO_BE ##### --> 467 <para> 468 Converts a #guint64 value from host byte order to big-endian. 469 </para> 470 471 @val: a #guint64 value in host byte order. 472 @Returns: @val converted to big-endian. 473 474 475 <!-- ##### MACRO GUINT64_TO_LE ##### --> 476 <para> 477 Converts a #guint64 value from host byte order to little-endian. 478 </para> 479 480 @val: a #guint64 value in host byte order. 481 @Returns: @val converted to little-endian. 482 483 484 <!-- ##### MACRO GUINT16_SWAP_BE_PDP ##### --> 485 <para> 486 Converts a #guint16 value between big-endian and pdp-endian byte order. 487 The conversion is symmetric so it can be used both ways. 488 </para> 489 490 @val: a #guint16 value in big-endian or pdp-endian byte order. 491 @Returns: @val converted to the opposite byte order. 492 493 494 <!-- ##### MACRO GUINT16_SWAP_LE_BE ##### --> 495 <para> 496 Converts a #guint16 value between little-endian and big-endian byte order. 497 The conversion is symmetric so it can be used both ways. 498 </para> 499 500 @val: a #guint16 value in little-endian or big-endian byte order. 501 @Returns: @val converted to the opposite byte order. 502 503 504 <!-- ##### MACRO GUINT16_SWAP_LE_PDP ##### --> 505 <para> 506 Converts a #guint16 value between little-endian and pdp-endian byte order. 507 The conversion is symmetric so it can be used both ways. 508 </para> 509 510 @val: a #guint16 value in little-endian or pdp-endian byte order. 511 @Returns: @val converted to the opposite byte order. 512 513 514 <!-- ##### MACRO GUINT32_SWAP_BE_PDP ##### --> 515 <para> 516 Converts a #guint32 value between big-endian and pdp-endian byte order. 517 The conversion is symmetric so it can be used both ways. 518 </para> 519 520 @val: a #guint32 value in big-endian or pdp-endian byte order. 521 @Returns: @val converted to the opposite byte order. 522 523 524 <!-- ##### MACRO GUINT32_SWAP_LE_BE ##### --> 525 <para> 526 Converts a #guint32 value between little-endian and big-endian byte order. 527 The conversion is symmetric so it can be used both ways. 528 </para> 529 530 @val: a #guint32 value in little-endian or big-endian byte order. 531 @Returns: @val converted to the opposite byte order. 532 533 534 <!-- ##### MACRO GUINT32_SWAP_LE_PDP ##### --> 535 <para> 536 Converts a #guint32 value between little-endian and pdp-endian byte order. 537 The conversion is symmetric so it can be used both ways. 538 </para> 539 540 @val: a #guint32 value in little-endian or pdp-endian byte order. 541 @Returns: @val converted to the opposite byte order. 542 543 544 <!-- ##### MACRO GUINT64_SWAP_LE_BE ##### --> 545 <para> 546 Converts a #guint64 value between little-endian and big-endian byte order. 547 The conversion is symmetric so it can be used both ways. 548 </para> 549 550 @val: a #guint64 value in little-endian or big-endian byte order. 551 @Returns: @val converted to the opposite byte order. 552 553 554
