glib/docs.c

   1 /*
   2  * Copyright © 2011 Red Hat, Inc
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the licence, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, 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  */
  21
  22
  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  */
  27
  28 /* Basic types {{{1 */
  29
  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  */
  54
  55 /**
  56  * gboolean:
  57  *
  58  * A standard boolean type.
  59  * Variables of this type should only contain the value
  60  * %TRUE or %FALSE.
  61  */
  62
  63 /**
  64  * gpointer:
  65  *
  66  * An untyped pointer.
  67  * #gpointer looks better and is easier to use
  68  * than <type>void*</type>.
  69  */
  70
  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  */
  80
  81 /**
  82  * gchar:
  83  *
  84  * Corresponds to the standard C <type>char</type> type.
  85  */
  86
  87 /**
  88  * guchar:
  89  *
  90  * Corresponds to the standard C <type>unsigned char</type> type.
  91  */
  92
  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  */
  99
 100 /**
 101  * G_MININT:
 102  *
 103  * The minimum value which can be held in a #gint.
 104  */
 105
 106 /**
 107  * G_MAXINT:
 108  *
 109  * The maximum value which can be held in a #gint.
 110  */
 111
 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  */
 118
 119 /**
 120  * G_MAXUINT:
 121  *
 122  * The maximum value which can be held in a #guint.
 123  */
 124
 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  */
 131
 132 /**
 133  * G_MINSHORT:
 134  *
 135  * The minimum value which can be held in a #gshort.
 136  */
 137
 138 /**
 139  * G_MAXSHORT:
 140  *
 141  * The maximum value which can be held in a #gshort.
 142  */
 143
 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  */
 150
 151 /**
 152  * G_MAXUSHORT:
 153  *
 154  * The maximum value which can be held in a #gushort.
 155  */
 156
 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  */
 163
 164 /**
 165  * G_MINLONG:
 166  *
 167  * The minimum value which can be held in a #glong.
 168  */
 169
 170 /**
 171  * G_MAXLONG:
 172  *
 173  * The maximum value which can be held in a #glong.
 174  */
 175
 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  */
 182
 183 /**
 184  * G_MAXULONG:
 185  *
 186  * The maximum value which can be held in a #gulong.
 187  */
 188
 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  */
 196
 197 /**
 198  * G_MININT8:
 199  *
 200  * The minimum value which can be held in a #gint8.
 201  *
 202  * Since: 2.4
 203  */
 204
 205 /**
 206  * G_MAXINT8:
 207  *
 208  * The maximum value which can be held in a #gint8.
 209  *
 210  * Since: 2.4
 211  */
 212
 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  */
 219
 220 /**
 221  * G_MAXUINT8:
 222  *
 223  * The maximum value which can be held in a #guint8.
 224  *
 225  * Since: 2.4
 226  */
 227
 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  */
 238
 239 /**
 240  * G_MININT16:
 241  *
 242  * The minimum value which can be held in a #gint16.
 243  *
 244  * Since: 2.4
 245  */
 246
 247 /**
 248  * G_MAXINT16:
 249  *
 250  * The maximum value which can be held in a #gint16.
 251  *
 252  * Since: 2.4
 253  */
 254
 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  */
 272
 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, &amp;in)
 285  * out = in * 1000;
 286  * g_print ("%" G_GINT32_FORMAT, out);
 287  * ]|
 288  */
 289
 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  */
 299
 300 /**
 301  * G_MAXUINT16:
 302  *
 303  * The maximum value which can be held in a #guint16.
 304  *
 305  * Since: 2.4
 306  */
 307
 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  */
 314
 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  */
 325
 326 /**
 327  * G_MININT32:
 328  *
 329  * The minimum value which can be held in a #gint32.
 330  *
 331  * Since: 2.4
 332  */
 333
 334 /**
 335  * G_MAXINT32:
 336  *
 337  * The maximum value which can be held in a #gint32.
 338  *
 339  * Since: 2.4
 340  */
 341
 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  */
 351
 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  */
 358
 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  */
 368
 369 /**
 370  * G_MAXUINT32:
 371  *
 372  * The maximum value which can be held in a #guint32.
 373  *
 374  * Since: 2.4
 375  */
 376
 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  */
 383
 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  */
 395
 396 /**
 397  * G_MININT64:
 398  *
 399  * The minimum value which can be held in a #gint64.
 400  */
 401
 402 /**
 403  * G_MAXINT64:
 404  *
 405  * The maximum value which can be held in a #gint64.
 406  */
 407
 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  */
 423
 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  */
 439
 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  */
 450
 451 /**
 452  * G_MAXUINT64:
 453  *
 454  * The maximum value which can be held in a #guint64.
 455  */
 456
 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  */
 472
 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  */
 480
 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  */
 490
 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  */
 497
 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  */
 506
 507 /**
 508  * G_MAXFLOAT:
 509  *
 510  * The maximum value which can be held in a #gfloat.
 511  */
 512
 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  */
 519
 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  */
 528
 529 /**
 530  * G_MAXDOUBLE:
 531  *
 532  * The maximum value which can be held in a #gdouble.
 533  */
 534
 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  */
 548
 549 /**
 550  * G_MAXSIZE:
 551  *
 552  * The maximum value which can be held in a #gsize.
 553  *
 554  * Since: 2.4
 555  */
 556
 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  */
 566
 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  */
 575
 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  */
 587
 588 /**
 589  * G_MINSSIZE:
 590  *
 591  * The minimum value which can be held in a #gssize.
 592  *
 593  * Since: 2.14
 594  */
 595
 596 /**
 597  * G_MAXSSIZE:
 598  *
 599  * The maximum value which can be held in a #gssize.
 600  *
 601  * Since: 2.14
 602  */
 603
 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  */
 612
 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  */
 626
 627 /**
 628  * G_MINOFFSET:
 629  *
 630  * The minimum value which can be held in a #goffset.
 631  */
 632
 633 /**
 634  * G_MAXOFFSET:
 635  *
 636  * The maximum value which can be held in a #goffset.
 637  */
 638
 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  */
 648
 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  */
 657
 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  */
 669
 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  */
 681
 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  */
 691
 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  */
 700
 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  */
 712
 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  */
 721
 722 /* Type conversion {{{1 */
 723
 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  */
 766
 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  */
 778
 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  */
 791
 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  */
 798
 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  */
 806
 807 /**
 808  * GSIZE_TO_POINTER:
 809  * @s: #gsize to stuff into the pointer
 810  *
 811  * Stuffs a #gsize into a pointer type.
 812  */
 813
 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  */
 821
 822 /* Byte order {{{1 */
 823
 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  */
 858
 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  */
 866
 867 /**
 868  * G_LITTLE_ENDIAN:
 869  *
 870  * Specifies one of the possible types of byte order.
 871  * See #G_BYTE_ORDER.
 872  */
 873
 874 /**
 875  * G_BIG_ENDIAN:
 876  *
 877  * Specifies one of the possible types of byte order.
 878  * See #G_BYTE_ORDER.
 879  */
 880
 881 /**
 882  * G_PDP_ENDIAN:
 883  *
 884  * Specifies one of the possible types of byte order
 885  * (currently unused). See #G_BYTE_ORDER.
 886  */
 887
 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  */
 896
 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  */
 905
 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  */
 914
 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  */
 923
 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  */
 932
 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  */
 941
 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  */
 950
 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  */
 959
 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  */
 968
 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  */
 977
 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  */
 986
 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  */
 995
 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  */
