1 /*
2 * Copyright © 2011 Red Hat, Inc
3 *
4 * SPDX-License-Identifier: LGPL-2.1-or-later
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 *
19 * Author: Matthias Clasen
20 */
21
22
23 /* This file collects documentation for macros, typedefs and
24 * the like, which have no good home in any of the 'real' source
25 * files.
26 */
27
28 /* Type conversion {{{1 */
29
30 /**
31 * GINT_TO_POINTER:
32 * @i: integer to stuff into a pointer
33 *
34 * Stuffs an integer into a pointer type.
35 *
36 * Remember, you may not store pointers in integers. This is not portable
37 * in any way, shape or form. These macros only allow storing integers in
38 * pointers, and only preserve 32 bits of the integer; values outside the
39 * range of a 32-bit integer will be mangled.
40 */
41
42 /**
43 * GPOINTER_TO_INT:
44 * @p: pointer containing an integer
45 *
46 * Extracts an integer from a pointer. The integer must have
47 * been stored in the pointer with GINT_TO_POINTER().
48 *
49 * Remember, you may not store pointers in integers. This is not portable
50 * in any way, shape or form. These macros only allow storing integers in
51 * pointers, and only preserve 32 bits of the integer; values outside the
52 * range of a 32-bit integer will be mangled.
53 */
54
55 /**
56 * GUINT_TO_POINTER:
57 * @u: unsigned integer to stuff into the pointer
58 *
59 * Stuffs an unsigned integer into a pointer type.
60 */
61
62 /**
63 * GPOINTER_TO_UINT:
64 * @p: pointer to extract an unsigned integer from
65 *
66 * Extracts an unsigned integer from a pointer. The integer must have
67 * been stored in the pointer with GUINT_TO_POINTER().
68 */
69
70 /**
71 * GSIZE_TO_POINTER:
72 * @s: #gsize to stuff into the pointer
73 *
74 * Stuffs a #gsize into a pointer type.
75 *
76 * Remember, you may not store pointers in integers. This is not portable
77 * in any way, shape or form. These macros only allow storing integers in
78 * pointers, and preserve all bits of a pointer (e.g. on CHERI systems).
79 * The only types that can store pointers as well as integers are #guintptr
80 * and #gintptr.
81 */
82
83 /**
84 * GPOINTER_TO_SIZE:
85 * @p: pointer to extract a #gsize from
86 *
87 * Extracts a #gsize from a pointer. The #gsize must have
88 * been stored in the pointer with GSIZE_TO_POINTER().
89 *
90 * Remember, you may not store pointers in integers. This is not portable
91 * in any way, shape or form. These macros only allow storing integers in
92 * pointers, and preserve all bits of a pointer (e.g. on CHERI systems).
93 * The only types that can store pointers as well as integers are #guintptr
94 * and #gintptr.
95 *
96 * See also GPOINTER_TO_TYPE() for #gsize.
97 */
98
99 /* Byte order {{{1 */
100
101 /**
102 * G_BYTE_ORDER:
103 *
104 * The host byte order.
105 * This can be either %G_LITTLE_ENDIAN or %G_BIG_ENDIAN (support for
106 * %G_PDP_ENDIAN may be added in future.)
107 */
108
109 /**
110 * G_LITTLE_ENDIAN:
111 *
112 * Specifies one of the possible types of byte order.
113 * See %G_BYTE_ORDER.
114 */
115
116 /**
117 * G_BIG_ENDIAN:
118 *
119 * Specifies one of the possible types of byte order.
120 * See %G_BYTE_ORDER.
121 */
122
123 /**
124 * G_PDP_ENDIAN:
125 *
126 * Specifies one of the possible types of byte order
127 * (currently unused). See %G_BYTE_ORDER.
128 */
129
130 /**
131 * g_htonl:
132 * @val: a 32-bit integer value in host byte order
133 *
134 * Converts a 32-bit integer value from host to network byte order.
135 *
136 * Returns: @val converted to network byte order
137 */
138
139 /**
140 * g_htons:
141 * @val: a 16-bit integer value in host byte order
142 *
143 * Converts a 16-bit integer value from host to network byte order.
144 *
145 * Returns: @val converted to network byte order
146 */
147
148 /**
149 * g_ntohl:
150 * @val: a 32-bit integer value in network byte order
151 *
152 * Converts a 32-bit integer value from network to host byte order.
153 *
154 * Returns: @val converted to host byte order.
155 */
156
157 /**
158 * g_ntohs:
159 * @val: a 16-bit integer value in network byte order
160 *
161 * Converts a 16-bit integer value from network to host byte order.
162 *
163 * Returns: @val converted to host byte order
164 */
165
166 /**
167 * GINT_FROM_BE:
168 * @val: a #gint value in big-endian byte order
169 *
170 * Converts a #gint value from big-endian to host byte order.
171 *
172 * Returns: @val converted to host byte order
173 */
174
175 /**
176 * GINT_FROM_LE:
177 * @val: a #gint value in little-endian byte order
178 *
179 * Converts a #gint value from little-endian to host byte order.
180 *
181 * Returns: @val converted to host byte order
182 */
183
184 /**
185 * GINT_TO_BE:
186 * @val: a #gint value in host byte order
187 *
188 * Converts a #gint value from host byte order to big-endian.
189 *
190 * Returns: @val converted to big-endian byte order
191 */
192
193 /**
194 * GINT_TO_LE:
195 * @val: a #gint value in host byte order
196 *
197 * Converts a #gint value from host byte order to little-endian.
198 *
199 * Returns: @val converted to little-endian byte order
200 */
201
202 /**
203 * GUINT_FROM_BE:
204 * @val: a #guint value in big-endian byte order
205 *
206 * Converts a #guint value from big-endian to host byte order.
207 *
208 * Returns: @val converted to host byte order
209 */
210
211 /**
212 * GUINT_FROM_LE:
213 * @val: a #guint value in little-endian byte order
214 *
215 * Converts a #guint value from little-endian to host byte order.
216 *
217 * Returns: @val converted to host byte order
218 */
219
220 /**
221 * GUINT_TO_BE:
222 * @val: a #guint value in host byte order
223 *
224 * Converts a #guint value from host byte order to big-endian.
225 *
226 * Returns: @val converted to big-endian byte order
227 */
228
229 /**
230 * GUINT_TO_LE:
231 * @val: a #guint value in host byte order
232 *
233 * Converts a #guint value from host byte order to little-endian.
234 *
235 * Returns: @val converted to little-endian byte order.
236 */
237
238 /**
239 * GLONG_FROM_BE:
240 * @val: a #glong value in big-endian byte order
241 *
242 * Converts a #glong value from big-endian to the host byte order.
243 *
244 * Returns: @val converted to host byte order
245 */
246
247 /**
248 * GLONG_FROM_LE:
249 * @val: a #glong value in little-endian byte order
250 *
251 * Converts a #glong value from little-endian to host byte order.
252 *
253 * Returns: @val converted to host byte order
254 */
255
256 /**
257 * GLONG_TO_BE:
258 * @val: a #glong value in host byte order
259 *
260 * Converts a #glong value from host byte order to big-endian.
261 *
262 * Returns: @val converted to big-endian byte order
263 */
264
265 /**
266 * GLONG_TO_LE:
267 * @val: a #glong value in host byte order
268 *
269 * Converts a #glong value from host byte order to little-endian.
270 *
271 * Returns: @val converted to little-endian
272 */
273
274 /**
275 * GULONG_FROM_BE:
276 * @val: a #gulong value in big-endian byte order
277 *
278 * Converts a #gulong value from big-endian to host byte order.
279 *
280 * Returns: @val converted to host byte order
281 */
282
283 /**
284 * GULONG_FROM_LE:
285 * @val: a #gulong value in little-endian byte order
286 *
287 * Converts a #gulong value from little-endian to host byte order.
288 *
289 * Returns: @val converted to host byte order
290 */
291
292 /**
293 * GULONG_TO_BE:
294 * @val: a #gulong value in host byte order
295 *
296 * Converts a #gulong value from host byte order to big-endian.
297 *
298 * Returns: @val converted to big-endian
299 */
300
301 /**
302 * GULONG_TO_LE:
303 * @val: a #gulong value in host byte order
304 *
305 * Converts a #gulong value from host byte order to little-endian.
306 *
307 * Returns: @val converted to little-endian
308 */
309
310 /**
311 * GSIZE_FROM_BE:
312 * @val: a #gsize value in big-endian byte order
313 *
314 * Converts a #gsize value from big-endian to the host byte order.
315 *
316 * Returns: @val converted to host byte order
317 */
318
319 /**
320 * GSIZE_FROM_LE:
321 * @val: a #gsize value in little-endian byte order
322 *
323 * Converts a #gsize value from little-endian to host byte order.
324 *
325 * Returns: @val converted to host byte order
326 */
327
328 /**
329 * GSIZE_TO_BE:
330 * @val: a #gsize value in host byte order
331 *
332 * Converts a #gsize value from host byte order to big-endian.
333 *
334 * Returns: @val converted to big-endian byte order
335 */
336
337 /**
338 * GSIZE_TO_LE:
339 * @val: a #gsize value in host byte order
340 *
341 * Converts a #gsize value from host byte order to little-endian.
342 *
343 * Returns: @val converted to little-endian
344 */
345
346 /**
347 * GSSIZE_FROM_BE:
348 * @val: a #gssize value in big-endian byte order
349 *
350 * Converts a #gssize value from big-endian to host byte order.
351 *
352 * Returns: @val converted to host byte order
353 */
354
355 /**
356 * GSSIZE_FROM_LE:
357 * @val: a #gssize value in little-endian byte order
358 *
359 * Converts a #gssize value from little-endian to host byte order.
360 *
361 * Returns: @val converted to host byte order
362 */
363
364 /**
365 * GSSIZE_TO_BE:
366 * @val: a #gssize value in host byte order
367 *
368 * Converts a #gssize value from host byte order to big-endian.
369 *
370 * Returns: @val converted to big-endian
371 */
372
373 /**
374 * GSSIZE_TO_LE:
375 * @val: a #gssize value in host byte order
376 *
377 * Converts a #gssize value from host byte order to little-endian.
378 *
379 * Returns: @val converted to little-endian
380 */
381
382 /**
383 * GINT16_FROM_BE:
384 * @val: a #gint16 value in big-endian byte order
385 *
386 * Converts a #gint16 value from big-endian to host byte order.
387 *
388 * Returns: @val converted to host byte order
389 */
390
391 /**
392 * GINT16_FROM_LE:
393 * @val: a #gint16 value in little-endian byte order
394 *
395 * Converts a #gint16 value from little-endian to host byte order.
396 *
397 * Returns: @val converted to host byte order
398 */
399
400 /**
401 * GINT16_TO_BE:
402 * @val: a #gint16 value in host byte order
403 *
404 * Converts a #gint16 value from host byte order to big-endian.
405 *
406 * Returns: @val converted to big-endian
407 */
408
409 /**
410 * GINT16_TO_LE:
411 * @val: a #gint16 value in host byte order
412 *
413 * Converts a #gint16 value from host byte order to little-endian.
414 *
415 * Returns: @val converted to little-endian
416 */
417
418 /**
419 * GUINT16_FROM_BE:
420 * @val: a #guint16 value in big-endian byte order
421 *
422 * Converts a #guint16 value from big-endian to host byte order.
423 *
424 * Returns: @val converted to host byte order
425 */
426
427 /**
428 * GUINT16_FROM_LE:
429 * @val: a #guint16 value in little-endian byte order
430 *
431 * Converts a #guint16 value from little-endian to host byte order.
432 *
433 * Returns: @val converted to host byte order
434 */
435
436 /**
437 * GUINT16_TO_BE:
438 * @val: a #guint16 value in host byte order
439 *
440 * Converts a #guint16 value from host byte order to big-endian.
441 *
442 * Returns: @val converted to big-endian
443 */
444
445 /**
446 * GUINT16_TO_LE:
447 * @val: a #guint16 value in host byte order
448 *
449 * Converts a #guint16 value from host byte order to little-endian.
450 *
451 * Returns: @val converted to little-endian
452 */
453
454 /**
455 * GINT32_FROM_BE:
456 * @val: a #gint32 value in big-endian byte order
457 *
458 * Converts a #gint32 value from big-endian to host byte order.
459 *
460 * Returns: @val converted to host byte order
461 */
462
463 /**
464 * GINT32_FROM_LE:
465 * @val: a #gint32 value in little-endian byte order
466 *
467 * Converts a #gint32 value from little-endian to host byte order.
468 *
469 * Returns: @val converted to host byte order
470 */
471
472 /**
473 * GINT32_TO_BE:
474 * @val: a #gint32 value in host byte order
475 *
476 * Converts a #gint32 value from host byte order to big-endian.
477 *
478 * Returns: @val converted to big-endian
479 */
480
481 /**
482 * GINT32_TO_LE:
483 * @val: a #gint32 value in host byte order
484 *
485 * Converts a #gint32 value from host byte order to little-endian.
486 *
487 * Returns: @val converted to little-endian
488 */
489
490 /**
491 * GUINT32_FROM_BE:
492 * @val: a #guint32 value in big-endian byte order
493 *
494 * Converts a #guint32 value from big-endian to host byte order.
495 *
496 * Returns: @val converted to host byte order
497 */
498
499 /**
500 * GUINT32_FROM_LE:
501 * @val: a #guint32 value in little-endian byte order
502 *
503 * Converts a #guint32 value from little-endian to host byte order.
504 *
505 * Returns: @val converted to host byte order
506 */
507
508 /**
509 * GUINT32_TO_BE:
510 * @val: a #guint32 value in host byte order
511 *
512 * Converts a #guint32 value from host byte order to big-endian.
513 *
514 * Returns: @val converted to big-endian
515 */
516
517 /**
518 * GUINT32_TO_LE:
519 * @val: a #guint32 value in host byte order
520 *
521 * Converts a #guint32 value from host byte order to little-endian.
522 *
523 * Returns: @val converted to little-endian
524 */
525
526 /**
527 * GINT64_FROM_BE:
528 * @val: a #gint64 value in big-endian byte order
529 *
530 * Converts a #gint64 value from big-endian to host byte order.
531 *
532 * Returns: @val converted to host byte order
533 */
534
535 /**
536 * GINT64_FROM_LE:
537 * @val: a #gint64 value in little-endian byte order
538 *
539 * Converts a #gint64 value from little-endian to host byte order.
540 *
541 * Returns: @val converted to host byte order
542 */
543
544 /**
545 * GINT64_TO_BE:
546 * @val: a #gint64 value in host byte order
547 *
548 * Converts a #gint64 value from host byte order to big-endian.
549 *
550 * Returns: @val converted to big-endian
551 */
552
553 /**
554 * GINT64_TO_LE:
555 * @val: a #gint64 value in host byte order
556 *
557 * Converts a #gint64 value from host byte order to little-endian.
558 *
559 * Returns: @val converted to little-endian
560 */
561
562 /**
563 * GUINT64_FROM_BE:
564 * @val: a #guint64 value in big-endian byte order
565 *
566 * Converts a #guint64 value from big-endian to host byte order.
567 *
568 * Returns: @val converted to host byte order
569 */
570
571 /**
572 * GUINT64_FROM_LE:
573 * @val: a #guint64 value in little-endian byte order
574 *
575 * Converts a #guint64 value from little-endian to host byte order.
576 *
577 * Returns: @val converted to host byte order
578 */
579
580 /**
581 * GUINT64_TO_BE:
582 * @val: a #guint64 value in host byte order
583 *
584 * Converts a #guint64 value from host byte order to big-endian.
585 *
586 * Returns: @val converted to big-endian
587 */
588
589 /**
590 * GUINT64_TO_LE:
591 * @val: a #guint64 value in host byte order
592 *
593 * Converts a #guint64 value from host byte order to little-endian.
594 *
595 * Returns: @val converted to little-endian
596 */
597
598 /**
599 * GUINT16_SWAP_BE_PDP:
600 * @val: a #guint16 value in big-endian or pdp-endian byte order
601 *
602 * Converts a #guint16 value between big-endian and pdp-endian byte order.
603 * The conversion is symmetric so it can be used both ways.
604 *
605 * Returns: @val converted to the opposite byte order
606 */
607
608 /**
609 * GUINT16_SWAP_LE_BE:
610 * @val: a #guint16 value in little-endian or big-endian byte order
611 *
612 * Converts a #guint16 value between little-endian and big-endian byte order.
613 * The conversion is symmetric so it can be used both ways.
614 *
615 * Returns: @val converted to the opposite byte order
616 */
617
618 /**
619 * GUINT16_SWAP_LE_PDP:
620 * @val: a #guint16 value in little-endian or pdp-endian byte order
621 *
622 * Converts a #guint16 value between little-endian and pdp-endian byte order.
623 * The conversion is symmetric so it can be used both ways.
624 *
625 * Returns: @val converted to the opposite byte order
626 */
627
628 /**
629 * GUINT32_SWAP_BE_PDP:
630 * @val: a #guint32 value in big-endian or pdp-endian byte order
631 *
632 * Converts a #guint32 value between big-endian and pdp-endian byte order.
633 * The conversion is symmetric so it can be used both ways.
634 *
635 * Returns: @val converted to the opposite byte order
636 */
637
638 /**
639 * GUINT32_SWAP_LE_BE:
640 * @val: a #guint32 value in little-endian or big-endian byte order
641 *
642 * Converts a #guint32 value between little-endian and big-endian byte order.
643 * The conversion is symmetric so it can be used both ways.
644 *
645 * Returns: @val converted to the opposite byte order
646 */
647
648 /**
649 * GUINT32_SWAP_LE_PDP:
650 * @val: a #guint32 value in little-endian or pdp-endian byte order
651 *
652 * Converts a #guint32 value between little-endian and pdp-endian byte order.
653 * The conversion is symmetric so it can be used both ways.
654 *
655 * Returns: @val converted to the opposite byte order
656 */
657
658 /**
659 * GUINT64_SWAP_LE_BE:
660 * @val: a #guint64 value in little-endian or big-endian byte order
661 *
662 * Converts a #guint64 value between little-endian and big-endian byte order.
663 * The conversion is symmetric so it can be used both ways.
664 *
665 * Returns: @val converted to the opposite byte order
666 */
667
668 /* Bounds-checked integer arithmetic {{{1 */
669
670 /**
671 * g_uint_checked_add
672 * @dest: a pointer to the #guint destination
673 * @a: the #guint left operand
674 * @b: the #guint right operand
675 *
676 * Performs a checked addition of @a and @b, storing the result in
677 * @dest.
678 *
679 * If the operation is successful, %TRUE is returned. If the operation
680 * overflows then the state of @dest is undefined and %FALSE is
681 * returned.
682 *
683 * Returns: %TRUE if there was no overflow
684 * Since: 2.48
685 */
686
687 /**
688 * g_uint_checked_mul
689 * @dest: a pointer to the #guint destination
690 * @a: the #guint left operand
691 * @b: the #guint right operand
692 *
693 * Performs a checked multiplication of @a and @b, storing the result in
694 * @dest.
695 *
696 * If the operation is successful, %TRUE is returned. If the operation
697 * overflows then the state of @dest is undefined and %FALSE is
698 * returned.
699 *
700 * Returns: %TRUE if there was no overflow
701 * Since: 2.48
702 */
703
704 /**
705 * g_uint64_checked_add
706 * @dest: a pointer to the #guint64 destination
707 * @a: the #guint64 left operand
708 * @b: the #guint64 right operand
709 *
710 * Performs a checked addition of @a and @b, storing the result in
711 * @dest.
712 *
713 * If the operation is successful, %TRUE is returned. If the operation
714 * overflows then the state of @dest is undefined and %FALSE is
715 * returned.
716 *
717 * Returns: %TRUE if there was no overflow
718 * Since: 2.48
719 */
720
721 /**
722 * g_uint64_checked_mul
723 * @dest: a pointer to the #guint64 destination
724 * @a: the #guint64 left operand
725 * @b: the #guint64 right operand
726 *
727 * Performs a checked multiplication of @a and @b, storing the result in
728 * @dest.
729 *
730 * If the operation is successful, %TRUE is returned. If the operation
731 * overflows then the state of @dest is undefined and %FALSE is
732 * returned.
733 *
734 * Returns: %TRUE if there was no overflow
735 * Since: 2.48
736 */
737
738 /**
739 * g_size_checked_add
740 * @dest: a pointer to the #gsize destination
741 * @a: the #gsize left operand
742 * @b: the #gsize right operand
743 *
744 * Performs a checked addition of @a and @b, storing the result in
745 * @dest.
746 *
747 * If the operation is successful, %TRUE is returned. If the operation
748 * overflows then the state of @dest is undefined and %FALSE is
749 * returned.
750 *
751 * Returns: %TRUE if there was no overflow
752 * Since: 2.48
753 */
754
755 /**
756 * g_size_checked_mul
757 * @dest: a pointer to the #gsize destination
758 * @a: the #gsize left operand
759 * @b: the #gsize right operand
760 *
761 * Performs a checked multiplication of @a and @b, storing the result in
762 * @dest.
763 *
764 * If the operation is successful, %TRUE is returned. If the operation
765 * overflows then the state of @dest is undefined and %FALSE is
766 * returned.
767 *
768 * Returns: %TRUE if there was no overflow
769 * Since: 2.48
770 */
771 /* Numerical Definitions {{{1 */
772
773 /**
774 * G_IEEE754_FLOAT_BIAS:
775 *
776 * The bias by which exponents in single-precision floats are offset.
777 */
778
779 /**
780 * G_IEEE754_DOUBLE_BIAS:
781 *
782 * The bias by which exponents in double-precision floats are offset.
783 */
784
785 /**
786 * GFloatIEEE754:
787 * @v_float: the double value
788 *
789 * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
790 * mantissa and exponent of IEEE floats and doubles. These unions are defined
791 * as appropriate for a given platform. IEEE floats and doubles are supported
792 * (used for storage) by at least Intel, PPC and Sparc.
793 */
794
795 /**
796 * GDoubleIEEE754:
797 * @v_double: the double value
798 *
799 * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
800 * mantissa and exponent of IEEE floats and doubles. These unions are defined
801 * as appropriate for a given platform. IEEE floats and doubles are supported
802 * (used for storage) by at least Intel, PPC and Sparc.
803 */
804
805 /**
806 * G_E:
807 *
808 * The base of natural logarithms.
809 */
810
811 /**
812 * G_LN2:
813 *
814 * The natural logarithm of 2.
815 */
816
817 /**
818 * G_LN10:
819 *
820 * The natural logarithm of 10.
821 */
822
823 /**
824 * G_PI:
825 *
826 * The value of pi (ratio of circle's circumference to its diameter).
827 */
828
829 /**
830 * G_PI_2:
831 *
832 * Pi divided by 2.
833 */
834
835 /**
836 * G_PI_4:
837 *
838 * Pi divided by 4.
839 */
840
841 /**
842 * G_SQRT2:
843 *
844 * The square root of two.
845 */
846
847 /**
848 * G_LOG_2_BASE_10:
849 *
850 * Multiplying the base 2 exponent by this number yields the base 10 exponent.
851 */
852
853 /* Macros {{{1 */
854
855 /**
856 * G_OS_WIN32:
857 *
858 * This macro is defined only on Windows. So you can bracket
859 * Windows-specific code in "\#ifdef G_OS_WIN32".
860 */
861
862 /**
863 * G_OS_UNIX:
864 *
865 * This macro is defined only on UNIX. So you can bracket
866 * UNIX-specific code in "\#ifdef G_OS_UNIX".
867 *
868 * To detect whether to compile features that require a specific kernel
869 * or operating system, check for the appropriate OS-specific predefined
870 * macros instead, for example:
871 *
872 * - Linux kernel (any libc, including glibc, musl or Android): `\#ifdef __linux__`
873 * - Linux kernel and GNU user-space: `\#if defined(__linux__) && defined(__GLIBC__)`
874 * - FreeBSD kernel (any libc, including glibc): `\#ifdef __FreeBSD_kernel__`
875 * - FreeBSD kernel and user-space: `\#ifdef __FreeBSD__`
876 * - Apple operating systems (macOS, iOS, tvOS), regardless of whether
877 * Cocoa/Carbon toolkits are available: `\#ifdef __APPLE__`
878 *
879 * See <https://sourceforge.net/p/predef/wiki/OperatingSystems/> for more.
880 */
881
882 /**
883 * G_DIR_SEPARATOR:
884 *
885 * The directory separator character.
886 * This is '/' on UNIX machines and '\' under Windows.
887 */
888
889 /**
890 * G_DIR_SEPARATOR_S:
891 *
892 * The directory separator as a string.
893 * This is "/" on UNIX machines and "\" under Windows.
894 */
895
896 /**
897 * G_IS_DIR_SEPARATOR:
898 * @c: a character
899 *
900 * Checks whether a character is a directory
901 * separator. It returns %TRUE for '/' on UNIX
902 * machines and for '\' or '/' under Windows.
903 *
904 * Since: 2.6
905 */
906
907 /**
908 * G_SEARCHPATH_SEPARATOR:
909 *
910 * The search path separator character.
911 * This is ':' on UNIX machines and ';' under Windows.
912 */
913
914 /**
915 * G_SEARCHPATH_SEPARATOR_S:
916 *
917 * The search path separator as a string.
918 * This is ":" on UNIX machines and ";" under Windows.
919 */
920
921 /**
922 * TRUE:
923 *
924 * Defines the %TRUE value for the #gboolean type.
925 */
926
927 /**
928 * FALSE:
929 *
930 * Defines the %FALSE value for the #gboolean type.
931 */
932
933 /**
934 * NULL:
935 *
936 * Defines the standard %NULL pointer.
937 */
938
939 /**
940 * MIN:
941 * @a: a numeric value
942 * @b: a numeric value
943 *
944 * Calculates the minimum of @a and @b.
945 *
946 * Returns: the minimum of @a and @b.
947 */
948
949 /**
950 * MAX:
951 * @a: a numeric value
952 * @b: a numeric value
953 *
954 * Calculates the maximum of @a and @b.
955 *
956 * Returns: the maximum of @a and @b.
957 */
958
959 /**
960 * ABS:
961 * @a: a numeric value
962 *
963 * Calculates the absolute value of @a.
964 * The absolute value is simply the number with any negative sign taken away.
965 *
966 * For example,
967 * - ABS(-10) is 10.
968 * - ABS(10) is also 10.
969 *
970 * Returns: the absolute value of @a.
971 */
972
973 /**
974 * CLAMP:
975 * @x: the value to clamp
976 * @low: the minimum value allowed
977 * @high: the maximum value allowed
978 *
979 * Ensures that @x is between the limits set by @low and @high. If @low is
980 * greater than @high the result is undefined.
981 *
982 * For example,
983 * - CLAMP(5, 10, 15) is 10.
984 * - CLAMP(15, 5, 10) is 10.
985 * - CLAMP(20, 15, 25) is 20.
986 *
987 * Returns: the value of @x clamped to the range between @low and @high
988 */
989
990 /**
991 * G_APPROX_VALUE:
992 * @a: a numeric value
993 * @b: a numeric value
994 * @epsilon: a numeric value that expresses the tolerance between @a and @b
995 *
996 * Evaluates to a truth value if the absolute difference between @a and @b is
997 * smaller than @epsilon, and to a false value otherwise.
998 *
999 * For example,
1000 * - `G_APPROX_VALUE (5, 6, 2)` evaluates to true
1001 * - `G_APPROX_VALUE (3.14, 3.15, 0.001)` evaluates to false
1002 * - `G_APPROX_VALUE (n, 0.f, FLT_EPSILON)` evaluates to true if `n` is within
1003 * the single precision floating point epsilon from zero
1004 *
1005 * Returns: %TRUE if the two values are within the desired range
1006 *
1007 * Since: 2.58
1008 */
1009
1010 /**
1011 * G_STRUCT_MEMBER:
1012 * @member_type: the type of the struct field
1013 * @struct_p: a pointer to a struct
1014 * @struct_offset: the offset of the field from the start of the struct,
1015 * in bytes
1016 *
1017 * Returns a member of a structure at a given offset, using the given type.
1018 *
1019 * Returns: the struct member
1020 */
1021
1022 /**
1023 * G_STRUCT_MEMBER_P:
1024 * @struct_p: a pointer to a struct
1025 * @struct_offset: the offset from the start of the struct, in bytes
1026 *
1027 * Returns an untyped pointer to a given offset of a struct.
1028 *
1029 * Returns: an untyped pointer to @struct_p plus @struct_offset bytes
1030 */
1031
1032 /**
1033 * G_STRUCT_OFFSET:
1034 * @struct_type: a structure type, e.g. #GtkWidget
1035 * @member: a field in the structure, e.g. @window
1036 *
1037 * Returns the offset, in bytes, of a member of a struct.
1038 *
1039 * Consider using standard C `offsetof()`, available since at least C89
1040 * and C++98, in new code (but note that `offsetof()` returns a `size_t`
1041 * rather than a `long`).
1042 *
1043 * Returns: the offset of @member from the start of @struct_type,
1044 * as a value of type #glong.
1045 */
1046
1047 /**
1048 * G_N_ELEMENTS:
1049 * @arr: the array
1050 *
1051 * Determines the number of elements in an array. The array must be
1052 * declared so the compiler knows its size at compile-time; this
1053 * macro will not work on an array allocated on the heap, only static
1054 * arrays or arrays on the stack.
1055 */
1056
1057 /* Miscellaneous Macros {{{1 */
1058
1059 /**
1060 * G_STMT_START:
1061 *
1062 * Used within multi-statement macros so that they can be used in places
1063 * where only one statement is expected by the compiler.
1064 */
1065
1066 /**
1067 * G_STMT_END:
1068 *
1069 * Used within multi-statement macros so that they can be used in places
1070 * where only one statement is expected by the compiler.
1071 */
1072
1073 /**
1074 * G_BEGIN_DECLS:
1075 *
1076 * Used (along with %G_END_DECLS) to bracket header files. If the
1077 * compiler in use is a C++ compiler, adds extern "C"
1078 * around the header.
1079 */
1080
1081 /**
1082 * G_END_DECLS:
1083 *
1084 * Used (along with %G_BEGIN_DECLS) to bracket header files. If the
1085 * compiler in use is a C++ compiler, adds extern "C"
1086 * around the header.
1087 */
1088
1089 /**
1090 * G_VA_COPY:
1091 * @ap1: the va_list variable to place a copy of @ap2 in
1092 * @ap2: a va_list
1093 *
1094 * Portable way to copy va_list variables.
1095 *
1096 * In order to use this function, you must include string.h yourself,
1097 * because this macro may use memmove() and GLib does not include
1098 * string.h for you.
1099 *
1100 * Each invocation of `G_VA_COPY (ap1, ap2)` must be matched with a
1101 * corresponding `va_end (ap1)` call in the same function.
1102 *
1103 * This is equivalent to standard C `va_copy()`, available since C99
1104 * and C++11, which should be preferred in new code.
1105 */
1106
1107 /**
1108 * G_STRINGIFY:
1109 * @macro_or_string: a macro or a string
1110 *
1111 * Accepts a macro or a string and converts it into a string after
1112 * preprocessor argument expansion. For example, the following code:
1113 *
1114 * |[<!-- language="C" -->
1115 * #define AGE 27
1116 * const gchar *greeting = G_STRINGIFY (AGE) " today!";
1117 * ]|
1118 *
1119 * is transformed by the preprocessor into (code equivalent to):
1120 *
1121 * |[<!-- language="C" -->
1122 * const gchar *greeting = "27 today!";
1123 * ]|
1124 */
1125
1126 /**
1127 * G_PASTE:
1128 * @identifier1: an identifier
1129 * @identifier2: an identifier
1130 *
1131 * Yields a new preprocessor pasted identifier
1132 * @identifier1identifier2 from its expanded
1133 * arguments @identifier1 and @identifier2. For example,
1134 * the following code:
1135 * |[<!-- language="C" -->
1136 * #define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller)
1137 * const gchar *name = GET (traveller, name);
1138 * const gchar *quest = GET (traveller, quest);
1139 * GdkColor *favourite = GET (traveller, favourite_colour);
1140 * ]|
1141 *
1142 * is transformed by the preprocessor into:
1143 * |[<!-- language="C" -->
1144 * const gchar *name = traveller_get_name (traveller);
1145 * const gchar *quest = traveller_get_quest (traveller);
1146 * GdkColor *favourite = traveller_get_favourite_colour (traveller);
1147 * ]|
1148 *
1149 * Since: 2.20
1150 */
1151
1152 /**
1153 * G_STATIC_ASSERT:
1154 * @expr: a constant expression
1155 *
1156 * The G_STATIC_ASSERT() macro lets the programmer check
1157 * a condition at compile time, the condition needs to
1158 * be compile time computable. The macro can be used in
1159 * any place where a typedef is valid.
1160 *
1161 * A typedef is generally allowed in exactly the same places that
1162 * a variable declaration is allowed. For this reason, you should
1163 * not use G_STATIC_ASSERT() in the middle of blocks of code.
1164 *
1165 * The macro should only be used once per source code line.
1166 *
1167 * Since: 2.20
1168 */
1169
1170 /**
1171 * G_STATIC_ASSERT_EXPR:
1172 * @expr: a constant expression
1173 *
1174 * The G_STATIC_ASSERT_EXPR() macro lets the programmer check
1175 * a condition at compile time. The condition needs to be
1176 * compile time computable.
1177 *
1178 * Unlike G_STATIC_ASSERT(), this macro evaluates to an expression
1179 * and, as such, can be used in the middle of other expressions.
1180 * Its value should be ignored. This can be accomplished by placing
1181 * it as the first argument of a comma expression.
1182 *
1183 * |[<!-- language="C" -->
1184 * #define ADD_ONE_TO_INT(x) \
1185 * (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1))
1186 * ]|
1187 *
1188 * Since: 2.30
1189 */
1190
1191 /**
1192 * G_GNUC_EXTENSION:
1193 *
1194 * Expands to __extension__ when gcc is used as the compiler. This simply
1195 * tells gcc not to warn about the following non-standard code when compiling
1196 * with the `-pedantic` option.
1197 */
1198
1199 /**
1200 * G_GNUC_CHECK_VERSION:
1201 * @major: major version to check against
1202 * @minor: minor version to check against
1203 *
1204 * Expands to a check for a compiler with __GNUC__ defined and a version
1205 * greater than or equal to the major and minor numbers provided. For example,
1206 * the following would only match on compilers such as GCC 4.8 or newer.
1207 *
1208 * |[<!-- language="C" -->
1209 * #if G_GNUC_CHECK_VERSION(4, 8)
1210 * #endif
1211 * ]|
1212 *
1213 * Since: 2.42
1214 */
1215
1216 /**
1217 * G_GNUC_BEGIN_IGNORE_DEPRECATIONS:
1218 *
1219 * Tells gcc (if it is a new enough version) to temporarily stop emitting
1220 * warnings when functions marked with %G_GNUC_DEPRECATED or
1221 * %G_GNUC_DEPRECATED_FOR are called. This is useful for when you have
1222 * one deprecated function calling another one, or when you still have
1223 * regression tests for deprecated functions.
1224 *
1225 * Use %G_GNUC_END_IGNORE_DEPRECATIONS to begin warning again. (If you
1226 * are not compiling with `-Wdeprecated-declarations` then neither macro
1227 * has any effect.)
1228 *
1229 * This macro can be used either inside or outside of a function body,
1230 * but must appear on a line by itself. Both this macro and the corresponding
1231 * %G_GNUC_END_IGNORE_DEPRECATIONS are considered statements, so they
1232 * should not be used around branching or loop conditions; for instance,
1233 * this use is invalid:
1234 *
1235 * |[<!-- language="C" -->
1236 * G_GNUC_BEGIN_IGNORE_DEPRECATIONS
1237 * if (check == some_deprecated_function ())
1238 * G_GNUC_END_IGNORE_DEPRECATIONS
1239 * {
1240 * do_something ();
1241 * }
1242 * ]|
1243 *
1244 * and you should move the deprecated section outside the condition
1245 *
1246 * |[<!-- language="C" -->
1247 *
1248 * // Solution A
1249 * some_data_t *res;
1250 *
1251 * G_GNUC_BEGIN_IGNORE_DEPRECATIONS
1252 * res = some_deprecated_function ();
1253 * G_GNUC_END_IGNORE_DEPRECATIONS
1254 *
1255 * if (check == res)
1256 * {
1257 * do_something ();
1258 * }
1259 *
1260 * // Solution B
1261 * G_GNUC_BEGIN_IGNORE_DEPRECATIONS
1262 * if (check == some_deprecated_function ())
1263 * {
1264 * do_something ();
1265 * }
1266 * G_GNUC_END_IGNORE_DEPRECATIONS
1267 * ]|
1268 *
1269 * |[<!-- language="C" -->
1270 * static void
1271 * test_deprecated_function (void)
1272 * {
1273 * G_GNUC_BEGIN_IGNORE_DEPRECATIONS
1274 * g_assert_cmpint (my_mistake (), ==, 42);
1275 * G_GNUC_END_IGNORE_DEPRECATIONS
1276 * }
1277 * ]|
1278 *
1279 * Since: 2.32
1280 */
1281
1282 /**
1283 * G_GNUC_END_IGNORE_DEPRECATIONS:
1284 *
1285 * Undoes the effect of %G_GNUC_BEGIN_IGNORE_DEPRECATIONS, telling
1286 * gcc to begin outputting warnings again (assuming those warnings
1287 * had been enabled to begin with).
1288 *
1289 * This macro can be used either inside or outside of a function body,
1290 * but must appear on a line by itself.
1291 *
1292 * Since: 2.32
1293 */
1294
1295 /**
1296 * G_DEPRECATED:
1297 *
1298 * This macro is similar to %G_GNUC_DEPRECATED, and can be used to mark
1299 * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED, it is
1300 * meant to be portable across different compilers and must be placed
1301 * before the function declaration.
1302 *
1303 * |[<!-- language="C" -->
1304 * G_DEPRECATED
1305 * int my_mistake (void);
1306 * ]|
1307 *
1308 * Since: 2.32
1309 */
1310
1311 /**
1312 * G_DEPRECATED_FOR:
1313 * @f: the name of the function that this function was deprecated for
1314 *
1315 * This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark
1316 * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it
1317 * is meant to be portable across different compilers and must be placed
1318 * before the function declaration.
1319 *
1320 * |[<!-- language="C" -->
1321 * G_DEPRECATED_FOR(my_replacement)
1322 * int my_mistake (void);
1323 * ]|
1324 *
1325 * Since: 2.32
1326 */
1327
1328 /**
1329 * G_UNAVAILABLE:
1330 * @maj: the major version that introduced the symbol
1331 * @min: the minor version that introduced the symbol
1332 *
1333 * This macro can be used to mark a function declaration as unavailable.
1334 * It must be placed before the function declaration. Use of a function
1335 * that has been annotated with this macros will produce a compiler warning.
1336 *
1337 * Since: 2.32
1338 */
1339
1340 /**
1341 * GLIB_DISABLE_DEPRECATION_WARNINGS:
1342 *
1343 * A macro that should be defined before including the glib.h header.
1344 * If it is defined, no compiler warnings will be produced for uses
1345 * of deprecated GLib APIs.
1346 */
1347
1348 /**
1349 * G_GNUC_INTERNAL:
1350 *
1351 * This attribute can be used for marking library functions as being used
1352 * internally to the library only, which may allow the compiler to handle
1353 * function calls more efficiently. Note that static functions do not need
1354 * to be marked as internal in this way. See the GNU C documentation for
1355 * details.
1356 *
1357 * When using a compiler that supports the GNU C hidden visibility attribute,
1358 * this macro expands to __attribute__((visibility("hidden"))).
1359 * When using the Sun Studio compiler, it expands to __hidden.
1360 *
1361 * Note that for portability, the attribute should be placed before the
1362 * function declaration. While GCC allows the macro after the declaration,
1363 * Sun Studio does not.
1364 *
1365 * |[<!-- language="C" -->
1366 * G_GNUC_INTERNAL
1367 * void _g_log_fallback_handler (const gchar *log_domain,
1368 * GLogLevelFlags log_level,
1369 * const gchar *message,
1370 * gpointer unused_data);
1371 * ]|
1372 *
1373 * Since: 2.6
1374 */
1375
1376 /**
1377 * G_C_STD_VERSION:
1378 *
1379 * The C standard version the code is compiling against, it's normally
1380 * defined with the same value of `__STDC_VERSION__` for C standard
1381 * compatible compilers, while it uses the lowest standard version
1382 * in pure MSVC, given that in such compiler the definition depends on
1383 * a compilation flag.
1384 *
1385 * This is granted to be undefined when compiling with a C++ compiler.
1386 *
1387 * See also: %G_C_STD_CHECK_VERSION and %G_CXX_STD_VERSION
1388 *
1389 * Since: 2.76
1390 */
1391
1392 /**
1393 * G_C_STD_CHECK_VERSION:
1394 * @version: The C version to be checked for compatibility
1395 *
1396 * Macro to check if the current compiler supports a specified @version
1397 * of the C standard. Such value must be numeric and can be provided both
1398 * in the short form for the well-known versions (e.g. `90`, `99`...) or in
1399 * the complete form otherwise (e.g. `199000L`, `199901L`, `205503L`...).
1400 *
1401 * When a C++ compiler is used, the macro is defined and returns always %FALSE.
1402 *
1403 * This value is compared against %G_C_STD_VERSION.
1404 *
1405 * |[<!-- language="C" -->
1406 * #if G_C_STD_CHECK_VERSION(17)
1407 * #endif
1408 * ]|
1409 *
1410 * See also: %G_CXX_STD_CHECK_VERSION
1411 *
1412 * Returns: %TRUE if @version is supported by the compiler, %FALSE otherwise
1413 *
1414 * Since: 2.76
1415 */
1416
1417 /**
1418 * G_CXX_STD_VERSION:
1419 *
1420 * The C++ standard version the code is compiling against, it's defined
1421 * with the same value of `__cplusplus` for C++ standard compatible
1422 * compilers, while it uses `_MSVC_LANG` in MSVC, given that the
1423 * standard definition depends on a compilation flag in such compiler.
1424 *
1425 * This is granted to be undefined when not compiling with a C++ compiler.
1426 *
1427 * See also: %G_CXX_STD_CHECK_VERSION and %G_C_STD_VERSION
1428 *
1429 * Since: 2.76
1430 */
1431
1432 /**
1433 * G_CXX_STD_CHECK_VERSION:
1434 * @version: The C++ version to be checked for compatibility
1435 *
1436 * Macro to check if the current compiler supports a specified @version
1437 * of the C++ standard. Such value must be numeric and can be provided both
1438 * in the short form for the well-known versions (e.g. `11`, `17`...) or in
1439 * the complete form otherwise (e.g. `201103L`, `201703L`, `205503L`...).
1440 *
1441 * When a C compiler is used, the macro is defined and returns always %FALSE.
1442 *
1443 * This value is compared against %G_CXX_STD_VERSION.
1444 *
1445 * |[<!-- language="C" -->
1446 * #if G_CXX_STD_CHECK_VERSION(20)
1447 * #endif
1448 * ]|
1449 *
1450 * See also: %G_C_STD_CHECK_VERSION
1451 *
1452 * Returns: %TRUE if @version is supported by the compiler, %FALSE otherwise
1453 *
1454 * Since: 2.76
1455 */
1456
1457 /**
1458 * G_LIKELY:
1459 * @expr: the expression
1460 *
1461 * Hints the compiler that the expression is likely to evaluate to
1462 * a true value. The compiler may use this information for optimizations.
1463 *
1464 * |[<!-- language="C" -->
1465 * if (G_LIKELY (random () != 1))
1466 * g_print ("not one");
1467 * ]|
1468 *
1469 * Returns: the value of @expr
1470 *
1471 * Since: 2.2
1472 */
1473
1474 /**
1475 * G_UNLIKELY:
1476 * @expr: the expression
1477 *
1478 * Hints the compiler that the expression is unlikely to evaluate to
1479 * a true value. The compiler may use this information for optimizations.
1480 *
1481 * |[<!-- language="C" -->
1482 * if (G_UNLIKELY (random () == 1))
1483 * g_print ("a random one");
1484 * ]|
1485 *
1486 * Returns: the value of @expr
1487 *
1488 * Since: 2.2
1489 */
1490
1491 /**
1492 * G_STRLOC:
1493 *
1494 * Expands to a string identifying the current code position.
1495 */
1496
1497 /**
1498 * G_STRFUNC:
1499 *
1500 * Expands to a string identifying the current function.
1501 *
1502 * Since: 2.4
1503 */
1504
1505 /**
1506 * G_HAVE_GNUC_VISIBILITY:
1507 *
1508 * Defined to 1 if gcc-style visibility handling is supported.
1509 */
1510
1511 /* g_auto(), g_autoptr() and helpers {{{1 */
1512
1513 /**
1514 * g_auto:
1515 * @TypeName: a supported variable type
1516 *
1517 * Helper to declare a variable with automatic cleanup.
1518 *
1519 * The variable is cleaned up in a way appropriate to its type when the
1520 * variable goes out of scope. The type must support this.
1521 * The way to clean up the type must have been defined using one of the macros
1522 * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC() or G_DEFINE_AUTO_CLEANUP_FREE_FUNC().
1523 *
1524 * This feature is only supported on GCC and clang. This macro is not
1525 * defined on other compilers and should not be used in programs that
1526 * are intended to be portable to those compilers.
1527 *
1528 * This is meant to be used with stack-allocated structures and
1529 * non-pointer types. For the (more commonly used) pointer version, see
1530 * g_autoptr().
1531 *
1532 * This macro can be used to avoid having to do explicit cleanups of
1533 * local variables when exiting functions. It often vastly simplifies
1534 * handling of error conditions, removing the need for various tricks
1535 * such as `goto out` or repeating of cleanup code. It is also helpful
1536 * for non-error cases.
1537 *
1538 * Consider the following example:
1539 *
1540 * |[
1541 * GVariant *
1542 * my_func(void)
1543 * {
1544 * g_auto(GQueue) queue = G_QUEUE_INIT;
1545 * g_auto(GVariantBuilder) builder;
1546 * g_auto(GStrv) strv;
1547 *
1548 * g_variant_builder_init (&builder, G_VARIANT_TYPE_VARDICT);
1549 * strv = g_strsplit("a:b:c", ":", -1);
1550 *
1551 * ...
1552 *
1553 * if (error_condition)
1554 * return NULL;
1555 *
1556 * ...
1557 *
1558 * return g_variant_builder_end (&builder);
1559 * }
1560 * ]|
1561 *
1562 * You must initialize the variable in some way — either by use of an
1563 * initialiser or by ensuring that an `_init` function will be called on
1564 * it unconditionally before it goes out of scope.
1565 *
1566 * Since: 2.44
1567 */
1568
1569 /**
1570 * g_autoptr:
1571 * @TypeName: a supported variable type
1572 *
1573 * Helper to declare a pointer variable with automatic cleanup.
1574 *
1575 * The variable is cleaned up in a way appropriate to its type when the
1576 * variable goes out of scope. The type must support this.
1577 * The way to clean up the type must have been defined using the macro
1578 * G_DEFINE_AUTOPTR_CLEANUP_FUNC().
1579 *
1580 * This feature is only supported on GCC and clang. This macro is not
1581 * defined on other compilers and should not be used in programs that
1582 * are intended to be portable to those compilers.
1583 *
1584 * This is meant to be used to declare pointers to types with cleanup
1585 * functions. The type of the variable is a pointer to @TypeName. You
1586 * must not add your own `*`.
1587 *
1588 * This macro can be used to avoid having to do explicit cleanups of
1589 * local variables when exiting functions. It often vastly simplifies
1590 * handling of error conditions, removing the need for various tricks
1591 * such as `goto out` or repeating of cleanup code. It is also helpful
1592 * for non-error cases.
1593 *
1594 * Consider the following example:
1595 *
1596 * |[
1597 * gboolean
1598 * check_exists(GVariant *dict)
1599 * {
1600 * g_autoptr(GVariant) dirname, basename = NULL;
1601 * g_autofree gchar *path = NULL;
1602 *
1603 * dirname = g_variant_lookup_value (dict, "dirname", G_VARIANT_TYPE_STRING);
1604 *
1605 * if (dirname == NULL)
1606 * return FALSE;
1607 *
1608 * basename = g_variant_lookup_value (dict, "basename", G_VARIANT_TYPE_STRING);
1609 *
1610 * if (basename == NULL)
1611 * return FALSE;
1612 *
1613 * path = g_build_filename (g_variant_get_string (dirname, NULL),
1614 * g_variant_get_string (basename, NULL),
1615 * NULL);
1616 *
1617 * return g_access (path, R_OK) == 0;
1618 * }
1619 * ]|
1620 *
1621 * You must initialise the variable in some way — either by use of an
1622 * initialiser or by ensuring that it is assigned to unconditionally
1623 * before it goes out of scope.
1624 *
1625 * See also g_auto(), g_autofree() and g_steal_pointer().
1626 *
1627 * Since: 2.44
1628 */
1629
1630 /**
1631 * g_autofree:
1632 *
1633 * Macro to add an attribute to pointer variable to ensure automatic
1634 * cleanup using g_free().
1635 *
1636 * This macro differs from g_autoptr() in that it is an attribute supplied
1637 * before the type name, rather than wrapping the type definition. Instead
1638 * of using a type-specific lookup, this macro always calls g_free() directly.
1639 *
1640 * This means it's useful for any type that is returned from
1641 * g_malloc().
1642 *
1643 * Otherwise, this macro has similar constraints as g_autoptr(): only
1644 * supported on GCC and clang, the variable must be initialized, etc.
1645 *
1646 * |[
1647 * gboolean
1648 * operate_on_malloc_buf (void)
1649 * {
1650 * g_autofree guint8* membuf = NULL;
1651 *
1652 * membuf = g_malloc (8192);
1653 *
1654 * // Some computation on membuf
1655 *
1656 * // membuf will be automatically freed here
1657 * return TRUE;
1658 * }
1659 * ]|
1660 *
1661 * Since: 2.44
1662 */
1663
1664 /**
1665 * g_autolist:
1666 * @TypeName: a supported variable type
1667 *
1668 * Helper to declare a list variable with automatic deep cleanup.
1669 *
1670 * The list is deeply freed, in a way appropriate to the specified type, when the
1671 * variable goes out of scope. The type must support this.
1672 *
1673 * This feature is only supported on GCC and clang. This macro is not
1674 * defined on other compilers and should not be used in programs that
1675 * are intended to be portable to those compilers.
1676 *
1677 * This is meant to be used to declare lists of a type with a cleanup
1678 * function. The type of the variable is a `GList *`. You
1679 * must not add your own `*`.
1680 *
1681 * This macro can be used to avoid having to do explicit cleanups of
1682 * local variables when exiting functions. It often vastly simplifies
1683 * handling of error conditions, removing the need for various tricks
1684 * such as `goto out` or repeating of cleanup code. It is also helpful
1685 * for non-error cases.
1686 *
1687 * See also g_autoslist(), g_autoptr() and g_steal_pointer().
1688 *
1689 * Since: 2.56
1690 */
1691
1692 /**
1693 * g_autoslist:
1694 * @TypeName: a supported variable type
1695 *
1696 * Helper to declare a singly linked list variable with automatic deep cleanup.
1697 *
1698 * The list is deeply freed, in a way appropriate to the specified type, when the
1699 * variable goes out of scope. The type must support this.
1700 *
1701 * This feature is only supported on GCC and clang. This macro is not
1702 * defined on other compilers and should not be used in programs that
1703 * are intended to be portable to those compilers.
1704 *
1705 * This is meant to be used to declare lists of a type with a cleanup
1706 * function. The type of the variable is a `GSList *`. You
1707 * must not add your own `*`.
1708 *
1709 * This macro can be used to avoid having to do explicit cleanups of
1710 * local variables when exiting functions. It often vastly simplifies
1711 * handling of error conditions, removing the need for various tricks
1712 * such as `goto out` or repeating of cleanup code. It is also helpful
1713 * for non-error cases.
1714 *
1715 * See also g_autolist(), g_autoptr() and g_steal_pointer().
1716 *
1717 * Since: 2.56
1718 */
1719
1720 /**
1721 * g_autoqueue:
1722 * @TypeName: a supported variable type
1723 *
1724 * Helper to declare a double-ended queue variable with automatic deep cleanup.
1725 *
1726 * The queue is deeply freed, in a way appropriate to the specified type, when the
1727 * variable goes out of scope. The type must support this.
1728 *
1729 * This feature is only supported on GCC and clang. This macro is not
1730 * defined on other compilers and should not be used in programs that
1731 * are intended to be portable to those compilers.
1732 *
1733 * This is meant to be used to declare queues of a type with a cleanup
1734 * function. The type of the variable is a `GQueue *`. You
1735 * must not add your own `*`.
1736 *
1737 * This macro can be used to avoid having to do explicit cleanups of
1738 * local variables when exiting functions. It often vastly simplifies
1739 * handling of error conditions, removing the need for various tricks
1740 * such as `goto out` or repeating of cleanup code. It is also helpful
1741 * for non-error cases.
1742 *
1743 * See also g_autolist(), g_autoptr() and g_steal_pointer().
1744 *
1745 * Since: 2.62
1746 */
1747
1748
1749 /**
1750 * G_DEFINE_AUTOPTR_CLEANUP_FUNC:
1751 * @TypeName: a type name to define a g_autoptr() cleanup function for
1752 * @func: the cleanup function
1753 *
1754 * Defines the appropriate cleanup function for a pointer type.
1755 *
1756 * The function will not be called if the variable to be cleaned up
1757 * contains %NULL.
1758 *
1759 * This will typically be the `_free()` or `_unref()` function for the given
1760 * type.
1761 *
1762 * With this definition, it will be possible to use g_autoptr() with
1763 * @TypeName.
1764 *
1765 * |[
1766 * G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref)
1767 * ]|
1768 *
1769 * This macro should be used unconditionally; it is a no-op on compilers
1770 * where cleanup is not supported.
1771 *
1772 * Since: 2.44
1773 */
1774
1775 /**
1776 * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC:
1777 * @TypeName: a type name to define a g_auto() cleanup function for
1778 * @func: the clear function
1779 *
1780 * Defines the appropriate cleanup function for a type.
1781 *
1782 * This will typically be the `_clear()` function for the given type.
1783 *
1784 * With this definition, it will be possible to use g_auto() with
1785 * @TypeName.
1786 *
1787 * |[
1788 * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear)
1789 * ]|
1790 *
1791 * This macro should be used unconditionally; it is a no-op on compilers
1792 * where cleanup is not supported.
1793 *
1794 * Since: 2.44
1795 */
1796
1797 /**
1798 * G_DEFINE_AUTO_CLEANUP_FREE_FUNC:
1799 * @TypeName: a type name to define a g_auto() cleanup function for
1800 * @func: the free function
1801 * @none: the "none" value for the type
1802 *
1803 * Defines the appropriate cleanup function for a type.
1804 *
1805 * With this definition, it will be possible to use g_auto() with
1806 * @TypeName.
1807 *
1808 * This function will be rarely used. It is used with pointer-based
1809 * typedefs and non-pointer types where the value of the variable
1810 * represents a resource that must be freed. Two examples are #GStrv
1811 * and file descriptors.
1812 *
1813 * @none specifies the "none" value for the type in question. It is
1814 * probably something like %NULL or `-1`. If the variable is found to
1815 * contain this value then the free function will not be called.
1816 *
1817 * |[
1818 * G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL)
1819 * ]|
1820 *
1821 * This macro should be used unconditionally; it is a no-op on compilers
1822 * where cleanup is not supported.
1823 *
1824 * Since: 2.44
1825 */
1826
1827 /* Windows Compatibility Functions {{{1 */
1828
1829 /**
1830 * MAXPATHLEN:
1831 *
1832 * Provided for UNIX emulation on Windows; equivalent to UNIX
1833 * macro %MAXPATHLEN, which is the maximum length of a filename
1834 * (including full path).
1835 */
1836
1837 /**
1838 * G_WIN32_DLLMAIN_FOR_DLL_NAME:
1839 * @static: empty or "static"
1840 * @dll_name: the name of the (pointer to the) char array where
1841 * the DLL name will be stored. If this is used, you must also
1842 * include `windows.h`. If you need a more complex DLL entry
1843 * point function, you cannot use this
1844 *
1845 * On Windows, this macro defines a DllMain() function that stores
1846 * the actual DLL name that the code being compiled will be included in.
1847 *
1848 * On non-Windows platforms, expands to nothing.
1849 */
1850
1851 /**
1852 * G_WIN32_HAVE_WIDECHAR_API:
1853 *
1854 * On Windows, this macro defines an expression which evaluates to
1855 * %TRUE if the code is running on a version of Windows where the wide
1856 * character versions of the Win32 API functions, and the wide character
1857 * versions of the C library functions work. (They are always present in
1858 * the DLLs, but don't work on Windows 9x and Me.)
1859 *
1860 * On non-Windows platforms, it is not defined.
1861 *
1862 * Since: 2.6
1863 */
1864
1865
1866 /**
1867 * G_WIN32_IS_NT_BASED:
1868 *
1869 * On Windows, this macro defines an expression which evaluates to
1870 * %TRUE if the code is running on an NT-based Windows operating system.
1871 *
1872 * On non-Windows platforms, it is not defined.
1873 *
1874 * Since: 2.6
1875 */
1876
1877 /* Epilogue {{{1 */
1878 /* vim: set foldmethod=marker: */