luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-26 05:56:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Move remaining docs inline

Browse Source 
This introduces a fake source file just for holding
docs that have no good place elsewhere. Not great, but
better than templates.
This commit is contained in:
Matthias Clasen 2011-11-14 07:44:52 -05:00
parent 127df9bd83
commit 3f0d275295
14 changed files with 2330 additions and 2655 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/glib-docs.sgml
View File

@ -43,7 +43,6 @@
<title>GLib Fundamentals</title>
<xi:include href="xml/version.xml" />
<xi:include href="xml/types.xml" />
<xi:include href="xml/limits.xml" />
<xi:include href="xml/macros.xml" />
<xi:include href="xml/type_conversion.xml" />
<xi:include href="xml/byte_order.xml" />

133
docs/reference/glib/glib-sections.txt
View File

@ -11,100 +11,90 @@ guchar
<SUBSECTION>
gint
G_MININT
G_MAXINT
guint
G_MAXUINT
gshort
G_MINSHORT
G_MAXSHORT
gushort
G_MAXUSHORT
glong
G_MINLONG
G_MAXLONG
gulong
G_MAXULONG
<SUBSECTION>
gint8
G_MININT8
G_MAXINT8
guint8
G_MAXUINT8
gint16
G_MININT16
G_MAXINT16
G_GINT16_MODIFIER
G_GINT16_FORMAT
guint16
G_MAXUINT16
G_GUINT16_FORMAT
gint32
G_MININT32
G_MAXINT32
G_GINT32_MODIFIER
G_GINT32_FORMAT
guint32
<SUBSECTION>
G_HAVE_GINT64
G_MAXUINT32
G_GUINT32_FORMAT
gint64
guint64
G_MININT64
G_MAXINT64
G_GINT64_MODIFIER
G_GINT64_FORMAT
G_GINT64_CONSTANT
guint64
G_MAXUINT64
G_GUINT64_FORMAT
G_GUINT64_CONSTANT
<SUBSECTION>
gfloat
G_MINFLOAT
G_MAXFLOAT
gdouble
G_MINDOUBLE
G_MAXDOUBLE
<SUBSECTION>
gsize
G_MAXSIZE
G_GSIZE_MODIFIER
G_GSIZE_FORMAT
gssize
G_MINSSIZE
G_MAXSSIZE
G_GSSIZE_FORMAT
goffset
G_MINOFFSET
G_MAXOFFSET
G_GOFFSET_MODIFIER
G_GOFFSET_FORMAT
G_GOFFSET_CONSTANT
<SUBSECTION>
gintptr
G_GINTPTR_MODIFIER
G_GINTPTR_FORMAT
guintptr
G_GUINTPTR_FORMAT
<SUBSECTION Private>
GLIB_SIZEOF_VOID_P
GLIB_SIZEOF_LONG
GLIB_SIZEOF_SIZE_T
</SECTION>
<SECTION>
<TITLE>Limits of Basic Types</TITLE>
<FILE>limits</FILE>
G_MININT
G_MAXINT
G_MAXUINT
<SUBSECTION>
G_MINSHORT
G_MAXSHORT
G_MAXUSHORT
<SUBSECTION>
G_MINLONG
G_MAXLONG
G_MAXULONG
<SUBSECTION>
G_MININT8
G_MAXINT8
G_MAXUINT8
<SUBSECTION>
G_MININT16
G_MAXINT16
G_MAXUINT16
<SUBSECTION>
G_MININT32
G_MAXINT32
G_MAXUINT32
<SUBSECTION>
G_MININT64
G_MAXINT64
G_MAXUINT64
<SUBSECTION>
G_MAXSIZE
G_MINSSIZE
G_MAXSSIZE
<SUBSECTION>
G_MINOFFSET
G_MAXOFFSET
<SUBSECTION>
G_MINFLOAT
G_MAXFLOAT
<SUBSECTION>
G_MINDOUBLE
G_MAXDOUBLE
G_HAVE_GINT64
</SECTION>
<SECTION>
@ -165,6 +155,8 @@ G_MEM_ALIGN
<SUBSECTION>
G_CONST_RETURN
<SUBSECTION>
G_N_ELEMENTS
</SECTION>
<SECTION>
@ -302,7 +294,6 @@ G_IEEE754_DOUBLE_BIAS
GFloatIEEE754
GDoubleIEEE754
<SUBSECTION>
<SUBSECTION>
G_E
G_LN2
@ -327,9 +318,6 @@ G_STMT_END
G_BEGIN_DECLS
G_END_DECLS
<SUBSECTION>
G_N_ELEMENTS
<SUBSECTION>
G_VA_COPY
@ -374,25 +362,6 @@ G_UNLIKELY
G_STRLOC
G_STRFUNC
<SUBSECTION>
G_GINT16_MODIFIER
G_GINT16_FORMAT
G_GUINT16_FORMAT
G_GINT32_MODIFIER
G_GINT32_FORMAT
G_GUINT32_FORMAT
G_GINT64_MODIFIER
G_GINT64_FORMAT
G_GUINT64_FORMAT
G_GSIZE_MODIFIER
G_GSIZE_FORMAT
G_GSSIZE_FORMAT
G_GOFFSET_MODIFIER
G_GOFFSET_FORMAT
G_GINTPTR_MODIFIER
G_GINTPTR_FORMAT
G_GUINTPTR_FORMAT
<SUBSECTION Private>
GLIB_VAR
G_STRINGIFY_ARG

8
docs/reference/glib/tmpl/.gitignore vendored
View File

@ -6,6 +6,7 @@ async_queues.sgml
atomic_operations.sgml
base64.sgml
bookmarkfile.sgml
byte_order.sgml
caches.sgml
checksum.sgml
completion.sgml
@ -29,8 +30,11 @@ hooks.sgml
iochannels.sgml
i18n.sgml
keyfile.sgml
limits.sgml
linked_lists_double.sgml
linked_lists_single.sgml
macros.sgml
macros_misc.sgml
main.sgml
markup.sgml
memory_chunks.sgml
@ -39,6 +43,7 @@ memory.sgml
messages.sgml
misc_utils.sgml
modules.sgml
numerical.sgml
option.sgml
patterns.sgml
quarks.sgml
@ -61,6 +66,9 @@ timezone.sgml
trash_stack.sgml
trees-binary.sgml
trees-nary.sgml
type_conversion.sgml
types.sgml
unicode.sgml
version.sgml
warnings.sgml
windows.sgml

628
docs/reference/glib/tmpl/byte_order.sgml
View File

@ -1,628 +0,0 @@
<!-- ##### 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.

253
docs/reference/glib/tmpl/limits.sgml
View File

