Català-Valencià – Catalan中文 – Chinese (Simplified)中文 – Chinese (Traditional)Česky – CzechDansk – DanishNederlands – DutchEnglish – EnglishSuomi – FinnishFrançais – FrenchDeutsch – Germanעברית – Hebrewहिंदी – HindiMagyar – HungarianBahasa Indonesia – IndonesianItaliano – Italian日本語 – Japanese한국어 – KoreanМакедонски – Macedonianमराठी – MarathiNorsk – NorwegianPolski – PolishPortuguês – PortuguesePortuguês – Portuguese (Brazil)Русский – RussianSlovenčina – SlovakSlovenščina – SlovenianEspañol – SpanishSvenska – SwedishTürkçe – TurkishУкраїнська – UkrainianOëzbekcha – Uzbek

nexmon – Blame information for rev 1

Rev	Author	Line No.	Line
1	office	1	/*
		2	* Copyright © 2011 Red Hat, Inc
		3	*
		4	* This library is free software; you can redistribute it and/or
		5	* modify it under the terms of the GNU Lesser General Public
		6	* License as published by the Free Software Foundation; either
		7	* version 2 of the licence, or (at your option) any later version.
		8	*
		9	* This library is distributed in the hope that it will be useful,
		10	* but WITHOUT ANY WARRANTY; without even the implied warranty of
		11	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
		12	* Lesser General Public License for more details.
		13	*
		14	* You should have received a copy of the GNU Lesser General Public
		15	* License along with this library; if not, see <http://www.gnu.org/licenses/>.
		16	*
		17	* Author: Matthias Clasen
		18	*/
		19
		20
		21	/* This file collects documentation for macros, typedefs and
		22	* the like, which have no good home in any of the 'real' source
		23	* files.
		24	*/
		25
		26	/* Basic types {{{1 */
		27
		28	/**
		29	* SECTION:types
		30	* @title: Basic Types
		31	* @short_description: standard GLib types, defined for ease-of-use
		32	* and portability
		33	*
		34	* GLib defines a number of commonly used types, which can be divided
		35	* into 4 groups:
		36	* - New types which are not part of standard C (but are defined in
		37	* various C standard library header files) - #gboolean, #gsize,
		38	* #gssize, #goffset, #gintptr, #guintptr.
		39	* - Integer types which are guaranteed to be the same size across
		40	* all platforms - #gint8, #guint8, #gint16, #guint16, #gint32,
		41	* #guint32, #gint64, #guint64.
		42	* - Types which are easier to use than their standard C counterparts -
		43	* #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
		44	* - Types which correspond exactly to standard C types, but are
		45	* included for completeness - #gchar, #gint, #gshort, #glong,
		46	* #gfloat, #gdouble.
		47	*
		48	* GLib also defines macros for the limits of some of the standard
		49	* integer and floating point types, as well as macros for suitable
		50	* printf() formats for these types.
		51	*/
		52
		53	/**
		54	* gboolean:
		55	*
		56	* A standard boolean type.
		57	* Variables of this type should only contain the value
		58	* %TRUE or %FALSE.
		59	*/
		60
		61	/**
		62	* gpointer:
		63	*
		64	* An untyped pointer.
		65	* #gpointer looks better and is easier to use than void*.
		66	*/
		67
		68	/**
		69	* gconstpointer:
		70	*
		71	* An untyped pointer to constant data.
		72	* The data pointed to should not be changed.
		73	*
		74	* This is typically used in function prototypes to indicate
		75	* that the data pointed to will not be altered by the function.
		76	*/
		77
		78	/**
		79	* gchar:
		80	*
		81	* Corresponds to the standard C char type.
		82	*/
		83
		84	/**
		85	* guchar:
		86	*
		87	* Corresponds to the standard C unsigned char type.
		88	*/
		89
		90	/**
		91	* gint:
		92	*
		93	* Corresponds to the standard C int type.
		94	* Values of this type can range from #G_MININT to #G_MAXINT.
		95	*/
		96
		97	/**
		98	* G_MININT:
		99	*
		100	* The minimum value which can be held in a #gint.
		101	*/
		102
		103	/**
		104	* G_MAXINT:
		105	*
		106	* The maximum value which can be held in a #gint.
		107	*/
		108
		109	/**
		110	* guint:
		111	*
		112	* Corresponds to the standard C unsigned int type.
		113	* Values of this type can range from 0 to #G_MAXUINT.
		114	*/
		115
		116	/**
		117	* G_MAXUINT:
		118	*
		119	* The maximum value which can be held in a #guint.
		120	*/
		121
		122	/**
		123	* gshort:
		124	*
		125	* Corresponds to the standard C short type.
		126	* Values of this type can range from #G_MINSHORT to #G_MAXSHORT.
		127	*/
		128
		129	/**
		130	* G_MINSHORT:
		131	*
		132	* The minimum value which can be held in a #gshort.
		133	*/
		134
		135	/**
		136	* G_MAXSHORT:
		137	*
		138	* The maximum value which can be held in a #gshort.
		139	*/
		140
		141	/**
		142	* gushort:
		143	*
		144	* Corresponds to the standard C unsigned short type.
		145	* Values of this type can range from 0 to #G_MAXUSHORT.
		146	*/
		147
		148	/**
		149	* G_MAXUSHORT:
		150	*
		151	* The maximum value which can be held in a #gushort.
		152	*/
		153
		154	/**
		155	* glong:
		156	*
		157	* Corresponds to the standard C long type.
		158	* Values of this type can range from #G_MINLONG to #G_MAXLONG.
		159	*/
		160
		161	/**
		162	* G_MINLONG:
		163	*
		164	* The minimum value which can be held in a #glong.
		165	*/
		166
		167	/**
		168	* G_MAXLONG:
		169	*
		170	* The maximum value which can be held in a #glong.
		171	*/
		172
		173	/**
		174	* gulong:
		175	*
		176	* Corresponds to the standard C unsigned long type.
		177	* Values of this type can range from 0 to #G_MAXULONG.
		178	*/
		179
		180	/**
		181	* G_MAXULONG:
		182	*
		183	* The maximum value which can be held in a #gulong.
		184	*/
		185
		186	/**
		187	* gint8:
		188	*
		189	* A signed integer guaranteed to be 8 bits on all platforms.
		190	* Values of this type can range from #G_MININT8 (= -128) to
		191	* #G_MAXINT8 (= 127).
		192	*/
		193
		194	/**
		195	* G_MININT8:
		196	*
		197	* The minimum value which can be held in a #gint8.
		198	*
		199	* Since: 2.4
		200	*/
		201
		202	/**
		203	* G_MAXINT8:
		204	*
		205	* The maximum value which can be held in a #gint8.
		206	*
		207	* Since: 2.4
		208	*/
		209
		210	/**
		211	* guint8:
		212	*
		213	* An unsigned integer guaranteed to be 8 bits on all platforms.
		214	* Values of this type can range from 0 to #G_MAXUINT8 (= 255).
		215	*/
		216
		217	/**
		218	* G_MAXUINT8:
		219	*
		220	* The maximum value which can be held in a #guint8.
		221	*
		222	* Since: 2.4
		223	*/
		224
		225	/**
		226	* gint16:
		227	*
		228	* A signed integer guaranteed to be 16 bits on all platforms.
		229	* Values of this type can range from #G_MININT16 (= -32,768) to
		230	* #G_MAXINT16 (= 32,767).
		231	*
		232	* To print or scan values of this type, use
		233	* %G_GINT16_MODIFIER and/or %G_GINT16_FORMAT.
		234	*/
		235
		236	/**
		237	* G_MININT16:
		238	*
		239	* The minimum value which can be held in a #gint16.
		240	*
		241	* Since: 2.4
		242	*/
		243
		244	/**
		245	* G_MAXINT16:
		246	*
		247	* The maximum value which can be held in a #gint16.
		248	*
		249	* Since: 2.4
		250	*/
		251
		252	/**
		253	* G_GINT16_MODIFIER:
		254	*
		255	* The platform dependent length modifier for conversion specifiers
		256	* for scanning and printing values of type #gint16 or #guint16. It
		257	* is a string literal, but doesn't include the percent-sign, such
		258	* that you can add precision and length modifiers between percent-sign
		259	* and conversion specifier and append a conversion specifier.
		260	*
		261	* The following example prints "0x7b";
		262	* |[<!-- language="C" -->
		263	* gint16 value = 123;
		264	* g_print ("%#" G_GINT16_MODIFIER "x", value);
		265	* ]|
		266	*
		267	* Since: 2.4
		268	*/
		269
		270	/**
		271	* G_GINT16_FORMAT:
		272	*
		273	* This is the platform dependent conversion specifier for scanning and
		274	* printing values of type #gint16. It is a string literal, but doesn't
		275	* include the percent-sign, such that you can add precision and length
		276	* modifiers between percent-sign and conversion specifier.
		277	*
		278	* |[<!-- language="C" -->
		279	* gint16 in;
		280	* gint32 out;
		281	* sscanf ("42", "%" G_GINT16_FORMAT, &in)
		282	* out = in * 1000;
		283	* g_print ("%" G_GINT32_FORMAT, out);
		284	* ]|
		285	*/
		286
		287	/**
		288	* guint16:
		289	*
		290	* An unsigned integer guaranteed to be 16 bits on all platforms.
		291	* Values of this type can range from 0 to #G_MAXUINT16 (= 65,535).
		292	*
		293	* To print or scan values of this type, use
		294	* %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT.
		295	*/
		296
		297	/**
		298	* G_MAXUINT16:
		299	*
		300	* The maximum value which can be held in a #guint16.
		301	*
		302	* Since: 2.4
		303	*/
		304
		305	/**
		306	* G_GUINT16_FORMAT:
		307	*
		308	* This is the platform dependent conversion specifier for scanning
		309	* and printing values of type #guint16. See also #G_GINT16_FORMAT
		310	*/
		311
		312	/**
		313	* gint32:
		314	*
		315	* A signed integer guaranteed to be 32 bits on all platforms.
		316	* Values of this type can range from #G_MININT32 (= -2,147,483,648)
		317	* to #G_MAXINT32 (= 2,147,483,647).
		318	*
		319	* To print or scan values of this type, use
		320	* %G_GINT32_MODIFIER and/or %G_GINT32_FORMAT.
		321	*/
		322
		323	/**
		324	* G_MININT32:
		325	*
		326	* The minimum value which can be held in a #gint32.
		327	*
		328	* Since: 2.4
		329	*/
		330
		331	/**
		332	* G_MAXINT32:
		333	*
		334	* The maximum value which can be held in a #gint32.
		335	*
		336	* Since: 2.4
		337	*/
		338
		339	/**
		340	* G_GINT32_MODIFIER:
		341	*
		342	* The platform dependent length modifier for conversion specifiers
		343	* for scanning and printing values of type #gint32 or #guint32. It
		344	* is a string literal. See also #G_GINT16_MODIFIER.
		345	*
		346	* Since: 2.4
		347	*/
		348
		349	/**
		350	* G_GINT32_FORMAT:
		351	*
		352	* This is the platform dependent conversion specifier for scanning
		353	* and printing values of type #gint32. See also #G_GINT16_FORMAT.
		354	*/
		355
		356	/**
		357	* guint32:
		358	*
		359	* An unsigned integer guaranteed to be 32 bits on all platforms.
		360	* Values of this type can range from 0 to #G_MAXUINT32 (= 4,294,967,295).
		361	*
		362	* To print or scan values of this type, use
		363	* %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
		364	*/
		365
		366	/**
		367	* G_MAXUINT32:
		368	*
		369	* The maximum value which can be held in a #guint32.
		370	*
		371	* Since: 2.4
		372	*/
		373
		374	/**
		375	* G_GUINT32_FORMAT:
		376	*
		377	* This is the platform dependent conversion specifier for scanning
		378	* and printing values of type #guint32. See also #G_GINT16_FORMAT.
		379	*/
		380
		381	/**
		382	* gint64:
		383	*
		384	* A signed integer guaranteed to be 64 bits on all platforms.
		385	* Values of this type can range from #G_MININT64
		386	* (= -9,223,372,036,854,775,808) to #G_MAXINT64
		387	* (= 9,223,372,036,854,775,807).
		388	*
		389	* To print or scan values of this type, use
		390	* %G_GINT64_MODIFIER and/or %G_GINT64_FORMAT.
		391	*/
		392
		393	/**
		394	* G_MININT64:
		395	*
		396	* The minimum value which can be held in a #gint64.
		397	*/
		398
		399	/**
		400	* G_MAXINT64:
		401	*
		402	* The maximum value which can be held in a #gint64.
		403	*/
		404
		405	/**
		406	* G_GINT64_MODIFIER:
		407	*
		408	* The platform dependent length modifier for conversion specifiers
		409	* for scanning and printing values of type #gint64 or #guint64.
		410	* It is a string literal.
		411	*
		412	* Some platforms do not support printing 64-bit integers, even
		413	* though the types are supported. On such platforms %G_GINT64_MODIFIER
		414	* is not defined.
		415	*
		416	* Since: 2.4
		417	*/
		418
		419	/**
		420	* G_GINT64_FORMAT:
		421	*
		422	* This is the platform dependent conversion specifier for scanning
		423	* and printing values of type #gint64. See also #G_GINT16_FORMAT.
		424	*
		425	* Some platforms do not support scanning and printing 64-bit integers,
		426	* even though the types are supported. On such platforms %G_GINT64_FORMAT
		427	* is not defined. Note that scanf() may not support 64-bit integers, even
		428	* if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
		429	* is not recommended for parsing anyway; consider using g_ascii_strtoull()
		430	* instead.
		431	*/
		432
		433	/**
		434	* guint64:
		435	*
		436	* An unsigned integer guaranteed to be 64-bits on all platforms.
		437	* Values of this type can range from 0 to #G_MAXUINT64
		438	* (= 18,446,744,073,709,551,615).
		439	*
		440	* To print or scan values of this type, use
		441	* %G_GINT64_MODIFIER and/or %G_GUINT64_FORMAT.
		442	*/
		443
		444	/**
		445	* G_MAXUINT64:
		446	*
		447	* The maximum value which can be held in a #guint64.
		448	*/
		449
		450	/**
		451	* G_GUINT64_FORMAT:
		452	*
		453	* This is the platform dependent conversion specifier for scanning
		454	* and printing values of type #guint64. See also #G_GINT16_FORMAT.
		455	*
		456	* Some platforms do not support scanning and printing 64-bit integers,
		457	* even though the types are supported. On such platforms %G_GUINT64_FORMAT
		458	* is not defined. Note that scanf() may not support 64-bit integers, even
		459	* if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
		460	* is not recommended for parsing anyway; consider using g_ascii_strtoull()
		461	* instead.
		462	*/
		463
		464	/**
		465	* G_GINT64_CONSTANT:
		466	* @val: a literal integer value, e.g. 0x1d636b02300a7aa7
		467	*
		468	* This macro is used to insert 64-bit integer literals
		469	* into the source code.
		470	*/
		471
		472	/**
		473	* G_GUINT64_CONSTANT:
		474	* @val: a literal integer value, e.g. 0x1d636b02300a7aa7U
		475	*
		476	* This macro is used to insert 64-bit unsigned integer
		477	* literals into the source code.
		478	*
		479	* Since: 2.10
		480	*/
		481
		482	/**
		483	* gfloat:
		484	*
		485	* Corresponds to the standard C float type.
		486	* Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT.
		487	*/
		488
		489	/**
		490	* G_MINFLOAT:
		491	*
		492	* The minimum positive value which can be held in a #gfloat.
		493	*
		494	* If you are interested in the smallest value which can be held
		495	* in a #gfloat, use -%G_MAXFLOAT.
		496	*/
		497
		498	/**
		499	* G_MAXFLOAT:
		500	*
		501	* The maximum value which can be held in a #gfloat.
		502	*/
		503
		504	/**
		505	* gdouble:
		506	*
		507	* Corresponds to the standard C double type.
		508	* Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE.
		509	*/
		510
		511	/**
		512	* G_MINDOUBLE:
		513	*
		514	* The minimum positive value which can be held in a #gdouble.
		515	*
		516	* If you are interested in the smallest value which can be held
		517	* in a #gdouble, use -%G_MAXDOUBLE.
		518	*/
		519
		520	/**
		521	* G_MAXDOUBLE:
		522	*
		523	* The maximum value which can be held in a #gdouble.
		524	*/
		525
		526	/**
		527	* gsize:
		528	*
		529	* An unsigned integer type of the result of the sizeof operator,
		530	* corresponding to the size_t type defined in C99.
		531	* This type is wide enough to hold the numeric value of a pointer,
		532	* so it is usually 32 bit wide on a 32-bit platform and 64 bit wide
		533	* on a 64-bit platform. Values of this type can range from 0 to
		534	* #G_MAXSIZE.
		535	*
		536	* To print or scan values of this type, use
		537	* %G_GSIZE_MODIFIER and/or %G_GSIZE_FORMAT.
		538	*/
		539
		540	/**
		541	* G_MAXSIZE:
		542	*
		543	* The maximum value which can be held in a #gsize.
		544	*
		545	* Since: 2.4
		546	*/
		547
		548	/**
		549	* G_GSIZE_MODIFIER:
		550	*
		551	* The platform dependent length modifier for conversion specifiers
		552	* for scanning and printing values of type #gsize. It
		553	* is a string literal.
		554	*
		555	* Since: 2.6
		556	*/
		557
		558	/**
		559	* G_GSIZE_FORMAT:
		560	*
		561	* This is the platform dependent conversion specifier for scanning
		562	* and printing values of type #gsize. See also #G_GINT16_FORMAT.
		563	*
		564	* Since: 2.6
		565	*/
		566
		567	/**
		568	* gssize:
		569	*
		570	* A signed variant of #gsize, corresponding to the
		571	* ssize_t defined on most platforms.
		572	* Values of this type can range from #G_MINSSIZE
		573	* to #G_MAXSSIZE.
		574	*
		575	* To print or scan values of this type, use
		576	* %G_GSSIZE_MODIFIER and/or %G_GSSIZE_FORMAT.
		577	*/
		578
		579	/**
		580	* G_MINSSIZE:
		581	*
		582	* The minimum value which can be held in a #gssize.
		583	*
		584	* Since: 2.14
		585	*/
		586
		587	/**
		588	* G_MAXSSIZE:
		589	*
		590	* The maximum value which can be held in a #gssize.
		591	*
		592	* Since: 2.14
		593	*/
		594
		595	/**
		596	* G_GSSIZE_FORMAT:
		597	*
		598	* This is the platform dependent conversion specifier for scanning
		599	* and printing values of type #gssize. See also #G_GINT16_FORMAT.
		600	*
		601	* Since: 2.6
		602	*/
		603
		604	/**
		605	* G_GSSIZE_MODIFIER:
		606	*
		607	* The platform dependent length modifier for conversion specifiers
		608	* for scanning and printing values of type #gssize. It
		609	* is a string literal.
		610	*
		611	* Since: 2.6
		612	*/
		613
		614	/**
		615	* goffset:
		616	*
		617	* A signed integer type that is used for file offsets,
		618	* corresponding to the C99 type off64_t.
		619	* Values of this type can range from #G_MINOFFSET to
		620	* #G_MAXOFFSET.
		621	*
		622	* To print or scan values of this type, use
		623	* %G_GOFFSET_MODIFIER and/or %G_GOFFSET_FORMAT.
		624	*
		625	* Since: 2.14
		626	*/
		627
		628	/**
		629	* G_MINOFFSET:
		630	*
		631	* The minimum value which can be held in a #goffset.
		632	*/
		633
		634	/**
		635	* G_MAXOFFSET:
		636	*
		637	* The maximum value which can be held in a #goffset.
		638	*/
		639
		640	/**
		641	* G_GOFFSET_MODIFIER:
		642	*
		643	* The platform dependent length modifier for conversion specifiers
		644	* for scanning and printing values of type #goffset. It is a string
		645	* literal. See also #G_GINT64_MODIFIER.
		646	*
		647	* Since: 2.20
		648	*/
		649
		650	/**
		651	* G_GOFFSET_FORMAT:
		652	*
		653	* This is the platform dependent conversion specifier for scanning
		654	* and printing values of type #goffset. See also #G_GINT64_FORMAT.
		655	*
		656	* Since: 2.20
		657	*/
		658
		659	/**
		660	* G_GOFFSET_CONSTANT:
		661	* @val: a literal integer value, e.g. 0x1d636b02300a7aa7
		662	*
		663	* This macro is used to insert #goffset 64-bit integer literals
		664	* into the source code.
		665	*
		666	* See also #G_GINT64_CONSTANT.
		667	*
		668	* Since: 2.20
		669	*/
		670
		671	/**
		672	* gintptr:
		673	*
		674	* Corresponds to the C99 type intptr_t,
		675	* a signed integer type that can hold any pointer.
		676	*
		677	* To print or scan values of this type, use
		678	* %G_GINTPTR_MODIFIER and/or %G_GINTPTR_FORMAT.
		679	*
		680	* Since: 2.18
		681	*/
		682
		683	/**
		684	* G_GINTPTR_MODIFIER:
		685	*
		686	* The platform dependent length modifier for conversion specifiers
		687	* for scanning and printing values of type #gintptr or #guintptr.
		688	* It is a string literal.
		689	*
		690	* Since: 2.22
		691	*/
		692
		693	/**
		694	* G_GINTPTR_FORMAT:
		695	*
		696	* This is the platform dependent conversion specifier for scanning
		697	* and printing values of type #gintptr.
		698	*
		699	* Since: 2.22
		700	*/
		701
		702	/**
		703	* guintptr:
		704	*
		705	* Corresponds to the C99 type uintptr_t,
		706	* an unsigned integer type that can hold any pointer.
		707	*
		708	* To print or scan values of this type, use
		709	* %G_GINTPTR_MODIFIER and/or %G_GUINTPTR_FORMAT.
		710	*
		711	* Since: 2.18
		712	*/
		713
		714	/**
		715	* G_GUINTPTR_FORMAT:
		716	*
		717	* This is the platform dependent conversion specifier
		718	* for scanning and printing values of type #guintptr.
		719	*
		720	* Since: 2.22
		721	*/
		722
		723	/* Type conversion {{{1 */
		724
		725	/**
		726	* SECTION:type_conversion
		727	* @title: Type Conversion Macros
		728	* @short_description: portably storing integers in pointer variables
		729	*
		730	* Many times GLib, GTK+, and other libraries allow you to pass "user
		731	* data" to a callback, in the form of a void pointer. From time to time
		732	* you want to pass an integer instead of a pointer. You could allocate
		733	* an integer, with something like:
		734	* |[<!-- language="C" -->
		735	* int *ip = g_new (int, 1);
		736	* *ip = 42;
		737	* ]|
		738	* But this is inconvenient, and it's annoying to have to free the
		739	* memory at some later time.
		740	*
		741	* Pointers are always at least 32 bits in size (on all platforms GLib
		742	* intends to support). Thus you can store at least 32-bit integer values
		743	* in a pointer value. Naively, you might try this, but it's incorrect:
		744	* |[<!-- language="C" -->
		745	* gpointer p;
		746	* int i;
		747	* p = (void*) 42;
		748	* i = (int) p;
		749	* ]|
		750	* Again, that example was not correct, don't copy it.
		751	* The problem is that on some systems you need to do this:
		752	* |[<!-- language="C" -->
		753	* gpointer p;
		754	* int i;
		755	* p = (void*) (long) 42;
		756	* i = (int) (long) p;
		757	* ]|
		758	* The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care
		759	* to do the right thing on the every platform.
		760	*
		761	* Warning: You may not store pointers in integers. This is not
		762	* portable in any way, shape or form. These macros only allow storing
		763	* integers in pointers, and only preserve 32 bits of the integer; values
		764	* outside the range of a 32-bit integer will be mangled.
		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 only allow storing integers in
		775	* pointers, and only preserve 32 bits of the integer; values outside the
		776	* 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 only allow storing integers in
		788	* pointers, and only preserve 32 bits of the integer; values outside the
		789	* 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	/* Bounds-checked integer arithmetic {{{1 */
		1427	/**
		1428	* SECTION:checkedmath
		1429	* @title: Bounds-checking integer arithmetic
		1430	* @short_description: a set of helpers for performing checked integer arithmetic
		1431	*
		1432	* GLib offers a set of macros for doing additions and multiplications
		1433	* of unsigned integers, with checks for overflows.
		1434	*
		1435	* The helpers all have three arguments. A pointer to the destination
		1436	* is always the first argument and the operands to the operation are
		1437	* the other two.
		1438	*
		1439	* Following standard GLib convention, the helpers return %TRUE in case
		1440	* of success (ie: no overflow).
		1441	*
		1442	* The helpers may be macros, normal functions or inlines. They may be
		1443	* implemented with inline assembly or compiler intrinsics where
		1444	* available.
		1445	*
		1446	* Since: 2.48
		1447	*/
		1448
		1449	/**
		1450	* g_uint_checked_add
		1451	* @dest: a pointer to the #guint destination
		1452	* @a: the #guint left operand
		1453	* @b: the #guint right operand
		1454	*
		1455	* Performs a checked addition of @a and @b, storing the result in
		1456	* @dest.
		1457	*
		1458	* If the operation is successful, %TRUE is returned. If the operation
		1459	* overflows then the state of @dest is undefined and %FALSE is
		1460	* returned.
		1461	*
		1462	* Returns: %TRUE if there was no overflow
		1463	* Since: 2.48
		1464	*/
		1465
		1466	/**
		1467	* g_uint_checked_mul
		1468	* @dest: a pointer to the #guint destination
		1469	* @a: the #guint left operand
		1470	* @b: the #guint right operand
		1471	*
		1472	* Performs a checked multiplication of @a and @b, storing the result in
		1473	* @dest.
		1474	*
		1475	* If the operation is successful, %TRUE is returned. If the operation
		1476	* overflows then the state of @dest is undefined and %FALSE is
		1477	* returned.
		1478	*
		1479	* Returns: %TRUE if there was no overflow
		1480	* Since: 2.48
		1481	*/
		1482
		1483	/**
		1484	* g_uint64_checked_add
		1485	* @dest: a pointer to the #guint64 destination
		1486	* @a: the #guint64 left operand
		1487	* @b: the #guint64 right operand
		1488	*
		1489	* Performs a checked addition of @a and @b, storing the result in
		1490	* @dest.
		1491	*
		1492	* If the operation is successful, %TRUE is returned. If the operation
		1493	* overflows then the state of @dest is undefined and %FALSE is
		1494	* returned.
		1495	*
		1496	* Returns: %TRUE if there was no overflow
		1497	* Since: 2.48
		1498	*/
		1499
		1500	/**
		1501	* g_uint64_checked_mul
		1502	* @dest: a pointer to the #guint64 destination
		1503	* @a: the #guint64 left operand
		1504	* @b: the #guint64 right operand
		1505	*
		1506	* Performs a checked multiplication of @a and @b, storing the result in
		1507	* @dest.
		1508	*
		1509	* If the operation is successful, %TRUE is returned. If the operation
		1510	* overflows then the state of @dest is undefined and %FALSE is
		1511	* returned.
		1512	*
		1513	* Returns: %TRUE if there was no overflow
		1514	* Since: 2.48
		1515	*/
		1516
		1517	/**
		1518	* g_size_checked_add
		1519	* @dest: a pointer to the #gsize destination
		1520	* @a: the #gsize left operand
		1521	* @b: the #gsize right operand
		1522	*
		1523	* Performs a checked addition of @a and @b, storing the result in
		1524	* @dest.
		1525	*
		1526	* If the operation is successful, %TRUE is returned. If the operation
		1527	* overflows then the state of @dest is undefined and %FALSE is
		1528	* returned.
		1529	*
		1530	* Returns: %TRUE if there was no overflow
		1531	* Since: 2.48
		1532	*/
		1533
		1534	/**
		1535	* g_size_checked_mul
		1536	* @dest: a pointer to the #gsize destination
		1537	* @a: the #gsize left operand
		1538	* @b: the #gsize right operand
		1539	*
		1540	* Performs a checked multiplication of @a and @b, storing the result in
		1541	* @dest.
		1542	*
		1543	* If the operation is successful, %TRUE is returned. If the operation
		1544	* overflows then the state of @dest is undefined and %FALSE is
		1545	* returned.
		1546	*
		1547	* Returns: %TRUE if there was no overflow
		1548	* Since: 2.48
		1549	*/
		1550	/* Numerical Definitions {{{1 */
		1551
		1552	/**
		1553	* SECTION:numerical
		1554	* @title: Numerical Definitions
		1555	* @short_description: mathematical constants, and floating point decomposition
		1556	*
		1557	* GLib offers mathematical constants such as #G_PI for the value of pi;
		1558	* many platforms have these in the C library, but some don't, the GLib
		1559	* versions always exist.
		1560	*
		1561	* The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the
		1562	* sign, mantissa and exponent of IEEE floats and doubles. These unions are
		1563	* defined as appropriate for a given platform. IEEE floats and doubles are
		1564	* supported (used for storage) by at least Intel, PPC and Sparc. See
		1565	* [IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float)
		1566	* for more information about IEEE number formats.
		1567	*/
		1568
		1569	/**
		1570	* G_IEEE754_FLOAT_BIAS:
		1571	*
		1572	* The bias by which exponents in single-precision floats are offset.
		1573	*/
		1574
		1575	/**
		1576	* G_IEEE754_DOUBLE_BIAS:
		1577	*
		1578	* The bias by which exponents in double-precision floats are offset.
		1579	*/
		1580
		1581	/**
		1582	* GFloatIEEE754:
		1583	* @v_float: the double value
		1584	*
		1585	* The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
		1586	* mantissa and exponent of IEEE floats and doubles. These unions are defined
		1587	* as appropriate for a given platform. IEEE floats and doubles are supported
		1588	* (used for storage) by at least Intel, PPC and Sparc.
		1589	*/
		1590
		1591	/**
		1592	* GDoubleIEEE754:
		1593	* @v_double: the double value
		1594	*
		1595	* The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
		1596	* mantissa and exponent of IEEE floats and doubles. These unions are defined
		1597	* as appropriate for a given platform. IEEE floats and doubles are supported
		1598	* (used for storage) by at least Intel, PPC and Sparc.
		1599	*/
		1600
		1601	/**
		1602	* G_E:
		1603	*
		1604	* The base of natural logarithms.
		1605	*/
		1606
		1607	/**
		1608	* G_LN2:
		1609	*
		1610	* The natural logarithm of 2.
		1611	*/
		1612
		1613	/**
		1614	* G_LN10:
		1615	*
		1616	* The natural logarithm of 10.
		1617	*/
		1618
		1619	/**
		1620	* G_PI:
		1621	*
		1622	* The value of pi (ratio of circle's circumference to its diameter).
		1623	*/
		1624
		1625	/**
		1626	* G_PI_2:
		1627	*
		1628	* Pi divided by 2.
		1629	*/
		1630
		1631	/**
		1632	* G_PI_4:
		1633	*
		1634	* Pi divided by 4.
		1635	*/
		1636
		1637	/**
		1638	* G_SQRT2:
		1639	*
		1640	* The square root of two.
		1641	*/
		1642
		1643	/**
		1644	* G_LOG_2_BASE_10:
		1645	*
		1646	* Multiplying the base 2 exponent by this number yields the base 10 exponent.
		1647	*/
		1648
		1649	/* Macros {{{1 */
		1650
		1651	/**
		1652	* SECTION:macros
		1653	* @title: Standard Macros
		1654	* @short_description: commonly-used macros
		1655	*
		1656	* These macros provide a few commonly-used features.
		1657	*/
		1658
		1659	/**
		1660	* G_OS_WIN32:
		1661	*
		1662	* This macro is defined only on Windows. So you can bracket
		1663	* Windows-specific code in "\#ifdef G_OS_WIN32".
		1664	*/
		1665
		1666	/**
		1667	* G_OS_UNIX:
		1668	*
		1669	* This macro is defined only on UNIX. So you can bracket
		1670	* UNIX-specific code in "\#ifdef G_OS_UNIX".
		1671	*/
		1672
		1673	/**
		1674	* G_DIR_SEPARATOR:
		1675	*
		1676	* The directory separator character.
		1677	* This is '/' on UNIX machines and '\' under Windows.
		1678	*/
		1679
		1680	/**
		1681	* G_DIR_SEPARATOR_S:
		1682	*
		1683	* The directory separator as a string.
		1684	* This is "/" on UNIX machines and "\" under Windows.
		1685	*/
		1686
		1687	/**
		1688	* G_IS_DIR_SEPARATOR:
		1689	* @c: a character
		1690	*
		1691	* Checks whether a character is a directory
		1692	* separator. It returns %TRUE for '/' on UNIX
		1693	* machines and for '\' or '/' under Windows.
		1694	*
		1695	* Since: 2.6
		1696	*/
		1697
		1698	/**
		1699	* G_SEARCHPATH_SEPARATOR:
		1700	*
		1701	* The search path separator character.
		1702	* This is ':' on UNIX machines and ';' under Windows.
		1703	*/
		1704
		1705	/**
		1706	* G_SEARCHPATH_SEPARATOR_S:
		1707	*
		1708	* The search path separator as a string.
		1709	* This is ":" on UNIX machines and ";" under Windows.
		1710	*/
		1711
		1712	/**
		1713	* TRUE:
		1714	*
		1715	* Defines the %TRUE value for the #gboolean type.
		1716	*/
		1717
		1718	/**
		1719	* FALSE:
		1720	*
		1721	* Defines the %FALSE value for the #gboolean type.
		1722	*/
		1723
		1724	/**
		1725	* NULL:
		1726	*
		1727	* Defines the standard %NULL pointer.
		1728	*/
		1729
		1730	/**
		1731	* MIN:
		1732	* @a: a numeric value
		1733	* @b: a numeric value
		1734	*
		1735	* Calculates the minimum of @a and @b.
		1736	*
		1737	* Returns: the minimum of @a and @b.
		1738	*/
		1739
		1740	/**
		1741	* MAX:
		1742	* @a: a numeric value
		1743	* @b: a numeric value
		1744	*
		1745	* Calculates the maximum of @a and @b.
		1746	*
		1747	* Returns: the maximum of @a and @b.
		1748	*/
		1749
		1750	/**
		1751	* ABS:
		1752	* @a: a numeric value
		1753	*
		1754	* Calculates the absolute value of @a.
		1755	* The absolute value is simply the number with any negative sign taken away.
		1756	*
		1757	* For example,
		1758	* - ABS(-10) is 10.
		1759	* - ABS(10) is also 10.
		1760	*
		1761	* Returns: the absolute value of @a.
		1762	*/
		1763
		1764	/**
		1765	* CLAMP:
		1766	* @x: the value to clamp
		1767	* @low: the minimum value allowed
		1768	* @high: the maximum value allowed
		1769	*
		1770	* Ensures that @x is between the limits set by @low and @high. If @low is
		1771	* greater than @high the result is undefined.
		1772	*
		1773	* For example,
		1774	* - CLAMP(5, 10, 15) is 10.
		1775	* - CLAMP(15, 5, 10) is 10.
		1776	* - CLAMP(20, 15, 25) is 20.
		1777	*
		1778	* Returns: the value of @x clamped to the range between @low and @high
		1779	*/
		1780
		1781	/**
		1782	* G_STRUCT_MEMBER:
		1783	* @member_type: the type of the struct field
		1784	* @struct_p: a pointer to a struct
		1785	* @struct_offset: the offset of the field from the start of the struct,
		1786	* in bytes
		1787	*
		1788	* Returns a member of a structure at a given offset, using the given type.
		1789	*
		1790	* Returns: the struct member
		1791	*/
		1792
		1793	/**
		1794	* G_STRUCT_MEMBER_P:
		1795	* @struct_p: a pointer to a struct
		1796	* @struct_offset: the offset from the start of the struct, in bytes
		1797	*
		1798	* Returns an untyped pointer to a given offset of a struct.
		1799	*
		1800	* Returns: an untyped pointer to @struct_p plus @struct_offset bytes
		1801	*/
		1802
		1803	/**
		1804	* G_STRUCT_OFFSET:
		1805	* @struct_type: a structure type, e.g. #GtkWidget
		1806	* @member: a field in the structure, e.g. @window
		1807	*
		1808	* Returns the offset, in bytes, of a member of a struct.
		1809	*
		1810	* Returns: the offset of @member from the start of @struct_type
		1811	*/
		1812
		1813	/**
		1814	* G_CONST_RETURN:
		1815	*
		1816	* If %G_DISABLE_CONST_RETURNS is defined, this macro expands
		1817	* to nothing. By default, the macro expands to const. The macro
		1818	* can be used in place of const for functions that return a value
		1819	* that should not be modified. The purpose of this macro is to allow
		1820	* us to turn on const for returned constant strings by default, while
		1821	* allowing programmers who find that annoying to turn it off. This macro
		1822	* should only be used for return values and for "out" parameters, it
		1823	* doesn't make sense for "in" parameters.
		1824	*
		1825	* Deprecated: 2.30: API providers should replace all existing uses with
		1826	* const and API consumers should adjust their code accordingly
		1827	*/
		1828
		1829	/**
		1830	* G_N_ELEMENTS:
		1831	* @arr: the array
		1832	*
		1833	* Determines the number of elements in an array. The array must be
		1834	* declared so the compiler knows its size at compile-time; this
		1835	* macro will not work on an array allocated on the heap, only static
		1836	* arrays or arrays on the stack.
		1837	*/
		1838
		1839	/* Miscellaneous Macros {{{1 */
		1840
		1841	/**
		1842	* SECTION:macros_misc
		1843	* @title: Miscellaneous Macros
		1844	* @short_description: specialized macros which are not used often
		1845	*
		1846	* These macros provide more specialized features which are not
		1847	* needed so often by application programmers.
		1848	*/
		1849
		1850	/**
		1851	* G_INLINE_FUNC:
		1852	*
		1853	* This macro used to be used to conditionally define inline functions
		1854	* in a compatible way before this feature was supported in all
		1855	* compilers. These days, GLib requires inlining support from the
		1856	* compiler, so your GLib-using programs can safely assume that the
		1857	* "inline" keywork works properly.
		1858	*
		1859	* Never use this macro anymore. Just say "static inline".
		1860	*
		1861	* Deprecated: 2.48: Use "static inline" instead
		1862	*/
		1863
		1864	/**
		1865	* G_STMT_START:
		1866	*
		1867	* Used within multi-statement macros so that they can be used in places
		1868	* where only one statement is expected by the compiler.
		1869	*/
		1870
		1871	/**
		1872	* G_STMT_END:
		1873	*
		1874	* Used within multi-statement macros so that they can be used in places
		1875	* where only one statement is expected by the compiler.
		1876	*/
		1877
		1878	/**
		1879	* G_BEGIN_DECLS:
		1880	*
		1881	* Used (along with #G_END_DECLS) to bracket header files. If the
		1882	* compiler in use is a C++ compiler, adds extern "C"
		1883	* around the header.
		1884	*/
		1885
		1886	/**
		1887	* G_END_DECLS:
		1888	*
		1889	* Used (along with #G_BEGIN_DECLS) to bracket header files. If the
		1890	* compiler in use is a C++ compiler, adds extern "C"
		1891	* around the header.
		1892	*/
		1893
		1894	/**
		1895	* G_VA_COPY:
		1896	* @ap1: the va_list variable to place a copy of @ap2 in
		1897	* @ap2: a va_list
		1898	*
		1899	* Portable way to copy va_list variables.
		1900	*
		1901	* In order to use this function, you must include string.h yourself,
		1902	* because this macro may use memmove() and GLib does not include
		1903	* string.h for you.
		1904	*/
		1905
		1906	/**
		1907	* G_STRINGIFY:
		1908	* @macro_or_string: a macro or a string
		1909	*
		1910	* Accepts a macro or a string and converts it into a string after
		1911	* preprocessor argument expansion. For example, the following code:
		1912	*
		1913	* |[<!-- language="C" -->
		1914	* #define AGE 27
		1915	* const gchar *greeting = G_STRINGIFY (AGE) " today!";
		1916	* ]|
		1917	*
		1918	* is transformed by the preprocessor into (code equivalent to):
		1919	*
		1920	* |[<!-- language="C" -->
		1921	* const gchar *greeting = "27 today!";
		1922	* ]|
		1923	*/
		1924
		1925	/**
		1926	* G_PASTE:
		1927	* @identifier1: an identifier
		1928	* @identifier2: an identifier
		1929	*
		1930	* Yields a new preprocessor pasted identifier
		1931	* @identifier1identifier2 from its expanded
		1932	* arguments @identifier1 and @identifier2. For example,
		1933	* the following code:
		1934	* |[<!-- language="C" -->
		1935	* #define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller)
		1936	* const gchar *name = GET (traveller, name);
		1937	* const gchar *quest = GET (traveller, quest);
		1938	* GdkColor *favourite = GET (traveller, favourite_colour);
		1939	* ]|
		1940	*
		1941	* is transformed by the preprocessor into:
		1942	* |[<!-- language="C" -->
		1943	* const gchar *name = traveller_get_name (traveller);
		1944	* const gchar *quest = traveller_get_quest (traveller);
		1945	* GdkColor *favourite = traveller_get_favourite_colour (traveller);
		1946	* ]|
		1947	*
		1948	* Since: 2.20
		1949	*/
		1950
		1951	/**
		1952	* G_STATIC_ASSERT:
		1953	* @expr: a constant expression
		1954	*
		1955	* The G_STATIC_ASSERT() macro lets the programmer check
		1956	* a condition at compile time, the condition needs to
		1957	* be compile time computable. The macro can be used in
		1958	* any place where a typedef is valid.
		1959	*
		1960	* A typedef is generally allowed in exactly the same places that
		1961	* a variable declaration is allowed. For this reason, you should
		1962	* not use G_STATIC_ASSERT() in the middle of blocks of code.
		1963	*
		1964	* The macro should only be used once per source code line.
		1965	*
		1966	* Since: 2.20
		1967	*/
		1968
		1969	/**
		1970	* G_STATIC_ASSERT_EXPR:
		1971	* @expr: a constant expression
		1972	*
		1973	* The G_STATIC_ASSERT_EXPR() macro lets the programmer check
		1974	* a condition at compile time. The condition needs to be
		1975	* compile time computable.
		1976	*
		1977	* Unlike G_STATIC_ASSERT(), this macro evaluates to an expression
		1978	* and, as such, can be used in the middle of other expressions.
		1979	* Its value should be ignored. This can be accomplished by placing
		1980	* it as the first argument of a comma expression.
		1981	*
		1982	* |[<!-- language="C" -->
		1983	* #define ADD_ONE_TO_INT(x) \
		1984	* (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1))
		1985	* ]|
		1986	*
		1987	* Since: 2.30
		1988	*/
		1989
		1990	/**
		1991	* G_GNUC_EXTENSION:
		1992	*
		1993	* Expands to __extension__ when gcc is used as the compiler. This simply
		1994	* tells gcc not to warn about the following non-standard code when compiling
		1995	* with the `-pedantic` option.
		1996	*/
		1997
		1998	/**
		1999	* G_GNUC_CHECK_VERSION:
		2000	*
		2001	* Expands to a a check for a compiler with __GNUC__ defined and a version
		2002	* greater than or equal to the major and minor numbers provided. For example,
		2003	* the following would only match on compilers such as GCC 4.8 or newer.
		2004	*
		2005	* |[<!-- language="C" -->
		2006	* #if G_GNUC_CHECK_VERSION(4, 8)
		2007	* #endif
		2008	* ]|
		2009	*
		2010	* Since: 2.42
		2011	*/
		2012
		2013	/**
		2014	* G_GNUC_CONST:
		2015	*
		2016	* Expands to the GNU C const function attribute if the compiler is gcc.
		2017	* Declaring a function as const enables better optimization of calls to
		2018	* the function. A const function doesn't examine any values except its
		2019	* parameters, and has no effects except its return value.
		2020	*
		2021	* Place the attribute after the declaration, just before the semicolon.
		2022	*
		2023	* See the GNU C documentation for more details.
		2024	*
		2025	* A function that has pointer arguments and examines the data pointed to
		2026	* must not be declared const. Likewise, a function that calls a non-const
		2027	* function usually must not be const. It doesn't make sense for a const
		2028	* function to return void.
		2029	*/
		2030
		2031	/**
		2032	* G_GNUC_PURE:
		2033	*
		2034	* Expands to the GNU C pure function attribute if the compiler is gcc.
		2035	* Declaring a function as pure enables better optimization of calls to
		2036	* the function. A pure function has no effects except its return value
		2037	* and the return value depends only on the parameters and/or global
		2038	* variables.
		2039	*
		2040	* Place the attribute after the declaration, just before the semicolon.
		2041	*
		2042	* See the GNU C documentation for more details.
		2043	*/
		2044
		2045	/**
		2046	* G_GNUC_MALLOC:
		2047	*
		2048	* Expands to the GNU C malloc function attribute if the compiler is gcc.
		2049	* Declaring a function as malloc enables better optimization of the function.
		2050	* A function can have the malloc attribute if it returns a pointer which is
		2051	* guaranteed to not alias with any other pointer when the function returns
		2052	* (in practice, this means newly allocated memory).
		2053	*
		2054	* Place the attribute after the declaration, just before the semicolon.
		2055	*
		2056	* See the GNU C documentation for more details.
		2057	*
		2058	* Since: 2.6
		2059	*/
		2060
		2061	/**
		2062	* G_GNUC_ALLOC_SIZE:
		2063	* @x: the index of the argument specifying the allocation size
		2064	*
		2065	* Expands to the GNU C alloc_size function attribute if the compiler
		2066	* is a new enough gcc. This attribute tells the compiler that the
		2067	* function returns a pointer to memory of a size that is specified
		2068	* by the @xth function parameter.
		2069	*
		2070	* Place the attribute after the function declaration, just before the
		2071	* semicolon.
		2072	*
		2073	* See the GNU C documentation for more details.
		2074	*
		2075	* Since: 2.18
		2076	*/
		2077
		2078	/**
		2079	* G_GNUC_ALLOC_SIZE2:
		2080	* @x: the index of the argument specifying one factor of the allocation size
		2081	* @y: the index of the argument specifying the second factor of the allocation size
		2082	*
		2083	* Expands to the GNU C alloc_size function attribute if the compiler is a
		2084	* new enough gcc. This attribute tells the compiler that the function returns
		2085	* a pointer to memory of a size that is specified by the product of two
		2086	* function parameters.
		2087	*
		2088	* Place the attribute after the function declaration, just before the
		2089	* semicolon.
		2090	*
		2091	* See the GNU C documentation for more details.
		2092	*
		2093	* Since: 2.18
		2094	*/
		2095
		2096	/**
		2097	* G_GNUC_DEPRECATED:
		2098	*
		2099	* Expands to the GNU C deprecated attribute if the compiler is gcc.
		2100	* It can be used to mark typedefs, variables and functions as deprecated.
		2101	* When called with the `-Wdeprecated-declarations` option,
		2102	* gcc will generate warnings when deprecated interfaces are used.
		2103	*
		2104	* Place the attribute after the declaration, just before the semicolon.
		2105	*
		2106	* See the GNU C documentation for more details.
		2107	*
		2108	* Since: 2.2
		2109	*/
		2110
		2111	/**
		2112	* G_GNUC_DEPRECATED_FOR:
		2113	* @f: the intended replacement for the deprecated symbol,
		2114	* such as the name of a function
		2115	*
		2116	* Like %G_GNUC_DEPRECATED, but names the intended replacement for the
		2117	* deprecated symbol if the version of gcc in use is new enough to support
		2118	* custom deprecation messages.
		2119	*
		2120	* Place the attribute after the declaration, just before the semicolon.
		2121	*
		2122	* See the GNU C documentation for more details.
		2123	*
		2124	* Note that if @f is a macro, it will be expanded in the warning message.
		2125	* You can enclose it in quotes to prevent this. (The quotes will show up
		2126	* in the warning, but it's better than showing the macro expansion.)
		2127	*
		2128	* Since: 2.26
		2129	*/
		2130
		2131	/**
		2132	* G_GNUC_BEGIN_IGNORE_DEPRECATIONS:
		2133	*
		2134	* Tells gcc (if it is a new enough version) to temporarily stop emitting
		2135	* warnings when functions marked with %G_GNUC_DEPRECATED or
		2136	* %G_GNUC_DEPRECATED_FOR are called. This is useful for when you have
		2137	* one deprecated function calling another one, or when you still have
		2138	* regression tests for deprecated functions.
		2139	*
		2140	* Use %G_GNUC_END_IGNORE_DEPRECATIONS to begin warning again. (If you
		2141	* are not compiling with `-Wdeprecated-declarations` then neither macro
		2142	* has any effect.)
		2143	*
		2144	* This macro can be used either inside or outside of a function body,
		2145	* but must appear on a line by itself.
		2146	*
		2147	* Since: 2.32
		2148	*/
		2149
		2150	/**
		2151	* G_GNUC_END_IGNORE_DEPRECATIONS:
		2152	*
		2153	* Undoes the effect of %G_GNUC_BEGIN_IGNORE_DEPRECATIONS, telling
		2154	* gcc to begin outputting warnings again (assuming those warnings
		2155	* had been enabled to begin with).
		2156	*
		2157	* This macro can be used either inside or outside of a function body,
		2158	* but must appear on a line by itself.
		2159	*
		2160	* Since: 2.32
		2161	*/
		2162
		2163	/**
		2164	* G_DEPRECATED:
		2165	*
		2166	* This macro is similar to %G_GNUC_DEPRECATED, and can be used to mark
		2167	* functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED, it is
		2168	* meant to be portable across different compilers and must be placed
		2169	* before the function declaration.
		2170	*
		2171	* Since: 2.32
		2172	*/
		2173
		2174	/**
		2175	* G_DEPRECATED_FOR:
		2176	* @f: the name of the function that this function was deprecated for
		2177	*
		2178	* This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark
		2179	* functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it
		2180	* is meant to be portable across different compilers and must be placed
		2181	* before the function declaration.
		2182	*
		2183	* Since: 2.32
		2184	*/
		2185
		2186	/**
		2187	* G_UNAVAILABLE:
		2188	* @maj: the major version that introduced the symbol
		2189	* @min: the minor version that introduced the symbol
		2190	*
		2191	* This macro can be used to mark a function declaration as unavailable.
		2192	* It must be placed before the function declaration. Use of a function
		2193	* that has been annotated with this macros will produce a compiler warning.
		2194	*
		2195	* Since: 2.32
		2196	*/
		2197
		2198	/**
		2199	* GLIB_DISABLE_DEPRECATION_WARNINGS:
		2200	*
		2201	* A macro that should be defined before including the glib.h header.
		2202	* If it is defined, no compiler warnings will be produced for uses
		2203	* of deprecated GLib APIs.
		2204	*/
		2205
		2206	/**
		2207	* G_GNUC_NORETURN:
		2208	*
		2209	* Expands to the GNU C noreturn function attribute if the compiler is gcc.
		2210	* It is used for declaring functions which never return. It enables
		2211	* optimization of the function, and avoids possible compiler warnings.
		2212	*
		2213	* Place the attribute after the declaration, just before the semicolon.
		2214	*
		2215	* See the GNU C documentation for more details.
		2216	*/
		2217
		2218	/**
		2219	* G_GNUC_UNUSED:
		2220	*
		2221	* Expands to the GNU C unused function attribute if the compiler is gcc.
		2222	* It is used for declaring functions and arguments which may never be used.
		2223	* It avoids possible compiler warnings.
		2224	*
		2225	* For functions, place the attribute after the declaration, just before the
		2226	* semicolon. For arguments, place the attribute at the beginning of the
		2227	* argument declaration.
		2228	*
		2229	* |[<!-- language="C" -->
		2230	* void my_unused_function (G_GNUC_UNUSED gint unused_argument,
		2231	* gint other_argument) G_GNUC_UNUSED;
		2232	* ]|
		2233	*
		2234	* See the GNU C documentation for more details.
		2235	*/
		2236
		2237	/**
		2238	* G_GNUC_PRINTF:
		2239	* @format_idx: the index of the argument corresponding to the
		2240	* format string (The arguments are numbered from 1)
		2241	* @arg_idx: the index of the first of the format arguments
		2242	*
		2243	* Expands to the GNU C format function attribute if the compiler is gcc.
		2244	* This is used for declaring functions which take a variable number of
		2245	* arguments, with the same syntax as printf(). It allows the compiler
		2246	* to type-check the arguments passed to the function.
		2247	*
		2248	* Place the attribute after the function declaration, just before the
		2249	* semicolon.
		2250	*
		2251	* See the GNU C documentation for more details.
		2252	*
		2253	* |[<!-- language="C" -->
		2254	* gint g_snprintf (gchar *string,
		2255	* gulong n,
		2256	* gchar const *format,
		2257	* ...) G_GNUC_PRINTF (3, 4);
		2258	* ]|
		2259	*/
		2260
		2261	/**
		2262	* G_GNUC_SCANF:
		2263	* @format_idx: the index of the argument corresponding to
		2264	* the format string (The arguments are numbered from 1)
		2265	* @arg_idx: the index of the first of the format arguments
		2266	*
		2267	* Expands to the GNU C format function attribute if the compiler is gcc.
		2268	* This is used for declaring functions which take a variable number of
		2269	* arguments, with the same syntax as scanf(). It allows the compiler
		2270	* to type-check the arguments passed to the function.
		2271	*
		2272	* See the GNU C documentation for details.
		2273	*/
		2274
		2275	/**
		2276	* G_GNUC_FORMAT:
		2277	* @arg_idx: the index of the argument
		2278	*
		2279	* Expands to the GNU C format_arg function attribute if the compiler
		2280	* is gcc. This function attribute specifies that a function takes a
		2281	* format string for a printf(), scanf(), strftime() or strfmon() style
		2282	* function and modifies it, so that the result can be passed to a printf(),
		2283	* scanf(), strftime() or strfmon() style function (with the remaining
		2284	* arguments to the format function the same as they would have been
		2285	* for the unmodified string).
		2286	*
		2287	* Place the attribute after the function declaration, just before the
		2288	* semicolon.
		2289	*
		2290	* See the GNU C documentation for more details.
		2291	*
		2292	* |[<!-- language="C" -->
		2293	* gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
		2294	* ]|
		2295	*/
		2296
		2297	/**
		2298	* G_GNUC_NULL_TERMINATED:
		2299	*
		2300	* Expands to the GNU C sentinel function attribute if the compiler is gcc.
		2301	* This function attribute only applies to variadic functions and instructs
		2302	* the compiler to check that the argument list is terminated with an
		2303	* explicit %NULL.
		2304	*
		2305	* Place the attribute after the declaration, just before the semicolon.
		2306	*
		2307	* See the GNU C documentation for more details.
		2308	*
		2309	* Since: 2.8
		2310	*/
		2311
		2312	/**
		2313	* G_GNUC_WARN_UNUSED_RESULT:
		2314	*
		2315	* Expands to the GNU C warn_unused_result function attribute if the compiler
		2316	* is gcc. This function attribute makes the compiler emit a warning if the
		2317	* result of a function call is ignored.
		2318	*
		2319	* Place the attribute after the declaration, just before the semicolon.
		2320	*
		2321	* See the GNU C documentation for more details.
		2322	*
		2323	* Since: 2.10
		2324	*/
		2325
		2326	/**
		2327	* G_GNUC_FUNCTION:
		2328	*
		2329	* Expands to "" on all modern compilers, and to __FUNCTION__ on gcc
		2330	* version 2.x. Don't use it.
		2331	*
		2332	* Deprecated: 2.16: Use G_STRFUNC() instead
		2333	*/
		2334
		2335	/**
		2336	* G_GNUC_PRETTY_FUNCTION:
		2337	*
		2338	* Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__
		2339	* on gcc version 2.x. Don't use it.
		2340	*
		2341	* Deprecated: 2.16: Use G_STRFUNC() instead
		2342	*/
		2343
		2344	/**
		2345	* G_GNUC_NO_INSTRUMENT:
		2346	*
		2347	* Expands to the GNU C no_instrument_function function attribute if the
		2348	* compiler is gcc. Functions with this attribute will not be instrumented
		2349	* for profiling, when the compiler is called with the
		2350	* `-finstrument-functions` option.
		2351	*
		2352	* Place the attribute after the declaration, just before the semicolon.
		2353	*
		2354	* See the GNU C documentation for more details.
		2355	*/
		2356
		2357	/**
		2358	* G_GNUC_INTERNAL:
		2359	*
		2360	* This attribute can be used for marking library functions as being used
		2361	* internally to the library only, which may allow the compiler to handle
		2362	* function calls more efficiently. Note that static functions do not need
		2363	* to be marked as internal in this way. See the GNU C documentation for
		2364	* details.
		2365	*
		2366	* When using a compiler that supports the GNU C hidden visibility attribute,
		2367	* this macro expands to __attribute__((visibility("hidden"))).
		2368	* When using the Sun Studio compiler, it expands to __hidden.
		2369	*
		2370	* Note that for portability, the attribute should be placed before the
		2371	* function declaration. While GCC allows the macro after the declaration,
		2372	* Sun Studio does not.
		2373	*
		2374	* |[<!-- language="C" -->
		2375	* G_GNUC_INTERNAL
		2376	* void _g_log_fallback_handler (const gchar *log_domain,
		2377	* GLogLevelFlags log_level,
		2378	* const gchar *message,
		2379	* gpointer unused_data);
		2380	* ]|
		2381	*
		2382	* Since: 2.6
		2383	*/
		2384
		2385	/**
		2386	* G_GNUC_MAY_ALIAS:
		2387	*
		2388	* Expands to the GNU C may_alias type attribute if the compiler is gcc.
		2389	* Types with this attribute will not be subjected to type-based alias
		2390	* analysis, but are assumed to alias with any other type, just like char.
		2391	*
		2392	* See the GNU C documentation for details.
		2393	*
		2394	* Since: 2.14
		2395	*/
		2396
		2397	/**
		2398	* G_LIKELY:
		2399	* @expr: the expression
		2400	*
		2401	* Hints the compiler that the expression is likely to evaluate to
		2402	* a true value. The compiler may use this information for optimizations.
		2403	*
		2404	* |[<!-- language="C" -->
		2405	* if (G_LIKELY (random () != 1))
		2406	* g_print ("not one");
		2407	* ]|
		2408	*
		2409	* Returns: the value of @expr
		2410	*
		2411	* Since: 2.2
		2412	*/
		2413
		2414	/**
		2415	* G_UNLIKELY:
		2416	* @expr: the expression
		2417	*
		2418	* Hints the compiler that the expression is unlikely to evaluate to
		2419	* a true value. The compiler may use this information for optimizations.
		2420	*
		2421	* |[<!-- language="C" -->
		2422	* if (G_UNLIKELY (random () == 1))
		2423	* g_print ("a random one");
		2424	* ]|
		2425	*
		2426	* Returns: the value of @expr
		2427	*
		2428	* Since: 2.2
		2429	*/
		2430
		2431	/**
		2432	* G_STRLOC:
		2433	*
		2434	* Expands to a string identifying the current code position.
		2435	*/
		2436
		2437	/**
		2438	* G_STRFUNC:
		2439	*
		2440	* Expands to a string identifying the current function.
		2441	*
		2442	* Since: 2.4
		2443	*/
		2444
		2445	/**
		2446	* G_HAVE_GNUC_VISIBILITY:
		2447	*
		2448	* Defined to 1 if gcc-style visibility handling is supported.
		2449	*/
		2450
		2451	/* g_auto(), g_autoptr() and helpers {{{1 */
		2452
		2453	/**
		2454	* g_auto:
		2455	* @TypeName: a supported variable type
		2456	*
		2457	* Helper to declare a variable with automatic cleanup.
		2458	*
		2459	* The variable is cleaned up in a way appropriate to its type when the
		2460	* variable goes out of scope. The type must support this.
		2461	*
		2462	* This feature is only supported on GCC and clang. This macro is not
		2463	* defined on other compilers and should not be used in programs that
		2464	* are intended to be portable to those compilers.
		2465	*
		2466	* This is meant to be used with stack-allocated structures and
		2467	* non-pointer types. For the (more commonly used) pointer version, see
		2468	* g_autoptr().
		2469	*
		2470	* This macro can be used to avoid having to do explicit cleanups of
		2471	* local variables when exiting functions. It often vastly simplifies
		2472	* handling of error conditions, removing the need for various tricks
		2473	* such as 'goto out' or repeating of cleanup code. It is also helpful
		2474	* for non-error cases.
		2475	*
		2476	* Consider the following example:
		2477	*
		2478	* |[
		2479	* GVariant *
		2480	* my_func(void)
		2481	* {
		2482	* g_auto(GQueue) queue = G_QUEUE_INIT;
		2483	* g_auto(GVariantBuilder) builder;
		2484	* g_auto(GStrv) strv;
		2485	*
		2486	* g_variant_builder_init (&builder, G_VARIANT_TYPE_VARDICT);
		2487	* strv = g_strsplit("a:b:c", ":", -1);
		2488	*
		2489	* ...
		2490	*
		2491	* if (error_condition)
		2492	* return NULL;
		2493	*
		2494	* ...
		2495	*
		2496	* return g_variant_builder_end (&builder);
		2497	* }
		2498	* ]|
		2499	*
		2500	* You must initialize the variable in some way -- either by use of an
		2501	* initialiser or by ensuring that an _init function will be called on
		2502	* it unconditionally before it goes out of scope.
		2503	*
		2504	* Since: 2.44
		2505	*/
		2506
		2507	/**
		2508	* g_autoptr:
		2509	* @TypeName: a supported variable type
		2510	*
		2511	* Helper to declare a pointer variable with automatic cleanup.
		2512	*
		2513	* The variable is cleaned up in a way appropriate to its type when the
		2514	* variable goes out of scope. The type must support this.
		2515	*
		2516	* This feature is only supported on GCC and clang. This macro is not
		2517	* defined on other compilers and should not be used in programs that
		2518	* are intended to be portable to those compilers.
		2519	*
		2520	* This is meant to be used to declare pointers to types with cleanup
		2521	* functions. The type of the variable is a pointer to @TypeName. You
		2522	* must not add your own '*'.
		2523	*
		2524	* This macro can be used to avoid having to do explicit cleanups of
		2525	* local variables when exiting functions. It often vastly simplifies
		2526	* handling of error conditions, removing the need for various tricks
		2527	* such as 'goto out' or repeating of cleanup code. It is also helpful
		2528	* for non-error cases.
		2529	*
		2530	* Consider the following example:
		2531	*
		2532	* |[
		2533	* gboolean
		2534	* check_exists(GVariant *dict)
		2535	* {
		2536	* g_autoptr(GVariant) dirname, basename = NULL;
		2537	* g_autofree gchar *path = NULL;
		2538	*
		2539	* dirname = g_variant_lookup_value (dict, "dirname", G_VARIANT_TYPE_STRING);
		2540	*
		2541	* if (dirname == NULL)
		2542	* return FALSE;
		2543	*
		2544	* basename = g_variant_lookup_value (dict, "basename", G_VARIANT_TYPE_STRING);
		2545	*
		2546	* if (basename == NULL)
		2547	* return FALSE;
		2548	*
		2549	* path = g_build_filename (g_variant_get_string (dirname, NULL),
		2550	* g_variant_get_string (basename, NULL),
		2551	* NULL);
		2552	*
		2553	* return g_access (path, R_OK) == 0;
		2554	* }
		2555	* ]|
		2556	*
		2557	* You must initialise the variable in some way -- either by use of an
		2558	* initialiser or by ensuring that it is assigned to unconditionally
		2559	* before it goes out of scope.
		2560	*
		2561	* See also g_auto(), g_autofree() and g_steal_pointer().
		2562	*
		2563	* Since: 2.44
		2564	*/
		2565
		2566	/**
		2567	* g_autofree:
		2568	*
		2569	* Macro to add an attribute to pointer variable to ensure automatic
		2570	* cleanup using g_free().
		2571	*
		2572	* This macro differs from g_autoptr() in that it is an attribute supplied
		2573	* before the type name, rather than wrapping the type definition. Instead
		2574	* of using a type-specific lookup, this macro always calls g_free() directly.
		2575	*
		2576	* This means it's useful for any type that is returned from
		2577	* g_malloc().
		2578	*
		2579	* Otherwise, this macro has similar constraints as g_autoptr() - only
		2580	* supported on GCC and clang, the variable must be initialized, etc.
		2581	*
		2582	* |[
		2583	* gboolean
		2584	* operate_on_malloc_buf (void)
		2585	* {
		2586	* g_autofree guint8* membuf = NULL;
		2587	*
		2588	* membuf = g_malloc (8192);
		2589	*
		2590	* /* Some computation on membuf */
		2591	*
		2592	* /* membuf will be automatically freed here */
		2593	* return TRUE;
		2594	* }
		2595	* ]|
		2596	*
		2597	* Since: 2.44
		2598	*/
		2599
		2600	/**
		2601	* G_DEFINE_AUTOPTR_CLEANUP_FUNC:
		2602	* @TypeName: a type name to define a g_autoptr() cleanup function for
		2603	* @func: the cleanup function
		2604	*
		2605	* Defines the appropriate cleanup function for a pointer type.
		2606	*
		2607	* The function will not be called if the variable to be cleaned up
		2608	* contains %NULL.
		2609	*
		2610	* This will typically be the _free() or _unref() function for the given
		2611	* type.
		2612	*
		2613	* With this definition, it will be possible to use g_autoptr() with
		2614	* @TypeName.
		2615	*
		2616	* |[
		2617	* G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref)
		2618	* ]|
		2619	*
		2620	* This macro should be used unconditionally; it is a no-op on compilers
		2621	* where cleanup is not supported.
		2622	*
		2623	* Since: 2.44
		2624	*/
		2625
		2626	/**
		2627	* G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC:
		2628	* @TypeName: a type name to define a g_auto() cleanup function for
		2629	* @func: the clear function
		2630	*
		2631	* Defines the appropriate cleanup function for a type.
		2632	*
		2633	* This will typically be the _clear() function for the given type.
		2634	*
		2635	* With this definition, it will be possible to use g_auto() with
		2636	* @TypeName.
		2637	*
		2638	* |[
		2639	* G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear)
		2640	* ]|
		2641	*
		2642	* This macro should be used unconditionally; it is a no-op on compilers
		2643	* where cleanup is not supported.
		2644	*
		2645	* Since: 2.44
		2646	*/
		2647
		2648	/**
		2649	* G_DEFINE_AUTO_CLEANUP_FREE_FUNC:
		2650	* @TypeName: a type name to define a g_auto() cleanup function for
		2651	* @func: the free function
		2652	* @none: the "none" value for the type
		2653	*
		2654	* Defines the appropriate cleanup function for a type.
		2655	*
		2656	* With this definition, it will be possible to use g_auto() with
		2657	* @TypeName.
		2658	*
		2659	* This function will be rarely used. It is used with pointer-based
		2660	* typedefs and non-pointer types where the value of the variable
		2661	* represents a resource that must be freed. Two examples are #GStrv
		2662	* and file descriptors.
		2663	*
		2664	* @none specifies the "none" value for the type in question. It is
		2665	* probably something like %NULL or -1. If the variable is found to
		2666	* contain this value then the free function will not be called.
		2667	*
		2668	* |[
		2669	* G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL)
		2670	* ]|
		2671	*
		2672	* This macro should be used unconditionally; it is a no-op on compilers
		2673	* where cleanup is not supported.
		2674	*
		2675	* Since: 2.44
		2676	*/
		2677
		2678	/* Windows Compatibility Functions {{{1 */
		2679
		2680	/**
		2681	* SECTION:windows
		2682	* @title: Windows Compatibility Functions
		2683	* @short_description: UNIX emulation on Windows
		2684	*
		2685	* These functions provide some level of UNIX emulation on the
		2686	* Windows platform. If your application really needs the POSIX
		2687	* APIs, we suggest you try the Cygwin project.
		2688	*/
		2689
		2690	/**
		2691	* MAXPATHLEN:
		2692	*
		2693	* Provided for UNIX emulation on Windows; equivalent to UNIX
		2694	* macro %MAXPATHLEN, which is the maximum length of a filename
		2695	* (including full path).
		2696	*/
		2697
		2698	/**
		2699	* G_WIN32_DLLMAIN_FOR_DLL_NAME:
		2700	* @static: empty or "static"
		2701	* @dll_name: the name of the (pointer to the) char array where
		2702	* the DLL name will be stored. If this is used, you must also
		2703	* include `windows.h`. If you need a more complex DLL entry
		2704	* point function, you cannot use this
		2705	*
		2706	* On Windows, this macro defines a DllMain() function that stores
		2707	* the actual DLL name that the code being compiled will be included in.
		2708	*
		2709	* On non-Windows platforms, expands to nothing.
		2710	*/
		2711
		2712	/**
		2713	* G_WIN32_HAVE_WIDECHAR_API:
		2714	*
		2715	* On Windows, this macro defines an expression which evaluates to
		2716	* %TRUE if the code is running on a version of Windows where the wide
		2717	* character versions of the Win32 API functions, and the wide character
		2718	* versions of the C library functions work. (They are always present in
		2719	* the DLLs, but don't work on Windows 9x and Me.)
		2720	*
		2721	* On non-Windows platforms, it is not defined.
		2722	*
		2723	* Since: 2.6
		2724	*/
		2725
		2726
		2727	/**
		2728	* G_WIN32_IS_NT_BASED:
		2729	*
		2730	* On Windows, this macro defines an expression which evaluates to
		2731	* %TRUE if the code is running on an NT-based Windows operating system.
		2732	*
		2733	* On non-Windows platforms, it is not defined.
		2734	*
		2735	* Since: 2.6
		2736	*/
		2737
		2738	/* Epilogue {{{1 */
		2739	/* vim: set foldmethod=marker: */