docs/reference/glib/tmpl/byte_order.sgml

   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 GSIZE_FROM_BE ##### -->
 269 <para>
 270 Converts a #gsize value from big-endian to the host byte order.
 271 </para>
 272
 273 @val: a #gsize value in big-endian byte order.
 274 @Returns: @val converted to host byte order.
 275
 276
 277 <!-- ##### MACRO GSIZE_FROM_LE ##### -->
 278 <para>
 279 Converts a #gsize value from little-endian to host byte order.
 280 </para>
 281
 282 @val: a #gsize value in little-endian byte order.
 283 @Returns: @val converted to host byte order.
 284
 285
 286 <!-- ##### MACRO GSIZE_TO_BE ##### -->
 287 <para>
 288 Converts a #gsize value from host byte order to big-endian.
 289 </para>
 290
 291 @val: a #gsize value in host byte order.
 292 @Returns: @val converted to big-endian byte order.
 293
 294
 295 <!-- ##### MACRO GSIZE_TO_LE ##### -->
 296 <para>
 297 Converts a #gsize value from host byte order to little-endian.
 298 </para>
 299
 300 @val: a #gsize value in host byte order.
 301 @Returns: @val converted to little-endian.
 302
 303
 304 <!-- ##### MACRO GSSIZE_FROM_BE ##### -->
 305 <para>
 306 Converts a #gssize value from big-endian to host byte order.
 307 </para>
 308
 309 @val: a #gssize value in big-endian byte order.
 310 @Returns: @val converted to host byte order.
 311
 312
 313 <!-- ##### MACRO GSSIZE_FROM_LE ##### -->
 314 <para>
 315 Converts a #gssize value from little-endian to host byte order.
 316 </para>
 317
 318 @val: a #gssize value in little-endian byte order.
 319 @Returns: @val converted to host byte order.
 320
 321
 322 <!-- ##### MACRO GSSIZE_TO_BE ##### -->
 323 <para>
 324 Converts a #gssize value from host byte order to big-endian.
 325 </para>
 326
 327 @val: a #gssize value in host byte order.
 328 @Returns: @val converted to big-endian.
 329
 330
 331 <!-- ##### MACRO GSSIZE_TO_LE ##### -->
 332 <para>
 333 Converts a #gssize value from host byte order to little-endian.
 334 </para>
 335
 336 @val: a #gssize value in host byte order.
 337 @Returns: @val converted to little-endian.
 338
 339
 340 <!-- ##### MACRO GINT16_FROM_BE ##### -->
 341 <para>
 342 Converts a #gint16 value from big-endian to host byte order.
 343 </para>
 344
 345 @val: a #gint16 value in big-endian byte order.
 346 @Returns: @val converted to host byte order.
 347
 348
 349 <!-- ##### MACRO GINT16_FROM_LE ##### -->
 350 <para>
 351 Converts a #gint16 value from little-endian to host byte order.
 352 </para>
 353
 354 @val: a #gint16 value in little-endian byte order.
 355 @Returns: @val converted to host byte order.
 356
 357
 358 <!-- ##### MACRO GINT16_TO_BE ##### -->
 359 <para>
 360 Converts a #gint16 value from host byte order to big-endian.
 361 </para>
 362
 363 @val: a #gint16 value in host byte order.
 364 @Returns: @val converted to big-endian.
 365
 366
 367 <!-- ##### MACRO GINT16_TO_LE ##### -->
 368 <para>
 369 Converts a #gint16 value from host byte order to little-endian.
 370 </para>
 371
 372 @val: a #gint16 value in host byte order.
 373 @Returns: @val converted to little-endian.
 374
 375
 376 <!-- ##### MACRO GUINT16_FROM_BE ##### -->
 377 <para>
 378 Converts a #guint16 value from big-endian to host byte order.
 379 </para>
 380
 381 @val: a #guint16 value in big-endian byte order.
 382 @Returns: @val converted to host byte order.
 383
 384
 385 <!-- ##### MACRO GUINT16_FROM_LE ##### -->
 386 <para>
 387 Converts a #guint16 value from little-endian to host byte order.
 388 </para>
 389
 390 @val: a #guint16 value in little-endian byte order.
 391 @Returns: @val converted to host byte order.
 392
 393
 394 <!-- ##### MACRO GUINT16_TO_BE ##### -->
 395 <para>
 396 Converts a #guint16 value from host byte order to big-endian.
 397 </para>
 398
 399 @val: a #guint16 value in host byte order.
 400 @Returns: @val converted to big-endian.
 401
 402
 403 <!-- ##### MACRO GUINT16_TO_LE ##### -->
 404 <para>
 405 Converts a #guint16 value from host byte order to little-endian.
 406 </para>
 407
 408 @val: a #guint16 value in host byte order.
 409 @Returns: @val converted to little-endian.
 410
 411
 412 <!-- ##### MACRO GINT32_FROM_BE ##### -->
 413 <para>
 414 Converts a #gint32 value from big-endian to host byte order.
 415 </para>
 416
 417 @val: a #gint32 value in big-endian byte order.
 418 @Returns: @val converted to host byte order.
 419
 420
 421 <!-- ##### MACRO GINT32_FROM_LE ##### -->
 422 <para>
 423 Converts a #gint32 value from little-endian to host byte order.
 424 </para>
 425
 426 @val: a #gint32 value in little-endian byte order.
 427 @Returns: @val converted to host byte order.
 428
 429
 430 <!-- ##### MACRO GINT32_TO_BE ##### -->
 431 <para>
 432 Converts a #gint32 value from host byte order to big-endian.
 433 </para>
 434
 435 @val: a #gint32 value in host byte order.
 436 @Returns: @val converted to big-endian.
 437
 438
 439 <!-- ##### MACRO GINT32_TO_LE ##### -->
 440 <para>
 441 Converts a #gint32 value from host byte order to little-endian.
 442 </para>
 443
 444 @val: a #gint32 value in host byte order.
 445 @Returns: @val converted to little-endian.
 446
 447
 448 <!-- ##### MACRO GUINT32_FROM_BE ##### -->
 449 <para>
 450 Converts a #guint32 value from big-endian to host byte order.
 451 </para>
 452
 453 @val: a #guint32 value in big-endian byte order.
 454 @Returns: @val converted to host byte order.
 455
 456
 457 <!-- ##### MACRO GUINT32_FROM_LE ##### -->
 458 <para>
 459 Converts a #guint32 value from little-endian to host byte order.
 460 </para>
 461
 462 @val: a #guint32 value in little-endian byte order.
 463 @Returns: @val converted to host byte order.
 464
 465
 466 <!-- ##### MACRO GUINT32_TO_BE ##### -->
 467 <para>
 468 Converts a #guint32 value from host byte order to big-endian.
 469 </para>
 470
 471 @val: a #guint32 value in host byte order.
 472 @Returns: @val converted to big-endian.
 473
 474
 475 <!-- ##### MACRO GUINT32_TO_LE ##### -->
 476 <para>
 477 Converts a #guint32 value from host byte order to little-endian.
 478 </para>
 479
 480 @val: a #guint32 value in host byte order.
 481 @Returns: @val converted to little-endian.
 482
 483
 484 <!-- ##### MACRO GINT64_FROM_BE ##### -->
 485 <para>
 486 Converts a #gint64 value from big-endian to host byte order.
 487 </para>
 488
 489 @val: a #gint64 value in big-endian byte order.
 490 @Returns: @val converted to host byte order.
 491
 492
 493 <!-- ##### MACRO GINT64_FROM_LE ##### -->
 494 <para>
 495 Converts a #gint64 value from little-endian to host byte order.
 496 </para>
 497
 498 @val: a #gint64 value in little-endian byte order.
 499 @Returns: @val converted to host byte order.
 500
 501
 502 <!-- ##### MACRO GINT64_TO_BE ##### -->
 503 <para>
 504 Converts a #gint64 value from host byte order to big-endian.
 505 </para>
 506
 507 @val: a #gint64 value in host byte order.
 508 @Returns: @val converted to big-endian.
 509
 510
 511 <!-- ##### MACRO GINT64_TO_LE ##### -->
 512 <para>
 513 Converts a #gint64 value from host byte order to little-endian.
 514 </para>
 515
 516 @val: a #gint64 value in host byte order.
 517 @Returns: @val converted to little-endian.
 518
 519
 520 <!-- ##### MACRO GUINT64_FROM_BE ##### -->
 521 <para>
 522 Converts a #guint64 value from big-endian to host byte order.
 523 </para>
 524
 525 @val: a #guint64 value in big-endian byte order.
 526 @Returns: @val converted to host byte order.
 527
 528
 529 <!-- ##### MACRO GUINT64_FROM_LE ##### -->
 530 <para>
 531 Converts a #guint64 value from little-endian to host byte order.
 532 </para>
 533
 534 @val: a #guint64 value in little-endian byte order.
 535 @Returns: @val converted to host byte order.
 536
 537
 538 <!-- ##### MACRO GUINT64_TO_BE ##### -->
 539 <para>
 540 Converts a #guint64 value from host byte order to big-endian.
 541 </para>
 542
 543 @val: a #guint64 value in host byte order.
 544 @Returns: @val converted to big-endian.
 545
 546
 547 <!-- ##### MACRO GUINT64_TO_LE ##### -->
 548 <para>
 549 Converts a #guint64 value from host byte order to little-endian.
 550 </para>
 551
 552 @val: a #guint64 value in host byte order.
 553 @Returns: @val converted to little-endian.
 554
 555
 556 <!-- ##### MACRO GUINT16_SWAP_BE_PDP ##### -->
 557 <para>
 558 Converts a #guint16 value between big-endian and pdp-endian byte order.
 559 The conversion is symmetric so it can be used both ways.
 560 </para>
 561
 562 @val: a #guint16 value in big-endian or pdp-endian byte order.
 563 @Returns: @val converted to the opposite byte order.
 564
 565
 566 <!-- ##### MACRO GUINT16_SWAP_LE_BE ##### -->
 567 <para>
 568 Converts a #guint16 value between little-endian and big-endian byte order.
 569 The conversion is symmetric so it can be used both ways.
 570 </para>
 571
 572 @val: a #guint16 value in little-endian or big-endian byte order.
 573 @Returns: @val converted to the opposite byte order.
 574
 575
 576 <!-- ##### MACRO GUINT16_SWAP_LE_PDP ##### -->
 577 <para>
 578 Converts a #guint16 value between little-endian and pdp-endian byte order.
 579 The conversion is symmetric so it can be used both ways.
 580 </para>
 581
 582 @val: a #guint16 value in little-endian or pdp-endian byte order.
 583 @Returns: @val converted to the opposite byte order.
 584
 585
 586 <!-- ##### MACRO GUINT32_SWAP_BE_PDP ##### -->
 587 <para>
 588 Converts a #guint32 value between big-endian and pdp-endian byte order.
 589 The conversion is symmetric so it can be used both ways.
 590 </para>
 591
 592 @val: a #guint32 value in big-endian or pdp-endian byte order.
 593 @Returns: @val converted to the opposite byte order.
 594
 595
 596 <!-- ##### MACRO GUINT32_SWAP_LE_BE ##### -->
 597 <para>
 598 Converts a #guint32 value between little-endian and big-endian byte order.
 599 The conversion is symmetric so it can be used both ways.
 600 </para>
 601
 602 @val: a #guint32 value in little-endian or big-endian byte order.
 603 @Returns: @val converted to the opposite byte order.
 604
 605
 606 <!-- ##### MACRO GUINT32_SWAP_LE_PDP ##### -->
 607 <para>
 608 Converts a #guint32 value between little-endian and pdp-endian byte order.
 609 The conversion is symmetric so it can be used both ways.
 610 </para>
 611
 612 @val: a #guint32 value in little-endian or pdp-endian byte order.
 613 @Returns: @val converted to the opposite byte order.
 614
 615
 616 <!-- ##### MACRO GUINT64_SWAP_LE_BE ##### -->
 617 <para>
 618 Converts a #guint64 value between little-endian and big-endian byte order.
 619 The conversion is symmetric so it can be used both ways.
 620 </para>
 621
 622 @val: a #guint64 value in little-endian or big-endian byte order.
 623 @Returns: @val converted to the opposite byte order.
 624
 625