@ -1,253 +0,0 @@
<!-- ##### SECTION Title ##### -->
Limits of Basic Types
<!-- ##### SECTION Short_Description ##### -->
portable method of determining the limits of the standard types
<!-- ##### SECTION Long_Description ##### -->
<para>
These macros provide a portable method to determine the limits of some of
the standard integer and floating point types.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### MACRO G_MININT ##### -->
<para>
The minimum value which can be held in a #gint.
</para>
<!-- ##### MACRO G_MAXINT ##### -->
<para>
The maximum value which can be held in a #gint.
</para>
<!-- ##### MACRO G_MAXUINT ##### -->
<para>
The maximum value which can be held in a #guint.
</para>
<!-- ##### MACRO G_MINSHORT ##### -->
<para>
The minimum value which can be held in a #gshort.
</para>
<!-- ##### MACRO G_MAXSHORT ##### -->
<para>
The maximum value which can be held in a #gshort.
</para>
<!-- ##### MACRO G_MAXUSHORT ##### -->
<para>
The maximum value which can be held in a #gushort.
</para>
<!-- ##### MACRO G_MINLONG ##### -->
<para>
The minimum value which can be held in a #glong.
</para>
<!-- ##### MACRO G_MAXLONG ##### -->
<para>
The maximum value which can be held in a #glong.
</para>
<!-- ##### MACRO G_MAXULONG ##### -->
<para>
The maximum value which can be held in a #gulong.
</para>
<!-- ##### MACRO G_MININT8 ##### -->
<para>
The minimum value which can be held in a #gint8.
</para>
@Since: 2.4
<!-- ##### MACRO G_MAXINT8 ##### -->
<para>
The maximum value which can be held in a #gint8.
</para>
@Since: 2.4
<!-- ##### MACRO G_MAXUINT8 ##### -->
<para>
The maximum value which can be held in a #guint8.
</para>
@Since: 2.4
<!-- ##### MACRO G_MININT16 ##### -->
<para>
The minimum value which can be held in a #gint16.
</para>
@Since: 2.4
<!-- ##### MACRO G_MAXINT16 ##### -->
<para>
The maximum value which can be held in a #gint16.
</para>
@Since: 2.4
<!-- ##### MACRO G_MAXUINT16 ##### -->
<para>
The maximum value which can be held in a #guint16.
</para>
@Since: 2.4
<!-- ##### MACRO G_MININT32 ##### -->
<para>
The minimum value which can be held in a #gint32.
</para>
@Since: 2.4
<!-- ##### MACRO G_MAXINT32 ##### -->
<para>
The maximum value which can be held in a #gint32.
</para>
@Since: 2.4
<!-- ##### MACRO G_MAXUINT32 ##### -->
<para>
The maximum value which can be held in a #guint32.
</para>
@Since: 2.4
<!-- ##### MACRO G_MININT64 ##### -->
<para>
The minimum value which can be held in a #gint64.
</para>
<!-- ##### MACRO G_MAXINT64 ##### -->
<para>
The maximum value which can be held in a #gint64.
</para>
<!-- ##### MACRO G_MAXUINT64 ##### -->
<para>
The maximum value which can be held in a #guint64.
</para>
<!-- ##### MACRO G_MAXSIZE ##### -->
<para>
The maximum value which can be held in a #gsize.
</para>
@Since: 2.4
<!-- ##### MACRO G_MINSSIZE ##### -->
<para>
The minimum value which can be held in a #gssize.
</para>
@Since: 2.14
<!-- ##### MACRO G_MAXSSIZE ##### -->
<para>
The maximum value which can be held in a #gssize.
</para>
@Since: 2.14
<!-- ##### MACRO G_MINOFFSET ##### -->
<para>
The minimum value which can be held in a #goffset.
</para>
<!-- ##### MACRO G_MAXOFFSET ##### -->
<para>
The maximum value which can be held in a #goffset.
</para>
<!-- ##### MACRO G_MINFLOAT ##### -->
<para>
The minimum positive value which can be held in a #gfloat.
</para>
<para>
If you are interested in the smallest value which can be held in a #gfloat,
use -G_MAXFLOAT.
</para>
<!-- ##### MACRO G_MAXFLOAT ##### -->
<para>
The maximum value which can be held in a #gfloat.
</para>
<!-- ##### MACRO G_MINDOUBLE ##### -->
<para>
The minimum positive value which can be held in a #gdouble.
</para>
<para>
If you are interested in the smallest value which can be held in a #gdouble,
use -G_MAXDOUBLE.
</para>
<!-- ##### MACRO G_MAXDOUBLE ##### -->
<para>
The maximum value which can be held in a #gdouble.
</para>

233
docs/reference/glib/tmpl/macros.sgml
View File

@ -1,233 +0,0 @@
<!-- ##### SECTION Title ##### -->
Standard Macros
<!-- ##### SECTION Short_Description ##### -->
commonly-used macros.
<!-- ##### SECTION Long_Description ##### -->
<para>
These macros provide a few commonly-used features.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### MACRO G_OS_WIN32 ##### -->
<para>
This macro is defined only on Windows. So you can bracket
Windows-specific code in "&num;ifdef G_OS_WIN32".
</para>
<!-- ##### MACRO G_OS_BEOS ##### -->
<para>
This macro is defined only on BeOS. So you can bracket
BeOS-specific code in "&num;ifdef G_OS_BEOS".
</para>
<!-- ##### MACRO G_OS_UNIX ##### -->
<para>
This macro is defined only on UNIX. So you can bracket
UNIX-specific code in "&num;ifdef G_OS_UNIX".
</para>
<!-- ##### MACRO G_DIR_SEPARATOR ##### -->
<para>
The directory separator character.
This is '/' on UNIX machines and '\' under Windows.
</para>
<!-- ##### MACRO G_DIR_SEPARATOR_S ##### -->
<para>
The directory separator as a string.
This is "/" on UNIX machines and "\" under Windows.
</para>
<!-- ##### MACRO G_IS_DIR_SEPARATOR ##### -->
<para>
Checks whether a character is a directory
separator. It returns %TRUE for '/' on UNIX
machines and for '\' or '/' under Windows.
</para>
@c: a character
@Since: 2.6
<!-- ##### MACRO G_SEARCHPATH_SEPARATOR ##### -->
<para>
The search path separator character.
This is ':' on UNIX machines and ';' under Windows.
</para>
<!-- ##### MACRO G_SEARCHPATH_SEPARATOR_S ##### -->
<para>
The search path separator as a string.
This is ":" on UNIX machines and ";" under Windows.
</para>
<!-- ##### MACRO TRUE ##### -->
<para>
Defines the %TRUE value for the #gboolean type.
</para>
<!-- ##### MACRO FALSE ##### -->
<para>
Defines the %FALSE value for the #gboolean type.
</para>
<!-- ##### MACRO NULL ##### -->
<para>
Defines the standard %NULL pointer.
</para>
<!-- ##### MACRO MIN ##### -->
<para>
Calculates the minimum of @a and @b.
</para>
@a: a numeric value.
@b: a numeric value.
@Returns: the minimum of @a and @b.
<!-- ##### MACRO MAX ##### -->
<para>
Calculates the maximum of @a and @b.
</para>
@a: a numeric value.
@b: a numeric value.
@Returns: the maximum of @a and @b.
<!-- ##### MACRO ABS ##### -->
<para>
Calculates the absolute value of @a.
The absolute value is simply the number with any negative sign taken away.
</para>
<para>
For example,
<itemizedlist>
<listitem><para>
ABS(-10) is 10.
</para></listitem>
<listitem><para>
ABS(10) is also 10.
</para></listitem>
</itemizedlist>
</para>
@a: a numeric value.
@Returns: the absolute value of @a.
<!-- ##### MACRO CLAMP ##### -->
<para>
Ensures that @x is between the limits set by @low and @high. If @low is
greater than @high the result is undefined.
</para>
<para>
For example,
<itemizedlist>
<listitem><para>
CLAMP(5, 10, 15) is 10.
</para></listitem>
<listitem><para>
CLAMP(15, 5, 10) is 10.
</para></listitem>
<listitem><para>
CLAMP(20, 15, 25) is 20.
</para></listitem>
</itemizedlist>
</para>
@x: the value to clamp.
@low: the minimum value allowed.
@high: the maximum value allowed.
@Returns: the value of @x clamped to the range between @low and @high.
<!-- ##### MACRO G_STRUCT_MEMBER ##### -->
<para>
Returns a member of a structure at a given offset, using the given type.
</para>
@member_type: the type of the struct field.
@struct_p: a pointer to a struct.
@struct_offset: the offset of the field from the start of the struct, in bytes.
@Returns: the struct member.
<!-- ##### MACRO G_STRUCT_MEMBER_P ##### -->
<para>
Returns an untyped pointer to a given offset of a struct.
</para>
@struct_p: a pointer to a struct.
@struct_offset: the offset from the start of the struct, in bytes.
@Returns: an untyped pointer to @struct_p plus @struct_offset bytes.
<!-- ##### MACRO G_STRUCT_OFFSET ##### -->
<para>
Returns the offset, in bytes, of a member of a struct.
</para>
@struct_type: a structure type, e.g. <structname>GtkWidget</structname>.
@member: a field in the structure, e.g. <structfield>window</structfield>.
@Returns: the offset of @member from the start of @struct_type.
<!-- ##### MACRO G_MEM_ALIGN ##### -->
<para>
</para>
<!-- ##### MACRO G_CONST_RETURN ##### -->
<para>
If %G_DISABLE_CONST_RETURNS is defined, this macro expands to nothing.
By default, the macro expands to <literal>const</literal>. The macro
should be used in place of <literal>const</literal> for functions that
return a value that should not be modified. The purpose of this macro is
to allow us to turn on <literal>const</literal> for returned constant
strings by default, while allowing programmers who find that annoying to
turn it off. This macro should only be used for return values and for
<emphasis>out</emphasis> parameters, it doesn't make sense for
<emphasis>in</emphasis> parameters.
</para>
@Deprecated: 2.30: API providers should replace all existing uses with
<literal>const</literal> and API consumers should adjust their code
accordingly.

