byte_order.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<refentry id="glib-Byte-Order-Macros">
<refmeta>
<refentrytitle>Byte Order Macros</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Byte Order Macros</refname><refpurpose>a portable way to convert between different byte orders.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


#define     <link linkend="G-BYTE-ORDER-CAPS">G_BYTE_ORDER</link>
#define     <link linkend="G-LITTLE-ENDIAN-CAPS">G_LITTLE_ENDIAN</link>
#define     <link linkend="G-BIG-ENDIAN-CAPS">G_BIG_ENDIAN</link>
#define     <link linkend="G-PDP-ENDIAN-CAPS">G_PDP_ENDIAN</link>

#define     <link linkend="g-htonl">g_htonl</link>                         (val)
#define     <link linkend="g-htons">g_htons</link>                         (val)
#define     <link linkend="g-ntohl">g_ntohl</link>                         (val)
#define     <link linkend="g-ntohs">g_ntohs</link>                         (val)

#define     <link linkend="GINT-FROM-BE-CAPS">GINT_FROM_BE</link>                    (val)
#define     <link linkend="GINT-FROM-LE-CAPS">GINT_FROM_LE</link>                    (val)
#define     <link linkend="GINT-TO-BE-CAPS">GINT_TO_BE</link>                      (val)
#define     <link linkend="GINT-TO-LE-CAPS">GINT_TO_LE</link>                      (val)

#define     <link linkend="GUINT-FROM-BE-CAPS">GUINT_FROM_BE</link>                   (val)
#define     <link linkend="GUINT-FROM-LE-CAPS">GUINT_FROM_LE</link>                   (val)
#define     <link linkend="GUINT-TO-BE-CAPS">GUINT_TO_BE</link>                     (val)
#define     <link linkend="GUINT-TO-LE-CAPS">GUINT_TO_LE</link>                     (val)

#define     <link linkend="GLONG-FROM-BE-CAPS">GLONG_FROM_BE</link>                   (val)
#define     <link linkend="GLONG-FROM-LE-CAPS">GLONG_FROM_LE</link>                   (val)
#define     <link linkend="GLONG-TO-BE-CAPS">GLONG_TO_BE</link>                     (val)
#define     <link linkend="GLONG-TO-LE-CAPS">GLONG_TO_LE</link>                     (val)

#define     <link linkend="GULONG-FROM-BE-CAPS">GULONG_FROM_BE</link>                  (val)
#define     <link linkend="GULONG-FROM-LE-CAPS">GULONG_FROM_LE</link>                  (val)
#define     <link linkend="GULONG-TO-BE-CAPS">GULONG_TO_BE</link>                    (val)
#define     <link linkend="GULONG-TO-LE-CAPS">GULONG_TO_LE</link>                    (val)

#define     <link linkend="GINT16-FROM-BE-CAPS">GINT16_FROM_BE</link>                  (val)
#define     <link linkend="GINT16-FROM-LE-CAPS">GINT16_FROM_LE</link>                  (val)
#define     <link linkend="GINT16-TO-BE-CAPS">GINT16_TO_BE</link>                    (val)
#define     <link linkend="GINT16-TO-LE-CAPS">GINT16_TO_LE</link>                    (val)

#define     <link linkend="GUINT16-FROM-BE-CAPS">GUINT16_FROM_BE</link>                 (val)
#define     <link linkend="GUINT16-FROM-LE-CAPS">GUINT16_FROM_LE</link>                 (val)
#define     <link linkend="GUINT16-TO-BE-CAPS">GUINT16_TO_BE</link>                   (val)
#define     <link linkend="GUINT16-TO-LE-CAPS">GUINT16_TO_LE</link>                   (val)

#define     <link linkend="GINT32-FROM-BE-CAPS">GINT32_FROM_BE</link>                  (val)
#define     <link linkend="GINT32-FROM-LE-CAPS">GINT32_FROM_LE</link>                  (val)
#define     <link linkend="GINT32-TO-BE-CAPS">GINT32_TO_BE</link>                    (val)
#define     <link linkend="GINT32-TO-LE-CAPS">GINT32_TO_LE</link>                    (val)

#define     <link linkend="GUINT32-FROM-BE-CAPS">GUINT32_FROM_BE</link>                 (val)
#define     <link linkend="GUINT32-FROM-LE-CAPS">GUINT32_FROM_LE</link>                 (val)
#define     <link linkend="GUINT32-TO-BE-CAPS">GUINT32_TO_BE</link>                   (val)
#define     <link linkend="GUINT32-TO-LE-CAPS">GUINT32_TO_LE</link>                   (val)

#define     <link linkend="GINT64-FROM-BE-CAPS">GINT64_FROM_BE</link>                  (val)
#define     <link linkend="GINT64-FROM-LE-CAPS">GINT64_FROM_LE</link>                  (val)
#define     <link linkend="GINT64-TO-BE-CAPS">GINT64_TO_BE</link>                    (val)
#define     <link linkend="GINT64-TO-LE-CAPS">GINT64_TO_LE</link>                    (val)

#define     <link linkend="GUINT64-FROM-BE-CAPS">GUINT64_FROM_BE</link>                 (val)
#define     <link linkend="GUINT64-FROM-LE-CAPS">GUINT64_FROM_LE</link>                 (val)
#define     <link linkend="GUINT64-TO-BE-CAPS">GUINT64_TO_BE</link>                   (val)
#define     <link linkend="GUINT64-TO-LE-CAPS">GUINT64_TO_LE</link>                   (val)

