Convert external links to markdown syntax
[platform/upstream/glib.git] / glib / docs.c
1 /*
2  * Copyright © 2011 Red Hat, Inc
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2 of the licence, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
16  *
17  * Author: Matthias Clasen
18  */
19
20
21 /* This file collects documentation for macros, typedefs and
22  * the like, which have no good home in any of the 'real' source
23  * files.
24  */
25
26 /* Basic types {{{1 */
27
28 /**
29  * SECTION:types
30  * @title: Basic Types
31  * @short_description: standard GLib types, defined for ease-of-use
32  *     and portability
33  *
34  * GLib defines a number of commonly used types, which can be divided
35  * into 4 groups:
36  * - New types which are not part of standard C (but are defined in
37  *   various C standard library header files) - #gboolean, #gsize,
38  *   #gssize, #goffset, #gintptr, #guintptr.
39  * - Integer types which are guaranteed to be the same size across
40  *   all platforms - #gint8, #guint8, #gint16, #guint16, #gint32,
41  *   #guint32, #gint64, #guint64.
42  * - Types which are easier to use than their standard C counterparts -
43  *   #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
44  * - Types which correspond exactly to standard C types, but are
45  *   included for completeness - #gchar, #gint, #gshort, #glong,
46  *   #gfloat, #gdouble.
47  *
48  * GLib also defines macros for the limits of some of the standard
49  * integer and floating point types, as well as macros for suitable
50  * printf() formats for these types.
51  */
52
53 /**
54  * gboolean:
55  *
56  * A standard boolean type.
57  * Variables of this type should only contain the value
58  * %TRUE or %FALSE.
59  */
60
61 /**
62  * gpointer:
63  *
64  * An untyped pointer.
65  * #gpointer looks better and is easier to use than void*.
66  */
67
68 /**
69  * gconstpointer:
70  *
71  * An untyped pointer to constant data.
72  * The data pointed to should not be changed.
73  *
74  * This is typically used in function prototypes to indicate
75  * that the data pointed to will not be altered by the function.
76  */
77
78 /**
79  * gchar:
80  *
81  * Corresponds to the standard C char type.
82  */
83
84 /**
85  * guchar:
86  *
87  * Corresponds to the standard C unsigned char type.
88  */
89
90 /**
91  * gint:
92  *
93  * Corresponds to the standard C int type.
94  * Values of this type can range from #G_MININT to #G_MAXINT.
95  */
96
97 /**
98  * G_MININT:
99  *
100  * The minimum value which can be held in a #gint.
101  */
102
103 /**
104  * G_MAXINT:
105  *
106  * The maximum value which can be held in a #gint.
107  */
108
109 /**
110  * guint:
111  *
112  * Corresponds to the standard C unsigned int type.
113  * Values of this type can range from 0 to #G_MAXUINT.
114  */
115
116 /**
117  * G_MAXUINT:
118  *
119  * The maximum value which can be held in a #guint.
120  */
121
122 /**
123  * gshort:
124  *
125  * Corresponds to the standard C short type.
126  * Values of this type can range from #G_MINSHORT to #G_MAXSHORT.
127  */
128
129 /**
130  * G_MINSHORT:
131  *
132  * The minimum value which can be held in a #gshort.
133  */
134
135 /**
136  * G_MAXSHORT:
137  *
138  * The maximum value which can be held in a #gshort.
139  */
140
141 /**
142  * gushort:
143  *
144  * Corresponds to the standard C unsigned short type.
145  * Values of this type can range from 0 to #G_MAXUSHORT.
146  */
147
148 /**
149  * G_MAXUSHORT:
150  *
151  * The maximum value which can be held in a #gushort.
152  */
153
154 /**
155  * glong:
156  *
157  * Corresponds to the standard C long type.
158  * Values of this type can range from #G_MINLONG to #G_MAXLONG.
159  */
160
161 /**
162  * G_MINLONG:
163  *
164  * The minimum value which can be held in a #glong.
165  */
166
167 /**
168  * G_MAXLONG:
169  *
170  * The maximum value which can be held in a #glong.
171  */
172
173 /**
174  * gulong:
175  *
176  * Corresponds to the standard C unsigned long type.
177  * Values of this type can range from 0 to #G_MAXULONG.
178  */
179
180 /**
181  * G_MAXULONG:
182  *
183  * The maximum value which can be held in a #gulong.
184  */
185
186 /**
187  * gint8:
188  *
189  * A signed integer guaranteed to be 8 bits on all platforms.
190  * Values of this type can range from #G_MININT8 (= -128) to
191  * #G_MAXINT8 (= 127).
192  */
193
194 /**
195  * G_MININT8:
196  *
197  * The minimum value which can be held in a #gint8.
198  *
199  * Since: 2.4
200  */
201
202 /**
203  * G_MAXINT8:
204  *
205  * The maximum value which can be held in a #gint8.
206  *
207  * Since: 2.4
208  */
209
210 /**
211  * guint8:
212  *
213  * An unsigned integer guaranteed to be 8 bits on all platforms.
214  * Values of this type can range from 0 to #G_MAXUINT8 (= 255).
215  */
216
217 /**
218  * G_MAXUINT8:
219  *
220  * The maximum value which can be held in a #guint8.
221  *
222  * Since: 2.4
223  */
224
225 /**
226  * gint16:
227  *
228  * A signed integer guaranteed to be 16 bits on all platforms.
229  * Values of this type can range from #G_MININT16 (= -32,768) to
230  * #G_MAXINT16 (= 32,767).
231  *
232  * To print or scan values of this type, use
233  * %G_GINT16_MODIFIER and/or %G_GINT16_FORMAT.
234  */
235
236 /**
237  * G_MININT16:
238  *
239  * The minimum value which can be held in a #gint16.
240  *
241  * Since: 2.4
242  */
243
244 /**
245  * G_MAXINT16:
246  *
247  * The maximum value which can be held in a #gint16.
248  *
249  * Since: 2.4
250  */
251
252 /**
253  * G_GINT16_MODIFIER:
254  *
255  * The platform dependent length modifier for conversion specifiers
256  * for scanning and printing values of type #gint16 or #guint16. It
257  * is a string literal, but doesn't include the percent-sign, such
258  * that you can add precision and length modifiers between percent-sign
259  * and conversion specifier and append a conversion specifier.
260  *
261  * The following example prints "0x7b";
262  * |[<!-- language="C" -->
263  * gint16 value = 123;
264  * g_print ("%#" G_GINT16_MODIFIER "x", value);
265  * ]|
266  *
267  * Since: 2.4
268  */
269
270 /**
271  * G_GINT16_FORMAT:
272  *
273  * This is the platform dependent conversion specifier for scanning and
274  * printing values of type #gint16. It is a string literal, but doesn't
275  * include the percent-sign, such that you can add precision and length
276  * modifiers between percent-sign and conversion specifier.
277  *
278  * |[<!-- language="C" -->
279  * gint16 in;
280  * gint32 out;
281  * sscanf ("42", "%" G_GINT16_FORMAT, &in)
282  * out = in * 1000;
283  * g_print ("%" G_GINT32_FORMAT, out);
284  * ]|
285  */
286
287 /**
288  * guint16:
289  *
290  * An unsigned integer guaranteed to be 16 bits on all platforms.
291  * Values of this type can range from 0 to #G_MAXUINT16 (= 65,535).
292  *
293  * To print or scan values of this type, use
294  * %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT.
295  */
296
297 /**
298  * G_MAXUINT16:
299  *
300  * The maximum value which can be held in a #guint16.
301  *
302  * Since: 2.4
303  */
304
305 /**
306  * G_GUINT16_FORMAT:
307  *
308  * This is the platform dependent conversion specifier for scanning
309  * and printing values of type #guint16. See also #G_GINT16_FORMAT
310  */
311
312 /**
313  * gint32:
314  *
315  * A signed integer guaranteed to be 32 bits on all platforms.
316  * Values of this type can range from #G_MININT32 (= -2,147,483,648)
317  * to #G_MAXINT32 (= 2,147,483,647).
318  *
319  * To print or scan values of this type, use
320  * %G_GINT32_MODIFIER and/or %G_GINT32_FORMAT.
321  */
322
323 /**
324  * G_MININT32:
325  *
326  * The minimum value which can be held in a #gint32.
327  *
328  * Since: 2.4
329  */
330
331 /**
332  * G_MAXINT32:
333  *
334  * The maximum value which can be held in a #gint32.
335  *
336  * Since: 2.4
337  */
338
339 /**
340  * G_GINT32_MODIFIER:
341  *
342  * The platform dependent length modifier for conversion specifiers
343  * for scanning and printing values of type #gint32 or #guint32. It
344  * is a string literal. See also #G_GINT16_MODIFIER.
345  *
346  * Since: 2.4
347  */
348
349 /**
350  * G_GINT32_FORMAT:
351  *
352  * This is the platform dependent conversion specifier for scanning
353  * and printing values of type #gint32. See also #G_GINT16_FORMAT.
354  */
355
356 /**
357  * guint32:
358  *
359  * An unsigned integer guaranteed to be 32 bits on all platforms.
360  * Values of this type can range from 0 to #G_MAXUINT32 (= 4,294,967,295).
361  *
362  * To print or scan values of this type, use
363  * %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
364  */
365
366 /**
367  * G_MAXUINT32:
368  *
369  * The maximum value which can be held in a #guint32.
370  *
371  * Since: 2.4
372  */
373
374 /**
375  * G_GUINT32_FORMAT:
376  *
377  * This is the platform dependent conversion specifier for scanning
378  * and printing values of type #guint32. See also #G_GINT16_FORMAT.
379  */
380
381 /**
382  * gint64:
383  *
384  * A signed integer guaranteed to be 64 bits on all platforms.
385  * Values of this type can range from #G_MININT64
386  * (= -9,223,372,036,854,775,808) to #G_MAXINT64
387  * (= 9,223,372,036,854,775,807).
388  *
389  * To print or scan values of this type, use
390  * %G_GINT64_MODIFIER and/or %G_GINT64_FORMAT.
391  */
392
393 /**
394  * G_MININT64:
395  *
396  * The minimum value which can be held in a #gint64.
397  */
398
399 /**
400  * G_MAXINT64:
401  *
402  * The maximum value which can be held in a #gint64.
403  */
404
405 /**
406  * G_GINT64_MODIFIER:
407  *
408  * The platform dependent length modifier for conversion specifiers
409  * for scanning and printing values of type #gint64 or #guint64.
410  * It is a string literal.
411  *
412  * Some platforms do not support printing 64-bit integers, even
413  * though the types are supported. On such platforms %G_GINT64_MODIFIER
414  * is not defined.
415  *
416  * Since: 2.4
417  */
418
419 /**
420  * G_GINT64_FORMAT:
421  *
422  * This is the platform dependent conversion specifier for scanning
423  * and printing values of type #gint64. See also #G_GINT16_FORMAT.
424  *
425  * Some platforms do not support scanning and printing 64-bit integers,
426  * even though the types are supported. On such platforms %G_GINT64_FORMAT
427  * is not defined. Note that scanf() may not support 64-bit integers, even
428  * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
429  * is not recommended for parsing anyway; consider using g_ascii_strtoull()
430  * instead.
431  */
432
433 /**
434  * guint64:
435  *
436  * An unsigned integer guaranteed to be 64-bits on all platforms.
437  * Values of this type can range from 0 to #G_MAXUINT64
438  * (= 18,446,744,073,709,551,615).
439  *
440  * To print or scan values of this type, use
441  * %G_GINT64_MODIFIER and/or %G_GUINT64_FORMAT.
442  */
443
444 /**
445  * G_MAXUINT64:
446  *
447  * The maximum value which can be held in a #guint64.
448  */
449
450 /**
451  * G_GUINT64_FORMAT:
452  *
453  * This is the platform dependent conversion specifier for scanning
454  * and printing values of type #guint64. See also #G_GINT16_FORMAT.
455  *
456  * Some platforms do not support scanning and printing 64-bit integers,
457  * even though the types are supported. On such platforms %G_GUINT64_FORMAT
458  * is not defined.  Note that scanf() may not support 64-bit integers, even
459  * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
460  * is not recommended for parsing anyway; consider using g_ascii_strtoull()
461  * instead.
462  */
463
464 /**
465  * G_GINT64_CONSTANT:
466  * @val: a literal integer value, e.g. 0x1d636b02300a7aa7
467  *
468  * This macro is used to insert 64-bit integer literals
469  * into the source code.
470  */
471
472 /**
473  * G_GUINT64_CONSTANT:
474  * @val: a literal integer value, e.g. 0x1d636b02300a7aa7U
475  *
476  * This macro is used to insert 64-bit unsigned integer
477  * literals into the source code.
478  *
479  * Since: 2.10
480  */
481
482 /**
483  * gfloat:
484  *
485  * Corresponds to the standard C float type.
486  * Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT.
487  */
488
489 /**
490  * G_MINFLOAT:
491  *
492  * The minimum positive value which can be held in a #gfloat.
493  *
494  * If you are interested in the smallest value which can be held
495  * in a #gfloat, use -%G_MAXFLOAT.
496  */
497
498 /**
499  * G_MAXFLOAT:
500  *
501  * The maximum value which can be held in a #gfloat.
502  */
503
504 /**
505  * gdouble:
506  *
507  * Corresponds to the standard C double type.
508  * Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE.
509  */
510
511 /**
512  * G_MINDOUBLE:
513  *
514  * The minimum positive value which can be held in a #gdouble.
515  *
516  * If you are interested in the smallest value which can be held
517  * in a #gdouble, use -%G_MAXDOUBLE.
518  */
519
520 /**
521  * G_MAXDOUBLE:
522  *
523  * The maximum value which can be held in a #gdouble.
524  */
525
526 /**
527  * gsize:
528  *
529  * An unsigned integer type of the result of the sizeof operator,
530  * corresponding to the size_t type defined in C99.
531  * This type is wide enough to hold the numeric value of a pointer,
532  * so it is usually 32 bit wide on a 32-bit platform and 64 bit wide
533  * on a 64-bit platform. Values of this type can range from 0 to
534  * #G_MAXSIZE.
535  *
536  * To print or scan values of this type, use
537  * %G_GSIZE_MODIFIER and/or %G_GSIZE_FORMAT.
538  */
539
540 /**
541  * G_MAXSIZE:
542  *
543  * The maximum value which can be held in a #gsize.
544  *
545  * Since: 2.4
546  */
547
548 /**
549  * G_GSIZE_MODIFIER:
550  *
551  * The platform dependent length modifier for conversion specifiers
552  * for scanning and printing values of type #gsize or #gssize. It
553  * is a string literal.
554  *
555  * Since: 2.6
556  */
557
558 /**
559  * G_GSIZE_FORMAT:
560  *
561  * This is the platform dependent conversion specifier for scanning
562  * and printing values of type #gsize. See also #G_GINT16_FORMAT.
563  *
564  * Since: 2.6
565  */
566
567 /**
568  * gssize:
569  *
570  * A signed variant of #gsize, corresponding to the
571  * ssize_t defined on most platforms.
572  * Values of this type can range from #G_MINSSIZE
573  * to #G_MAXSSIZE.
574  *
575  * To print or scan values of this type, use
576  * %G_GSIZE_MODIFIER and/or %G_GSSIZE_FORMAT.
577  */
578
579 /**
580  * G_MINSSIZE:
581  *
582  * The minimum value which can be held in a #gssize.
583  *
584  * Since: 2.14
585  */
586
587 /**
588  * G_MAXSSIZE:
589  *
590  * The maximum value which can be held in a #gssize.
591  *
592  * Since: 2.14
593  */
594
595 /**
596  * G_GSSIZE_FORMAT:
597  *
598  * This is the platform dependent conversion specifier for scanning
599  * and printing values of type #gssize. See also #G_GINT16_FORMAT.
600  *
601  * Since: 2.6
602  */
603
604 /**
605  * goffset:
606  *
607  * A signed integer type that is used for file offsets,
608  * corresponding to the C99 type off64_t.
609  * Values of this type can range from #G_MINOFFSET to
610  * #G_MAXOFFSET.
611  *
612  * To print or scan values of this type, use
613  * %G_GOFFSET_MODIFIER and/or %G_GOFFSET_FORMAT.
614  *
615  * Since: 2.14
616  */
617
618 /**
619  * G_MINOFFSET:
620  *
621  * The minimum value which can be held in a #goffset.
622  */
623
624 /**
625  * G_MAXOFFSET:
626  *
627  * The maximum value which can be held in a #goffset.
628  */
629
630 /**
631  * G_GOFFSET_MODIFIER:
632  *
633  * The platform dependent length modifier for conversion specifiers
634  * for scanning and printing values of type #goffset. It is a string
635  * literal. See also #G_GINT64_MODIFIER.
636  *
637  * Since: 2.20
638  */
639
640 /**
641  * G_GOFFSET_FORMAT:
642  *
643  * This is the platform dependent conversion specifier for scanning
644  * and printing values of type #goffset. See also #G_GINT64_FORMAT.
645  *
646  * Since: 2.20
647  */
648
649 /**
650  * G_GOFFSET_CONSTANT:
651  * @val: a literal integer value, e.g. 0x1d636b02300a7aa7
652  *
653  * This macro is used to insert #goffset 64-bit integer literals
654  * into the source code.
655  *
656  * See also #G_GINT64_CONSTANT.
657  *
658  * Since: 2.20
659  */
660
661 /**
662  * gintptr:
663  *
664  * Corresponds to the C99 type intptr_t,
665  * a signed integer type that can hold any pointer.
666  *
667  * To print or scan values of this type, use
668  * %G_GINTPTR_MODIFIER and/or %G_GINTPTR_FORMAT.
669  *
670  * Since: 2.18
671  */
672
673 /**
674  * G_GINTPTR_MODIFIER:
675  *
676  * The platform dependent length modifier for conversion specifiers
677  * for scanning and printing values of type #gintptr or #guintptr.
678  * It is a string literal.
679  *
680  * Since: 2.22
681  */
682
683 /**
684  * G_GINTPTR_FORMAT:
685  *
686  * This is the platform dependent conversion specifier for scanning
687  * and printing values of type #gintptr.
688  *
689  * Since: 2.22
690  */
691
692 /**
693  * guintptr:
694  *
695  * Corresponds to the C99 type uintptr_t,
696  * an unsigned integer type that can hold any pointer.
697  *
698  * To print or scan values of this type, use
699  * %G_GINTPTR_MODIFIER and/or %G_GUINTPTR_FORMAT.
700  *
701  * Since: 2.18
702  */
703
704 /**
705  * G_GUINTPTR_FORMAT:
706  *
707  * This is the platform dependent conversion specifier
708  * for scanning and printing values of type #guintptr.
709  *
710  * Since: 2.22
711  */
712
713 /* Type conversion {{{1 */
714
715 /**
716  * SECTION:type_conversion
717  * @title: Type Conversion Macros
718  * @short_description: portably storing integers in pointer variables
719  *
720  * Many times GLib, GTK+, and other libraries allow you to pass "user
721  * data" to a callback, in the form of a void pointer. From time to time
722  * you want to pass an integer instead of a pointer. You could allocate
723  * an integer, with something like:
724  * |[<!-- language="C" -->
725  *   int *ip = g_new (int, 1);
726  *   *ip = 42;
727  * ]|
728  * But this is inconvenient, and it's annoying to have to free the
729  * memory at some later time.
730  *
731  * Pointers are always at least 32 bits in size (on all platforms GLib
732  * intends to support). Thus you can store at least 32-bit integer values
733  * in a pointer value. Naively, you might try this, but it's incorrect:
734  * |[<!-- language="C" -->
735  *   gpointer p;
736  *   int i;
737  *   p = (void*) 42;
738  *   i = (int) p;
739  * ]|
740  * Again, that example was not correct, don't copy it.
741  * The problem is that on some systems you need to do this:
742  * |[<!-- language="C" -->
743  *   gpointer p;
744  *   int i;
745  *   p = (void*) (long) 42;
746  *   i = (int) (long) p;
747  * ]|
748  * The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care
749  * to do the right thing on the every platform.
750  *
751  * Warning: You may not store pointers in integers. This is not
752  * portable in any way, shape or form. These macros only allow storing
753  * integers in pointers, and only preserve 32 bits of the integer; values
754  * outside the range of a 32-bit integer will be mangled.
755  */
756
757 /**
758  * GINT_TO_POINTER:
759  * @i: integer to stuff into a pointer
760  *
761  * Stuffs an integer into a pointer type.
762  *
763  * Remember, you may not store pointers in integers. This is not portable
764  * in any way, shape or form. These macros only allow storing integers in
765  * pointers, and only preserve 32 bits of the integer; values outside the
766  * range of a 32-bit integer will be mangled.
767  */
768
769 /**
770  * GPOINTER_TO_INT:
771  * @p: pointer containing an integer
772  *
773  * Extracts an integer from a pointer. The integer must have
774  * been stored in the pointer with GINT_TO_POINTER().
775  *
776  * Remember, you may not store pointers in integers. This is not portable
777  * in any way, shape or form. These macros only allow storing integers in
778  * pointers, and only preserve 32 bits of the integer; values outside the
779  * range of a 32-bit integer will be mangled.
780  */
781
782 /**
783  * GUINT_TO_POINTER:
784  * @u: unsigned integer to stuff into the pointer
785  *
786  * Stuffs an unsigned integer into a pointer type.
787  */
788
789 /**
790  * GPOINTER_TO_UINT:
791  * @p: pointer to extract an unsigned integer from
792  *
793  * Extracts an unsigned integer from a pointer. The integer must have
794  * been stored in the pointer with GUINT_TO_POINTER().
795  */
796
797 /**
798  * GSIZE_TO_POINTER:
799  * @s: #gsize to stuff into the pointer
800  *
801  * Stuffs a #gsize into a pointer type.
802  */
803
804 /**
805  * GPOINTER_TO_SIZE:
806  * @p: pointer to extract a #gsize from
807  *
808  * Extracts a #gsize from a pointer. The #gsize must have
809  * been stored in the pointer with GSIZE_TO_POINTER().
810  */
811  
812 /* Byte order {{{1 */
813
814 /**
815  * SECTION:byte_order
816  * @title: Byte Order Macros
817  * @short_description: a portable way to convert between different byte orders
818  *
819  * These macros provide a portable way to determine the host byte order
820  * and to convert values between different byte orders.
821  *
822  * The byte order is the order in which bytes are stored to create larger
823  * data types such as the #gint and #glong values.
824  * The host byte order is the byte order used on the current machine.
825  *
826  * Some processors store the most significant bytes (i.e. the bytes that
827  * hold the largest part of the value) first. These are known as big-endian
828  * processors. Other processors (notably the x86 family) store the most
829  * significant byte last. These are known as little-endian processors.
830  *
831  * Finally, to complicate matters, some other processors store the bytes in
832  * a rather curious order known as PDP-endian. For a 4-byte word, the 3rd
833  * most significant byte is stored first, then the 4th, then the 1st and
834  * finally the 2nd.
835  *
836  * Obviously there is a problem when these different processors communicate
837  * with each other, for example over networks or by using binary file formats.
838  * This is where these macros come in. They are typically used to convert
839  * values into a byte order which has been agreed on for use when
840  * communicating between different processors. The Internet uses what is
841  * known as 'network byte order' as the standard byte order (which is in
842  * fact the big-endian byte order).
843  *
844  * Note that the byte order conversion macros may evaluate their arguments
845  * multiple times, thus you should not use them with arguments which have
846  * side-effects.
847  */
848
849 /**
850  * G_BYTE_ORDER:
851  *
852  * The host byte order.
853  * This can be either #G_LITTLE_ENDIAN or #G_BIG_ENDIAN (support for
854  * #G_PDP_ENDIAN may be added in future.)
855  */
856
857 /**
858  * G_LITTLE_ENDIAN:
859  *
860  * Specifies one of the possible types of byte order.
861  * See #G_BYTE_ORDER.
862  */
863
864 /**
865  * G_BIG_ENDIAN:
866  *
867  * Specifies one of the possible types of byte order.
868  * See #G_BYTE_ORDER.
869  */
870
871 /**
872  * G_PDP_ENDIAN:
873  *
874  * Specifies one of the possible types of byte order
875  * (currently unused). See #G_BYTE_ORDER.
876  */
877
878 /**
879  * g_htonl:
880  * @val: a 32-bit integer value in host byte order
881  *
882  * Converts a 32-bit integer value from host to network byte order.
883  *
884  * Returns: @val converted to network byte order
885  */
886
887 /**
888  * g_htons:
889  * @val: a 16-bit integer value in host byte order
890  *
891  * Converts a 16-bit integer value from host to network byte order.
892  *
893  * Returns: @val converted to network byte order
894  */
895
896 /**
897  * g_ntohl:
898  * @val: a 32-bit integer value in network byte order
899  *
900  * Converts a 32-bit integer value from network to host byte order.
901  *
902  * Returns: @val converted to host byte order.
903  */
904
905 /**
906  * g_ntohs:
907  * @val: a 16-bit integer value in network byte order
908  *
909  * Converts a 16-bit integer value from network to host byte order.
910  *
911  * Returns: @val converted to host byte order
912  */
913
914 /**
915  * GINT_FROM_BE:
916  * @val: a #gint value in big-endian byte order
917  *
918  * Converts a #gint value from big-endian to host byte order.
919  *
920  * Returns: @val converted to host byte order
921  */
922
923 /**
924  * GINT_FROM_LE:
925  * @val: a #gint value in little-endian byte order
926  *
927  * Converts a #gint value from little-endian to host byte order.
928  *
929  * Returns: @val converted to host byte order
930  */
931
932 /**
933  * GINT_TO_BE:
934  * @val: a #gint value in host byte order
935  *
936  * Converts a #gint value from host byte order to big-endian.
937  *
938  * Returns: @val converted to big-endian byte order
939  */
940
941 /**
942  * GINT_TO_LE:
943  * @val: a #gint value in host byte order
944  *
945  * Converts a #gint value from host byte order to little-endian.
946  *
947  * Returns: @val converted to little-endian byte order
948  */
949
950 /**
951  * GUINT_FROM_BE:
952  * @val: a #guint value in big-endian byte order
953  *
954  * Converts a #guint value from big-endian to host byte order.
955  *
956  * Returns: @val converted to host byte order
957  */
958
959 /**
960  * GUINT_FROM_LE:
961  * @val: a #guint value in little-endian byte order
962  *
963  * Converts a #guint value from little-endian to host byte order.
964  *
965  * Returns: @val converted to host byte order
966  */
967
968 /**
969  * GUINT_TO_BE:
970  * @val: a #guint value in host byte order
971  *
972  * Converts a #guint value from host byte order to big-endian.
973  *
974  * Returns: @val converted to big-endian byte order
975  */
976
977 /**
978  * GUINT_TO_LE:
979  * @val: a #guint value in host byte order
980  *
981  * Converts a #guint value from host byte order to little-endian.
982  *
983  * Returns: @val converted to little-endian byte order.
984  */
985
986 /**
987  * GLONG_FROM_BE:
988  * @val: a #glong value in big-endian byte order
989  *
990  * Converts a #glong value from big-endian to the host byte order.
991  *
992  * Returns: @val converted to host byte order
993  */
994
995 /**
996  * GLONG_FROM_LE:
997  * @val: a #glong value in little-endian byte order
998  *
999  * Converts a #glong value from little-endian to host byte order.
1000  *
1001  * Returns: @val converted to host byte order
1002  */
1003
1004 /**
1005  * GLONG_TO_BE:
1006  * @val: a #glong value in host byte order
1007  *
1008  * Converts a #glong value from host byte order to big-endian.
1009  *
1010  * Returns: @val converted to big-endian byte order
1011  */
1012
1013 /**
1014  * GLONG_TO_LE:
1015  * @val: a #glong value in host byte order
1016  *
1017  * Converts a #glong value from host byte order to little-endian.
1018  *
1019  * Returns: @val converted to little-endian
1020  */
1021
1022 /**
1023  * GULONG_FROM_BE:
1024  * @val: a #gulong value in big-endian byte order
1025  *
1026  * Converts a #gulong value from big-endian to host byte order.
1027  *
1028  * Returns: @val converted to host byte order
1029  */
1030
1031 /**
1032  * GULONG_FROM_LE:
1033  * @val: a #gulong value in little-endian byte order
1034  *
1035  * Converts a #gulong value from little-endian to host byte order.
1036  *
1037  * Returns: @val converted to host byte order
1038  */
1039
1040 /**
1041  * GULONG_TO_BE:
1042  * @val: a #gulong value in host byte order
1043  *
1044  * Converts a #gulong value from host byte order to big-endian.
1045  *
1046  * Returns: @val converted to big-endian
1047  */
1048
1049 /**
1050  * GULONG_TO_LE:
1051  * @val: a #gulong value in host byte order
1052  *
1053  * Converts a #gulong value from host byte order to little-endian.
1054  *
1055  * Returns: @val converted to little-endian
1056  */
1057
1058 /**
1059  * GSIZE_FROM_BE:
1060  * @val: a #gsize value in big-endian byte order
1061  *
1062  * Converts a #gsize value from big-endian to the host byte order.
1063  *
1064  * Returns: @val converted to host byte order
1065  */
1066
1067 /**
1068  * GSIZE_FROM_LE:
1069  * @val: a #gsize value in little-endian byte order
1070  *
1071  * Converts a #gsize value from little-endian to host byte order.
1072  *
1073  * Returns: @val converted to host byte order
1074  */
1075
1076 /**
1077  * GSIZE_TO_BE:
1078  * @val: a #gsize value in host byte order
1079  *
1080  * Converts a #gsize value from host byte order to big-endian.
1081  *
1082  * Returns: @val converted to big-endian byte order
1083  */
1084
1085 /**
1086  * GSIZE_TO_LE:
1087  * @val: a #gsize value in host byte order
1088  *
1089  * Converts a #gsize value from host byte order to little-endian.
1090  *
1091  * Returns: @val converted to little-endian
1092  */
1093
1094 /**
1095  * GSSIZE_FROM_BE:
1096  * @val: a #gssize value in big-endian byte order
1097  *
1098  * Converts a #gssize value from big-endian to host byte order.
1099  *
1100  * Returns: @val converted to host byte order
1101  */
1102
1103 /**
1104  * GSSIZE_FROM_LE:
1105  * @val: a #gssize value in little-endian byte order
1106  *
1107  * Converts a #gssize value from little-endian to host byte order.
1108  *
1109  * Returns: @val converted to host byte order
1110  */
1111
1112 /**
1113  * GSSIZE_TO_BE:
1114  * @val: a #gssize value in host byte order
1115  *
1116  * Converts a #gssize value from host byte order to big-endian.
1117  *
1118  * Returns: @val converted to big-endian
1119  */
1120
1121 /**
1122  * GSSIZE_TO_LE:
1123  * @val: a #gssize value in host byte order
1124  *
1125  * Converts a #gssize value from host byte order to little-endian.
1126  *
1127  * Returns: @val converted to little-endian
1128  */
1129
1130 /**
1131  * GINT16_FROM_BE:
1132  * @val: a #gint16 value in big-endian byte order
1133  *
1134  * Converts a #gint16 value from big-endian to host byte order.
1135  *
1136  * Returns: @val converted to host byte order
1137  */
1138
1139 /**
1140  * GINT16_FROM_LE:
1141  * @val: a #gint16 value in little-endian byte order
1142  *
1143  * Converts a #gint16 value from little-endian to host byte order.
1144  *
1145  * Returns: @val converted to host byte order
1146  */
1147
1148 /**
1149  * GINT16_TO_BE:
1150  * @val: a #gint16 value in host byte order
1151  *
1152  * Converts a #gint16 value from host byte order to big-endian.
1153  *
1154  * Returns: @val converted to big-endian
1155  */
1156
1157 /**
1158  * GINT16_TO_LE:
1159  * @val: a #gint16 value in host byte order
1160  *
1161  * Converts a #gint16 value from host byte order to little-endian.
1162  *
1163  * Returns: @val converted to little-endian
1164  */
1165
1166 /**
1167  * GUINT16_FROM_BE:
1168  * @val: a #guint16 value in big-endian byte order
1169  *
1170  * Converts a #guint16 value from big-endian to host byte order.
1171  *
1172  * Returns: @val converted to host byte order
1173  */
1174
1175 /**
1176  * GUINT16_FROM_LE:
1177  * @val: a #guint16 value in little-endian byte order
1178  *
1179  * Converts a #guint16 value from little-endian to host byte order.
1180  *
1181  * Returns: @val converted to host byte order
1182  */
1183
1184 /**
1185  * GUINT16_TO_BE:
1186  * @val: a #guint16 value in host byte order
1187  *
1188  * Converts a #guint16 value from host byte order to big-endian.
1189  *
1190  * Returns: @val converted to big-endian
1191  */
1192
1193 /**
1194  * GUINT16_TO_LE:
1195  * @val: a #guint16 value in host byte order
1196  *
1197  * Converts a #guint16 value from host byte order to little-endian.
1198  *
1199  * Returns: @val converted to little-endian
1200  */
1201
1202 /**
1203  * GINT32_FROM_BE:
1204  * @val: a #gint32 value in big-endian byte order
1205  *
1206  * Converts a #gint32 value from big-endian to host byte order.
1207  *
1208  * Returns: @val converted to host byte order
1209  */
1210
1211 /**
1212  * GINT32_FROM_LE:
1213  * @val: a #gint32 value in little-endian byte order
1214  *
1215  * Converts a #gint32 value from little-endian to host byte order.
1216  *
1217  * Returns: @val converted to host byte order
1218  */
1219
1220 /**
1221  * GINT32_TO_BE:
1222  * @val: a #gint32 value in host byte order
1223  *
1224  * Converts a #gint32 value from host byte order to big-endian.
1225  *
1226  * Returns: @val converted to big-endian
1227  */
1228
1229 /**
1230  * GINT32_TO_LE:
1231  * @val: a #gint32 value in host byte order
1232  *
1233  * Converts a #gint32 value from host byte order to little-endian.
1234  *
1235  * Returns: @val converted to little-endian
1236  */
1237
1238 /**
1239  * GUINT32_FROM_BE:
1240  * @val: a #guint32 value in big-endian byte order
1241  *
1242  * Converts a #guint32 value from big-endian to host byte order.
1243  *
1244  * Returns: @val converted to host byte order
1245  */
1246
1247 /**
1248  * GUINT32_FROM_LE:
1249  * @val: a #guint32 value in little-endian byte order
1250  *
1251  * Converts a #guint32 value from little-endian to host byte order.
1252  *
1253  * Returns: @val converted to host byte order
1254  */
1255
1256 /**
1257  * GUINT32_TO_BE:
1258  * @val: a #guint32 value in host byte order
1259  *
1260  * Converts a #guint32 value from host byte order to big-endian.
1261  *
1262  * Returns: @val converted to big-endian
1263  */
1264
1265 /**
1266  * GUINT32_TO_LE:
1267  * @val: a #guint32 value in host byte order
1268  *
1269  * Converts a #guint32 value from host byte order to little-endian.
1270  *
1271  * Returns: @val converted to little-endian
1272  */
1273
1274 /**
1275  * GINT64_FROM_BE:
1276  * @val: a #gint64 value in big-endian byte order
1277  *
1278  * Converts a #gint64 value from big-endian to host byte order.
1279  *
1280  * Returns: @val converted to host byte order
1281  */
1282
1283 /**
1284  * GINT64_FROM_LE:
1285  * @val: a #gint64 value in little-endian byte order
1286  *
1287  * Converts a #gint64 value from little-endian to host byte order.
1288  *
1289  * Returns: @val converted to host byte order
1290  */
1291
1292 /**
1293  * GINT64_TO_BE:
1294  * @val: a #gint64 value in host byte order
1295  *
1296  * Converts a #gint64 value from host byte order to big-endian.
1297  *
1298  * Returns: @val converted to big-endian
1299  */
1300
1301 /**
1302  * GINT64_TO_LE:
1303  * @val: a #gint64 value in host byte order
1304  *
1305  * Converts a #gint64 value from host byte order to little-endian.
1306  *
1307  * Returns: @val converted to little-endian
1308  */
1309
1310 /**
1311  * GUINT64_FROM_BE:
1312  * @val: a #guint64 value in big-endian byte order
1313  *
1314  * Converts a #guint64 value from big-endian to host byte order.
1315  *
1316  * Returns: @val converted to host byte order
1317  */
1318
1319 /**
1320  * GUINT64_FROM_LE:
1321  * @val: a #guint64 value in little-endian byte order
1322  *
1323  * Converts a #guint64 value from little-endian to host byte order.
1324  *
1325  * Returns: @val converted to host byte order
1326  */
1327
1328 /**
1329  * GUINT64_TO_BE:
1330  * @val: a #guint64 value in host byte order
1331  *
1332  * Converts a #guint64 value from host byte order to big-endian.
1333  *
1334  * Returns: @val converted to big-endian
1335  */
1336
1337 /**
1338  * GUINT64_TO_LE:
1339  * @val: a #guint64 value in host byte order
1340  *
1341  * Converts a #guint64 value from host byte order to little-endian.
1342  *
1343  * Returns: @val converted to little-endian
1344  */
1345
1346 /**
1347  * GUINT16_SWAP_BE_PDP:
1348  * @val: a #guint16 value in big-endian or pdp-endian byte order
1349  *
1350  * Converts a #guint16 value between big-endian and pdp-endian byte order.
1351  * The conversion is symmetric so it can be used both ways.
1352  *
1353  * Returns: @val converted to the opposite byte order
1354  */
1355
1356 /**
1357  * GUINT16_SWAP_LE_BE:
1358  * @val: a #guint16 value in little-endian or big-endian byte order
1359  *
1360  * Converts a #guint16 value between little-endian and big-endian byte order.
1361  * The conversion is symmetric so it can be used both ways.
1362  *
1363  * Returns: @val converted to the opposite byte order
1364  */
1365
1366 /**
1367  * GUINT16_SWAP_LE_PDP:
1368  * @val: a #guint16 value in little-endian or pdp-endian byte order
1369  *
1370  * Converts a #guint16 value between little-endian and pdp-endian byte order.
1371  * The conversion is symmetric so it can be used both ways.
1372  *
1373  * Returns: @val converted to the opposite byte order
1374  */
1375
1376 /**
1377  * GUINT32_SWAP_BE_PDP:
1378  * @val: a #guint32 value in big-endian or pdp-endian byte order
1379  *
1380  * Converts a #guint32 value between big-endian and pdp-endian byte order.
1381  * The conversion is symmetric so it can be used both ways.
1382  *
1383  * Returns: @val converted to the opposite byte order
1384  */
1385
1386 /**
1387  * GUINT32_SWAP_LE_BE:
1388  * @val: a #guint32 value in little-endian or big-endian byte order
1389  *
1390  * Converts a #guint32 value between little-endian and big-endian byte order.
1391  * The conversion is symmetric so it can be used both ways.
1392  *
1393  * Returns: @val converted to the opposite byte order
1394  */
1395
1396 /**
1397  * GUINT32_SWAP_LE_PDP:
1398  * @val: a #guint32 value in little-endian or pdp-endian byte order
1399  *
1400  * Converts a #guint32 value between little-endian and pdp-endian byte order.
1401  * The conversion is symmetric so it can be used both ways.
1402  *
1403  * Returns: @val converted to the opposite byte order
1404  */
1405
1406 /**
1407  * GUINT64_SWAP_LE_BE:
1408  * @val: a #guint64 value in little-endian or big-endian byte order
1409  *
1410  * Converts a #guint64 value between little-endian and big-endian byte order.
1411  * The conversion is symmetric so it can be used both ways.
1412  *
1413  * Returns: @val converted to the opposite byte order
1414  */
1415  
1416 /* Numerical Definitions {{{1 */
1417
1418 /**
1419  * SECTION:numerical
1420  * @title: Numerical Definitions
1421  * @short_description: mathematical constants, and floating point decomposition
1422  *
1423  * GLib offers mathematical constants such as #G_PI for the value of pi;
1424  * many platforms have these in the C library, but some don't, the GLib
1425  * versions always exist.
1426  *
1427  * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the
1428  * sign, mantissa and exponent of IEEE floats and doubles. These unions are
1429  * defined as appropriate for a given platform. IEEE floats and doubles are
1430  * supported (used for storage) by at least Intel, PPC and Sparc. See
1431  * [IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float)
1432  * for more information about IEEE number formats.
1433  */
1434
1435 /**
1436  * G_IEEE754_FLOAT_BIAS:
1437  *
1438  * The bias by which exponents in single-precision floats are offset.
1439  */
1440
1441 /**
1442  * G_IEEE754_DOUBLE_BIAS:
1443  *
1444  * The bias by which exponents in double-precision floats are offset.
1445  */
1446
1447 /**
1448  * GFloatIEEE754:
1449  * @v_float: the double value
1450  *
1451  * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
1452  * mantissa and exponent of IEEE floats and doubles. These unions are defined
1453  * as appropriate for a given platform. IEEE floats and doubles are supported
1454  * (used for storage) by at least Intel, PPC and Sparc.
1455  */
1456
1457 /**
1458  * GDoubleIEEE754:
1459  * @v_double: the double value
1460  *
1461  * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
1462  * mantissa and exponent of IEEE floats and doubles. These unions are defined
1463  * as appropriate for a given platform. IEEE floats and doubles are supported
1464  * (used for storage) by at least Intel, PPC and Sparc.
1465  */
1466
1467 /**
1468  * G_E:
1469  *
1470  * The base of natural logarithms.
1471  */
1472
1473 /**
1474  * G_LN2:
1475  *
1476  * The natural logarithm of 2.
1477  */
1478
1479 /**
1480  * G_LN10:
1481  *
1482  * The natural logarithm of 10.
1483  */
1484
1485 /**
1486  * G_PI:
1487  *
1488  * The value of pi (ratio of circle's circumference to its diameter).
1489  */
1490
1491 /**
1492  * G_PI_2:
1493  *
1494  * Pi divided by 2.
1495  */
1496
1497 /**
1498  * G_PI_4:
1499  *
1500  * Pi divided by 4.
1501  */
1502
1503 /**
1504  * G_SQRT2:
1505  *
1506  * The square root of two.
1507  */
1508
1509 /**
1510  * G_LOG_2_BASE_10:
1511  *
1512  * Multiplying the base 2 exponent by this number yields the base 10 exponent.
1513  */
1514  
1515 /* Macros {{{1 */
1516
1517 /**
1518  * SECTION:macros
1519  * @title: Standard Macros
1520  * @short_description: commonly-used macros
1521  *
1522  * These macros provide a few commonly-used features.
1523  */
1524
1525 /**
1526  * G_OS_WIN32:
1527  *
1528  * This macro is defined only on Windows. So you can bracket
1529  * Windows-specific code in "&num;ifdef G_OS_WIN32".
1530  */
1531
1532 /**
1533  * G_OS_UNIX:
1534  *
1535  * This macro is defined only on UNIX. So you can bracket
1536  * UNIX-specific code in "&num;ifdef G_OS_UNIX".
1537  */
1538
1539 /**
1540  * G_DIR_SEPARATOR:
1541  *
1542  * The directory separator character.
1543  * This is '/' on UNIX machines and '\' under Windows.
1544  */
1545
1546 /**
1547  * G_DIR_SEPARATOR_S:
1548  *
1549  * The directory separator as a string.
1550  * This is "/" on UNIX machines and "\" under Windows.
1551  */
1552
1553 /**
1554  * G_IS_DIR_SEPARATOR:
1555  * @c: a character
1556  *
1557  * Checks whether a character is a directory
1558  * separator. It returns %TRUE for '/' on UNIX
1559  * machines and for '\' or '/' under Windows.
1560  *
1561  * Since: 2.6
1562  */
1563
1564 /**
1565  * G_SEARCHPATH_SEPARATOR:
1566  *
1567  * The search path separator character.
1568  * This is ':' on UNIX machines and ';' under Windows.
1569  */
1570
1571 /**
1572  * G_SEARCHPATH_SEPARATOR_S:
1573  *
1574  * The search path separator as a string.
1575  * This is ":" on UNIX machines and ";" under Windows.
1576  */
1577
1578 /**
1579  * TRUE:
1580  *
1581  * Defines the %TRUE value for the #gboolean type.
1582  */
1583
1584 /**
1585  * FALSE:
1586  *
1587  * Defines the %FALSE value for the #gboolean type.
1588  */
1589
1590 /**
1591  * NULL:
1592  *
1593  * Defines the standard %NULL pointer.
1594  */
1595
1596 /**
1597  * MIN:
1598  * @a: a numeric value
1599  * @b: a numeric value
1600  *
1601  * Calculates the minimum of @a and @b.
1602  *
1603  * Returns: the minimum of @a and @b.
1604  */
1605
1606 /**
1607  * MAX:
1608  * @a: a numeric value
1609  * @b: a numeric value
1610  *
1611  * Calculates the maximum of @a and @b.
1612  *
1613  * Returns: the maximum of @a and @b.
1614  */
1615
1616 /**
1617  * ABS:
1618  * @a: a numeric value
1619  *
1620  * Calculates the absolute value of @a.
1621  * The absolute value is simply the number with any negative sign taken away.
1622  *
1623  * For example,
1624  * - ABS(-10) is 10.
1625  * - ABS(10) is also 10.
1626  *
1627  * Returns: the absolute value of @a.
1628  */
1629
1630 /**
1631  * CLAMP:
1632  * @x: the value to clamp
1633  * @low: the minimum value allowed
1634  * @high: the maximum value allowed
1635  *
1636  * Ensures that @x is between the limits set by @low and @high. If @low is
1637  * greater than @high the result is undefined.
1638  *
1639  * For example,
1640  * - CLAMP(5, 10, 15) is 10.
1641  * - CLAMP(15, 5, 10) is 10.
1642  * - CLAMP(20, 15, 25) is 20.
1643  *
1644  * Returns: the value of @x clamped to the range between @low and @high
1645  */
1646
1647 /**
1648  * G_STRUCT_MEMBER:
1649  * @member_type: the type of the struct field
1650  * @struct_p: a pointer to a struct
1651  * @struct_offset: the offset of the field from the start of the struct,
1652  *     in bytes
1653  *
1654  * Returns a member of a structure at a given offset, using the given type.
1655  *
1656  * Returns: the struct member
1657  */
1658
1659 /**
1660  * G_STRUCT_MEMBER_P:
1661  * @struct_p: a pointer to a struct
1662  * @struct_offset: the offset from the start of the struct, in bytes
1663  *
1664  * Returns an untyped pointer to a given offset of a struct.
1665  *
1666  * Returns: an untyped pointer to @struct_p plus @struct_offset bytes
1667  */
1668
1669 /**
1670  * G_STRUCT_OFFSET:
1671  * @struct_type: a structure type, e.g. #GtkWidget
1672  * @member: a field in the structure, e.g. @window
1673  *
1674  * Returns the offset, in bytes, of a member of a struct.
1675  *
1676  * Returns: the offset of @member from the start of @struct_type
1677  */
1678
1679 /**
1680  * G_CONST_RETURN:
1681  *
1682  * If %G_DISABLE_CONST_RETURNS is defined, this macro expands
1683  * to nothing. By default, the macro expands to const. The macro
1684  * can be used in place of const for functions that return a value
1685  * that should not be modified. The purpose of this macro is to allow
1686  * us to turn on const for returned constant strings by default, while
1687  * allowing programmers who find that annoying to turn it off. This macro
1688  * should only be used for return values and for "out" parameters, it
1689  * doesn't make sense for "in" parameters.
1690  *
1691  * Deprecated: 2.30: API providers should replace all existing uses with
1692  * const and API consumers should adjust their code accordingly
1693  */
1694
1695 /**
1696  * G_N_ELEMENTS:
1697  * @arr: the array
1698  *
1699  * Determines the number of elements in an array. The array must be
1700  * declared so the compiler knows its size at compile-time; this
1701  * macro will not work on an array allocated on the heap, only static
1702  * arrays or arrays on the stack.
1703  */
1704  
1705 / * Miscellaneous Macros {{{1 */
1706
1707 /**
1708  * SECTION:macros_misc
1709  * @title: Miscellaneous Macros
1710  * @short_description: specialized macros which are not used often
1711  *
1712  * These macros provide more specialized features which are not
1713  * needed so often by application programmers.
1714  */
1715
1716 /**
1717  * G_INLINE_FUNC:
1718  *
1719  * This macro is used to export function prototypes so they can be linked
1720  * with an external version when no inlining is performed. The file which
1721  * implements the functions should define %G_IMPLEMENTS_INLINES
1722  * before including the headers which contain %G_INLINE_FUNC declarations.
1723  * Since inlining is very compiler-dependent using these macros correctly
1724  * is very difficult. Their use is strongly discouraged.
1725  *
1726  * This macro is often mistaken for a replacement for the inline keyword;
1727  * inline is already declared in a portable manner in the GLib headers
1728  * and can be used normally.
1729  */
1730
1731 /**
1732  * G_STMT_START:
1733  *
1734  * Used within multi-statement macros so that they can be used in places
1735  * where only one statement is expected by the compiler.
1736  */
1737
1738 /**
1739  * G_STMT_END:
1740  *
1741  * Used within multi-statement macros so that they can be used in places
1742  * where only one statement is expected by the compiler.
1743  */
1744
1745 /**
1746  * G_BEGIN_DECLS:
1747  *
1748  * Used (along with #G_END_DECLS) to bracket header files. If the
1749  * compiler in use is a C++ compiler, adds extern "C"
1750  * around the header.
1751  */
1752
1753 /**
1754  * G_END_DECLS:
1755  *
1756  * Used (along with #G_BEGIN_DECLS) to bracket header files. If the
1757  * compiler in use is a C++ compiler, adds extern "C"
1758  * around the header.
1759  */
1760
1761 /**
1762  * G_VA_COPY:
1763  * @ap1: the va_list variable to place a copy of @ap2 in
1764  * @ap2: a va_list
1765  *
1766  * Portable way to copy va_list variables.
1767  *
1768  * In order to use this function, you must include string.h yourself,
1769  * because this macro may use memmove() and GLib does not include
1770  * string.h for you.
1771  */
1772
1773 /**
1774  * G_STRINGIFY:
1775  * @macro_or_string: a macro or a string
1776  *
1777  * Accepts a macro or a string and converts it into a string after
1778  * preprocessor argument expansion. For example, the following code:
1779  *
1780  * |[<!-- language="C" -->
1781  * #define AGE 27
1782  * const gchar *greeting = G_STRINGIFY (AGE) " today!";
1783  * ]|
1784  *
1785  * is transformed by the preprocessor into (code equivalent to):
1786  *
1787  * |[<!-- language="C" -->
1788  * const gchar *greeting = "27 today!";
1789  * ]|
1790  */
1791
1792 /**
1793  * G_PASTE:
1794  * @identifier1: an identifier
1795  * @identifier2: an identifier
1796  *
1797  * Yields a new preprocessor pasted identifier
1798  * @identifier1identifier2 from its expanded
1799  * arguments @identifier1 and @identifier2. For example,
1800  * the following code:
1801  * |[<!-- language="C" -->
1802  * #define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller)
1803  * const gchar *name = GET (traveller, name);
1804  * const gchar *quest = GET (traveller, quest);
1805  * GdkColor *favourite = GET (traveller, favourite_colour);
1806  * ]|
1807  *
1808  * is transformed by the preprocessor into:
1809  * |[<!-- language="C" -->
1810  * const gchar *name = traveller_get_name (traveller);
1811  * const gchar *quest = traveller_get_quest (traveller);
1812  * GdkColor *favourite = traveller_get_favourite_colour (traveller);
1813  * ]|
1814  *
1815  * Since: 2.20
1816  */
1817
1818 /**
1819  * G_STATIC_ASSERT:
1820  * @expr: a constant expression
1821  *
1822  * The G_STATIC_ASSERT() macro lets the programmer check
1823  * a condition at compile time, the condition needs to
1824  * be compile time computable. The macro can be used in
1825  * any place where a typedef is valid.
1826  *
1827  * A typedef is generally allowed in exactly the same places that
1828  * a variable declaration is allowed. For this reason, you should
1829  * not use G_STATIC_ASSERT() in the middle of blocks of code.
1830  *
1831  * The macro should only be used once per source code line.
1832  *
1833  * Since: 2.20
1834  */
1835
1836 /**
1837  * G_STATIC_ASSERT_EXPR:
1838  * @expr: a constant expression
1839  *
1840  * The G_STATIC_ASSERT_EXPR() macro lets the programmer check
1841  * a condition at compile time. The condition needs to be
1842  * compile time computable.
1843  *
1844  * Unlike G_STATIC_ASSERT(), this macro evaluates to an expression
1845  * and, as such, can be used in the middle of other expressions.
1846  * Its value should be ignored. This can be accomplished by placing
1847  * it as the first argument of a comma expression.
1848  *
1849  * |[<!-- language="C" -->
1850  * #define ADD_ONE_TO_INT(x) \
1851  *   (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1))
1852  * ]|
1853  *
1854  * Since: 2.30
1855  */
1856
1857 /**
1858  * G_GNUC_EXTENSION:
1859  *
1860  * Expands to __extension__ when gcc is used as the compiler. This simply
1861  * tells gcc not to warn about the following non-standard code when compiling
1862  * with the <option>-pedantic</option> option.
1863  */
1864
1865 /**
1866  * G_GNUC_CONST:
1867  *
1868  * Expands to the GNU C const function attribute if the compiler is gcc.
1869  * Declaring a function as const enables better optimization of calls to
1870  * the function. A const function doesn't examine any values except its
1871  * parameters, and has no effects except its return value.
1872  *
1873  * Place the attribute after the declaration, just before the semicolon.
1874  *
1875  * See the GNU C documentation for more details.
1876  *
1877  * A function that has pointer arguments and examines the data pointed to
1878  * must not be declared const. Likewise, a function that calls a non-const
1879  * function usually must not be const. It doesn't make sense for a const
1880  * function to return void.
1881  */
1882
1883 /**
1884  * G_GNUC_PURE:
1885  *
1886  * Expands to the GNU C pure function attribute if the compiler is gcc.
1887  * Declaring a function as pure enables better optimization of calls to
1888  * the function. A pure function has no effects except its return value
1889  * and the return value depends only on the parameters and/or global
1890  * variables.
1891  *
1892  * Place the attribute after the declaration, just before the semicolon.
1893  *
1894  * See the GNU C documentation for more details.
1895  */
1896
1897 /**
1898  * G_GNUC_MALLOC:
1899  *
1900  * Expands to the GNU C malloc function attribute if the compiler is gcc.
1901  * Declaring a function as malloc enables better optimization of the function.
1902  * A function can have the malloc attribute if it returns a pointer which is
1903  * guaranteed to not alias with any other pointer when the function returns
1904  * (in practice, this means newly allocated memory).
1905  *
1906  * Place the attribute after the declaration, just before the semicolon.
1907  *
1908  * See the GNU C documentation for more details.
1909  *
1910  * Since: 2.6
1911  */
1912
1913 /**
1914  * G_GNUC_ALLOC_SIZE:
1915  * @x: the index of the argument specifying the allocation size
1916  *
1917  * Expands to the GNU C alloc_size function attribute if the compiler
1918  * is a new enough gcc. This attribute tells the compiler that the
1919  * function returns a pointer to memory of a size that is specified
1920  * by the @xth function parameter.
1921  *
1922  * Place the attribute after the function declaration, just before the
1923  * semicolon.
1924  *
1925  * See the GNU C documentation for more details.
1926  *
1927  * Since: 2.18
1928  */
1929
1930 /**
1931  * G_GNUC_ALLOC_SIZE2:
1932  * @x: the index of the argument specifying one factor of the allocation size
1933  * @y: the index of the argument specifying the second factor of the allocation size
1934  *
1935  * Expands to the GNU C alloc_size function attribute if the compiler is a
1936  * new enough gcc. This attribute tells the compiler that the function returns
1937  * a pointer to memory of a size that is specified by the product of two
1938  * function parameters.
1939  *
1940  * Place the attribute after the function declaration, just before the
1941  * semicolon.
1942  *
1943  * See the GNU C documentation for more details.
1944  *
1945  * Since: 2.18
1946  */
1947
1948 /**
1949  * G_GNUC_DEPRECATED:
1950  *
1951  * Expands to the GNU C deprecated attribute if the compiler is gcc.
1952  * It can be used to mark typedefs, variables and functions as deprecated.
1953  * When called with the <option>-Wdeprecated-declarations</option> option,
1954  * gcc will generate warnings when deprecated interfaces are used.
1955  *
1956  * Place the attribute after the declaration, just before the semicolon.
1957  *
1958  * See the GNU C documentation for more details.
1959  *
1960  * Since: 2.2
1961  */
1962
1963 /**
1964  * G_GNUC_DEPRECATED_FOR:
1965  * @f: the intended replacement for the deprecated symbol,
1966  *     such as the name of a function
1967  *
1968  * Like %G_GNUC_DEPRECATED, but names the intended replacement for the
1969  * deprecated symbol if the version of gcc in use is new enough to support
1970  * custom deprecation messages.
1971  *
1972  * Place the attribute after the declaration, just before the semicolon.
1973  *
1974  * See the GNU C documentation for more details.
1975  *
1976  * Note that if @f is a macro, it will be expanded in the warning message.
1977  * You can enclose it in quotes to prevent this. (The quotes will show up
1978  * in the warning, but it's better than showing the macro expansion.)
1979  *
1980  * Since: 2.26
1981  */
1982
1983 /**
1984  * G_GNUC_BEGIN_IGNORE_DEPRECATIONS:
1985  *
1986  * Tells gcc (if it is a new enough version) to temporarily stop emitting
1987  * warnings when functions marked with %G_GNUC_DEPRECATED or
1988  * %G_GNUC_DEPRECATED_FOR are called. This is useful for when you have
1989  * one deprecated function calling another one, or when you still have
1990  * regression tests for deprecated functions.
1991  *
1992  * Use %G_GNUC_END_IGNORE_DEPRECATIONS to begin warning again. (If you
1993  * are not compiling with <literal>-Wdeprecated-declarations</literal>
1994  * then neither macro has any effect.)
1995  *
1996  * This macro can be used either inside or outside of a function body,
1997  * but must appear on a line by itself.
1998  *
1999  * Since: 2.32
2000  */
2001
2002 /**
2003  * G_GNUC_END_IGNORE_DEPRECATIONS:
2004  *
2005  * Undoes the effect of %G_GNUC_BEGIN_IGNORE_DEPRECATIONS, telling
2006  * gcc to begin outputting warnings again (assuming those warnings
2007  * had been enabled to begin with).
2008  *
2009  * This macro can be used either inside or outside of a function body,
2010  * but must appear on a line by itself.
2011  *
2012  * Since: 2.32
2013  */
2014
2015 /**
2016  * G_DEPRECATED:
2017  *
2018  * This macro is similar to %G_GNUC_DEPRECATED, and can be used to mark
2019  * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED, it is
2020  * meant to be portable across different compilers and must be placed
2021  * before the function declaration.
2022  *
2023  * Since: 2.32
2024  */
2025
2026 /**
2027  * G_DEPRECATED_FOR:
2028  * @f: the name of the function that this function was deprecated for
2029  *
2030  * This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark
2031  * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it
2032  * is meant to be portable across different compilers and must be placed
2033  * before the function declaration.
2034  *
2035  * Since: 2.32
2036  */
2037
2038 /**
2039  * G_UNAVAILABLE:
2040  * @maj: the major version that introduced the symbol
2041  * @min: the minor version that introduced the symbol
2042  *
2043  * This macro can be used to mark a function declaration as unavailable.
2044  * It must be placed before the function declaration. Use of a function
2045  * that has been annotated with this macros will produce a compiler warning.
2046  *
2047  * Since: 2.32
2048  */
2049
2050 /**
2051  * GLIB_DISABLE_DEPRECATION_WARNINGS:
2052  *
2053  * A macro that should be defined before including the glib.h header.
2054  * If it is defined, no compiler warnings will be produced for uses
2055  * of deprecated GLib APIs.
2056  */
2057
2058 /**
2059  * G_GNUC_NORETURN:
2060  *
2061  * Expands to the GNU C noreturn function attribute if the compiler is gcc.
2062  * It is used for declaring functions which never return. It enables
2063  * optimization of the function, and avoids possible compiler warnings.
2064  *
2065  * Place the attribute after the declaration, just before the semicolon.
2066  *
2067  * See the GNU C documentation for more details.
2068  */
2069
2070 /**
2071  * G_GNUC_UNUSED:
2072  *
2073  * Expands to the GNU C unused function attribute if the compiler is gcc.
2074  * It is used for declaring functions and arguments which may never be used.
2075  * It avoids possible compiler warnings.
2076  *
2077  * For functions, place the attribute after the declaration, just before the
2078  * semicolon. For arguments, place the attribute at the beginning of the
2079  * argument declaration.
2080  *
2081  * |[<!-- language="C" -->
2082  * void my_unused_function (G_GNUC_UNUSED gint unused_argument,
2083  *                          gint other_argument) G_GNUC_UNUSED;
2084  * ]|
2085  *
2086  * See the GNU C documentation for more details.
2087  */
2088
2089 /**
2090  * G_GNUC_PRINTF:
2091  * @format_idx: the index of the argument corresponding to the
2092  *     format string (The arguments are numbered from 1)
2093  * @arg_idx: the index of the first of the format arguments
2094  *
2095  * Expands to the GNU C format function attribute if the compiler is gcc.
2096  * This is used for declaring functions which take a variable number of
2097  * arguments, with the same syntax as printf(). It allows the compiler
2098  * to type-check the arguments passed to the function.
2099  *
2100  * Place the attribute after the function declaration, just before the
2101  * semicolon.
2102  *
2103  * See the GNU C documentation for more details.
2104  *
2105  * |[<!-- language="C" -->
2106  * gint g_snprintf (gchar  *string,
2107  *                  gulong       n,
2108  *                  gchar const *format,
2109  *                  ...) G_GNUC_PRINTF (3, 4);
2110  * ]|
2111  */
2112
2113 /**
2114  * G_GNUC_SCANF:
2115  * @format_idx: the index of the argument corresponding to
2116  *     the format string (The arguments are numbered from 1)
2117  * @arg_idx: the index of the first of the format arguments
2118  *
2119  * Expands to the GNU C format function attribute if the compiler is gcc.
2120  * This is used for declaring functions which take a variable number of
2121  * arguments, with the same syntax as scanf(). It allows the compiler
2122  * to type-check the arguments passed to the function.
2123  *
2124  * See the GNU C documentation for details.
2125  */
2126
2127 /**
2128  * G_GNUC_FORMAT:
2129  * @arg_idx: the index of the argument
2130  *
2131  * Expands to the GNU C format_arg function attribute if the compiler
2132  * is gcc. This function attribute specifies that a function takes a
2133  * format string for a printf(), scanf(), strftime() or strfmon() style
2134  * function and modifies it, so that the result can be passed to a printf(),
2135  * scanf(), strftime() or strfmon() style function (with the remaining
2136  * arguments to the format function the same as they would have been
2137  * for the unmodified string).
2138  *
2139  * Place the attribute after the function declaration, just before the
2140  * semicolon.
2141  *
2142  * See the GNU C documentation for more details.
2143  *
2144  * |[<!-- language="C" -->
2145  * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
2146  * ]|
2147  */
2148
2149 /**
2150  * G_GNUC_NULL_TERMINATED:
2151  *
2152  * Expands to the GNU C sentinel function attribute if the compiler is gcc.
2153  * This function attribute only applies to variadic functions and instructs
2154  * the compiler to check that the argument list is terminated with an
2155  * explicit %NULL.
2156  *
2157  * Place the attribute after the declaration, just before the semicolon.
2158  *
2159  * See the GNU C documentation for more details.
2160  *
2161  * Since: 2.8
2162  */
2163
2164 /**
2165  * G_GNUC_WARN_UNUSED_RESULT:
2166  *
2167  * Expands to the GNU C warn_unused_result function attribute if the compiler
2168  * is gcc. This function attribute makes the compiler emit a warning if the
2169  * result of a function call is ignored.
2170  *
2171  * Place the attribute after the declaration, just before the semicolon.
2172  *
2173  * See the GNU C documentation for more details.
2174  *
2175  * Since: 2.10
2176  */
2177
2178 /**
2179  * G_GNUC_FUNCTION:
2180  *
2181  * Expands to "" on all modern compilers, and to  __FUNCTION__ on gcc
2182  * version 2.x. Don't use it.
2183  *
2184  * Deprecated: 2.16: Use G_STRFUNC() instead
2185  */
2186
2187 /**
2188  * G_GNUC_PRETTY_FUNCTION:
2189  *
2190  * Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__
2191  * on gcc version 2.x. Don't use it.
2192  *
2193  * Deprecated: 2.16: Use G_STRFUNC() instead
2194  */
2195
2196 /**
2197  * G_GNUC_NO_INSTRUMENT:
2198  *
2199  * Expands to the GNU C no_instrument_function function attribute if the
2200  * compiler is gcc. Functions with this attribute will not be instrumented
2201  * for profiling, when the compiler is called with the
2202  * <option>-finstrument-functions</option> option.
2203  *
2204  * Place the attribute after the declaration, just before the semicolon.
2205  *
2206  * See the GNU C documentation for more details.
2207  */
2208
2209 /**
2210  * G_GNUC_INTERNAL:
2211  *
2212  * This attribute can be used for marking library functions as being used
2213  * internally to the library only, which may allow the compiler to handle
2214  * function calls more efficiently. Note that static functions do not need
2215  * to be marked as internal in this way. See the GNU C documentation for
2216  * details.
2217  *
2218  * When using a compiler that supports the GNU C hidden visibility attribute,
2219  * this macro expands to __attribute__((visibility("hidden"))).
2220  * When using the Sun Studio compiler, it expands to __hidden.
2221  *
2222  * Note that for portability, the attribute should be placed before the
2223  * function declaration. While GCC allows the macro after the declaration,
2224  * Sun Studio does not.
2225  *
2226  * |[<!-- language="C" -->
2227  * G_GNUC_INTERNAL
2228  * void _g_log_fallback_handler (const gchar    *log_domain,
2229  *                               GLogLevelFlags  log_level,
2230  *                               const gchar    *message,
2231  *                               gpointer        unused_data);
2232  * ]|
2233  *
2234  * Since: 2.6
2235  */
2236
2237 /**
2238  * G_GNUC_MAY_ALIAS:
2239  *
2240  * Expands to the GNU C may_alias type attribute if the compiler is gcc.
2241  * Types with this attribute will not be subjected to type-based alias
2242  * analysis, but are assumed to alias with any other type, just like char.
2243  *
2244  * See the GNU C documentation for details.
2245  *
2246  * Since: 2.14
2247  */
2248
2249 /**
2250  * G_LIKELY:
2251  * @expr: the expression
2252  *
2253  * Hints the compiler that the expression is likely to evaluate to
2254  * a true value. The compiler may use this information for optimizations.
2255  *
2256  * |[<!-- language="C" -->
2257  * if (G_LIKELY (random () != 1))
2258  *   g_print ("not one");
2259  * ]|
2260  *
2261  * Returns: the value of @expr
2262  *
2263  * Since: 2.2
2264  */
2265
2266 /**
2267  * G_UNLIKELY:
2268  * @expr: the expression
2269  *
2270  * Hints the compiler that the expression is unlikely to evaluate to
2271  * a true value. The compiler may use this information for optimizations.
2272  *
2273  * |[<!-- language="C" -->
2274  * if (G_UNLIKELY (random () == 1))
2275  *   g_print ("a random one");
2276  * ]|
2277  *
2278  * Returns: the value of @expr
2279  *
2280  * Since: 2.2
2281  */
2282
2283 /**
2284  * G_STRLOC:
2285  *
2286  * Expands to a string identifying the current code position.
2287  */
2288
2289 /**
2290  * G_STRFUNC:
2291  *
2292  * Expands to a string identifying the current function.
2293  *
2294  * Since: 2.4
2295  */
2296
2297 /* Windows Compatibility Functions {{{1 */
2298
2299 /**
2300  * SECTION:windows
2301  * @title: Windows Compatibility Functions
2302  * @short_description: UNIX emulation on Windows
2303  *
2304  * These functions provide some level of UNIX emulation on the
2305  * Windows platform. If your application really needs the POSIX
2306  * APIs, we suggest you try the Cygwin project.
2307  */
2308
2309 /**
2310  * MAXPATHLEN:
2311  *
2312  * Provided for UNIX emulation on Windows; equivalent to UNIX
2313  * macro %MAXPATHLEN, which is the maximum length of a filename
2314  * (including full path).
2315  */
2316
2317 /**
2318  * G_WIN32_DLLMAIN_FOR_DLL_NAME:
2319  * @static: empty or "static"
2320  * @dll_name: the name of the (pointer to the) char array where
2321  *     the DLL name will be stored. If this is used, you must also
2322  *     include `windows.h`. If you need a more complex DLL entry
2323  *     point function, you cannot use this
2324  *
2325  * On Windows, this macro defines a DllMain() function that stores
2326  * the actual DLL name that the code being compiled will be included in.
2327  *
2328  * On non-Windows platforms, expands to nothing.
2329  */
2330
2331 /**
2332  * G_WIN32_HAVE_WIDECHAR_API:
2333  *
2334  * On Windows, this macro defines an expression which evaluates to
2335  * %TRUE if the code is running on a version of Windows where the wide
2336  * character versions of the Win32 API functions, and the wide character
2337  * versions of the C library functions work. (They are always present in
2338  * the DLLs, but don't work on Windows 9x and Me.)
2339  *
2340  * On non-Windows platforms, it is not defined.
2341  *
2342  * Since: 2.6
2343  */
2344
2345
2346 /**
2347  * G_WIN32_IS_NT_BASED:
2348  *
2349  * On Windows, this macro defines an expression which evaluates to
2350  * %TRUE if the code is running on an NT-based Windows operating system.
2351  *
2352  * On non-Windows platforms, it is not defined.
2353  *
2354  * Since: 2.6
2355  */
2356  
2357  /* Epilogue {{{1 */
2358 /* vim: set foldmethod=marker: */