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