Integrate gnulib vasnprintf().

[platform/upstream/glib.git] / docs / reference / glib / tmpl / macros_misc.sgml

diff --git a/docs/reference/glib/tmpl/macros_misc.sgml b/docs/reference/glib/tmpl/macros_misc.sgml
index bdccfc6..d66ff4f 100644 (file)
--- a/docs/reference/glib/tmpl/macros_misc.sgml
+++ b/docs/reference/glib/tmpl/macros_misc.sgml
@@ -118,9 +118,23 @@ for a const function to return void.
 
 
 
+<!-- ##### 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</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_NORETURN ##### -->
 <para>
-Expands to the GNU C <literal>noreturn</literal> function attribute if the compiler is <command>gcc</command>.
+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. 
@@ -237,6 +251,34 @@ See the GNU C documentation for details.
 
 
 
+<!-- ##### 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
+@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
+@Since: 2.2
+
+
 <!-- ##### MACRO G_STRLOC ##### -->
 <para>
 Expands to a string identifying the current code position. 
@@ -244,6 +286,28 @@ Expands to a string identifying the current code position.
 
 
 
+<!-- ##### MACRO G_GINT16_MODIFIER ##### -->
+<para>
+The platform dependent length modifier for constructing printf() conversion
+specifiers for 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 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
@@ -274,6 +338,14 @@ printing values of type #guint16. See also #G_GINT16_FORMAT.
 
 
 
+<!-- ##### MACRO G_GINT32_MODIFIER ##### -->
+<para>
+The platform dependent length modifier for constructing printf() conversion
+specifiers for values of type #gint32. See also #G_GINT16_MODIFIER.
+</para>
+
+@Since: 2.4
+
 <!-- ##### MACRO G_GINT32_FORMAT ##### -->
 <para>
 This is the platform dependent conversion specifier for scanning and
@@ -290,6 +362,22 @@ printing values of type #guint32. See also #G_GINT16_FORMAT.
 
 
 
+<!-- ##### MACRO G_GINT64_MODIFIER ##### -->
+<para>
+The platform dependent length modifier for constructing printf() conversion
+specifiers for values of type #gint32. See also #G_GINT16_MODIFIER.
+</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
@@ -300,7 +388,9 @@ printing values of type #gint64. See also #G_GINT16_FORMAT.
 <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.
+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_strtoull() instead.
 </para>
 </note>
 
@@ -316,7 +406,9 @@ printing values of type #guint64. See also #G_GINT16_FORMAT.
 <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.
+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_strtoull() instead.
 </para>
 </note>