<!-- ##### SECTION Title ##### -->
Byte Order Macros

<!-- ##### SECTION Short_Description ##### -->
a portable way to convert between different byte orders.

<!-- ##### SECTION Long_Description ##### -->
<para>
These macros provide a portable way to determine the host byte order
and to convert values between different byte orders.
(The host byte order is the byte order used on the current machine.)
</para>
<para>
The byte order is the order in which bytes are stored to create larger
data types such as the #gint and #glong values.
</para>
<para>
Some processors store the most significant bytes (i.e. the bytes that
hold the largest part of the value) first. These are known as big-endian
processors. 
</para>
<para>
Other processors (notably the x86 family) store the most significant byte
last. These are known as little-endian processors.
</para>
<para>
Finally, to complicate matters, some other processors store the bytes in
a rather curious order known as PDP-endian. For a 4-byte word, the 3rd
most significant byte is stored first, then the 4th, then the 1st and finally
the 2nd.
</para>
<para>
Obviously there is a problem when these different processors communicate
with each other, for example over networks or by using binary file formats.
This is where these macros come in.
They are typically used to convert values into a byte order
which has been agreed on for use when communicating between different
processors. The Internet uses what is known as 'network byte order'
as the standard byte order (which is in fact the big-endian byte order).
</para>

<!-- ##### MACRO G_BYTE_ORDER ##### -->
<para>
The host byte order.
This can be either #G_LITTLE_ENDIAN or #G_BIG_ENDIAN (support for
#G_PDP_ENDIAN may be added in future.)
</para>


<!-- ##### MACRO G_LITTLE_ENDIAN ##### -->
<para>
Specifies one of the possible types of byte order.
See #G_BYTE_ORDER.
</para>


<!-- ##### MACRO G_BIG_ENDIAN ##### -->
<para>
Specifies one of the possible types of byte order.
See #G_BYTE_ORDER.
</para>


<!-- ##### MACRO G_PDP_ENDIAN ##### -->
<para>
Specifies one of the possible types of byte order (currently unused).
See #G_BYTE_ORDER.
</para>


<!-- ##### MACRO GLONG_TO_LE ##### -->
<para>
Converts a #glong value to little-endian byte order.
</para>

@long_val: a #glong value.
@Returns: the #glong converted to little-endian.

<!-- ##### MACRO GLONG_FROM_LE ##### -->
<para>
Converts a #glong value from little-endian to the host byte order.
</para>

@long_val: a #glong value in little-endian byte order.
@Returns: the #glong converted to the host byte order.

<!-- ##### MACRO GULONG_TO_LE ##### -->
<para>
Converts a #gulong value to little-endian byte order.
</para>

@long_val: a #gulong value.
@Returns: the #gulong converted to little-endian.

<!-- ##### MACRO GULONG_FROM_LE ##### -->
<para>
Converts a #gulong value from little-endian to the host byte order.
</para>

@long_val: a #gulong value in little-endian byte order.
@Returns: the #gulong converted to the host byte order.

<!-- ##### MACRO GLONG_TO_BE ##### -->
<para>
Converts a #glong value to big-endian byte order.
</para>

@long_val: a #glong value.
@Returns: the #glong converted to big-endian.

<!-- ##### MACRO GLONG_FROM_BE ##### -->
<para>
Converts a #glong value from big-endian to the host byte order.
</para>

@long_val: a #glong value in big-endian byte order.
@Returns: the #glong converted to the host byte order.

<!-- ##### MACRO GULONG_TO_BE ##### -->
<para>
Converts a #gulong value to big-endian byte order.
</para>

@long_val: a #gulong value.
@Returns: the #gulong converted to big-endian.

<!-- ##### MACRO GULONG_FROM_BE ##### -->
<para>
Converts a #gulong value from big-endian to the host byte order.
</para>

@long_val: a #gulong value in big-endian byte order.
@Returns: the #gulong converted to the host byte order.

<!-- ##### MACRO GULONG_SWAP_LE_BE ##### -->
<para>
Swaps a #gulong value between little-endian and big-endian, and vice versa.
</para>

@long_val: a #gulong value in little-endian or big-endian byte order.
@Returns: the #gulong swapped to the other byte order.

<!-- ##### MACRO GULONG_SWAP_LE_PDP ##### -->
<para>
Swaps a #gulong value between little-endian and PDP-endian, and vice versa.
</para>

@long_val: a #gulong value in little-endian or PDP-endian byte order.
@Returns: the #gulong swapped to the other byte order.

<!-- ##### MACRO GULONG_SWAP_BE_PDP ##### -->
<para>
Swaps a #gulong value between big-endian and PDP-endian, and vice versa.
</para>

@long_val: a #gulong value in big-endian or PDP-endian byte order.
@Returns: the #gulong swapped to the other byte order.

