glib/docs/reference/glib/tmpl/byte_order.sgml

<!-- ##### 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. 
</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.
The host byte order is the byte order used on the current machine.
</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>
<para>
Note that the byte order conversion macros may evaluate their arguments 
multiple times, thus you should not use them with arguments which have
side-effects.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### SECTION Image ##### -->


<!-- ##### 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 g_htonl ##### -->
<para>
Converts a 32-bit integer value from host to network byte order.
</para>

@val: a 32-bit integer value in host byte order.
@Returns: @val converted to network byte order.


<!-- ##### MACRO g_htons ##### -->
<para>
Converts a 16-bit integer value from host to network byte order.
</para>

@val: a 16-bit integer value in host byte order.
@Returns: @val converted to network byte order.


<!-- ##### MACRO g_ntohl ##### -->
<para>
Converts a 32-bit integer value from network to host byte order.
</para>

@val: a 32-bit integer value in network byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO g_ntohs ##### -->
<para>
Converts a 16-bit integer value from network to host byte order.
</para>

@val: a 16-bit integer value in network byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GINT_FROM_BE ##### -->
<para>
Converts a #gint value from big-endian to host byte order.
</para>

@val: a #gint value in big-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GINT_FROM_LE ##### -->
<para>
Converts a #gint value from little-endian to host byte order.
</para>

@val: a #gint value in little-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GINT_TO_BE ##### -->
<para>
Converts a #gint value from host byte order to big-endian.
</para>

@val: a #gint value in host byte order.
@Returns: @val converted to big-endian byte order.


<!-- ##### MACRO GINT_TO_LE ##### -->
<para>
Converts a #gint value from host byte order to little-endian.
</para>

@val: a #gint value in host byte order.
@Returns: @val converted to little-endian byte order.


<!-- ##### MACRO GUINT_FROM_BE ##### -->
<para>
Converts a #guint value from big-endian to host byte order.
</para>

@val: a #guint value in big-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GUINT_FROM_LE ##### -->
<para>
Converts a #guint value from little-endian to host byte order.
</para>

@val: a #guint value in little-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GUINT_TO_BE ##### -->
<para>
Converts a #guint value from host byte order to big-endian.
</para>

@val: a #guint value in host byte order.
@Returns: @val converted to big-endian byte order.


<!-- ##### MACRO GUINT_TO_LE ##### -->
<para>
Converts a #guint value from host byte order to little-endian.
</para>

@val: a #guint value in host byte order.
@Returns: @val converted to little-endian byte order.


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

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


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

@val: a #gsize value in big-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GSIZE_FROM_LE ##### -->
<para>
Converts a #gsize value from little-endian to host byte order.
</para>

@val: a #gsize value in little-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GSIZE_TO_BE ##### -->
<para>
Converts a #gsize value from host byte order to big-endian.
</para>

@val: a #gsize value in host byte order.
@Returns: @val converted to big-endian byte order.


<!-- ##### MACRO GSIZE_TO_LE ##### -->
<para>
Converts a #gsize value from host byte order to little-endian.
</para>

@val: a #gsize value in host byte order.
@Returns: @val converted to little-endian.


<!-- ##### MACRO GSSIZE_FROM_BE ##### -->
<para>
Converts a #gssize value from big-endian to host byte order.
</para>

@val: a #gssize value in big-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GSSIZE_FROM_LE ##### -->
<para>
Converts a #gssize value from little-endian to host byte order.
</para>

@val: a #gssize value in little-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GSSIZE_TO_BE ##### -->
<para>
Converts a #gssize value from host byte order to big-endian.
</para>

@val: a #gssize value in host byte order.
@Returns: @val converted to big-endian.


<!-- ##### MACRO GSSIZE_TO_LE ##### -->
<para>
Converts a #gssize value from host byte order to little-endian.
</para>

@val: a #gssize value in host byte order.
@Returns: @val converted to little-endian.


<!-- ##### MACRO GINT16_FROM_BE ##### -->
<para>
Converts a #gint16 value from big-endian to host byte order.
</para>

@val: a #gint16 value in big-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GINT16_FROM_LE ##### -->
<para>
Converts a #gint16 value from little-endian to host byte order.
</para>

@val: a #gint16 value in little-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GINT16_TO_BE ##### -->
<para>
Converts a #gint16 value from host byte order to big-endian.
</para>

@val: a #gint16 value in host byte order.
@Returns: @val converted to big-endian.


<!-- ##### MACRO GINT16_TO_LE ##### -->
<para>
Converts a #gint16 value from host byte order to little-endian.
</para>

@val: a #gint16 value in host byte order.
@Returns: @val converted to little-endian.


<!-- ##### MACRO GUINT16_FROM_BE ##### -->
<para>
Converts a #guint16 value from big-endian to host byte order.
</para>

@val: a #guint16 value in big-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GUINT16_FROM_LE ##### -->
<para>
Converts a #guint16 value from little-endian to host byte order.
</para>

@val: a #guint16 value in little-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GUINT16_TO_BE ##### -->
<para>
Converts a #guint16 value from host byte order to big-endian.
</para>

@val: a #guint16 value in host byte order.
@Returns: @val converted to big-endian.


<!-- ##### MACRO GUINT16_TO_LE ##### -->
<para>
Converts a #guint16 value from host byte order to little-endian.
</para>

@val: a #guint16 value in host byte order.
@Returns: @val converted to little-endian.