743
docs/reference/glib/tmpl/macros_misc.sgml
View File

@ -1,743 +0,0 @@
<!-- ##### SECTION Title ##### -->
Miscellaneous Macros
<!-- ##### SECTION Short_Description ##### -->
specialized macros which are not used often
<!-- ##### SECTION Long_Description ##### -->
<para>
These macros provide more specialized features which are not needed so often
by application programmers.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### MACRO G_INLINE_FUNC ##### -->
<para>
This macro is used to export function prototypes so they can be linked
with an external version when no inlining is performed. The file which
implements the functions should define %G_IMPLEMENTS_INLINES
before including the headers which contain %G_INLINE_FUNC declarations.
Since inlining is very compiler-dependent using these macros correctly
is very difficult. Their use is strongly discouraged.
</para>
<para>
This macro is often mistaken for a replacement for the inline keyword;
inline is already declared in a portable manner in the glib headers
and can be used normally.
</para>
<!-- ##### MACRO G_STMT_START ##### -->
<para>
Used within multi-statement macros so that they can be used in places where
only one statement is expected by the compiler.
</para>
<!-- ##### MACRO G_STMT_END ##### -->
<para>
Used within multi-statement macros so that they can be used in places where
only one statement is expected by the compiler.
</para>
<!-- ##### MACRO G_BEGIN_DECLS ##### -->
<para>
Used (along with #G_END_DECLS) to bracket header files. If the
compiler in use is a C++ compiler, adds <literal>extern "C"</literal>
around the header.
</para>
<!-- ##### MACRO G_END_DECLS ##### -->
<para>
Used (along with #G_BEGIN_DECLS) to bracket header files. If the
compiler in use is a C++ compiler, adds <literal>extern "C"</literal>
around the header.
</para>
<!-- ##### MACRO G_N_ELEMENTS ##### -->
<para>
Determines the number of elements in an array. The array must be
declared so the compiler knows its size at compile-time; this
macro will not work on an array allocated on the heap, only static
arrays or arrays on the stack.
</para>
@arr: the array
<!-- ##### MACRO G_VA_COPY ##### -->
<para>
Portable way to copy <type>va_list</type> variables.
</para>
<para>
In order to use this function, you must include <filename>string.h</filename>
yourself, because this macro may use <function>memmove()</function> and GLib
does not include <function>string.h</function> for you.
</para>
@ap1: the <type>va_list</type> variable to place a copy of @ap2 in.
@ap2: a <type>va_list</type>.
<!-- ##### MACRO G_STRINGIFY ##### -->
<para>
Accepts a macro or a string and converts it into a string after
preprocessor argument expansion. For example, the following code:
</para>
<informalexample><programlisting>
#define AGE 27
const gchar *greeting = G_STRINGIFY (AGE) " today!";
</programlisting></informalexample>
<para>
is transformed by the preprocessor into (code equivalent to):
</para>
<informalexample><programlisting>
const gchar *greeting = "27 today!";
</programlisting></informalexample>
@macro_or_string: a macro or a string.
<!-- ##### MACRO G_PASTE ##### -->
<para>
Yields a new preprocessor pasted identifier <code>identifier1identifier2</code>
from its expanded arguments @identifier1 and @identifier2. For example, the
following code:
</para>
<informalexample><programlisting>
#define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller)
const gchar *name = GET (traveller, name);
const gchar *quest = GET (traveller, quest);
GdkColor *favourite = GET (traveller, favourite_colour);
</programlisting></informalexample>
<para>
is transformed by the preprocessor into:
</para>
<informalexample><programlisting>
const gchar *name = traveller_get_name (traveller);
const gchar *quest = traveller_get_quest (traveller);
GdkColor *favourite = traveller_get_favourite_colour (traveller);
</programlisting></informalexample>
@identifier1: an identifier
@identifier2: an identifier
@Since: 2.20
<!-- ##### MACRO G_STATIC_ASSERT ##### -->
<para>
The G_STATIC_ASSERT macro lets the programmer check a condition at compile time,
the condition needs to be compile time computable.
The macro can be used in any place where a <literal>typedef</literal> is valid.
</para>
<note><para>
A <literal>typedef</literal> is generally allowed in exactly the same
places that a variable declaration is allowed. For this reason, you should not use <literal>G_STATIC_ASSERT</literal> in the middle of blocks of code.
</para></note>
<para>
The macro should only be used once per source code line.
</para>
@expr: a constant expression.
@Since: 2.20
<!-- ##### MACRO G_STATIC_ASSERT_EXPR ##### -->
<para>
The G_STATIC_ASSERT_EXPR macro lets the programmer check a condition at
compile time. The condition needs to be compile time computable.
</para>
<para>
Unlike <literal>G_STATIC_ASSERT</literal>, this macro evaluates to an
expression and, as such, can be used in the middle of other expressions.
Its value should be ignored. This can be accomplished by placing it as
the first argument of a comma expression.
</para>
<informalexample><programlisting>
#define ADD_ONE_TO_INT(x) \
(G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1))
</programlisting></informalexample>
@expr: a constant expression.
@Since: 2.30
<!-- ##### MACRO G_GNUC_EXTENSION ##### -->
<para>
Expands to <literal>__extension__</literal> when <command>gcc</command> is
used as the compiler.
This simply tells <command>gcc</command> not to warn about the following non-standard code
when compiling with the <option>-pedantic</option> option.
</para>
<!-- ##### MACRO G_GNUC_CONST ##### -->
<para>
Expands to the GNU C <literal>const</literal> function attribute if the compiler is
<command>gcc</command>. Declaring a function as const enables better optimization of calls
to the function. A const function doesn't examine any values except its parameters, and has no
effects except its return value. See the GNU C documentation for details.
</para>
<note><para>
A function that has pointer arguments and examines the data pointed to
must <emphasis>not</emphasis> be declared const. Likewise, a function that
calls a non-const function usually must not be const. It doesn't make sense
for a const function to return void.
</para></note>
<!-- ##### MACRO G_GNUC_PURE ##### -->
<para>
Expands to the GNU C <literal>pure</literal> function attribute if the compiler is
<command>gcc</command>. Declaring a function as pure enables better optimization of
calls to the function. A pure function has no effects except its return value and the
return value depends only on the parameters and/or global variables.
See the GNU C documentation for details.
</para>
<!-- ##### MACRO G_GNUC_MALLOC ##### -->
<para>
Expands to the GNU C <literal>malloc</literal> function attribute if the
compiler is <command>gcc</command>. Declaring a function as malloc enables
better optimization of the function. A function can have the malloc attribute
if it returns a pointer which is guaranteed to not alias with any other pointer
when the function returns (in practice, this means newly allocated memory).
See the GNU C documentation for details.
</para>
@Since: 2.6
<!-- ##### MACRO G_GNUC_ALLOC_SIZE ##### -->
<para>
Expands to the GNU C <literal>alloc_size</literal> function attribute if the
compiler is a new enough <command>gcc</command>. This attribute tells the
compiler that the function returns a pointer to memory of a size that is
specified by the @x<!-- -->th function parameter.
See the GNU C documentation for details.
</para>
@x: the index of the argument specifying the allocation size
@Since: 2.18
<!-- ##### MACRO G_GNUC_ALLOC_SIZE2 ##### -->
<para>
Expands to the GNU C <literal>alloc_size</literal> function attribute if the
compiler is a new enough <command>gcc</command>. This attribute tells the
compiler that the function returns a pointer to memory of a size that is
specified by the product of two function parameters.
See the GNU C documentation for details.
</para>
@x: the index of the argument specifying one factor of the allocation size
@y: the index of the argument specifying the second factor of the allocation size
@Since: 2.18
<!-- ##### MACRO G_GNUC_DEPRECATED ##### -->
<para>
Expands to the GNU C <literal>deprecated</literal> attribute if the compiler
is <command>gcc</command>.
It can be used to mark typedefs, variables and functions as deprecated.
When called with the <option>-Wdeprecated-declarations</option> option, the compiler will
generate warnings when deprecated interfaces are used.
See the GNU C documentation for details.
</para>
@Since: 2.2
<!-- ##### MACRO G_GNUC_DEPRECATED_FOR ##### -->
<para>
Like %G_GNUC_DEPRECATED, but names the intended replacement for the
deprecated symbol if the version of <command>gcc</command> in use is
new enough to support custom deprecation messages.
See the GNU C documentation for details.
</para>
<para>
Note that if <literal>f</literal> is a macro, it will be expanded in
the warning message. You can enclose it in quotes to prevent this.
(The quotes will show up in the warning, but it's better than showing
the macro expansion.)
</para>
@f: the intended replacement for the deprecated symbol, such as the name of a
function
@Since: 2.26
<!-- ##### MACRO G_GNUC_NORETURN ##### -->
<para>
Expands to the GNU C <literal>noreturn</literal> function attribute if the
compiler is <command>gcc</command>. It is used for declaring functions which never return.
It enables optimization of the function, and avoids possible compiler
warnings. See the GNU C documentation for details.
</para>
<!-- ##### MACRO G_GNUC_UNUSED ##### -->
<para>
Expands to the GNU C <literal>unused</literal> function attribute if the compiler is
<command>gcc</command>. It is used for declaring functions which may never be used.
It avoids possible compiler warnings. See the GNU C documentation for details.
</para>
<!-- ##### MACRO G_GNUC_PRINTF ##### -->
<para>
Expands to the GNU C <literal>format</literal> function attribute if the compiler is
<command>gcc</command>. This is used for declaring functions which take a variable number of
arguments, with the same syntax as <function>printf()</function>.
It allows the compiler to type-check the arguments passed to the function.
See the GNU C documentation for details.
</para>
<informalexample><programlisting>
gint g_snprintf (gchar *string,
gulong n,
gchar const *format,
...) G_GNUC_PRINTF (3, 4);
</programlisting></informalexample>
@format_idx: the index of the argument corresponding to the format string.
(The arguments are numbered from 1).
@arg_idx: the index of the first of the format arguments.
<!-- ##### MACRO G_GNUC_SCANF ##### -->
<para>
Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
This is used for declaring functions which take a variable number of
arguments, with the same syntax as <function>scanf()</function>.
It allows the compiler to type-check the arguments passed to the function.
See the GNU C documentation for details.
</para>
@format_idx: the index of the argument corresponding to the format string.
(The arguments are numbered from 1).
@arg_idx: the index of the first of the format arguments.
<!-- ##### MACRO G_GNUC_FORMAT ##### -->
<para>
Expands to the GNU C <literal>format_arg</literal> function attribute if the compiler is <command>gcc</command>.
This function attribute specifies that a function takes a format
string for a <function>printf()</function>, <function>scanf()</function>,
<function>strftime()</function> or <function>strfmon()</function> style
function and modifies it, so that the result can be passed to a
<function>printf()</function>, <function>scanf()</function>,
<function>strftime()</function> or <function>strfmon()</function> style
function (with the remaining arguments to the format function the same as
they would have been for the unmodified string).
See the GNU C documentation for details.
</para>
<informalexample><programlisting>
gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
</programlisting></informalexample>
@arg_idx: the index of the argument.
<!-- ##### MACRO G_GNUC_NULL_TERMINATED ##### -->
<para>
Expands to the GNU C <literal>sentinel</literal> function attribute if the
compiler is <command>gcc</command>, or "" if it isn't. This function attribute
only applies to variadic functions and instructs the compiler to check that
the argument list is terminated with an explicit %NULL.
See the GNU C documentation for details.
</para>
Since: 2.8
<!-- ##### MACRO G_GNUC_WARN_UNUSED_RESULT ##### -->
<para>
Expands to the GNU C <literal>warn_unused_result</literal> function attribute
if the compiler is <command>gcc</command>, or "" if it isn't. This function
attribute makes the compiler emit a warning if the result of a function call
is ignored. See the GNU C documentation for details.
</para>
@Since: 2.10
<!-- ##### MACRO G_GNUC_FUNCTION ##### -->
<para>
Expands to "" on all modern compilers, and to <literal>__FUNCTION__</literal>
on <command>gcc</command> version 2.x. Don't use it.
</para>
@Deprecated: 2.16: Use #G_STRFUNC instead.
<!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
<para>
Expands to "" on all modern compilers, and to
<literal>__PRETTY_FUNCTION__</literal> on <command>gcc</command> version 2.x.
Don't use it.
</para>
@Deprecated: 2.16: Use #G_STRFUNC instead.
<!-- ##### MACRO G_GNUC_NO_INSTRUMENT ##### -->
<para>
Expands to the GNU C <literal>no_instrument_function</literal> function
attribute if the compiler is <command>gcc</command>. Functions with this
attribute will not be
instrumented for profiling, when the compiler is called with the
<option>-finstrument-functions</option> option.
See the GNU C documentation for details.
</para>
<!-- ##### MACRO G_HAVE_GNUC_VISIBILITY ##### -->
<para>
</para>
<!-- ##### MACRO G_GNUC_INTERNAL ##### -->
<para>
This attribute can be used for marking library functions as being used
internally to the library only, which may allow the compiler to handle
function calls more efficiently.
Note that static functions do not need to be marked as internal in this way.
See the GNU C documentation for details.
</para>
<para>
When using a compiler that supports the GNU C hidden visibility attribute,
this macro expands to <literal>__attribute__((visibility("hidden")))</literal>.
When using the Sun Studio compiler, it expands to <literal>__hidden</literal>.
</para>
<para>
Note that for portability, the attribute should be placed before the
function declaration. While GCC allows the macro after the declaration,
Sun Studio does not.
</para>
<informalexample><programlisting>
G_GNUC_INTERNAL
void _g_log_fallback_handler (const gchar *log_domain,
GLogLevelFlags log_level,
const gchar *message,
gpointer unused_data);
</programlisting></informalexample>
Since: 2.6
<!-- ##### MACRO G_GNUC_MAY_ALIAS ##### -->
<para>
Expands to the GNU C <literal>may_alias</literal> type attribute
if the compiler is <command>gcc</command>. Types with this attribute
will not be subjected to type-based alias analysis, but are assumed
to alias with any other type, just like char.
See the GNU C documentation for details.
</para>
Since: 2.14
<!-- ##### MACRO G_DEPRECATED ##### -->
<para>
</para>
<!-- ##### MACRO G_DEPRECATED_FOR ##### -->
<para>
</para>
@f:
<!-- ##### MACRO G_LIKELY ##### -->
<para>
Hints the compiler that the expression is likely to evaluate to a true
value. The compiler may use this information for optimizations.
</para>
<informalexample><programlisting>
if (G_LIKELY (random () != 1))
g_print ("not one");
</programlisting></informalexample>
@expr: the expression
@Returns: the value of @expr
@Since: 2.2
<!-- ##### MACRO G_UNLIKELY ##### -->
<para>
Hints the compiler that the expression is unlikely to evaluate to a true
value. The compiler may use this information for optimizations.
</para>
<informalexample><programlisting>
if (G_UNLIKELY (random () == 1))
g_print ("a random one");
</programlisting></informalexample>
@expr: the expression
@Returns: the value of @expr
@Since: 2.2
<!-- ##### MACRO G_STRLOC ##### -->
<para>
Expands to a string identifying the current code position.
</para>
<!-- ##### MACRO G_STRFUNC ##### -->
<para>
Expands to a string identifying the current function.
</para>
@Since: 2.4
<!-- ##### MACRO G_GINT16_MODIFIER ##### -->
<para>
The platform dependent length modifier for conversion specifiers for scanning
and printing values of type #gint16 or #guint16. It is a string literal,
but doesn't include the percent-sign, such that you can add precision and
length modifiers between percent-sign and conversion specifier and append a
conversion specifier.
</para>
<para>
The following example prints "0x7b";
<informalexample>
<programlisting>
gint16 value = 123;
g_print ("%#" G_GINT16_MODIFIER "x", value);
</programlisting>
</informalexample>
</para>
@Since: 2.4
<!-- ##### MACRO G_GINT16_FORMAT ##### -->
<para>
This is the platform dependent conversion specifier for scanning and
printing values of type #gint16. It is a string literal, but doesn't
include the percent-sign, such that you can add precision and length
modifiers between percent-sign and conversion specifier.
</para>
<para>
<informalexample>
<programlisting>
gint16 in;
gint32 out;
sscanf ("42", "%" G_GINT16_FORMAT, &amp;in)
out = in * 1000;
g_print ("%" G_GINT32_FORMAT, out);
</programlisting>
</informalexample>
</para>
<!-- ##### MACRO G_GUINT16_FORMAT ##### -->
<para>
This is the platform dependent conversion specifier for scanning and
printing values of type #guint16. See also #G_GINT16_FORMAT.
</para>
<!-- ##### MACRO G_GINT32_MODIFIER ##### -->
<para>
The platform dependent length modifier for conversion specifiers for scanning
and printing values of type #gint32 or #guint32. It is a string literal,
See also #G_GINT16_MODIFIER.
</para>
@Since: 2.4
<!-- ##### MACRO G_GINT32_FORMAT ##### -->
<para>
This is the platform dependent conversion specifier for scanning and
printing values of type #gint32. See also #G_GINT16_FORMAT.
</para>
<!-- ##### MACRO G_GUINT32_FORMAT ##### -->
<para>
This is the platform dependent conversion specifier for scanning and
printing values of type #guint32. See also #G_GINT16_FORMAT.
</para>
<!-- ##### MACRO G_GINT64_MODIFIER ##### -->
<para>
The platform dependent length modifier for conversion specifiers for scanning
and printing values of type #gint64 or #guint64. It is a string literal.
</para>
<note>
<para>
Some platforms do not support printing 64 bit integers,
even though the types are supported. On such platforms #G_GINT64_MODIFIER
is not defined.
</para>
</note>
@Since: 2.4
<!-- ##### MACRO G_GINT64_FORMAT ##### -->
<para>
This is the platform dependent conversion specifier for scanning and
printing values of type #gint64. See also #G_GINT16_FORMAT.
</para>
<note>
<para>
Some platforms do not support scanning and printing 64 bit integers,
even though the types are supported. On such platforms #G_GINT64_FORMAT
is not defined. Note that scanf() may not support 64 bit integers, even
if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
is not recommended for parsing anyway; consider using g_ascii_strtoull()
instead.
</para>
</note>
<!-- ##### MACRO G_GUINT64_FORMAT ##### -->
<para>
This is the platform dependent conversion specifier for scanning and
printing values of type #guint64. See also #G_GINT16_FORMAT.
</para>
<note>
<para>
Some platforms do not support scanning and printing 64 bit integers,
even though the types are supported. On such platforms #G_GUINT64_FORMAT
is not defined. Note that scanf() may not support 64 bit integers, even
if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
is not recommended for parsing anyway; consider using g_ascii_strtoull()
instead.
</para>
</note>
<!-- ##### MACRO G_GSIZE_MODIFIER ##### -->
<para>
The platform dependent length modifier for conversion specifiers for scanning
and printing values of type #gsize or #gssize. It is a string literal,
</para>
@Since: 2.6
<!-- ##### MACRO G_GSIZE_FORMAT ##### -->
<para>
This is the platform dependent conversion specifier for scanning and
printing values of type #gsize. See also #G_GINT16_FORMAT.
</para>
@Since: 2.6
<!-- ##### MACRO G_GSSIZE_FORMAT ##### -->
<para>
This is the platform dependent conversion specifier for scanning and
printing values of type #gssize. See also #G_GINT16_FORMAT.
</para>
@Since: 2.6
<!-- ##### MACRO G_GOFFSET_MODIFIER ##### -->
<para>
The platform dependent length modifier for conversion specifiers for scanning
and printing values of type #goffset. It is a string literal. See also
#G_GINT64_MODIFIER.
</para>
@Since: 2.20
<!-- ##### MACRO G_GOFFSET_FORMAT ##### -->
<para>
This is the platform dependent conversion specifier for scanning and
printing values of type #goffset. See also #G_GINT64_FORMAT.
</para>
Since: 2.20
<!-- ##### MACRO G_GINTPTR_MODIFIER ##### -->
<para>
The platform dependent length modifier for conversion specifiers for scanning
and printing values of type #gintptr or #guintptr. It is a string literal.
</para>
@Since: 2.22
<!-- ##### MACRO G_GINTPTR_FORMAT ##### -->
<para>
This is the platform dependent conversion specifier for scanning and
printing values of type #gintptr.
</para>
@Since: 2.22
<!-- ##### MACRO G_GUINTPTR_FORMAT ##### -->
<para>
This is the platform dependent conversion specifier for scanning and
printing values of type #guintptr.
</para>
@Since: 2.22

121
docs/reference/glib/tmpl/numerical.sgml
View File

@ -1,121 +0,0 @@
<!-- ##### SECTION Title ##### -->
Numerical Definitions
<!-- ##### SECTION Short_Description ##### -->
mathematical constants, and floating point decomposition
<!-- ##### SECTION Long_Description ##### -->
<para>
GLib offers mathematical constants such as #G_PI for the value of pi;
many platforms have these in the C library, but some don't, the GLib
versions always exist.
</para>
<para>
The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the
sign, mantissa and exponent of IEEE floats and doubles. These unions are
defined as appropriate for a given platform. IEEE floats and doubles are
supported (used for storage) by at least Intel, PPC and Sparc. See
<ulink url="http://en.wikipedia.org/wiki/IEEE_float">IEEE 754-2008</ulink>
for more information about IEEE number formats.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### MACRO G_IEEE754_FLOAT_BIAS ##### -->
<para>
The bias by which exponents in single-precision floats are offset.
</para>
<!-- ##### MACRO G_IEEE754_DOUBLE_BIAS ##### -->
<para>
The bias by which exponents in double-precision floats are offset.
</para>
<!-- ##### UNION GFloatIEEE754 ##### -->
<para>
The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
mantissa and exponent of IEEE floats and doubles. These unions are defined
as appropriate for a given platform. IEEE floats and doubles are supported
(used for storage) by at least Intel, PPC and Sparc.
</para>
<!-- ##### UNION GDoubleIEEE754 ##### -->
<para>
The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
mantissa and exponent of IEEE floats and doubles. These unions are defined
as appropriate for a given platform. IEEE floats and doubles are supported
(used for storage) by at least Intel, PPC and Sparc.
</para>
<!-- ##### MACRO G_E ##### -->
<para>
The base of natural logarithms.
</para>
<!-- ##### MACRO G_LN2 ##### -->
<para>
The natural logarithm of 2.
</para>
<!-- ##### MACRO G_LN10 ##### -->
<para>
The natural logarithm of 10.
</para>
<!-- ##### MACRO G_PI ##### -->
<para>
The value of pi (ratio of circle's circumference to its diameter).
</para>
<!-- ##### MACRO G_PI_2 ##### -->
<para>
Pi divided by 2.
</para>
<!-- ##### MACRO G_PI_4 ##### -->
<para>
Pi divided by 4.
</para>
<!-- ##### MACRO G_SQRT2 ##### -->
<para>
The square root of two.
</para>
<!-- ##### MACRO G_LOG_2_BASE_10 ##### -->
<para>
Multiplying the base 2 exponent by this number yields the base 10 exponent.
</para>

125
docs/reference/glib/tmpl/type_conversion.sgml
View File

@ -1,125 +0,0 @@
<!-- ##### SECTION Title ##### -->
Type Conversion Macros
<!-- ##### SECTION Short_Description ##### -->
portably storing integers in pointer variables
<!-- ##### SECTION Long_Description ##### -->
<para>
Many times GLib, GTK+, and other libraries allow you to pass "user
data" to a callback, in the form of a void pointer. From time to time
you want to pass an integer instead of a pointer. You could allocate
an integer, with something like:
<informalexample><programlisting>
int *ip = g_new (int, 1);
*ip = 42;
</programlisting></informalexample>
But this is inconvenient, and it's annoying to have to free the
memory at some later time.
</para>
<para>
Pointers are always at least 32 bits in size (on all platforms GLib
intends to support). Thus you can store at least 32-bit integer values
in a pointer value. Naively, you might try this, but it's incorrect:
<informalexample><programlisting>
gpointer p;
int i;
p = (void*) 42;
i = (int) p;
</programlisting></informalexample>
Again, that example was <emphasis>not</emphasis> correct, don't copy it.
The problem is that on some systems you need to do this:
<informalexample><programlisting>
gpointer p;
int i;
p = (void*) (long) 42;
i = (int) (long) p;
</programlisting></informalexample>
So GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. do the right thing
on the current platform.
</para>
<para>
<warning>
<para>
YOU MAY NOT STORE POINTERS IN INTEGERS. THIS IS NOT PORTABLE IN ANY
WAY SHAPE OR FORM. These macros <emphasis>ONLY</emphasis> allow
storing integers in pointers, and only preserve 32 bits of the
integer; values outside the range of a 32-bit integer will be mangled.
</para>
</warning>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### MACRO GINT_TO_POINTER ##### -->
<para>
Stuffs an integer into a pointer type.
</para>
<para>
Remember, YOU MAY NOT STORE POINTERS IN INTEGERS. THIS IS NOT PORTABLE
IN ANY WAY SHAPE OR FORM. These macros <emphasis>ONLY</emphasis> allow
storing integers in pointers, and only preserve 32 bits of the
integer; values outside the range of a 32-bit integer will be mangled.
</para>
@i: integer to stuff into a pointer.
<!-- ##### MACRO GPOINTER_TO_INT ##### -->
<para>
Extracts an integer from a pointer. The integer must have
been stored in the pointer with GINT_TO_POINTER().
</para>
<para>
Remember, YOU MAY NOT STORE POINTERS IN INTEGERS. THIS IS NOT PORTABLE
IN ANY WAY SHAPE OR FORM. These macros <emphasis>ONLY</emphasis> allow
storing integers in pointers, and only preserve 32 bits of the
integer; values outside the range of a 32-bit integer will be mangled.
</para>
@p: pointer containing an integer.
<!-- ##### MACRO GUINT_TO_POINTER ##### -->
<para>
Stuffs an unsigned integer into a pointer type.
</para>
@u: unsigned integer to stuff into the pointer.
<!-- ##### MACRO GPOINTER_TO_UINT ##### -->
<para>
Extracts an unsigned integer from a pointer. The integer must have
been stored in the pointer with GUINT_TO_POINTER().
</para>
@p: pointer to extract an unsigned integer from.
<!-- ##### MACRO GSIZE_TO_POINTER ##### -->
<para>
Stuffs a #gsize into a pointer type.
</para>
@s: #gsize to stuff into the pointer.
<!-- ##### MACRO GPOINTER_TO_SIZE ##### -->
<para>
Extracts a #gsize from a pointer. The #gsize must have
been stored in the pointer with GSIZE_TO_POINTER().
</para>
@p: pointer to extract a #gsize from.

327
docs/reference/glib/tmpl/types.sgml
View File

@ -1,327 +0,0 @@
<!-- ##### SECTION Title ##### -->
Basic Types
<!-- ##### SECTION Short_Description ##### -->
standard GLib types, defined for ease-of-use and portability
<!-- ##### SECTION Long_Description ##### -->
<para>
GLib defines a number of commonly used types, which can be divided into
4 groups:
<itemizedlist>
<listitem><para>
New types which are not part of standard C (but are defined
in various C standard library header files) -
#gboolean, #gsize, #gssize, #goffset, #gintptr, #guintptr.
</para></listitem>
<listitem><para>
Integer types which are guaranteed to be the same size across all platforms -
#gint8, #guint8, #gint16, #guint16, #gint32, #guint32, #gint64, #guint64.
</para></listitem>
<listitem><para>
Types which are easier to use than their standard C counterparts -
#gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
</para></listitem>
<listitem><para>
Types which correspond exactly to standard C types, but are included
for completeness - #gchar, #gint, #gshort, #glong, #gfloat, #gdouble.
</para></listitem>
</itemizedlist>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### TYPEDEF gboolean ##### -->
<para>
A standard <type>boolean</type> type.
Variables of this type should only contain the value %TRUE or %FALSE.
</para>
<!-- ##### TYPEDEF gpointer ##### -->
<para>
An untyped pointer.
#gpointer looks better and is easier to use than <type>void*</type>.
</para>
<!-- ##### TYPEDEF gconstpointer ##### -->
<para>
An untyped pointer to constant data.
The data pointed to should not be changed.
</para>
<para>
This is typically used in function prototypes to indicate that the
data pointed to will not be altered by the function.
</para>
<!-- ##### TYPEDEF gchar ##### -->
<para>
Corresponds to the standard C <type>char</type> type.
</para>
<!-- ##### TYPEDEF guchar ##### -->
<para>
Corresponds to the standard C <type>unsigned char</type> type.
</para>
<!-- ##### TYPEDEF gint ##### -->
<para>
Corresponds to the standard C <type>int</type> type.
Values of this type can range from #G_MININT to #G_MAXINT.
</para>
<!-- ##### TYPEDEF guint ##### -->
<para>
Corresponds to the standard C <type>unsigned int</type> type.
Values of this type can range from 0 to #G_MAXUINT.
</para>
<!-- ##### TYPEDEF gshort ##### -->
<para>
Corresponds to the standard C <type>short</type> type.
Values of this type can range from #G_MINSHORT to #G_MAXSHORT.
</para>
<!-- ##### TYPEDEF gushort ##### -->
<para>
Corresponds to the standard C <type>unsigned short</type> type.
Values of this type can range from 0 to #G_MAXUSHORT.
</para>
<!-- ##### TYPEDEF glong ##### -->
<para>
Corresponds to the standard C <type>long</type> type.
Values of this type can range from #G_MINLONG to #G_MAXLONG.
</para>
<!-- ##### TYPEDEF gulong ##### -->
<para>
Corresponds to the standard C <type>unsigned long</type> type.
Values of this type can range from 0 to #G_MAXULONG.
</para>
<!-- ##### TYPEDEF gint8 ##### -->
<para>
A signed integer guaranteed to be 8 bits on all platforms.
Values of this type can range from #G_MININT8 (= -128) to
#G_MAXINT8 (= 127).
</para>
<!-- ##### TYPEDEF guint8 ##### -->
<para>
An unsigned integer guaranteed to be 8 bits on all platforms.
Values of this type can range from 0 to #G_MAXUINT8 (= 255).
</para>
<!-- ##### TYPEDEF gint16 ##### -->
<para>
A signed integer guaranteed to be 16 bits on all platforms.
Values of this type can range from #G_MININT16 (= -32,768) to
#G_MAXINT16 (= 32,767).
</para>
<para>
To print or scan values of this type, use
%G_GINT16_MODIFIER and/or %G_GINT16_FORMAT.
</para>
<!-- ##### TYPEDEF guint16 ##### -->
<para>
An unsigned integer guaranteed to be 16 bits on all platforms.
Values of this type can range from 0 to #G_MAXUINT16 (= 65,535).
</para>
<para>
To print or scan values of this type, use
%G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT.
</para>
<!-- ##### TYPEDEF gint32 ##### -->
<para>
A signed integer guaranteed to be 32 bits on all platforms.
Values of this type can range from #G_MININT32 (= -2,147,483,648) to
#G_MAXINT32 (= 2,147,483,647).
</para>
<para>
To print or scan values of this type, use
%G_GINT32_MODIFIER and/or %G_GINT32_FORMAT.
</para>
<!-- ##### TYPEDEF guint32 ##### -->
<para>
An unsigned integer guaranteed to be 32 bits on all platforms.
Values of this type can range from 0 to #G_MAXUINT32 (= 4,294,967,295).
</para>
<para>
To print or scan values of this type, use
%G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
</para>
<!-- ##### MACRO G_HAVE_GINT64 ##### -->
<para>
This macro is defined if 64-bit signed and unsigned integers are available
on the platform.
</para>
@Deprecated: GLib requires 64-bit integer support since version 2.0, therefore
%G_HAVE_GINT64 is <emphasis>always</emphasis> defined.
<!-- ##### TYPEDEF gint64 ##### -->
<para>
A signed integer guaranteed to be 64 bits on all platforms.
Values of this type can range from #G_MININT64 (= -9,223,372,036,854,775,808) to
#G_MAXINT64 (= 9,223,372,036,854,775,807).
</para>
<para>
To print or scan values of this type, use
%G_GINT64_MODIFIER and/or %G_GINT64_FORMAT.
</para>
<!-- ##### TYPEDEF guint64 ##### -->
<para>
An unsigned integer guaranteed to be 64 bits on all platforms.
Values of this type can range from 0 to #G_MAXUINT64 (= 18,446,744,073,709,551,615).
</para>
<para>
To print or scan values of this type, use
%G_GINT64_MODIFIER and/or %G_GUINT64_FORMAT.
</para>
<!-- ##### MACRO G_GINT64_CONSTANT ##### -->
<para>
This macro is used to insert 64-bit integer literals into the source code.
</para>
@val: a literal integer value, e.g. 0x1d636b02300a7aa7.
<!-- ##### MACRO G_GUINT64_CONSTANT ##### -->
<para>
This macro is used to insert 64-bit unsigned integer literals into the
source code.
</para>
@val: a literal integer value, e.g. 0x1d636b02300a7aa7U.
@Since: 2.10
<!-- ##### TYPEDEF gfloat ##### -->
<para>
Corresponds to the standard C <type>float</type> type.
Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT.
</para>
<!-- ##### TYPEDEF gdouble ##### -->
<para>
Corresponds to the standard C <type>double</type> type.
Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE.
</para>
<!-- ##### TYPEDEF gsize ##### -->
<para>
An unsigned integer type of the result of the sizeof operator, corresponding
to the size_t type defined in C99. This type is wide enough to hold the numeric
value of a pointer, so it is usually 32bit wide on a 32bit platform and
64bit wide on a 64bit platform.
Values of this type can range from 0 to #G_MAXSIZE.
</para>
<para>
To print or scan values of this type, use
%G_GSIZE_MODIFIER and/or %G_GSIZE_FORMAT.
</para>
<!-- ##### TYPEDEF gssize ##### -->
<para>
A signed variant of gsize, corresponding to the ssize_t defined on most platforms.
Values of this type can range from #G_MINSSIZE to #G_MAXSSIZE.
</para>
<para>
To print or scan values of this type, use
%G_GSIZE_MODIFIER and/or %G_GSSIZE_FORMAT.
</para>
<!-- ##### TYPEDEF goffset ##### -->
<para>
A signed integer type that is used for file offsets, corresponding to the
C99 type off64_t.
Values of this type can range from #G_MINOFFSET to #G_MAXOFFSET.
</para>
<para>
To print or scan values of this type, use
%G_GOFFSET_MODIFIER and/or %G_GOFFSET_FORMAT.
</para>
Since: 2.14
<!-- ##### MACRO G_GOFFSET_CONSTANT ##### -->
<para>
This macro is used to insert #goffset 64-bit integer literals into the source code.
See also #G_GINT64_CONSTANT.
</para>
@val: a literal integer value, e.g. 0x1d636b02300a7aa7.
Since: 2.20
<!-- ##### TYPEDEF gintptr ##### -->
<para>
Corresponds to the C99 type <type>intptr_t</type>, a signed integer type that
can hold any pointer.
</para>
<para>
To print or scan values of this type, use
%G_GINTPTR_MODIFIER and/or %G_GINTPTR_FORMAT.
</para>
Since: 2.18
<!-- ##### TYPEDEF guintptr ##### -->
<para>
Corresponds to the C99 type <type>uintptr_t</type>, an unsigned integer type that
can hold any pointer.
</para>
<para>
To print or scan values of this type, use
%G_GINTPTR_MODIFIER and/or %G_GUINTPTR_FORMAT.
</para>
Since: 2.18

142
docs/reference/glib/tmpl/windows.sgml
View File

@ -1,142 +0,0 @@
<!-- ##### SECTION Title ##### -->
Windows Compatibility Functions
<!-- ##### SECTION Short_Description ##### -->
UNIX emulation on Windows
<!-- ##### SECTION Long_Description ##### -->
<para>
These functions provide some level of UNIX emulation on the Windows platform.
If your application really needs the POSIX APIs, we suggest you try the Cygwin
project.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### MACRO MAXPATHLEN ##### -->
<para>
Provided for UNIX emulation on Windows; equivalent to UNIX
macro %MAXPATHLEN, which is the maximum length of a filename
(including full path).
</para>
<!-- ##### FUNCTION g_win32_error_message ##### -->
<para>
</para>
@error:
@Returns:
<!-- ##### FUNCTION g_win32_getlocale ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_win32_get_package_installation_directory ##### -->
<para>
</para>
@package:
@dll_name:
@Returns:
<!-- ##### FUNCTION g_win32_get_package_installation_directory_of_module ##### -->
<para>
</para>
@hmodule:
@Returns:
<!-- ##### FUNCTION g_win32_get_package_installation_subdirectory ##### -->
<para>
</para>
@package:
@dll_name:
@subdir:
@Returns:
<!-- ##### FUNCTION g_win32_get_windows_version ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_win32_locale_filename_from_utf8 ##### -->
<para>
</para>
@utf8filename:
@Returns:
<!-- ##### MACRO G_WIN32_DLLMAIN_FOR_DLL_NAME ##### -->
<para>
On Windows, this macro defines a DllMain() function that stores the actual
DLL name that the code being compiled will be included in.
</para>
<para>
On non-Windows platforms, expands to nothing.
</para>
@static: empty or "static".
@dll_name: the name of the (pointer to the) char array where the DLL name
will be stored. If this is used, you must also include
<filename>windows.h</filename>. If you need a more complex DLL entry
point function, you cannot use this.
<!-- ##### MACRO G_WIN32_HAVE_WIDECHAR_API ##### -->
<para>
On Windows, this macro defines an expression which evaluates to %TRUE
if the code is running on a version of Windows where the wide
character versions of the Win32 API functions, and the wide chaacter
versions of the C library functions work. (They are always present in
the DLLs, but don't work on Windows 9x and Me.)
</para>
<para>
On non-Windows platforms, it is not defined.
</para>
@Since: 2.6
<!-- ##### MACRO G_WIN32_IS_NT_BASED ##### -->
<para>
On Windows, this macro defines an expression which evaluates to %TRUE
if the code is running on an NT-based Windows operating system.
</para>
<para>
On non-Windows platforms, it is not defined.
</para>
@Since: 2.6

1
glib/Makefile.am
View File

@ -85,6 +85,7 @@ EXTRA_DIST += \
gregex.h \
win_iconv.c \
libglib-gdb.py.in \
docs.c \
$(MIRRORING_TAB_SOURCE)
# These may be in the builddir too

2259
glib/docs.c Normal file
View File

File diff suppressed because it is too large Load Diff

11
glib/gtimer.c
View File

@ -236,6 +236,17 @@ g_timer_elapsed (GTimer *timer,
return total;
}
/**
* g_usleep:
* @microseconds: number of microseconds to pause
*
* Pauses the current thread for the given number of microseconds.
*
* There are 1 million microseconds per second (represented by the
* #G_USEC_PER_SEC macro). g_usleep() may have limited precision,
* depending on hardware and operating system; don't rely on the exact
* length of the sleep.
*/
void
g_usleep (gulong microseconds)
{