2 * Copyright © 2011 Red Hat, Inc
4 * SPDX-License-Identifier: LGPL-2.1-or-later
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 * Author: Matthias Clasen
23 /* This file collects documentation for macros, typedefs and
24 * the like, which have no good home in any of the 'real' source
28 /* Basic types {{{1 */
33 * @short_description: standard GLib types, defined for ease-of-use
36 * GLib defines a number of commonly used types, which can be divided
37 * into several groups:
38 * - New types which are not part of standard C (but are defined in
39 * various C standard library header files) — #gboolean, #gssize.
40 * - Integer types which are guaranteed to be the same size across
41 * all platforms — #gint8, #guint8, #gint16, #guint16, #gint32,
42 * #guint32, #gint64, #guint64.
43 * - Types which are easier to use than their standard C counterparts -
44 * #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
45 * - Types which correspond exactly to standard C types, but are
46 * included for completeness — #gchar, #gint, #gshort, #glong,
48 * - Types which correspond exactly to standard C99 types, but are available
49 * to use even if your compiler does not support C99 — #gsize, #goffset,
50 * #gintptr, #guintptr.
52 * GLib also defines macros for the limits of some of the standard
53 * integer and floating point types, as well as macros for suitable
54 * printf() formats for these types.
56 * Note that depending on the platform and build configuration, the format
57 * macros might not be compatible with the system provided printf() function,
58 * because GLib might use a different printf() implementation internally.
59 * The format macros will always work with GLib API (like g_print()), and with
60 * any C99 compatible printf() implementation.
66 * A standard boolean type.
67 * Variables of this type should only contain the value
70 * Never directly compare the contents of a #gboolean variable with the values
71 * %TRUE or %FALSE. Use `if (condition)` to check a #gboolean is "true", instead
72 * of `if (condition == TRUE)`. Likewise use `if (!condition)` to check a
73 * #gboolean is "false".
75 * There is no validation when assigning to a #gboolean variable and so it could
76 * contain any value represented by a #gint. This is why the use of `if
77 * (condition)` is recommended. All non-zero values in C evaluate to "true".
83 * An untyped pointer, exactly equivalent to `void *`.
85 * The standard C `void *` type should usually be preferred in
86 * new code, but `gpointer` can be used in contexts where a type name
87 * must be a single word, such as in the g_type_name() of %G_TYPE_POINTER
88 * or when generating a family of function names for multiple types
95 * An untyped pointer to constant data, exactly equivalent to `const void *`.
97 * The data pointed to should not be changed.
99 * This is typically used in function prototypes to indicate
100 * that the data pointed to will not be altered by the function.
102 * The standard C `const void *` type should usually be preferred in
103 * new code, but `gconstpointer` can be used in contexts where a type name
104 * must be a single word.
110 * Equivalent to the standard C `char` type.
112 * This type only exists for symmetry with `guchar`.
113 * The standard C `char` type should be preferred in new code.
119 * Equivalent to the standard C `unsigned char` type.
121 * The standard C `unsigned char` type should usually be preferred in
122 * new code, but `guchar` can be used in contexts where a type name
123 * must be a single word, such as in the g_type_name() of %G_TYPE_UCHAR
124 * or when generating a family of function names for multiple types
131 * Equivalent to the standard C `int` type.
133 * Values of this type can range from `INT_MIN` to `INT_MAX`,
134 * or equivalently from %G_MININT to %G_MAXINT.
136 * This type only exists for symmetry with `guint`.
137 * The standard C `int` type should be preferred in new code.
143 * The minimum value which can be held in a #gint.
145 * This is the same as standard C `INT_MIN`, which is available since C99
146 * and should be preferred in new code.
152 * The maximum value which can be held in a #gint.
154 * This is the same as standard C `INT_MAX`, which is available since C99
155 * and should be preferred in new code.
161 * Equivalent to the standard C `unsigned int` type.
163 * Values of this type can range from 0 to `UINT_MAX`,
164 * or equivalently 0 to %G_MAXUINT.
166 * The standard C `unsigned int` type should usually be preferred in
167 * new code, but `guint` can be used in contexts where a type name
168 * must be a single word, such as in the g_type_name() of %G_TYPE_UINT
169 * or when generating a family of function names for multiple types
176 * The maximum value which can be held in a #guint.
178 * This is the same as standard C `UINT_MAX`, which is available since C99
179 * and should be preferred in new code.
185 * Equivalent to the standard C `short` type.
187 * Values of this type can range from `SHRT_MIN` to `SHRT_MAX`,
188 * or equivalently %G_MINSHORT to %G_MAXSHORT.
190 * This type only exists for symmetry with `gushort`.
191 * The standard C `short` type should be preferred in new code.
197 * The minimum value which can be held in a #gshort.
199 * This is the same as standard C `SHRT_MIN`, which is available since C99
200 * and should be preferred in new code.
206 * The maximum value which can be held in a #gshort.
208 * This is the same as standard C `SHRT_MAX`, which is available since C99
209 * and should be preferred in new code.
215 * Equivalent to the standard C `unsigned short` type.
217 * Values of this type can range from 0 to `USHRT_MAX`,
218 * or equivalently from 0 to %G_MAXUSHORT.
220 * The standard C `unsigned short` type should usually be preferred in
221 * new code, but `gushort` can be used in contexts where a type name
222 * must be a single word, such as when generating a family of function
223 * names for multiple types using macros.
229 * The maximum value which can be held in a #gushort.
231 * This is the same as standard C `USHRT_MAX`, which is available since C99
232 * and should be preferred in new code.
238 * Equivalent to the standard C `long` type.
240 * Values of this type can range from `LONG_MIN` to `LONG_MAX`,
241 * or equivalently %G_MINLONG to %G_MAXLONG.
243 * This type only exists for symmetry with `gulong`.
244 * The standard C `long` type should be preferred in new code.
250 * The minimum value which can be held in a #glong.
252 * This is the same as standard C `LONG_MIN`, which is available since C99
253 * and should be preferred in new code.
259 * The maximum value which can be held in a #glong.
261 * This is the same as standard C `ULONG_MAX`, which is available since C99
262 * and should be preferred in new code.
268 * Equivalent to the standard C `unsigned long` type.
270 * Values of this type can range from 0 to %G_MAXULONG.
272 * The standard C `unsigned long` type should usually be preferred in
273 * new code, but `gulong` can be used in contexts where a type name
274 * must be a single word, such as in the g_type_name() of %G_TYPE_ULONG
275 * or when generating a family of function names for multiple types
282 * The maximum value which can be held in a #gulong.
284 * This is the same as standard C `ULONG_MAX`, which is available since C99
285 * and should be preferred in new code.
291 * A signed integer guaranteed to be 8 bits on all platforms,
292 * similar to the standard C `int8_t`.
294 * The `int8_t` type should be preferred in new code, unless
295 * consistency with pre-existing APIs requires use of `gint8`
296 * (see #gsize for more details).
298 * Values of this type can range from %G_MININT8 (= -128) to
299 * %G_MAXINT8 (= 127).
305 * The maximum value which can be held in a #gint8.
307 * This is the same as standard C `INT8_MAX`, which should be
308 * preferred in new code.
316 * An unsigned integer guaranteed to be 8 bits on all platforms,
317 * similar to the standard C `uint8_t`.
319 * The `uint8_t` type should be preferred in new code, unless
320 * consistency with pre-existing APIs requires use of `guint8`
321 * (see #gsize for more details).
323 * Values of this type can range from 0 to %G_MAXUINT8 (= 255).
329 * The maximum value which can be held in a #guint8.
331 * This is the same as standard C `UINT8_MAX`, which should be
332 * preferred in new code.
340 * A signed integer guaranteed to be 16 bits on all platforms,
341 * similar to the standard C `int16_t`.
343 * The `int16_t` type should be preferred in new code, unless
344 * consistency with pre-existing APIs requires use of `gint16`
345 * (see #gsize for more details).
347 * Values of this type can range from %G_MININT16 (= -32,768) to
348 * %G_MAXINT16 (= 32,767).
350 * To print or scan values of this type, use
351 * %G_GINT16_MODIFIER and/or %G_GINT16_FORMAT.
357 * The maximum value which can be held in a #gint16.
359 * This is the same as standard C `INT16_MAX`, which should be
360 * preferred in new code.
368 * The platform dependent length modifier for conversion specifiers
369 * for scanning and printing values of type #gint16 or #guint16. It
370 * is a string literal, but doesn't include the percent-sign, such
371 * that you can add precision and length modifiers between percent-sign
372 * and conversion specifier and append a conversion specifier.
374 * The following example prints "0x7b";
375 * |[<!-- language="C" -->
376 * gint16 value = 123;
377 * g_print ("%#" G_GINT16_MODIFIER "x", value);
380 * This is not necessarily the correct modifier for printing and scanning
381 * `int16_t` values, even though the in-memory representation is the same.
382 * Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`.
390 * This is the platform dependent conversion specifier for scanning and
391 * printing values of type #gint16. It is a string literal, but doesn't
392 * include the percent-sign, such that you can add precision and length
393 * modifiers between percent-sign and conversion specifier.
395 * |[<!-- language="C" -->
398 * sscanf ("42", "%" G_GINT16_FORMAT, &in)
400 * g_print ("%" G_GINT32_FORMAT, out);
402 * This is not necessarily the correct format for printing and scanning
403 * `int16_t` values, even though the in-memory representation is the same.
404 * Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`.
411 * An unsigned integer guaranteed to be 16 bits on all platforms,
412 * similar to the standard C `uint16_t`.
414 * The `uint16_t` type should be preferred in new code, unless
415 * consistency with pre-existing APIs requires use of `guint16`
416 * (see #gsize for more details).
418 * Values of this type can range from 0 to %G_MAXUINT16 (= 65,535).
420 * To print or scan values of this type, use
421 * %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT.
427 * The maximum value which can be held in a #guint16.
429 * This is the same as standard C `UINT16_MAX`, which should be
430 * preferred in new code.
438 * This is the platform dependent conversion specifier for scanning
439 * and printing values of type #guint16. See also %G_GINT16_FORMAT
441 * This is not necessarily the correct modifier for printing and scanning
442 * `uint16_t` values, even though the in-memory representation is the same.
443 * Standard C macros like `PRIu16` and `SCNu16` should be used for `uint16_t`.
449 * A signed integer guaranteed to be 32 bits on all platforms.
451 * The `int32_t` type should be preferred in new code, unless
452 * consistency with pre-existing APIs requires use of `gint16`
453 * (see #gsize for more details).
455 * Values of this type can range from %G_MININT32 (= -2,147,483,648)
456 * to %G_MAXINT32 (= 2,147,483,647).
458 * To print or scan values of this type, use
459 * %G_GINT32_MODIFIER and/or %G_GINT32_FORMAT.
461 * Note that on platforms with more than one 32-bit standard integer type,
462 * `gint32` and `int32_t` are not necessarily implemented by the same
463 * 32-bit integer type.
464 * For example, on an ILP32 platform where `int` and `long` are both 32-bit,
465 * it might be the case that one of these types is `int` and the other
467 * See #gsize for more details of what this implies.
473 * The maximum value which can be held in a #gint32.
475 * This is the same as standard C `INT32_MAX`, which should be
476 * preferred in new code.
484 * The platform dependent length modifier for conversion specifiers
485 * for scanning and printing values of type #gint32 or #guint32. It
486 * is a string literal. See also %G_GINT16_MODIFIER.
488 * This is not necessarily the correct modifier for printing and scanning
489 * `int32_t` values, even though the in-memory representation is the same.
490 * Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`.
498 * This is the platform dependent conversion specifier for scanning
499 * and printing values of type #gint32. See also %G_GINT16_FORMAT.
501 * This is not necessarily the correct modifier for printing and scanning
502 * `int32_t` values, even though the in-memory representation is the same.
503 * Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`.
509 * An unsigned integer guaranteed to be 32 bits on all platforms,
510 * similar to the standard C `uint32_t`.
512 * The `uint32_t` type should be preferred in new code, unless
513 * consistency with pre-existing APIs requires use of `guint32`
514 * (see #gsize for more details).
516 * Values of this type can range from 0 to %G_MAXUINT32 (= 4,294,967,295).
518 * To print or scan values of this type, use
519 * %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
521 * Note that on platforms with more than one 32-bit standard integer type,
522 * `guint32` and `uint32_t` are not necessarily implemented by the same
523 * 32-bit integer type.
524 * See #gsize for more details of what this implies.
530 * The maximum value which can be held in a #guint32.
532 * This is the same as standard C `UINT32_MAX`, which should be
533 * preferred in new code.
541 * This is the platform dependent conversion specifier for scanning
542 * and printing values of type #guint32. See also %G_GINT16_FORMAT.
544 * This is not necessarily the correct modifier for printing and scanning
545 * `uint32_t` values, even though the in-memory representation is the same.
546 * Standard C macros like `PRIu32` and `SCNu32` should be used for `uint32_t`.
552 * A signed integer guaranteed to be 64 bits on all platforms,
553 * similar to the standard C `int64_t`.
555 * The `int64_t` type should be preferred in new code, unless
556 * consistency with pre-existing APIs requires use of `gint64`
557 * (see #gsize for more details).
559 * Values of this type can range from %G_MININT64
560 * (= -9,223,372,036,854,775,808) to %G_MAXINT64
561 * (= 9,223,372,036,854,775,807).
563 * To print or scan values of this type, use
564 * %G_GINT64_MODIFIER and/or %G_GINT64_FORMAT.
566 * Note that on platforms with more than one 64-bit standard integer type,
567 * `gint64` and `int64_t` are not necessarily implemented by the same
568 * 64-bit integer type.
569 * For example, on a platform where both `long` and `long long` are 64-bit,
570 * it might be the case that one of those types is used for `gint64`
571 * and the other is used for `int64_t`.
572 * See #gsize for more details of what this implies.
578 * The maximum value which can be held in a #gint64.
584 * The platform dependent length modifier for conversion specifiers
585 * for scanning and printing values of type #gint64 or #guint64.
586 * It is a string literal.
588 * Some platforms do not support printing 64-bit integers, even
589 * though the types are supported. On such platforms %G_GINT64_MODIFIER
592 * This is not necessarily the correct modifier for printing and scanning
593 * `int64_t` values, even though the in-memory representation is the same.
594 * Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`.
602 * This is the platform dependent conversion specifier for scanning
603 * and printing values of type #gint64. See also %G_GINT16_FORMAT.
605 * Some platforms do not support scanning and printing 64-bit integers,
606 * even though the types are supported. On such platforms %G_GINT64_FORMAT
607 * is not defined. Note that scanf() may not support 64-bit integers, even
608 * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
609 * is not recommended for parsing anyway; consider using g_ascii_strtoull()
612 * This is not necessarily the correct format for printing and scanning
613 * `int64_t` values, even though the in-memory representation is the same.
614 * Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`.
620 * An unsigned integer guaranteed to be 64-bits on all platforms,
621 * similar to the standard C `uint64_t` type.
623 * The `uint64_t` type should be preferred in new code, unless
624 * consistency with pre-existing APIs requires use of `guint64`
625 * (see #gsize for more details).
627 * Values of this type can range from 0 to %G_MAXUINT64
628 * (= 18,446,744,073,709,551,615).
630 * To print or scan values of this type, use
631 * %G_GINT64_MODIFIER and/or %G_GUINT64_FORMAT.
633 * Note that on platforms with more than one 64-bit standard integer type,
634 * `guint64` and `uint64_t` are not necessarily implemented by the same
635 * 64-bit integer type.
636 * See #gsize for more details of what this implies.
642 * The maximum value which can be held in a #guint64.
644 * This is the same as standard C `UINT64_MAX`, which should be
645 * preferred in new code.
651 * This is the platform dependent conversion specifier for scanning
652 * and printing values of type #guint64. See also %G_GINT16_FORMAT.
654 * Some platforms do not support scanning and printing 64-bit integers,
655 * even though the types are supported. On such platforms %G_GUINT64_FORMAT
656 * is not defined. Note that scanf() may not support 64-bit integers, even
657 * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
658 * is not recommended for parsing anyway; consider using g_ascii_strtoull()
661 * This is not necessarily the correct modifier for printing and scanning
662 * `uint64_t` values, even though the in-memory representation is the same.
663 * Standard C macros like `PRIu64` and `SCNu64` should be used for `uint64_t`.
668 * @val: a literal integer value, e.g. 0x1d636b02300a7aa7
670 * This macro is used to insert 64-bit integer literals
671 * into the source code.
673 * It is similar to the standard C `INT64_C` macro,
674 * which should be preferred in new code.
678 * G_GUINT64_CONSTANT:
679 * @val: a literal integer value, e.g. 0x1d636b02300a7aa7U
681 * This macro is used to insert 64-bit unsigned integer
682 * literals into the source code.
684 * It is similar to the standard C `UINT64_C` macro,
685 * which should be preferred in new code.
693 * Equivalent to the standard C `float` type.
695 * Values of this type can range from `-FLT_MAX` to `FLT_MAX`,
696 * or equivalently from -%G_MAXFLOAT to %G_MAXFLOAT.
702 * The minimum positive value which can be held in a #gfloat.
704 * If you are interested in the smallest value which can be held
705 * in a #gfloat, use -%G_MAXFLOAT.
707 * This is the same as standard C `FLT_MIN`, which is available since C99
708 * and should be preferred in new code.
714 * The maximum value which can be held in a #gfloat.
716 * This is the same as standard C `FLT_MAX`, which is available since C99
717 * and should be preferred in new code.
723 * Equivalent to the standard C `double` type.
725 * Values of this type can range from `-DBL_MAX` to `DBL_MAX`,
726 * or equivalently from -%G_MAXDOUBLE to %G_MAXDOUBLE.
732 * The minimum positive value which can be held in a #gdouble.
734 * If you are interested in the smallest value which can be held
735 * in a #gdouble, use -%G_MAXDOUBLE.
737 * This is the same as standard C `DBL_MIN`, which is available since C99
738 * and should be preferred in new code.
744 * The maximum value which can be held in a #gdouble.
746 * This is the same as standard C `DBL_MAX`, which is available since C99
747 * and should be preferred in new code.
753 * An unsigned integer type of the result of the `sizeof` operator,
754 * corresponding to the `size_t` type defined in C99.
756 * The standard `size_t` type should be preferred in new code, unless
757 * consistency with pre-existing APIs requires `gsize`
758 * (see below for more details).
760 * `gsize` is usually 32 bit wide on a 32-bit platform and 64 bit wide
761 * on a 64-bit platform. Values of this type can range from 0 to
764 * This type is wide enough to hold the size of the largest possible
765 * memory allocation, but is not guaranteed to be wide enough to hold
766 * the numeric value of a pointer: on platforms that use tagged pointers,
767 * such as [CHERI](https://cheri-cpu.org/), pointers can be numerically
768 * larger than the size of the address space.
769 * If the numeric value of a pointer needs to be stored in an integer
770 * without information loss, use the standard C types `intptr_t` or
771 * `uintptr_t`, or the similar GLib types #gintptr or #guintptr.
773 * To print or scan values of this type, use
774 * %G_GSIZE_MODIFIER and/or %G_GSIZE_FORMAT.
776 * Note that on platforms where more than one standard integer type is
777 * the same size, `size_t` and `gsize` are always the same size but are
778 * not necessarily implemented by the same standard integer type.
779 * For example, on an ILP32 platform where `int`, `long` and pointers
780 * are all 32-bit, `size_t` might be `unsigned long` while `gsize`
781 * might be `unsigned int`.
782 * This can result in compiler warnings or unexpected C++ name-mangling
783 * if the two types are used inconsistently.
785 * As a result, changing a type from `gsize` to `size_t` in existing APIs
786 * might be an incompatible API or ABI change, especially if C++
787 * is involved. The safe option is to leave existing APIs using the same type
788 * that they have historically used, and only use the standard C types in
791 * Similar considerations apply to all the fixed-size types
792 * (#gint8, #guint8, #gint16, #guint16, #gint32, #guint32, #gint64,
793 * #guint64 and #goffset), as well as #gintptr and #guintptr.
794 * Types that are 32 bits or larger are particularly likely to be
801 * The maximum value which can be held in a #gsize.
803 * This is the same as standard C `SIZE_MAX` (available since C99),
804 * which should be preferred in new code.
812 * The platform dependent length modifier for conversion specifiers
813 * for scanning and printing values of type #gsize. It
814 * is a string literal.
816 * Note that this is not necessarily the correct modifier to scan or
817 * print a `size_t`, even though the in-memory representation is the
818 * same. The Standard C `"z"` modifier should be used for `size_t`,
819 * assuming a C99-compliant `printf` implementation is available.
827 * This is the platform dependent conversion specifier for scanning
828 * and printing values of type #gsize. See also %G_GINT16_FORMAT.
830 * Note that this is not necessarily the correct format to scan or
831 * print a `size_t`, even though the in-memory representation is the
832 * same. The standard C `"zu"` format should be used for `size_t`,
833 * assuming a C99-compliant `printf` implementation is available.
841 * A signed variant of #gsize, corresponding to the
842 * `ssize_t` defined in POSIX or the similar `SSIZE_T` in Windows.
844 * In new platform-specific code, consider using `ssize_t` or `SSIZE_T`
847 * Values of this type can range from %G_MINSSIZE
850 * Note that on platforms where `ssize_t` is implemented, `ssize_t` and
851 * `gssize` might be implemented by different standard integer types
852 * of the same size. Similarly, on Windows, `SSIZE_T` and `gssize`
853 * might be implemented by different standard integer types of the same
854 * size. See #gsize for more details.
856 * This type is also not guaranteed to be the same as standard C
857 * `ptrdiff_t`, although they are the same on many platforms.
859 * To print or scan values of this type, use
860 * %G_GSSIZE_MODIFIER and/or %G_GSSIZE_FORMAT.
866 * The minimum value which can be held in a #gssize.
874 * The maximum value which can be held in a #gssize.
882 * This is the platform dependent conversion specifier for scanning
883 * and printing values of type #gssize. See also %G_GINT16_FORMAT.
885 * Note that this is not necessarily the correct format to scan or print
886 * a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory
887 * representation is the same.
888 * On POSIX platforms, the `"zd"` format should be used for `ssize_t`.
896 * The platform dependent length modifier for conversion specifiers
897 * for scanning and printing values of type #gssize. It
898 * is a string literal.
900 * Note that this is not necessarily the correct modifier to scan or print
901 * a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory
902 * representation is the same.
903 * On POSIX platforms, the `"z"` modifier should be used for `ssize_t`.
911 * A signed integer type that is used for file offsets,
912 * corresponding to the POSIX type `off_t` as if compiling with
913 * `_FILE_OFFSET_BITS` set to 64. #goffset is always 64 bits wide, even on
914 * 32-bit architectures, and even if `off_t` is only 32 bits.
915 * Values of this type can range from %G_MINOFFSET to
918 * To print or scan values of this type, use
919 * %G_GOFFSET_MODIFIER and/or %G_GOFFSET_FORMAT.
921 * On platforms with more than one 64-bit standard integer type,
922 * even if `off_t` is also 64 bits in size, `goffset` and `off_t` are not
923 * necessarily implemented by the same 64-bit integer type.
924 * See #gsize for more details of what this implies.
932 * The minimum value which can be held in a #goffset.
938 * The maximum value which can be held in a #goffset.
942 * G_GOFFSET_MODIFIER:
944 * The platform dependent length modifier for conversion specifiers
945 * for scanning and printing values of type #goffset. It is a string
946 * literal. See also %G_GINT64_MODIFIER.
948 * This modifier should only be used with #goffset values, and not
949 * with `off_t`, which is not necessarily the same type or even the same size.
957 * This is the platform dependent conversion specifier for scanning
958 * and printing values of type #goffset. See also %G_GINT64_FORMAT.
960 * This format should only be used with #goffset values, and not
961 * with `off_t`, which is not necessarily the same type or even the same size.
967 * G_GOFFSET_CONSTANT:
968 * @val: a literal integer value, e.g. 0x1d636b02300a7aa7
970 * This macro is used to insert #goffset 64-bit integer literals
971 * into the source code.
973 * See also G_GINT64_CONSTANT().
981 * Corresponds to the C99 type intptr_t,
982 * a signed integer type that can hold any pointer.
984 * The standard `intptr_t` type should be preferred in new code, unless
985 * consistency with pre-existing APIs requires `gintptr`.
986 * Note that `intptr_t` and `gintptr` might be implemented by different
987 * standard integer types of the same size. See #gsize for more details.
989 * #gintptr is not guaranteed to be the same type or the same size as #gssize,
990 * even though they are the same on many CPU architectures.
992 * To print or scan values of this type, use
993 * %G_GINTPTR_MODIFIER and/or %G_GINTPTR_FORMAT.
999 * G_GINTPTR_MODIFIER:
1001 * The platform dependent length modifier for conversion specifiers
1002 * for scanning and printing values of type #gintptr or #guintptr.
1003 * It is a string literal.
1005 * Note that this is not necessarily the correct modifier to scan or
1006 * print an `intptr_t`, even though the in-memory representation is the
1008 * Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for
1017 * This is the platform dependent conversion specifier for scanning
1018 * and printing values of type #gintptr.
1020 * Note that this is not necessarily the correct format to scan or
1021 * print an `intptr_t`, even though the in-memory representation is the
1023 * Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for
1032 * Corresponds to the C99 type uintptr_t,
1033 * an unsigned integer type that can hold any pointer.
1035 * The standard `uintptr_t` type should be preferred in new code, unless
1036 * consistency with pre-existing APIs requires `guintptr`.
1037 * Note that `uintptr_t` and `guintptr` might be implemented by different
1038 * standard integer types of the same size. See #gsize for more details.
1040 * #guintptr is not guaranteed to be the same type or the same size as #gsize,
1041 * even though they are the same on many CPU architectures.
1043 * To print or scan values of this type, use
1044 * %G_GINTPTR_MODIFIER and/or %G_GUINTPTR_FORMAT.
1050 * G_GUINTPTR_FORMAT:
1052 * This is the platform dependent conversion specifier
1053 * for scanning and printing values of type #guintptr.
1055 * Note that this is not necessarily the correct format to scan or
1056 * print a `uintptr_t`, even though the in-memory representation is the
1058 * Standard C macros like `PRIuPTR` and `SCNuPTR` should be used for
1064 /* Type conversion {{{1 */
1067 * SECTION:type_conversion
1068 * @title: Type Conversion Macros
1069 * @short_description: portably storing integers in pointer variables
1071 * Many times GLib, GTK, and other libraries allow you to pass "user
1072 * data" to a callback, in the form of a void pointer. From time to time
1073 * you want to pass an integer instead of a pointer. You could allocate
1074 * an integer, with something like:
1075 * |[<!-- language="C" -->
1076 * int *ip = g_new (int, 1);
1079 * But this is inconvenient, and it's annoying to have to free the
1080 * memory at some later time.
1082 * Pointers are always at least 32 bits in size (on all platforms GLib
1083 * intends to support). Thus you can store at least 32-bit integer values
1084 * in a pointer value. Naively, you might try this, but it's incorrect:
1085 * |[<!-- language="C" -->
1091 * Again, that example was not correct, don't copy it.
1092 * The problem is that on some systems you need to do this:
1093 * |[<!-- language="C" -->
1096 * p = (void*) (long) 42;
1097 * i = (int) (long) p;
1099 * The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care
1100 * to do the right thing on every platform.
1102 * Warning: You may not store pointers in integers. This is not
1103 * portable in any way, shape or form. These macros only allow storing
1104 * integers in pointers, and only preserve 32 bits of the integer; values
1105 * outside the range of a 32-bit integer will be mangled.
1110 * @i: integer to stuff into a pointer
1112 * Stuffs an integer into a pointer type.
1114 * Remember, you may not store pointers in integers. This is not portable
1115 * in any way, shape or form. These macros only allow storing integers in
1116 * pointers, and only preserve 32 bits of the integer; values outside the
1117 * range of a 32-bit integer will be mangled.
1122 * @p: pointer containing an integer
1124 * Extracts an integer from a pointer. The integer must have
1125 * been stored in the pointer with GINT_TO_POINTER().
1127 * Remember, you may not store pointers in integers. This is not portable
1128 * in any way, shape or form. These macros only allow storing integers in
1129 * pointers, and only preserve 32 bits of the integer; values outside the
1130 * range of a 32-bit integer will be mangled.
1135 * @u: unsigned integer to stuff into the pointer
1137 * Stuffs an unsigned integer into a pointer type.
1142 * @p: pointer to extract an unsigned integer from
1144 * Extracts an unsigned integer from a pointer. The integer must have
1145 * been stored in the pointer with GUINT_TO_POINTER().
1150 * @s: #gsize to stuff into the pointer
1152 * Stuffs a #gsize into a pointer type.
1157 * @p: pointer to extract a #gsize from
1159 * Extracts a #gsize from a pointer. The #gsize must have
1160 * been stored in the pointer with GSIZE_TO_POINTER().
1163 /* Byte order {{{1 */
1166 * SECTION:byte_order
1167 * @title: Byte Order Macros
1168 * @short_description: a portable way to convert between different byte orders
1170 * These macros provide a portable way to determine the host byte order
1171 * and to convert values between different byte orders.
1173 * The byte order is the order in which bytes are stored to create larger
1174 * data types such as the #gint and #glong values.
1175 * The host byte order is the byte order used on the current machine.
1177 * Some processors store the most significant bytes (i.e. the bytes that
1178 * hold the largest part of the value) first. These are known as big-endian
1179 * processors. Other processors (notably the x86 family) store the most
1180 * significant byte last. These are known as little-endian processors.
1182 * Finally, to complicate matters, some other processors store the bytes in
1183 * a rather curious order known as PDP-endian. For a 4-byte word, the 3rd
1184 * most significant byte is stored first, then the 4th, then the 1st and
1187 * Obviously there is a problem when these different processors communicate
1188 * with each other, for example over networks or by using binary file formats.
1189 * This is where these macros come in. They are typically used to convert
1190 * values into a byte order which has been agreed on for use when
1191 * communicating between different processors. The Internet uses what is
1192 * known as 'network byte order' as the standard byte order (which is in
1193 * fact the big-endian byte order).
1195 * Note that the byte order conversion macros may evaluate their arguments
1196 * multiple times, thus you should not use them with arguments which have
1203 * The host byte order.
1204 * This can be either %G_LITTLE_ENDIAN or %G_BIG_ENDIAN (support for
1205 * %G_PDP_ENDIAN may be added in future.)
1211 * Specifies one of the possible types of byte order.
1212 * See %G_BYTE_ORDER.
1218 * Specifies one of the possible types of byte order.
1219 * See %G_BYTE_ORDER.
1225 * Specifies one of the possible types of byte order
1226 * (currently unused). See %G_BYTE_ORDER.
1231 * @val: a 32-bit integer value in host byte order
1233 * Converts a 32-bit integer value from host to network byte order.
1235 * Returns: @val converted to network byte order
1240 * @val: a 16-bit integer value in host byte order
1242 * Converts a 16-bit integer value from host to network byte order.
1244 * Returns: @val converted to network byte order
1249 * @val: a 32-bit integer value in network byte order
1251 * Converts a 32-bit integer value from network to host byte order.
1253 * Returns: @val converted to host byte order.
1258 * @val: a 16-bit integer value in network byte order
1260 * Converts a 16-bit integer value from network to host byte order.
1262 * Returns: @val converted to host byte order
1267 * @val: a #gint value in big-endian byte order
1269 * Converts a #gint value from big-endian to host byte order.
1271 * Returns: @val converted to host byte order
1276 * @val: a #gint value in little-endian byte order
1278 * Converts a #gint value from little-endian to host byte order.
1280 * Returns: @val converted to host byte order
1285 * @val: a #gint value in host byte order
1287 * Converts a #gint value from host byte order to big-endian.
1289 * Returns: @val converted to big-endian byte order
1294 * @val: a #gint value in host byte order
1296 * Converts a #gint value from host byte order to little-endian.
1298 * Returns: @val converted to little-endian byte order
1303 * @val: a #guint value in big-endian byte order
1305 * Converts a #guint value from big-endian to host byte order.
1307 * Returns: @val converted to host byte order
1312 * @val: a #guint value in little-endian byte order
1314 * Converts a #guint value from little-endian to host byte order.
1316 * Returns: @val converted to host byte order
1321 * @val: a #guint value in host byte order
1323 * Converts a #guint value from host byte order to big-endian.
1325 * Returns: @val converted to big-endian byte order
1330 * @val: a #guint value in host byte order
1332 * Converts a #guint value from host byte order to little-endian.
1334 * Returns: @val converted to little-endian byte order.
1339 * @val: a #glong value in big-endian byte order
1341 * Converts a #glong value from big-endian to the host byte order.
1343 * Returns: @val converted to host byte order
1348 * @val: a #glong value in little-endian byte order
1350 * Converts a #glong value from little-endian to host byte order.
1352 * Returns: @val converted to host byte order
1357 * @val: a #glong value in host byte order
1359 * Converts a #glong value from host byte order to big-endian.
1361 * Returns: @val converted to big-endian byte order
1366 * @val: a #glong value in host byte order
1368 * Converts a #glong value from host byte order to little-endian.
1370 * Returns: @val converted to little-endian
1375 * @val: a #gulong value in big-endian byte order
1377 * Converts a #gulong value from big-endian to host byte order.
1379 * Returns: @val converted to host byte order
1384 * @val: a #gulong value in little-endian byte order
1386 * Converts a #gulong value from little-endian to host byte order.
1388 * Returns: @val converted to host byte order
1393 * @val: a #gulong value in host byte order
1395 * Converts a #gulong value from host byte order to big-endian.
1397 * Returns: @val converted to big-endian
1402 * @val: a #gulong value in host byte order
1404 * Converts a #gulong value from host byte order to little-endian.
1406 * Returns: @val converted to little-endian
1411 * @val: a #gsize value in big-endian byte order
1413 * Converts a #gsize value from big-endian to the host byte order.
1415 * Returns: @val converted to host byte order
1420 * @val: a #gsize value in little-endian byte order
1422 * Converts a #gsize value from little-endian to host byte order.
1424 * Returns: @val converted to host byte order
1429 * @val: a #gsize value in host byte order
1431 * Converts a #gsize value from host byte order to big-endian.
1433 * Returns: @val converted to big-endian byte order
1438 * @val: a #gsize value in host byte order
1440 * Converts a #gsize value from host byte order to little-endian.
1442 * Returns: @val converted to little-endian
1447 * @val: a #gssize value in big-endian byte order
1449 * Converts a #gssize value from big-endian to host byte order.
1451 * Returns: @val converted to host byte order
1456 * @val: a #gssize value in little-endian byte order
1458 * Converts a #gssize value from little-endian to host byte order.
1460 * Returns: @val converted to host byte order
1465 * @val: a #gssize value in host byte order
1467 * Converts a #gssize value from host byte order to big-endian.
1469 * Returns: @val converted to big-endian
1474 * @val: a #gssize value in host byte order
1476 * Converts a #gssize value from host byte order to little-endian.
1478 * Returns: @val converted to little-endian
1483 * @val: a #gint16 value in big-endian byte order
1485 * Converts a #gint16 value from big-endian to host byte order.
1487 * Returns: @val converted to host byte order
1492 * @val: a #gint16 value in little-endian byte order
1494 * Converts a #gint16 value from little-endian to host byte order.
1496 * Returns: @val converted to host byte order
1501 * @val: a #gint16 value in host byte order
1503 * Converts a #gint16 value from host byte order to big-endian.
1505 * Returns: @val converted to big-endian
1510 * @val: a #gint16 value in host byte order
1512 * Converts a #gint16 value from host byte order to little-endian.
1514 * Returns: @val converted to little-endian
1519 * @val: a #guint16 value in big-endian byte order
1521 * Converts a #guint16 value from big-endian to host byte order.
1523 * Returns: @val converted to host byte order
1528 * @val: a #guint16 value in little-endian byte order
1530 * Converts a #guint16 value from little-endian to host byte order.
1532 * Returns: @val converted to host byte order
1537 * @val: a #guint16 value in host byte order
1539 * Converts a #guint16 value from host byte order to big-endian.
1541 * Returns: @val converted to big-endian
1546 * @val: a #guint16 value in host byte order
1548 * Converts a #guint16 value from host byte order to little-endian.
1550 * Returns: @val converted to little-endian
1555 * @val: a #gint32 value in big-endian byte order
1557 * Converts a #gint32 value from big-endian to host byte order.
1559 * Returns: @val converted to host byte order
1564 * @val: a #gint32 value in little-endian byte order
1566 * Converts a #gint32 value from little-endian to host byte order.
1568 * Returns: @val converted to host byte order
1573 * @val: a #gint32 value in host byte order
1575 * Converts a #gint32 value from host byte order to big-endian.
1577 * Returns: @val converted to big-endian
1582 * @val: a #gint32 value in host byte order
1584 * Converts a #gint32 value from host byte order to little-endian.
1586 * Returns: @val converted to little-endian
1591 * @val: a #guint32 value in big-endian byte order
1593 * Converts a #guint32 value from big-endian to host byte order.
1595 * Returns: @val converted to host byte order
1600 * @val: a #guint32 value in little-endian byte order
1602 * Converts a #guint32 value from little-endian to host byte order.
1604 * Returns: @val converted to host byte order
1609 * @val: a #guint32 value in host byte order
1611 * Converts a #guint32 value from host byte order to big-endian.
1613 * Returns: @val converted to big-endian
1618 * @val: a #guint32 value in host byte order
1620 * Converts a #guint32 value from host byte order to little-endian.
1622 * Returns: @val converted to little-endian
1627 * @val: a #gint64 value in big-endian byte order
1629 * Converts a #gint64 value from big-endian to host byte order.
1631 * Returns: @val converted to host byte order
1636 * @val: a #gint64 value in little-endian byte order
1638 * Converts a #gint64 value from little-endian to host byte order.
1640 * Returns: @val converted to host byte order
1645 * @val: a #gint64 value in host byte order
1647 * Converts a #gint64 value from host byte order to big-endian.
1649 * Returns: @val converted to big-endian
1654 * @val: a #gint64 value in host byte order
1656 * Converts a #gint64 value from host byte order to little-endian.
1658 * Returns: @val converted to little-endian
1663 * @val: a #guint64 value in big-endian byte order
1665 * Converts a #guint64 value from big-endian to host byte order.
1667 * Returns: @val converted to host byte order
1672 * @val: a #guint64 value in little-endian byte order
1674 * Converts a #guint64 value from little-endian to host byte order.
1676 * Returns: @val converted to host byte order
1681 * @val: a #guint64 value in host byte order
1683 * Converts a #guint64 value from host byte order to big-endian.
1685 * Returns: @val converted to big-endian
1690 * @val: a #guint64 value in host byte order
1692 * Converts a #guint64 value from host byte order to little-endian.
1694 * Returns: @val converted to little-endian
1698 * GUINT16_SWAP_BE_PDP:
1699 * @val: a #guint16 value in big-endian or pdp-endian byte order
1701 * Converts a #guint16 value between big-endian and pdp-endian byte order.
1702 * The conversion is symmetric so it can be used both ways.
1704 * Returns: @val converted to the opposite byte order
1708 * GUINT16_SWAP_LE_BE:
1709 * @val: a #guint16 value in little-endian or big-endian byte order
1711 * Converts a #guint16 value between little-endian and big-endian byte order.
1712 * The conversion is symmetric so it can be used both ways.
1714 * Returns: @val converted to the opposite byte order
1718 * GUINT16_SWAP_LE_PDP:
1719 * @val: a #guint16 value in little-endian or pdp-endian byte order
1721 * Converts a #guint16 value between little-endian and pdp-endian byte order.
1722 * The conversion is symmetric so it can be used both ways.
1724 * Returns: @val converted to the opposite byte order
1728 * GUINT32_SWAP_BE_PDP:
1729 * @val: a #guint32 value in big-endian or pdp-endian byte order
1731 * Converts a #guint32 value between big-endian and pdp-endian byte order.
1732 * The conversion is symmetric so it can be used both ways.
1734 * Returns: @val converted to the opposite byte order
1738 * GUINT32_SWAP_LE_BE:
1739 * @val: a #guint32 value in little-endian or big-endian byte order
1741 * Converts a #guint32 value between little-endian and big-endian byte order.
1742 * The conversion is symmetric so it can be used both ways.
1744 * Returns: @val converted to the opposite byte order
1748 * GUINT32_SWAP_LE_PDP:
1749 * @val: a #guint32 value in little-endian or pdp-endian byte order
1751 * Converts a #guint32 value between little-endian and pdp-endian byte order.
1752 * The conversion is symmetric so it can be used both ways.
1754 * Returns: @val converted to the opposite byte order
1758 * GUINT64_SWAP_LE_BE:
1759 * @val: a #guint64 value in little-endian or big-endian byte order
1761 * Converts a #guint64 value between little-endian and big-endian byte order.
1762 * The conversion is symmetric so it can be used both ways.
1764 * Returns: @val converted to the opposite byte order
1767 /* Bounds-checked integer arithmetic {{{1 */
1769 * SECTION:checkedmath
1770 * @title: Bounds-checking integer arithmetic
1771 * @short_description: a set of helpers for performing checked integer arithmetic
1773 * GLib offers a set of macros for doing additions and multiplications
1774 * of unsigned integers, with checks for overflows.
1776 * The helpers all have three arguments. A pointer to the destination
1777 * is always the first argument and the operands to the operation are
1780 * Following standard GLib convention, the helpers return %TRUE in case
1781 * of success (ie: no overflow).
1783 * The helpers may be macros, normal functions or inlines. They may be
1784 * implemented with inline assembly or compiler intrinsics where
1791 * g_uint_checked_add
1792 * @dest: a pointer to the #guint destination
1793 * @a: the #guint left operand
1794 * @b: the #guint right operand
1796 * Performs a checked addition of @a and @b, storing the result in
1799 * If the operation is successful, %TRUE is returned. If the operation
1800 * overflows then the state of @dest is undefined and %FALSE is
1803 * Returns: %TRUE if there was no overflow
1808 * g_uint_checked_mul
1809 * @dest: a pointer to the #guint destination
1810 * @a: the #guint left operand
1811 * @b: the #guint right operand
1813 * Performs a checked multiplication of @a and @b, storing the result in
1816 * If the operation is successful, %TRUE is returned. If the operation
1817 * overflows then the state of @dest is undefined and %FALSE is
1820 * Returns: %TRUE if there was no overflow
1825 * g_uint64_checked_add
1826 * @dest: a pointer to the #guint64 destination
1827 * @a: the #guint64 left operand
1828 * @b: the #guint64 right operand
1830 * Performs a checked addition of @a and @b, storing the result in
1833 * If the operation is successful, %TRUE is returned. If the operation
1834 * overflows then the state of @dest is undefined and %FALSE is
1837 * Returns: %TRUE if there was no overflow
1842 * g_uint64_checked_mul
1843 * @dest: a pointer to the #guint64 destination
1844 * @a: the #guint64 left operand
1845 * @b: the #guint64 right operand
1847 * Performs a checked multiplication of @a and @b, storing the result in
1850 * If the operation is successful, %TRUE is returned. If the operation
1851 * overflows then the state of @dest is undefined and %FALSE is
1854 * Returns: %TRUE if there was no overflow
1859 * g_size_checked_add
1860 * @dest: a pointer to the #gsize destination
1861 * @a: the #gsize left operand
1862 * @b: the #gsize right operand
1864 * Performs a checked addition of @a and @b, storing the result in
1867 * If the operation is successful, %TRUE is returned. If the operation
1868 * overflows then the state of @dest is undefined and %FALSE is
1871 * Returns: %TRUE if there was no overflow
1876 * g_size_checked_mul
1877 * @dest: a pointer to the #gsize destination
1878 * @a: the #gsize left operand
1879 * @b: the #gsize right operand
1881 * Performs a checked multiplication of @a and @b, storing the result in
1884 * If the operation is successful, %TRUE is returned. If the operation
1885 * overflows then the state of @dest is undefined and %FALSE is
1888 * Returns: %TRUE if there was no overflow
1891 /* Numerical Definitions {{{1 */
1895 * @title: Numerical Definitions
1896 * @short_description: mathematical constants, and floating point decomposition
1898 * GLib offers mathematical constants such as %G_PI for the value of pi;
1899 * many platforms have these in the C library, but some don't, the GLib
1900 * versions always exist.
1902 * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the
1903 * sign, mantissa and exponent of IEEE floats and doubles. These unions are
1904 * defined as appropriate for a given platform. IEEE floats and doubles are
1905 * supported (used for storage) by at least Intel, PPC and Sparc. See
1906 * [IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float)
1907 * for more information about IEEE number formats.
1911 * G_IEEE754_FLOAT_BIAS:
1913 * The bias by which exponents in single-precision floats are offset.
1917 * G_IEEE754_DOUBLE_BIAS:
1919 * The bias by which exponents in double-precision floats are offset.
1924 * @v_float: the double value
1926 * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
1927 * mantissa and exponent of IEEE floats and doubles. These unions are defined
1928 * as appropriate for a given platform. IEEE floats and doubles are supported
1929 * (used for storage) by at least Intel, PPC and Sparc.
1934 * @v_double: the double value
1936 * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
1937 * mantissa and exponent of IEEE floats and doubles. These unions are defined
1938 * as appropriate for a given platform. IEEE floats and doubles are supported
1939 * (used for storage) by at least Intel, PPC and Sparc.
1945 * The base of natural logarithms.
1951 * The natural logarithm of 2.
1957 * The natural logarithm of 10.
1963 * The value of pi (ratio of circle's circumference to its diameter).
1981 * The square root of two.
1987 * Multiplying the base 2 exponent by this number yields the base 10 exponent.
1994 * @title: Standard Macros
1995 * @short_description: commonly-used macros
1997 * These macros provide a few commonly-used features.
2003 * This macro is defined only on Windows. So you can bracket
2004 * Windows-specific code in "\#ifdef G_OS_WIN32".
2010 * This macro is defined only on UNIX. So you can bracket
2011 * UNIX-specific code in "\#ifdef G_OS_UNIX".
2013 * To detect whether to compile features that require a specific kernel
2014 * or operating system, check for the appropriate OS-specific predefined
2015 * macros instead, for example:
2017 * - Linux kernel (any libc, including glibc, musl or Android): `\#ifdef __linux__`
2018 * - Linux kernel and GNU user-space: `\#if defined(__linux__) && defined(__GLIBC__)`
2019 * - FreeBSD kernel (any libc, including glibc): `\#ifdef __FreeBSD_kernel__`
2020 * - FreeBSD kernel and user-space: `\#ifdef __FreeBSD__`
2021 * - Apple operating systems (macOS, iOS, tvOS), regardless of whether
2022 * Cocoa/Carbon toolkits are available: `\#ifdef __APPLE__`
2024 * See <https://sourceforge.net/p/predef/wiki/OperatingSystems/> for more.
2030 * The directory separator character.
2031 * This is '/' on UNIX machines and '\' under Windows.
2035 * G_DIR_SEPARATOR_S:
2037 * The directory separator as a string.
2038 * This is "/" on UNIX machines and "\" under Windows.
2042 * G_IS_DIR_SEPARATOR:
2045 * Checks whether a character is a directory
2046 * separator. It returns %TRUE for '/' on UNIX
2047 * machines and for '\' or '/' under Windows.
2053 * G_SEARCHPATH_SEPARATOR:
2055 * The search path separator character.
2056 * This is ':' on UNIX machines and ';' under Windows.
2060 * G_SEARCHPATH_SEPARATOR_S:
2062 * The search path separator as a string.
2063 * This is ":" on UNIX machines and ";" under Windows.
2069 * Defines the %TRUE value for the #gboolean type.
2075 * Defines the %FALSE value for the #gboolean type.
2081 * Defines the standard %NULL pointer.
2086 * @a: a numeric value
2087 * @b: a numeric value
2089 * Calculates the minimum of @a and @b.
2091 * Returns: the minimum of @a and @b.
2096 * @a: a numeric value
2097 * @b: a numeric value
2099 * Calculates the maximum of @a and @b.
2101 * Returns: the maximum of @a and @b.
2106 * @a: a numeric value
2108 * Calculates the absolute value of @a.
2109 * The absolute value is simply the number with any negative sign taken away.
2113 * - ABS(10) is also 10.
2115 * Returns: the absolute value of @a.
2120 * @x: the value to clamp
2121 * @low: the minimum value allowed
2122 * @high: the maximum value allowed
2124 * Ensures that @x is between the limits set by @low and @high. If @low is
2125 * greater than @high the result is undefined.
2128 * - CLAMP(5, 10, 15) is 10.
2129 * - CLAMP(15, 5, 10) is 10.
2130 * - CLAMP(20, 15, 25) is 20.
2132 * Returns: the value of @x clamped to the range between @low and @high
2137 * @a: a numeric value
2138 * @b: a numeric value
2139 * @epsilon: a numeric value that expresses the tolerance between @a and @b
2141 * Evaluates to a truth value if the absolute difference between @a and @b is
2142 * smaller than @epsilon, and to a false value otherwise.
2145 * - `G_APPROX_VALUE (5, 6, 2)` evaluates to true
2146 * - `G_APPROX_VALUE (3.14, 3.15, 0.001)` evaluates to false
2147 * - `G_APPROX_VALUE (n, 0.f, FLT_EPSILON)` evaluates to true if `n` is within
2148 * the single precision floating point epsilon from zero
2150 * Returns: %TRUE if the two values are within the desired range
2157 * @member_type: the type of the struct field
2158 * @struct_p: a pointer to a struct
2159 * @struct_offset: the offset of the field from the start of the struct,
2162 * Returns a member of a structure at a given offset, using the given type.
2164 * Returns: the struct member
2168 * G_STRUCT_MEMBER_P:
2169 * @struct_p: a pointer to a struct
2170 * @struct_offset: the offset from the start of the struct, in bytes
2172 * Returns an untyped pointer to a given offset of a struct.
2174 * Returns: an untyped pointer to @struct_p plus @struct_offset bytes
2179 * @struct_type: a structure type, e.g. #GtkWidget
2180 * @member: a field in the structure, e.g. @window
2182 * Returns the offset, in bytes, of a member of a struct.
2184 * Consider using standard C `offsetof()`, available since at least C89
2185 * and C++98, in new code (but note that `offsetof()` returns a `size_t`
2186 * rather than a `long`).
2188 * Returns: the offset of @member from the start of @struct_type,
2189 * as a value of type #glong.
2196 * Determines the number of elements in an array. The array must be
2197 * declared so the compiler knows its size at compile-time; this
2198 * macro will not work on an array allocated on the heap, only static
2199 * arrays or arrays on the stack.
2202 /* Miscellaneous Macros {{{1 */
2205 * SECTION:macros_misc
2206 * @title: Miscellaneous Macros
2207 * @short_description: specialized macros which are not used often
2209 * These macros provide more specialized features which are not
2210 * needed so often by application programmers.
2216 * Used within multi-statement macros so that they can be used in places
2217 * where only one statement is expected by the compiler.
2223 * Used within multi-statement macros so that they can be used in places
2224 * where only one statement is expected by the compiler.
2230 * Used (along with %G_END_DECLS) to bracket header files. If the
2231 * compiler in use is a C++ compiler, adds extern "C"
2232 * around the header.
2238 * Used (along with %G_BEGIN_DECLS) to bracket header files. If the
2239 * compiler in use is a C++ compiler, adds extern "C"
2240 * around the header.
2245 * @ap1: the va_list variable to place a copy of @ap2 in
2248 * Portable way to copy va_list variables.
2250 * In order to use this function, you must include string.h yourself,
2251 * because this macro may use memmove() and GLib does not include
2254 * Each invocation of `G_VA_COPY (ap1, ap2)` must be matched with a
2255 * corresponding `va_end (ap1)` call in the same function.
2257 * This is equivalent to standard C `va_copy()`, available since C99
2258 * and C++11, which should be preferred in new code.
2263 * @macro_or_string: a macro or a string
2265 * Accepts a macro or a string and converts it into a string after
2266 * preprocessor argument expansion. For example, the following code:
2268 * |[<!-- language="C" -->
2270 * const gchar *greeting = G_STRINGIFY (AGE) " today!";
2273 * is transformed by the preprocessor into (code equivalent to):
2275 * |[<!-- language="C" -->
2276 * const gchar *greeting = "27 today!";
2282 * @identifier1: an identifier
2283 * @identifier2: an identifier
2285 * Yields a new preprocessor pasted identifier
2286 * @identifier1identifier2 from its expanded
2287 * arguments @identifier1 and @identifier2. For example,
2288 * the following code:
2289 * |[<!-- language="C" -->
2290 * #define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller)
2291 * const gchar *name = GET (traveller, name);
2292 * const gchar *quest = GET (traveller, quest);
2293 * GdkColor *favourite = GET (traveller, favourite_colour);
2296 * is transformed by the preprocessor into:
2297 * |[<!-- language="C" -->
2298 * const gchar *name = traveller_get_name (traveller);
2299 * const gchar *quest = traveller_get_quest (traveller);
2300 * GdkColor *favourite = traveller_get_favourite_colour (traveller);
2308 * @expr: a constant expression
2310 * The G_STATIC_ASSERT() macro lets the programmer check
2311 * a condition at compile time, the condition needs to
2312 * be compile time computable. The macro can be used in
2313 * any place where a typedef is valid.
2315 * A typedef is generally allowed in exactly the same places that
2316 * a variable declaration is allowed. For this reason, you should
2317 * not use G_STATIC_ASSERT() in the middle of blocks of code.
2319 * The macro should only be used once per source code line.
2325 * G_STATIC_ASSERT_EXPR:
2326 * @expr: a constant expression
2328 * The G_STATIC_ASSERT_EXPR() macro lets the programmer check
2329 * a condition at compile time. The condition needs to be
2330 * compile time computable.
2332 * Unlike G_STATIC_ASSERT(), this macro evaluates to an expression
2333 * and, as such, can be used in the middle of other expressions.
2334 * Its value should be ignored. This can be accomplished by placing
2335 * it as the first argument of a comma expression.
2337 * |[<!-- language="C" -->
2338 * #define ADD_ONE_TO_INT(x) \
2339 * (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1))
2348 * Expands to __extension__ when gcc is used as the compiler. This simply
2349 * tells gcc not to warn about the following non-standard code when compiling
2350 * with the `-pedantic` option.
2354 * G_GNUC_CHECK_VERSION:
2355 * @major: major version to check against
2356 * @minor: minor version to check against
2358 * Expands to a check for a compiler with __GNUC__ defined and a version
2359 * greater than or equal to the major and minor numbers provided. For example,
2360 * the following would only match on compilers such as GCC 4.8 or newer.
2362 * |[<!-- language="C" -->
2363 * #if G_GNUC_CHECK_VERSION(4, 8)
2371 * G_GNUC_BEGIN_IGNORE_DEPRECATIONS:
2373 * Tells gcc (if it is a new enough version) to temporarily stop emitting
2374 * warnings when functions marked with %G_GNUC_DEPRECATED or
2375 * %G_GNUC_DEPRECATED_FOR are called. This is useful for when you have
2376 * one deprecated function calling another one, or when you still have
2377 * regression tests for deprecated functions.
2379 * Use %G_GNUC_END_IGNORE_DEPRECATIONS to begin warning again. (If you
2380 * are not compiling with `-Wdeprecated-declarations` then neither macro
2383 * This macro can be used either inside or outside of a function body,
2384 * but must appear on a line by itself. Both this macro and the corresponding
2385 * %G_GNUC_END_IGNORE_DEPRECATIONS are considered statements, so they
2386 * should not be used around branching or loop conditions; for instance,
2387 * this use is invalid:
2389 * |[<!-- language="C" -->
2390 * G_GNUC_BEGIN_IGNORE_DEPRECATIONS
2391 * if (check == some_deprecated_function ())
2392 * G_GNUC_END_IGNORE_DEPRECATIONS
2398 * and you should move the deprecated section outside the condition
2400 * |[<!-- language="C" -->
2405 * G_GNUC_BEGIN_IGNORE_DEPRECATIONS
2406 * res = some_deprecated_function ();
2407 * G_GNUC_END_IGNORE_DEPRECATIONS
2415 * G_GNUC_BEGIN_IGNORE_DEPRECATIONS
2416 * if (check == some_deprecated_function ())
2420 * G_GNUC_END_IGNORE_DEPRECATIONS
2423 * |[<!-- language="C" -->
2425 * test_deprecated_function (void)
2427 * G_GNUC_BEGIN_IGNORE_DEPRECATIONS
2428 * g_assert_cmpint (my_mistake (), ==, 42);
2429 * G_GNUC_END_IGNORE_DEPRECATIONS
2437 * G_GNUC_END_IGNORE_DEPRECATIONS:
2439 * Undoes the effect of %G_GNUC_BEGIN_IGNORE_DEPRECATIONS, telling
2440 * gcc to begin outputting warnings again (assuming those warnings
2441 * had been enabled to begin with).
2443 * This macro can be used either inside or outside of a function body,
2444 * but must appear on a line by itself.
2452 * This macro is similar to %G_GNUC_DEPRECATED, and can be used to mark
2453 * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED, it is
2454 * meant to be portable across different compilers and must be placed
2455 * before the function declaration.
2457 * |[<!-- language="C" -->
2459 * int my_mistake (void);
2467 * @f: the name of the function that this function was deprecated for
2469 * This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark
2470 * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it
2471 * is meant to be portable across different compilers and must be placed
2472 * before the function declaration.
2474 * |[<!-- language="C" -->
2475 * G_DEPRECATED_FOR(my_replacement)
2476 * int my_mistake (void);
2484 * @maj: the major version that introduced the symbol
2485 * @min: the minor version that introduced the symbol
2487 * This macro can be used to mark a function declaration as unavailable.
2488 * It must be placed before the function declaration. Use of a function
2489 * that has been annotated with this macros will produce a compiler warning.
2495 * GLIB_DISABLE_DEPRECATION_WARNINGS:
2497 * A macro that should be defined before including the glib.h header.
2498 * If it is defined, no compiler warnings will be produced for uses
2499 * of deprecated GLib APIs.
2505 * This attribute can be used for marking library functions as being used
2506 * internally to the library only, which may allow the compiler to handle
2507 * function calls more efficiently. Note that static functions do not need
2508 * to be marked as internal in this way. See the GNU C documentation for
2511 * When using a compiler that supports the GNU C hidden visibility attribute,
2512 * this macro expands to __attribute__((visibility("hidden"))).
2513 * When using the Sun Studio compiler, it expands to __hidden.
2515 * Note that for portability, the attribute should be placed before the
2516 * function declaration. While GCC allows the macro after the declaration,
2517 * Sun Studio does not.
2519 * |[<!-- language="C" -->
2521 * void _g_log_fallback_handler (const gchar *log_domain,
2522 * GLogLevelFlags log_level,
2523 * const gchar *message,
2524 * gpointer unused_data);
2533 * The C standard version the code is compiling against, it's normally
2534 * defined with the same value of `__STDC_VERSION__` for C standard
2535 * compatible compilers, while it uses the lowest standard version
2536 * in pure MSVC, given that in such compiler the definition depends on
2537 * a compilation flag.
2539 * This is granted to be undefined when compiling with a C++ compiler.
2541 * See also: %G_C_STD_CHECK_VERSION and %G_CXX_STD_VERSION
2547 * G_C_STD_CHECK_VERSION:
2548 * @version: The C version to be checked for compatibility
2550 * Macro to check if the current compiler supports a specified @version
2551 * of the C standard. Such value must be numeric and can be provided both
2552 * in the short form for the well-known versions (e.g. `90`, `99`...) or in
2553 * the complete form otherwise (e.g. `199000L`, `199901L`, `205503L`...).
2555 * When a C++ compiler is used, the macro is defined and returns always %FALSE.
2557 * This value is compared against %G_C_STD_VERSION.
2559 * |[<!-- language="C" -->
2560 * #if G_C_STD_CHECK_VERSION(17)
2564 * See also: %G_CXX_STD_CHECK_VERSION
2566 * Returns: %TRUE if @version is supported by the compiler, %FALSE otherwise
2572 * G_CXX_STD_VERSION:
2574 * The C++ standard version the code is compiling against, it's defined
2575 * with the same value of `__cplusplus` for C++ standard compatible
2576 * compilers, while it uses `_MSVC_LANG` in MSVC, given that the
2577 * standard definition depends on a compilation flag in such compiler.
2579 * This is granted to be undefined when not compiling with a C++ compiler.
2581 * See also: %G_CXX_STD_CHECK_VERSION and %G_C_STD_VERSION
2587 * G_CXX_STD_CHECK_VERSION:
2588 * @version: The C++ version to be checked for compatibility
2590 * Macro to check if the current compiler supports a specified @version
2591 * of the C++ standard. Such value must be numeric and can be provided both
2592 * in the short form for the well-known versions (e.g. `11`, `17`...) or in
2593 * the complete form otherwise (e.g. `201103L`, `201703L`, `205503L`...).
2595 * When a C compiler is used, the macro is defined and returns always %FALSE.
2597 * This value is compared against %G_CXX_STD_VERSION.
2599 * |[<!-- language="C" -->
2600 * #if G_CXX_STD_CHECK_VERSION(20)
2604 * See also: %G_C_STD_CHECK_VERSION
2606 * Returns: %TRUE if @version is supported by the compiler, %FALSE otherwise
2613 * @expr: the expression
2615 * Hints the compiler that the expression is likely to evaluate to
2616 * a true value. The compiler may use this information for optimizations.
2618 * |[<!-- language="C" -->
2619 * if (G_LIKELY (random () != 1))
2620 * g_print ("not one");
2623 * Returns: the value of @expr
2630 * @expr: the expression
2632 * Hints the compiler that the expression is unlikely to evaluate to
2633 * a true value. The compiler may use this information for optimizations.
2635 * |[<!-- language="C" -->
2636 * if (G_UNLIKELY (random () == 1))
2637 * g_print ("a random one");
2640 * Returns: the value of @expr
2648 * Expands to a string identifying the current code position.
2654 * Expands to a string identifying the current function.
2660 * G_HAVE_GNUC_VISIBILITY:
2662 * Defined to 1 if gcc-style visibility handling is supported.
2665 /* g_auto(), g_autoptr() and helpers {{{1 */
2669 * @TypeName: a supported variable type
2671 * Helper to declare a variable with automatic cleanup.
2673 * The variable is cleaned up in a way appropriate to its type when the
2674 * variable goes out of scope. The type must support this.
2675 * The way to clean up the type must have been defined using one of the macros
2676 * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC() or G_DEFINE_AUTO_CLEANUP_FREE_FUNC().
2678 * This feature is only supported on GCC and clang. This macro is not
2679 * defined on other compilers and should not be used in programs that
2680 * are intended to be portable to those compilers.
2682 * This is meant to be used with stack-allocated structures and
2683 * non-pointer types. For the (more commonly used) pointer version, see
2686 * This macro can be used to avoid having to do explicit cleanups of
2687 * local variables when exiting functions. It often vastly simplifies
2688 * handling of error conditions, removing the need for various tricks
2689 * such as `goto out` or repeating of cleanup code. It is also helpful
2690 * for non-error cases.
2692 * Consider the following example:
2698 * g_auto(GQueue) queue = G_QUEUE_INIT;
2699 * g_auto(GVariantBuilder) builder;
2700 * g_auto(GStrv) strv;
2702 * g_variant_builder_init (&builder, G_VARIANT_TYPE_VARDICT);
2703 * strv = g_strsplit("a:b:c", ":", -1);
2707 * if (error_condition)
2712 * return g_variant_builder_end (&builder);
2716 * You must initialize the variable in some way — either by use of an
2717 * initialiser or by ensuring that an `_init` function will be called on
2718 * it unconditionally before it goes out of scope.
2725 * @TypeName: a supported variable type
2727 * Helper to declare a pointer variable with automatic cleanup.
2729 * The variable is cleaned up in a way appropriate to its type when the
2730 * variable goes out of scope. The type must support this.
2731 * The way to clean up the type must have been defined using the macro
2732 * G_DEFINE_AUTOPTR_CLEANUP_FUNC().
2734 * This feature is only supported on GCC and clang. This macro is not
2735 * defined on other compilers and should not be used in programs that
2736 * are intended to be portable to those compilers.
2738 * This is meant to be used to declare pointers to types with cleanup
2739 * functions. The type of the variable is a pointer to @TypeName. You
2740 * must not add your own `*`.
2742 * This macro can be used to avoid having to do explicit cleanups of
2743 * local variables when exiting functions. It often vastly simplifies
2744 * handling of error conditions, removing the need for various tricks
2745 * such as `goto out` or repeating of cleanup code. It is also helpful
2746 * for non-error cases.
2748 * Consider the following example:
2752 * check_exists(GVariant *dict)
2754 * g_autoptr(GVariant) dirname, basename = NULL;
2755 * g_autofree gchar *path = NULL;
2757 * dirname = g_variant_lookup_value (dict, "dirname", G_VARIANT_TYPE_STRING);
2759 * if (dirname == NULL)
2762 * basename = g_variant_lookup_value (dict, "basename", G_VARIANT_TYPE_STRING);
2764 * if (basename == NULL)
2767 * path = g_build_filename (g_variant_get_string (dirname, NULL),
2768 * g_variant_get_string (basename, NULL),
2771 * return g_access (path, R_OK) == 0;
2775 * You must initialise the variable in some way — either by use of an
2776 * initialiser or by ensuring that it is assigned to unconditionally
2777 * before it goes out of scope.
2779 * See also g_auto(), g_autofree() and g_steal_pointer().
2787 * Macro to add an attribute to pointer variable to ensure automatic
2788 * cleanup using g_free().
2790 * This macro differs from g_autoptr() in that it is an attribute supplied
2791 * before the type name, rather than wrapping the type definition. Instead
2792 * of using a type-specific lookup, this macro always calls g_free() directly.
2794 * This means it's useful for any type that is returned from
2797 * Otherwise, this macro has similar constraints as g_autoptr(): only
2798 * supported on GCC and clang, the variable must be initialized, etc.
2802 * operate_on_malloc_buf (void)
2804 * g_autofree guint8* membuf = NULL;
2806 * membuf = g_malloc (8192);
2808 * // Some computation on membuf
2810 * // membuf will be automatically freed here
2820 * @TypeName: a supported variable type
2822 * Helper to declare a list variable with automatic deep cleanup.
2824 * The list is deeply freed, in a way appropriate to the specified type, when the
2825 * variable goes out of scope. The type must support this.
2827 * This feature is only supported on GCC and clang. This macro is not
2828 * defined on other compilers and should not be used in programs that
2829 * are intended to be portable to those compilers.
2831 * This is meant to be used to declare lists of a type with a cleanup
2832 * function. The type of the variable is a `GList *`. You
2833 * must not add your own `*`.
2835 * This macro can be used to avoid having to do explicit cleanups of
2836 * local variables when exiting functions. It often vastly simplifies
2837 * handling of error conditions, removing the need for various tricks
2838 * such as `goto out` or repeating of cleanup code. It is also helpful
2839 * for non-error cases.
2841 * See also g_autoslist(), g_autoptr() and g_steal_pointer().
2848 * @TypeName: a supported variable type
2850 * Helper to declare a singly linked list variable with automatic deep cleanup.
2852 * The list is deeply freed, in a way appropriate to the specified type, when the
2853 * variable goes out of scope. The type must support this.
2855 * This feature is only supported on GCC and clang. This macro is not
2856 * defined on other compilers and should not be used in programs that
2857 * are intended to be portable to those compilers.
2859 * This is meant to be used to declare lists of a type with a cleanup
2860 * function. The type of the variable is a `GSList *`. You
2861 * must not add your own `*`.
2863 * This macro can be used to avoid having to do explicit cleanups of
2864 * local variables when exiting functions. It often vastly simplifies
2865 * handling of error conditions, removing the need for various tricks
2866 * such as `goto out` or repeating of cleanup code. It is also helpful
2867 * for non-error cases.
2869 * See also g_autolist(), g_autoptr() and g_steal_pointer().
2876 * @TypeName: a supported variable type
2878 * Helper to declare a double-ended queue variable with automatic deep cleanup.
2880 * The queue is deeply freed, in a way appropriate to the specified type, when the
2881 * variable goes out of scope. The type must support this.
2883 * This feature is only supported on GCC and clang. This macro is not
2884 * defined on other compilers and should not be used in programs that
2885 * are intended to be portable to those compilers.
2887 * This is meant to be used to declare queues of a type with a cleanup
2888 * function. The type of the variable is a `GQueue *`. You
2889 * must not add your own `*`.
2891 * This macro can be used to avoid having to do explicit cleanups of
2892 * local variables when exiting functions. It often vastly simplifies
2893 * handling of error conditions, removing the need for various tricks
2894 * such as `goto out` or repeating of cleanup code. It is also helpful
2895 * for non-error cases.
2897 * See also g_autolist(), g_autoptr() and g_steal_pointer().
2904 * G_DEFINE_AUTOPTR_CLEANUP_FUNC:
2905 * @TypeName: a type name to define a g_autoptr() cleanup function for
2906 * @func: the cleanup function
2908 * Defines the appropriate cleanup function for a pointer type.
2910 * The function will not be called if the variable to be cleaned up
2913 * This will typically be the `_free()` or `_unref()` function for the given
2916 * With this definition, it will be possible to use g_autoptr() with
2920 * G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref)
2923 * This macro should be used unconditionally; it is a no-op on compilers
2924 * where cleanup is not supported.
2930 * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC:
2931 * @TypeName: a type name to define a g_auto() cleanup function for
2932 * @func: the clear function
2934 * Defines the appropriate cleanup function for a type.
2936 * This will typically be the `_clear()` function for the given type.
2938 * With this definition, it will be possible to use g_auto() with
2942 * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear)
2945 * This macro should be used unconditionally; it is a no-op on compilers
2946 * where cleanup is not supported.
2952 * G_DEFINE_AUTO_CLEANUP_FREE_FUNC:
2953 * @TypeName: a type name to define a g_auto() cleanup function for
2954 * @func: the free function
2955 * @none: the "none" value for the type
2957 * Defines the appropriate cleanup function for a type.
2959 * With this definition, it will be possible to use g_auto() with
2962 * This function will be rarely used. It is used with pointer-based
2963 * typedefs and non-pointer types where the value of the variable
2964 * represents a resource that must be freed. Two examples are #GStrv
2965 * and file descriptors.
2967 * @none specifies the "none" value for the type in question. It is
2968 * probably something like %NULL or `-1`. If the variable is found to
2969 * contain this value then the free function will not be called.
2972 * G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL)
2975 * This macro should be used unconditionally; it is a no-op on compilers
2976 * where cleanup is not supported.
2981 /* Warnings and Assertions {{{1 */
2985 * @title: Warnings and Assertions
2986 * @short_description: warnings and assertions to use in runtime code
2988 * GLib defines several warning functions and assertions which can be used to
2989 * warn of programmer errors when calling functions, and print error messages
2990 * from command line programs.
2992 * The g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
2993 * g_return_val_if_reached() macros are intended as pre-condition assertions, to
2994 * be used at the top of a public function to check that the function’s
2995 * arguments are acceptable. Any failure of such a pre-condition assertion is
2996 * considered a programming error on the part of the caller of the public API,
2997 * and the program is considered to be in an undefined state afterwards. They
2998 * are similar to the libc assert() function, but provide more context on
3002 * |[<!-- language="C" -->
3004 * g_dtls_connection_shutdown (GDtlsConnection *conn,
3005 * gboolean shutdown_read,
3006 * gboolean shutdown_write,
3007 * GCancellable *cancellable,
3010 * // local variable declarations
3012 * g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
3013 * g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
3014 * g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
3018 * return return_val;
3022 * g_print() and g_printerr() are intended to be used for
3023 * output from command line applications, since they output to standard output
3024 * and standard error by default — whereas functions like g_message() and
3025 * g_log() may be redirected to special purpose message windows, files, or the
3028 * If the console encoding is not UTF-8 (as specified by g_get_console_charset())
3029 * then these functions convert the message first. Any Unicode
3030 * characters not defined by that charset are replaced by `'?'`. On Linux,
3031 * setlocale() must be called early in main() to load the encoding. This behaviour
3032 * can be changed by providing custom handlers to g_set_print_handler(),
3033 * g_set_printerr_handler() and g_log_set_handler().
3036 /* Windows Compatibility Functions {{{1 */
3040 * @title: Windows Compatibility Functions
3041 * @short_description: UNIX emulation on Windows
3043 * These functions provide some level of UNIX emulation on the
3044 * Windows platform. If your application really needs the POSIX
3045 * APIs, we suggest you try the Cygwin project.
3051 * Provided for UNIX emulation on Windows; equivalent to UNIX
3052 * macro %MAXPATHLEN, which is the maximum length of a filename
3053 * (including full path).
3057 * G_WIN32_DLLMAIN_FOR_DLL_NAME:
3058 * @static: empty or "static"
3059 * @dll_name: the name of the (pointer to the) char array where
3060 * the DLL name will be stored. If this is used, you must also
3061 * include `windows.h`. If you need a more complex DLL entry
3062 * point function, you cannot use this
3064 * On Windows, this macro defines a DllMain() function that stores
3065 * the actual DLL name that the code being compiled will be included in.
3067 * On non-Windows platforms, expands to nothing.
3071 * G_WIN32_HAVE_WIDECHAR_API:
3073 * On Windows, this macro defines an expression which evaluates to
3074 * %TRUE if the code is running on a version of Windows where the wide
3075 * character versions of the Win32 API functions, and the wide character
3076 * versions of the C library functions work. (They are always present in
3077 * the DLLs, but don't work on Windows 9x and Me.)
3079 * On non-Windows platforms, it is not defined.
3086 * G_WIN32_IS_NT_BASED:
3088 * On Windows, this macro defines an expression which evaluates to
3089 * %TRUE if the code is running on an NT-based Windows operating system.
3091 * On non-Windows platforms, it is not defined.
3097 /* vim: set foldmethod=marker: */