| <!-- ##### 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 ##### --> |
| |
| |
| <!-- ##### 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 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. |
| |
| |