<!-- ##### MACRO GINT32_FROM_BE ##### -->
<para>
Converts a #gint32 value from big-endian to host byte order.
</para>

@val: a #gint32 value in big-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GINT32_FROM_LE ##### -->
<para>
Converts a #gint32 value from little-endian to host byte order.
</para>

@val: a #gint32 value in little-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GINT32_TO_BE ##### -->
<para>
Converts a #gint32 value from host byte order to big-endian.
</para>

@val: a #gint32 value in host byte order.
@Returns: @val converted to big-endian.


<!-- ##### MACRO GINT32_TO_LE ##### -->
<para>
Converts a #gint32 value from host byte order to little-endian.
</para>

@val: a #gint32 value in host byte order.
@Returns: @val converted to little-endian.


<!-- ##### MACRO GUINT32_FROM_BE ##### -->
<para>
Converts a #guint32 value from big-endian to host byte order.
</para>

@val: a #guint32 value in big-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GUINT32_FROM_LE ##### -->
<para>
Converts a #guint32 value from little-endian to host byte order.
</para>

@val: a #guint32 value in little-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GUINT32_TO_BE ##### -->
<para>
Converts a #guint32 value from host byte order to big-endian.
</para>

@val: a #guint32 value in host byte order.
@Returns: @val converted to big-endian.


<!-- ##### MACRO GUINT32_TO_LE ##### -->
<para>
Converts a #guint32 value from host byte order to little-endian.
</para>

@val: a #guint32 value in host byte order.
@Returns: @val converted to little-endian.


<!-- ##### MACRO GINT64_FROM_BE ##### -->
<para>
Converts a #gint64 value from big-endian to host byte order.
</para>

@val: a #gint64 value in big-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GINT64_FROM_LE ##### -->
<para>
Converts a #gint64 value from little-endian to host byte order.
</para>

@val: a #gint64 value in little-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GINT64_TO_BE ##### -->
<para>
Converts a #gint64 value from host byte order to big-endian.
</para>

@val: a #gint64 value in host byte order.
@Returns: @val converted to big-endian.


<!-- ##### MACRO GINT64_TO_LE ##### -->
<para>
Converts a #gint64 value from host byte order to little-endian.
</para>

@val: a #gint64 value in host byte order.
@Returns: @val converted to little-endian.


<!-- ##### MACRO GUINT64_FROM_BE ##### -->
<para>
Converts a #guint64 value from big-endian to host byte order.
</para>

@val: a #guint64 value in big-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GUINT64_FROM_LE ##### -->
<para>
Converts a #guint64 value from little-endian to host byte order.
</para>

@val: a #guint64 value in little-endian byte order.
@Returns: @val converted to host byte order.


<!-- ##### MACRO GUINT64_TO_BE ##### -->
<para>
Converts a #guint64 value from host byte order to big-endian.
</para>

@val: a #guint64 value in host byte order.
@Returns: @val converted to big-endian.


<!-- ##### MACRO GUINT64_TO_LE ##### -->
<para>
Converts a #guint64 value from host byte order to little-endian.
</para>

@val: a #guint64 value in host byte order.
@Returns: @val converted to little-endian.


<!-- ##### MACRO GUINT16_SWAP_BE_PDP ##### -->
<para>
Converts a #guint16 value between big-endian and pdp-endian byte order.
The conversion is symmetric so it can be used both ways.
</para>

@val: a #guint16 value in big-endian or pdp-endian byte order.
@Returns: @val converted to the opposite byte order.


<!-- ##### MACRO GUINT16_SWAP_LE_BE ##### -->
<para>
Converts a #guint16 value between little-endian and big-endian byte order.
The conversion is symmetric so it can be used both ways.
</para>

@val: a #guint16 value in little-endian or big-endian byte order.
@Returns: @val converted to the opposite byte order.


<!-- ##### MACRO GUINT16_SWAP_LE_PDP ##### -->
<para>
Converts a #guint16 value between little-endian and pdp-endian byte order.
The conversion is symmetric so it can be used both ways.
</para>

@val: a #guint16 value in little-endian or pdp-endian byte order.
@Returns: @val converted to the opposite byte order.


<!-- ##### MACRO GUINT32_SWAP_BE_PDP ##### -->
<para>
Converts a #guint32 value between big-endian and pdp-endian byte order.
The conversion is symmetric so it can be used both ways.
</para>

@val: a #guint32 value in big-endian or pdp-endian byte order.
@Returns: @val converted to the opposite byte order.


<!-- ##### MACRO GUINT32_SWAP_LE_BE ##### -->
<para>
Converts a #guint32 value between little-endian and big-endian byte order.
The conversion is symmetric so it can be used both ways.
</para>

@val: a #guint32 value in little-endian or big-endian byte order.
@Returns: @val converted to the opposite byte order.


<!-- ##### MACRO GUINT32_SWAP_LE_PDP ##### -->
<para>
Converts a #guint32 value between little-endian and pdp-endian byte order.
The conversion is symmetric so it can be used both ways.
</para>

@val: a #guint32 value in little-endian or pdp-endian byte order.
@Returns: @val converted to the opposite byte order.


<!-- ##### MACRO GUINT64_SWAP_LE_BE ##### -->
<para>
Converts a #guint64 value between little-endian and big-endian byte order.
The conversion is symmetric so it can be used both ways.
</para>

@val: a #guint64 value in little-endian or big-endian byte order.
@Returns: @val converted to the opposite byte order.