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