#define     <link linkend="GUINT16-SWAP-BE-PDP-CAPS">GUINT16_SWAP_BE_PDP</link>             (val)
#define     <link linkend="GUINT16-SWAP-LE-BE-CAPS">GUINT16_SWAP_LE_BE</link>              (val)
#define     <link linkend="GUINT16-SWAP-LE-PDP-CAPS">GUINT16_SWAP_LE_PDP</link>             (val)

#define     <link linkend="GUINT32-SWAP-BE-PDP-CAPS">GUINT32_SWAP_BE_PDP</link>             (val)
#define     <link linkend="GUINT32-SWAP-LE-BE-CAPS">GUINT32_SWAP_LE_BE</link>              (val)
#define     <link linkend="GUINT32-SWAP-LE-PDP-CAPS">GUINT32_SWAP_LE_PDP</link>             (val)

#define     <link linkend="GUINT64-SWAP-LE-BE-CAPS">GUINT64_SWAP_LE_BE</link>              (val)

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<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 <link linkend="gint">gint</link> and <link linkend="glong">glong</link> 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>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="G-BYTE-ORDER-CAPS">G_BYTE_ORDER</title>
<programlisting>#define G_BYTE_ORDER G_LITTLE_ENDIAN
</programlisting>
<para>
The host byte order.
This can be either <link linkend="G-LITTLE-ENDIAN-CAPS">G_LITTLE_ENDIAN</link> or <link linkend="G-BIG-ENDIAN-CAPS">G_BIG_ENDIAN</link> (support for
<link linkend="G-PDP-ENDIAN-CAPS">G_PDP_ENDIAN</link> may be added in future.)
</para></refsect2>
<refsect2>
<title><anchor id="G-LITTLE-ENDIAN-CAPS">G_LITTLE_ENDIAN</title>
<programlisting>#define G_LITTLE_ENDIAN 1234
</programlisting>
<para>
Specifies one of the possible types of byte order.
See <link linkend="G-BYTE-ORDER-CAPS">G_BYTE_ORDER</link>.
</para></refsect2>
<refsect2>
<title><anchor id="G-BIG-ENDIAN-CAPS">G_BIG_ENDIAN</title>
<programlisting>#define G_BIG_ENDIAN    4321
</programlisting>
<para>
Specifies one of the possible types of byte order.
See <link linkend="G-BYTE-ORDER-CAPS">G_BYTE_ORDER</link>.
</para></refsect2>
<refsect2>
<title><anchor id="G-PDP-ENDIAN-CAPS">G_PDP_ENDIAN</title>
<programlisting>#define G_PDP_ENDIAN    3412		/* unused, need specific PDP check */	
</programlisting>
<para>
Specifies one of the possible types of byte order (currently unused).
See <link linkend="G-BYTE-ORDER-CAPS">G_BYTE_ORDER</link>.
</para></refsect2>
<refsect2>
<title><anchor id="g-htonl">g_htonl()</title>
<programlisting>#define     g_htonl(val)</programlisting>
<para>
Converts a 32-bit integer value from host to network byte order.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>val</parameter>&nbsp;:</entry>
<entry>a 32-bit integer value in host byte order.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><parameter>val</parameter> converted to network byte order.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-htons">g_htons()</title>
<programlisting>#define     g_htons(val)</programlisting>
<para>
Converts a 16-bit integer value from host to network byte order.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>val</parameter>&nbsp;:</entry>
<entry>a 16-bit integer value in host byte order.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><parameter>val</parameter> converted to network byte order.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ntohl">g_ntohl()</title>
<programlisting>#define     g_ntohl(val)</programlisting>
<para>
Converts a 32-bit integer value from network to host byte order.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>val</parameter>&nbsp;:</entry>
<entry>a 32-bit integer value in network byte order.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><parameter>val</parameter> converted to host byte order.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ntohs">g_ntohs()</title>
<programlisting>#define     g_ntohs(val)</programlisting>
<para>
Converts a 16-bit integer value from network to host byte order.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>val</parameter>&nbsp;:</entry>
<entry>a 16-bit integer value in network byte order.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><parameter>val</parameter> converted to host byte order.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GINT-FROM-BE-CAPS">GINT_FROM_BE()</title>
<programlisting>#define GINT_FROM_BE(val)	(GINT_TO_BE (val))
</programlisting>
<para>
Converts a <link linkend="gint">gint</link> value from big-endian to host byte order.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>val</parameter>&nbsp;:</entry>
<entry>a <link linkend="gint">gint</link> value in big-endian byte order.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><parameter>val</parameter> converted to host byte order.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GINT-FROM-LE-CAPS">GINT_FROM_LE()</title>
<programlisting>#define GINT_FROM_LE(val)	(GINT_TO_LE (val))
</programlisting>
<para>
Converts a <link linkend="gint">gint</link> value from little-endian to host byte order.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>val</parameter>&nbsp;:</entry>
<entry>a <link linkend="gint">gint</link> value in little-endian byte order.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><parameter>val</parameter> converted to host byte order.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GINT-TO-BE-CAPS">GINT_TO_BE()</title>
<programlisting>#define GINT_TO_BE(val)		((gint) GINT32_TO_BE (val))
</programlisting>
<para>
Converts a <link linkend="gint">gint</link> value from host byte order to big-endian.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">