1004
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  */
1013
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  */
1022
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  */
1031
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  */
1040
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  */
1049
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  */
1058
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  */
1067
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  */
1076
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  */
1085
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  */
1094
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  */
1103
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  */
1112
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  */
1121
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  */
1130
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  */
1139
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  */
1148
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  */
1157
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  */
1166
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  */
1175
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  */
1184
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  */
1193
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  */
1202
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  */
1211
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  */
1220
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  */
1229
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  */
1238
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  */
1247
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  */
1256
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  */
1265
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  */
1274
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  */
1283
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  */
1292
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  */
1301
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  */
1310
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  */
1319
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  */
1328
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  */
1337
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  */
1346
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  */
1355
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  */
1365
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  */
1375
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  */
1385
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  */
1395
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  */
1405
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  */
1415
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  */
1425
1426 /* Numerical Definitions {{{1 */
1427
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  */
1444
1445 /**
1446  * G_IEEE754_FLOAT_BIAS:
1447  *
1448  * The bias by which exponents in single-precision floats are offset.
1449  */
1450
1451 /**
1452  * G_IEEE754_DOUBLE_BIAS:
1453  *
1454  * The bias by which exponents in double-precision floats are offset.
1455  */
1456
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  */
1466
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  */
1476
1477 /**
1478  * G_E:
1479  *
1480  * The base of natural logarithms.
1481  */
1482
1483 /**
1484  * G_LN2:
1485  *
1486  * The natural logarithm of 2.
1487  */
1488
1489 /**
1490  * G_LN10:
1491  *
1492  * The natural logarithm of 10.
1493  */
1494
1495 /**
1496  * G_PI:
1497  *
1498  * The value of pi (ratio of circle's circumference to its diameter).
1499  */
1500
1501 /**
1502  * G_PI_2:
1503  *
1504  * Pi divided by 2.
1505  */
1506
1507 /**
1508  * G_PI_4:
1509  *
1510  * Pi divided by 4.
1511  */
1512
1513 /**
1514  * G_SQRT2:
1515  *
1516  * The square root of two.
1517  */
1518
1519 /**
1520  * G_LOG_2_BASE_10:
1521  *
1522  * Multiplying the base 2 exponent by this number yields the base 10 exponent.
1523  */
1524
1525 /* Macros {{{1 */
1526
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  */
1534
1535 /**
1536  * G_OS_WIN32:
1537  *
1538  * This macro is defined only on Windows. So you can bracket
1539  * Windows-specific code in "&num;ifdef G_OS_WIN32".
1540  */
1541
1542 /**
1543  * G_OS_BEOS:
1544  *
1545  * This macro is defined only on BeOS. So you can bracket
1546  * BeOS-specific code in "&num;ifdef G_OS_BEOS".
1547  */
1548
1549 /**
1550  * G_OS_UNIX:
1551  *
1552  * This macro is defined only on UNIX. So you can bracket
1553  * UNIX-specific code in "&num;ifdef G_OS_UNIX".
1554  */
1555
1556 /**
1557  * G_DIR_SEPARATOR:
1558  *
1559  * The directory separator character.
1560  * This is '/' on UNIX machines and '\' under Windows.
1561  */
1562
1563 /**
1564  * G_DIR_SEPARATOR_S:
1565  *
1566  * The directory separator as a string.
1567  * This is "/" on UNIX machines and "\" under Windows.
1568  */
1569
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  */
1580
1581 /**
1582  * G_SEARCHPATH_SEPARATOR:
1583  *
1584  * The search path separator character.
1585  * This is ':' on UNIX machines and ';' under Windows.
1586  */
1587
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  */
1594
1595 /**
1596  * TRUE:
1597  *
1598  * Defines the %TRUE value for the #gboolean type.
1599  */
1600
1601 /**
1602  * FALSE:
1603  *
1604  * Defines the %FALSE value for the #gboolean type.
1605  */
1606
1607 /**
1608  * NULL:
1609  *
1610  * Defines the standard %NULL pointer.
1611  */
1612
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  */
1622
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  */
1632
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  */
1646
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  */
1663
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  */
1675
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  */
1685
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  */
1695
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  */
1713
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  */
1723
1724 /* Miscellaneous Macros {{{1 */
1725
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  */
1734
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  */
1749
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  */
1756
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  */
1763
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  */
1771
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  */
1779
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  */
1792
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  */
1811
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  */
1837
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  */
1859
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  */
1881
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  */
1890
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  */
1907
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  */
1918
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  */
1931
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  */
1944
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  */
1958
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  */
1971
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  */
1988
1989 /**
1990  * G_GNUC_BEGIN_IGNORE_DEPRECATIONS:
1991  *
1992  * Tells <command>gcc</command> (if it is a new enough version) to
1993  * temporarily stop emitting warnings when functions marked with
1994  * %G_GNUC_DEPRECATED or %G_GNUC_DEPRECATED_FOR are called. This is
1995  * useful for when you have one deprecated function calling another
1996  * one, or when you still have regression tests for deprecated
1997  * functions.
1998  *
1999  * Use %G_GNUC_END_IGNORE_DEPRECATIONS to begin warning again. (If you
2000  * are not compiling with <literal>-Wdeprecated-declarations</literal>
2001  * then neither macro has any effect.)
2002  *
2003  * This macro can be used either inside or outside of a function body,
2004  * but must appear on a line by itself.
2005  *
2006  * Since: 2.32
2007  */
2008
2009 /**
2010  * G_GNUC_END_IGNORE_DEPRECATIONS:
2011  *
2012  * Undoes the effect of %G_GNUC_BEGIN_IGNORE_DEPRECATIONS, telling
2013  * <command>gcc</command> to begin outputting warnings again
2014  * (assuming those warnings had been enabled to begin with).
2015  *
2016  * This macro can be used either inside or outside of a function body,
2017  * but must appear on a line by itself.
2018  *
2019  * Since: 2.32
2020  */
2021
2022 /**
2023  * G_DEPRECATED:
2024  *
2025  * This macro is similar to %G_GNUC_DEPRECATED, and can be used to mark
2026  * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED, it is
2027  * meant to be portable across different compilers and must be placed
2028  * before the function declaration.
2029  *
2030  * Since: 2.32
2031  */
2032
2033 /**
2034  * G_DEPRECATED_FOR:
2035  * @f: the name of the function that this function was deprecated for
2036  *
2037  * This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark
2038  * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it is
2039  * meant to be portable across different compilers and must be placed
2040  * before the function declaration.
2041  *
2042  * Since: 2.32
2043  */
2044
2045 /**
2046  * G_UNAVAILABLE:
2047  * @maj: the major version that introduced the symbol
2048  * @min: the minor version that introduced the symbol
2049  *
2050  * This macro can be used to mark a function declaration as unavailable.
2051  * It must be placed before the function declaration. Use of a function
2052  * that has been annotated with this macros will produce a compiler warning.
2053  *
2054  * Since: 2.32
2055  */
2056
2057 /**
2058  * GLIB_DISABLE_DEPRECATION_WARNINGS:
2059  *
2060  * A macro that should be defined before including the glib.h header.
2061  * If it is defined, no compiler warnings will be produced for uses
2062  * of deprecated GLib APIs.
2063  */
2064
2065 /**
2066  * G_GNUC_NORETURN:
2067  *
2068  * Expands to the GNU C <literal>noreturn</literal> function attribute
2069  * if the compiler is <command>gcc</command>. It is used for declaring
2070  * functions which never return. It enables optimization of the function,
2071  * and avoids possible compiler warnings. See the GNU C documentation for
2072  * details.
2073  */
2074
2075 /**
2076  * G_GNUC_UNUSED:
2077  *
2078  * Expands to the GNU C <literal>unused</literal> function attribute if
2079  * the compiler is <command>gcc</command>. It is used for declaring
2080  * functions which may never be used. It avoids possible compiler warnings.
2081  * See the GNU C documentation for details.
2082  */
2083
2084 /**
2085  * G_GNUC_PRINTF:
2086  * @format_idx: the index of the argument corresponding to the
2087  *     format string (The arguments are numbered from 1)
2088  * @arg_idx: the index of the first of the format arguments
2089  *
2090  * Expands to the GNU C <literal>format</literal> function attribute
2091  * if the compiler is <command>gcc</command>. This is used for declaring
2092  * functions which take a variable number of arguments, with the same
2093  * syntax as printf(). It allows the compiler to type-check the arguments
2094  * passed to the function. See the GNU C documentation for details.
2095  *
2096  * |[
2097  * gint g_snprintf (gchar  *string,
2098  *                  gulong       n,
2099  *                  gchar const *format,
2100  *                  ...) G_GNUC_PRINTF (3, 4);
2101  * ]|
2102  */
2103
2104 /**
2105  * G_GNUC_SCANF:
2106  * @format_idx: the index of the argument corresponding to
2107  *     the format string (The arguments are numbered from 1)
2108  * @arg_idx: the index of the first of the format arguments
2109  *
2110  * Expands to the GNU C <literal>format</literal> function attribute
2111  * if the compiler is <command>gcc</command>. This is used for declaring
2112  * functions which take a variable number of arguments, with the same
2113  * syntax as scanf(). It allows the compiler to type-check the arguments
2114  * passed to the function. See the GNU C documentation for details.
2115  */
2116
2117 /**
2118  * G_GNUC_FORMAT:
2119  * @arg_idx: the index of the argument
2120  *
2121  * Expands to the GNU C <literal>format_arg</literal> function attribute
2122  * if the compiler is <command>gcc</command>. This function attribute
2123  * specifies that a function takes a format string for a printf(),
2124  * scanf(), strftime() or strfmon() style function and modifies it,
2125  * so that the result can be passed to a printf(), scanf(), strftime()
2126  * or strfmon() style function (with the remaining arguments to the
2127  * format function the same as they would have been for the unmodified
2128  * string). See the GNU C documentation for details.
2129  *
2130  * |[
2131  * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
2132  * ]|
2133  */
2134
2135 /**
2136  * G_GNUC_NULL_TERMINATED:
2137  *
2138  * Expands to the GNU C <literal>sentinel</literal> function attribute
2139  * if the compiler is <command>gcc</command>, or "" if it isn't. This
2140  * function attribute only applies to variadic functions and instructs
2141  * the compiler to check that the argument list is terminated with an
2142  * explicit %NULL. See the GNU C documentation for details.
2143  *
2144  * Since: 2.8
2145  */
2146
2147 /**
2148  * G_GNUC_WARN_UNUSED_RESULT:
2149  *
2150  * Expands to the GNU C <literal>warn_unused_result</literal> function
2151  * attribute if the compiler is <command>gcc</command>, or "" if it isn't.
2152  * This function attribute makes the compiler emit a warning if the result
2153  * of a function call is ignored. See the GNU C documentation for details.
2154  *
2155  * Since: 2.10
2156  */
2157
2158 /**
2159  * G_GNUC_FUNCTION:
2160  *
2161  * Expands to "" on all modern compilers, and to
2162  * <literal>__FUNCTION__</literal> on <command>gcc</command> version 2.x.
2163  * Don't use it.
2164  *
2165  * Deprecated: 2.16: Use #G_STRFUNC instead
2166  */
2167
2168 /**
2169  * G_GNUC_PRETTY_FUNCTION:
2170  *
2171  * Expands to "" on all modern compilers, and to
2172  * <literal>__PRETTY_FUNCTION__</literal> on <command>gcc</command>
2173  * version 2.x. Don't use it.
2174  *
2175  * Deprecated: 2.16: Use #G_STRFUNC instead
2176  */
2177
2178 /**
2179  * G_GNUC_NO_INSTRUMENT:
2180  *
2181  * Expands to the GNU C <literal>no_instrument_function</literal> function
2182  * attribute if the compiler is <command>gcc</command>. Functions with this
2183  * attribute will not be instrumented for profiling, when the compiler is
2184  * called with the <option>-finstrument-functions</option> option.
2185  * See the GNU C documentation for details.
2186  */
2187
2188 /**
2189  * G_GNUC_INTERNAL:
2190  *
2191  * This attribute can be used for marking library functions as being used
2192  * internally to the library only, which may allow the compiler to handle
2193  * function calls more efficiently. Note that static functions do not need
2194  * to be marked as internal in this way. See the GNU C documentation for
2195  * details.
2196  *
2197  * When using a compiler that supports the GNU C hidden visibility attribute,
2198  * this macro expands to <literal>__attribute__((visibility("hidden")))</literal>.
2199  * When using the Sun Studio compiler, it expands to <literal>__hidden</literal>.
2200  *
2201  * Note that for portability, the attribute should be placed before the
2202  * function declaration. While GCC allows the macro after the declaration,
2203  * Sun Studio does not.
2204  *
2205  * |[
2206  * G_GNUC_INTERNAL
2207  * void _g_log_fallback_handler (const gchar    *log_domain,
2208  *                               GLogLevelFlags  log_level,
2209  *                               const gchar    *message,
2210  *                               gpointer        unused_data);
2211  * ]|
2212  *
2213  * Since: 2.6
2214  */
2215
2216 /**
2217  * G_GNUC_MAY_ALIAS:
2218  *
2219  * Expands to the GNU C <literal>may_alias</literal> type attribute
2220  * if the compiler is <command>gcc</command>. Types with this attribute
2221  * will not be subjected to type-based alias analysis, but are assumed
2222  * to alias with any other type, just like char.
2223  * See the GNU C documentation for details.
2224  *
2225  * Since: 2.14
2226  */
2227
2228 /**
2229  * G_LIKELY:
2230  * @expr: the expression
2231  *
2232  * Hints the compiler that the expression is likely to evaluate to
2233  * a true value. The compiler may use this information for optimizations.
2234  *
2235  * |[
2236  * if (G_LIKELY (random () != 1))
2237  *   g_print ("not one");
2238  * ]|
2239  *
2240  * Returns: the value of @expr
2241  *
2242  * Since: 2.2
2243  */
2244
2245 /**
2246  * G_UNLIKELY:
2247  * @expr: the expression
2248  *
2249  * Hints the compiler that the expression is unlikely to evaluate to
2250  * a true value. The compiler may use this information for optimizations.
2251  *
2252  * |[
2253  * if (G_UNLIKELY (random () == 1))
2254  *   g_print ("a random one");
2255  * ]|
2256  *
2257  * Returns: the value of @expr
2258  *
2259  * Since: 2.2
2260  */
2261
2262 /**
2263  * G_STRLOC:
2264  *
2265  * Expands to a string identifying the current code position.
2266  */
2267
2268 /**
2269  * G_STRFUNC:
2270  *
2271  * Expands to a string identifying the current function.
2272  *
2273  * Since: 2.4
2274  */
2275
2276 /* Windows Compatibility Functions {{{1 */
2277
2278 /**
2279  * SECTION:windows
2280  * @title: Windows Compatibility Functions
2281  * @short_description: UNIX emulation on Windows
2282  *
2283  * These functions provide some level of UNIX emulation on the
2284  * Windows platform. If your application really needs the POSIX
2285  * APIs, we suggest you try the Cygwin project.
2286  */
2287
2288 /**
2289  * MAXPATHLEN:
2290  *
2291  * Provided for UNIX emulation on Windows; equivalent to UNIX
2292  * macro %MAXPATHLEN, which is the maximum length of a filename
2293  * (including full path).
2294  */
2295
2296 /**
2297  * G_WIN32_DLLMAIN_FOR_DLL_NAME:
2298  * @static: empty or "static"
2299  * @dll_name: the name of the (pointer to the) char array where
2300  *     the DLL name will be stored. If this is used, you must also
2301  *     include <filename>windows.h</filename>. If you need a more
2302  *     complex DLL entry point function, you cannot use this
2303  *
2304  * On Windows, this macro defines a DllMain() function that stores
2305  * the actual DLL name that the code being compiled will be included in.
2306  *
2307  * On non-Windows platforms, expands to nothing.
2308  */
2309
2310 /**
2311  * G_WIN32_HAVE_WIDECHAR_API:
2312  *
2313  * On Windows, this macro defines an expression which evaluates to
2314  * %TRUE if the code is running on a version of Windows where the wide
2315  * character versions of the Win32 API functions, and the wide character
2316  * versions of the C library functions work. (They are always present in
2317  * the DLLs, but don't work on Windows 9x and Me.)
2318  *
2319  * On non-Windows platforms, it is not defined.
2320  *
2321  * Since: 2.6
2322  */
2323
2324
2325 /**
2326  * G_WIN32_IS_NT_BASED:
2327  *
2328  * On Windows, this macro defines an expression which evaluates to
2329  * %TRUE if the code is running on an NT-based Windows operating system.
2330  *
2331  * On non-Windows platforms, it is not defined.
2332  *
2333  * Since: 2.6
2334  */
2335
2336 /* Epilogue {{{1 */
2337 /* vim: set foldmethod=marker: */