1 /************************************************************/
2 /* THIS FILE IS GENERATED DO NOT EDIT */
3 /************************************************************/
9 * Calculates the absolute value of @a.
10 * The absolute value is simply the number with any negative sign taken away.
14 * - ABS(10) is also 10.
16 * Returns: the absolute value of @a.
22 * @x: the value to clamp
23 * @low: the minimum value allowed
24 * @high: the maximum value allowed
26 * Ensures that @x is between the limits set by @low and @high. If @low is
27 * greater than @high the result is undefined.
30 * - CLAMP(5, 10, 15) is 10.
31 * - CLAMP(15, 5, 10) is 10.
32 * - CLAMP(20, 15, 25) is 20.
34 * Returns: the value of @x clamped to the range between @low and @high
40 * @Context: a message context, must be a string literal
41 * @String: a message id, must be a string literal
43 * Uses gettext to get the translation for @String. @Context is
44 * used as a context. This is mainly useful for short strings which
45 * may need different translations, depending on the context in which
47 * |[<!-- language="C" -->
48 * label1 = C_("Navigation", "Back");
49 * label2 = C_("Body part", "Back");
52 * If you are using the C_() macro, you need to make sure that you pass
53 * `--keyword=C_:1c,2` to xgettext when extracting messages.
54 * Note that this only works with GNU gettext >= 0.15.
56 * Returns: the translated message
64 * Defines the %FALSE value for the #gboolean type.
70 * @data: a pointer to the element data. The data may be moved as
71 * elements are added to the #GArray.
72 * @len: the number of elements in the #GArray not including the
73 * possible terminating zero element.
75 * Contains the public fields of a GArray.
82 * The GAsyncQueue struct is an opaque data structure which represents
83 * an asynchronous queue. It should only be accessed through the
84 * g_async_queue_* functions.
90 * @data: a pointer to the element data. The data may be moved as
91 * elements are added to the #GByteArray
92 * @len: the number of elements in the #GByteArray
94 * Contains the public fields of a GByteArray.
101 * A simple refcounted data type representing an immutable sequence of zero or
102 * more bytes from an unspecified origin.
104 * The purpose of a #GBytes is to keep the memory region that it holds
105 * alive for as long as anyone holds a reference to the bytes. When
106 * the last reference count is dropped, the memory is released. Multiple
107 * unrelated callers can use byte data in the #GBytes without coordinating
108 * their activities, resting assured that the byte data will not change or
109 * move while they hold a reference.
111 * A #GBytes can come from many different origins that may have
112 * different procedures for freeing the memory region. Examples are
113 * memory from g_malloc(), from memory slices, from a #GMappedFile or
114 * memory from other allocators.
116 * #GBytes work well as keys in #GHashTable. Use g_bytes_equal() and
117 * g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full().
118 * #GBytes can also be used as keys in a #GTree by passing the g_bytes_compare()
119 * function to g_tree_new().
121 * The data pointed to by this bytes must not be modified. For a mutable
122 * array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a
123 * mutable array for a #GBytes sequence. To create an immutable #GBytes from
124 * a mutable #GByteArray, use the g_byte_array_free_to_bytes() function.
133 * @b: a value to compare with
134 * @user_data: user data
136 * Specifies the type of a comparison function used to compare two
137 * values. The function should return a negative integer if the first
138 * value comes before the second, 0 if they are equal, or a positive
139 * integer if the first value comes after the second.
141 * Returns: negative value if @a < @b; zero if @a = @b; positive
149 * @b: a value to compare with
151 * Specifies the type of a comparison function used to compare two
152 * values. The function should return a negative integer if the first
153 * value comes before the second, 0 if they are equal, or a positive
154 * integer if the first value comes after the second.
156 * Returns: negative value if @a < @b; zero if @a = @b; positive
164 * The #GCond struct is an opaque data structure that represents a
165 * condition. Threads can block on a #GCond if they find a certain
166 * condition to be false. If other threads change the state of this
167 * condition they signal the #GCond, and that causes the waiting
168 * threads to be woken up.
170 * Consider the following example of a shared variable. One or more
171 * threads can wait for data to be published to the variable and when
172 * another thread publishes the data, it can signal one of the waiting
173 * threads to wake up to collect the data.
175 * Here is an example for using GCond to block a thread until a condition
177 * |[<!-- language="C" -->
178 * gpointer current_data = NULL;
183 * push_data (gpointer data)
185 * g_mutex_lock (&data_mutex);
186 * current_data = data;
187 * g_cond_signal (&data_cond);
188 * g_mutex_unlock (&data_mutex);
196 * g_mutex_lock (&data_mutex);
197 * while (!current_data)
198 * g_cond_wait (&data_cond, &data_mutex);
199 * data = current_data;
200 * current_data = NULL;
201 * g_mutex_unlock (&data_mutex);
206 * Whenever a thread calls pop_data() now, it will wait until
207 * current_data is non-%NULL, i.e. until some other thread
208 * has called push_data().
210 * The example shows that use of a condition variable must always be
211 * paired with a mutex. Without the use of a mutex, there would be a
212 * race between the check of @current_data by the while loop in
213 * pop_data() and waiting. Specifically, another thread could set
214 * @current_data after the check, and signal the cond (with nobody
215 * waiting on it) before the first thread goes to sleep. #GCond is
216 * specifically useful for its ability to release the mutex and go
217 * to sleep atomically.
219 * It is also important to use the g_cond_wait() and g_cond_wait_until()
220 * functions only inside a loop which checks for the condition to be
221 * true. See g_cond_wait() for an explanation of why the condition may
222 * not be true even after it returns.
224 * If a #GCond is allocated in static storage then it can be used
225 * without initialisation. Otherwise, you should call g_cond_init()
226 * on it and g_cond_clear() when done.
228 * A #GCond should only be accessed via the g_cond_ functions.
235 * The #GData struct is an opaque data structure to represent a
236 * [Keyed Data List][glib-Keyed-Data-Lists]. It should only be
237 * accessed via the following functions.
243 * @key_id: the #GQuark id to identifying the data element.
244 * @data: the data element.
245 * @user_data: user data passed to g_dataset_foreach().
247 * Specifies the type of function passed to g_dataset_foreach(). It is
248 * called with each #GQuark id and associated data element, together
249 * with the @user_data parameter supplied to g_dataset_foreach().
255 * @julian_days: the Julian representation of the date
256 * @julian: this bit is set if @julian_days is valid
257 * @dmy: this is set if @day, @month and @year are valid
258 * @day: the day of the day-month-year representation of the date,
259 * as a number between 1 and 31
260 * @month: the day of the day-month-year representation of the date,
261 * as a number between 1 and 12
262 * @year: the day of the day-month-year representation of the date
264 * Represents a day between January 1, Year 1 and a few thousand years in
265 * the future. None of its members should be accessed directly.
267 * If the #GDate-struct is obtained from g_date_new(), it will be safe
268 * to mutate but invalid and thus not safe for calendrical computations.
270 * If it's declared on the stack, it will contain garbage so must be
271 * initialized with g_date_clear(). g_date_clear() makes the date invalid
272 * but sane. An invalid date doesn't represent a day, it's "empty." A date
273 * becomes valid after you set it to a Julian day or you set a day, month,
281 * @G_DATE_MONTH: a month
282 * @G_DATE_YEAR: a year
284 * This enumeration isn't used in the API, but may be useful if you need
285 * to mark a number as a day, month, or year.
292 * Integer representing a day of the month; between 1 and 31.
293 * #G_DATE_BAD_DAY represents an invalid day of the month.
299 * @G_DATE_BAD_MONTH: invalid value
300 * @G_DATE_JANUARY: January
301 * @G_DATE_FEBRUARY: February
302 * @G_DATE_MARCH: March
303 * @G_DATE_APRIL: April
307 * @G_DATE_AUGUST: August
308 * @G_DATE_SEPTEMBER: September
309 * @G_DATE_OCTOBER: October
310 * @G_DATE_NOVEMBER: November
311 * @G_DATE_DECEMBER: December
313 * Enumeration representing a month; values are #G_DATE_JANUARY,
314 * #G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value.
320 * @G_DATE_BAD_WEEKDAY: invalid value
321 * @G_DATE_MONDAY: Monday
322 * @G_DATE_TUESDAY: Tuesday
323 * @G_DATE_WEDNESDAY: Wednesday
324 * @G_DATE_THURSDAY: Thursday
325 * @G_DATE_FRIDAY: Friday
326 * @G_DATE_SATURDAY: Saturday
327 * @G_DATE_SUNDAY: Sunday
329 * Enumeration representing a day of the week; #G_DATE_MONDAY,
330 * #G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday.
337 * Integer representing a year; #G_DATE_BAD_YEAR is the invalid
338 * value. The year must be 1 or higher; negative (BC) years are not
339 * allowed. The year is represented with four digits.
345 * @data: the data element.
347 * Specifies the type of function which is called when a data element
348 * is destroyed. It is passed the pointer to the data element and
349 * should free any memory and resources allocated for it.
356 * An opaque structure representing an opened directory.
362 * @v_double: the double value
364 * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
365 * mantissa and exponent of IEEE floats and doubles. These unions are defined
366 * as appropriate for a given platform. IEEE floats and doubles are supported
367 * (used for storage) by at least Intel, PPC and Sparc.
373 * @data: the data to duplicate
374 * @user_data: user data that was specified in g_datalist_id_dup_data()
376 * The type of functions that are used to 'duplicate' an object.
377 * What this means depends on the context, it could just be
378 * incrementing the reference count, if @data is a ref-counted
381 * Returns: a duplicate of data
388 * @b: a value to compare with
390 * Specifies the type of a function used to test two values for
391 * equality. The function should return %TRUE if both values are equal
392 * and %FALSE otherwise.
394 * Returns: %TRUE if @a = @b; %FALSE otherwise
400 * @G_ERR_UNKNOWN: unknown error
401 * @G_ERR_UNEXP_EOF: unexpected end of file
402 * @G_ERR_UNEXP_EOF_IN_STRING: unterminated string constant
403 * @G_ERR_UNEXP_EOF_IN_COMMENT: unterminated comment
404 * @G_ERR_NON_DIGIT_IN_CONST: non-digit character in a number
405 * @G_ERR_DIGIT_RADIX: digit beyond radix in a number
406 * @G_ERR_FLOAT_RADIX: non-decimal floating point number
407 * @G_ERR_FLOAT_MALFORMED: malformed floating point number
409 * The possible errors, used in the @v_error field
410 * of #GTokenValue, when the token is a %G_TOKEN_ERROR.
416 * @G_FILE_ERROR_EXIST: Operation not permitted; only the owner of
417 * the file (or other resource) or processes with special privileges
418 * can perform the operation.
419 * @G_FILE_ERROR_ISDIR: File is a directory; you cannot open a directory
420 * for writing, or create or remove hard links to it.
421 * @G_FILE_ERROR_ACCES: Permission denied; the file permissions do not
422 * allow the attempted operation.
423 * @G_FILE_ERROR_NAMETOOLONG: Filename too long.
424 * @G_FILE_ERROR_NOENT: No such file or directory. This is a "file
425 * doesn't exist" error for ordinary files that are referenced in
426 * contexts where they are expected to already exist.
427 * @G_FILE_ERROR_NOTDIR: A file that isn't a directory was specified when
428 * a directory is required.
429 * @G_FILE_ERROR_NXIO: No such device or address. The system tried to
430 * use the device represented by a file you specified, and it
431 * couldn't find the device. This can mean that the device file was
432 * installed incorrectly, or that the physical device is missing or
433 * not correctly attached to the computer.
434 * @G_FILE_ERROR_NODEV: The underlying file system of the specified file
435 * does not support memory mapping.
436 * @G_FILE_ERROR_ROFS: The directory containing the new link can't be
437 * modified because it's on a read-only file system.
438 * @G_FILE_ERROR_TXTBSY: Text file busy.
439 * @G_FILE_ERROR_FAULT: You passed in a pointer to bad memory.
440 * (GLib won't reliably return this, don't pass in pointers to bad
442 * @G_FILE_ERROR_LOOP: Too many levels of symbolic links were encountered
443 * in looking up a file name. This often indicates a cycle of symbolic
445 * @G_FILE_ERROR_NOSPC: No space left on device; write operation on a
446 * file failed because the disk is full.
447 * @G_FILE_ERROR_NOMEM: No memory available. The system cannot allocate
448 * more virtual memory because its capacity is full.
449 * @G_FILE_ERROR_MFILE: The current process has too many files open and
450 * can't open any more. Duplicate descriptors do count toward this
452 * @G_FILE_ERROR_NFILE: There are too many distinct file openings in the
454 * @G_FILE_ERROR_BADF: Bad file descriptor; for example, I/O on a
455 * descriptor that has been closed or reading from a descriptor open
456 * only for writing (or vice versa).
457 * @G_FILE_ERROR_INVAL: Invalid argument. This is used to indicate
458 * various kinds of problems with passing the wrong argument to a
460 * @G_FILE_ERROR_PIPE: Broken pipe; there is no process reading from the
461 * other end of a pipe. Every library function that returns this
462 * error code also generates a 'SIGPIPE' signal; this signal
463 * terminates the program if not handled or blocked. Thus, your
464 * program will never actually see this code unless it has handled
465 * or blocked 'SIGPIPE'.
466 * @G_FILE_ERROR_AGAIN: Resource temporarily unavailable; the call might
467 * work if you try again later.
468 * @G_FILE_ERROR_INTR: Interrupted function call; an asynchronous signal
469 * occurred and prevented completion of the call. When this
470 * happens, you should try the call again.
471 * @G_FILE_ERROR_IO: Input/output error; usually used for physical read
472 * or write errors. i.e. the disk or other physical device hardware
473 * is returning errors.
474 * @G_FILE_ERROR_PERM: Operation not permitted; only the owner of the
475 * file (or other resource) or processes with special privileges can
476 * perform the operation.
477 * @G_FILE_ERROR_NOSYS: Function not implemented; this indicates that
478 * the system is missing some functionality.
479 * @G_FILE_ERROR_FAILED: Does not correspond to a UNIX error code; this
480 * is the standard "failed for unspecified reason" error code present
481 * in all #GError error code enumerations. Returned if no specific
484 * Values corresponding to @errno codes returned from file operations
485 * on UNIX. Unlike @errno codes, GFileError values are available on
486 * all systems, even Windows. The exact meaning of each code depends
487 * on what sort of file operation you were performing; the UNIX
488 * documentation gives more details. The following error code descriptions
489 * come from the GNU C Library manual, and are under the copyright
492 * It's not very portable to make detailed assumptions about exactly
493 * which errors will be returned from a given operation. Some errors
494 * don't occur on some systems, etc., sometimes there are subtle
495 * differences in when a system will report a given error, etc.
501 * @G_FILE_TEST_IS_REGULAR: %TRUE if the file is a regular file
502 * (not a directory). Note that this test will also return %TRUE
503 * if the tested file is a symlink to a regular file.
504 * @G_FILE_TEST_IS_SYMLINK: %TRUE if the file is a symlink.
505 * @G_FILE_TEST_IS_DIR: %TRUE if the file is a directory.
506 * @G_FILE_TEST_IS_EXECUTABLE: %TRUE if the file is executable.
507 * @G_FILE_TEST_EXISTS: %TRUE if the file exists. It may or may not
510 * A test to perform on a file using g_file_test().
516 * @v_float: the double value
518 * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
519 * mantissa and exponent of IEEE floats and doubles. These unions are defined
520 * as appropriate for a given platform. IEEE floats and doubles are supported
521 * (used for storage) by at least Intel, PPC and Sparc.
527 * @G_FORMAT_SIZE_DEFAULT: behave the same as g_format_size()
528 * @G_FORMAT_SIZE_LONG_FORMAT: include the exact number of bytes as part
529 * of the returned string. For example, "45.6 kB (45,612 bytes)".
530 * @G_FORMAT_SIZE_IEC_UNITS: use IEC (base 1024) units with "KiB"-style
531 * suffixes. IEC units should only be used for reporting things with
532 * a strong "power of 2" basis, like RAM sizes or RAID stripe sizes.
533 * Network and storage sizes should be reported in the normal SI units.
535 * Flags to modify the format of the string returned by g_format_size_full().
541 * @data: the element's data
542 * @user_data: user data passed to g_list_foreach() or g_slist_foreach()
544 * Specifies the type of functions passed to g_list_foreach() and
552 * @value: the value corresponding to the key
553 * @user_data: user data passed to g_hash_table_foreach()
555 * Specifies the type of the function passed to g_hash_table_foreach().
556 * It is called with each key/value pair, together with the @user_data
557 * parameter which is passed to g_hash_table_foreach().
564 * @value: the value associated with the key
565 * @user_data: user data passed to g_hash_table_remove()
567 * Specifies the type of the function passed to
568 * g_hash_table_foreach_remove(). It is called with each key/value
569 * pair, together with the @user_data parameter passed to
570 * g_hash_table_foreach_remove(). It should return %TRUE if the
571 * key/value pair should be removed from the #GHashTable.
573 * Returns: %TRUE if the key/value pair should be removed from the
582 * Specifies the type of the hash function which is passed to
583 * g_hash_table_new() when a #GHashTable is created.
585 * The function is passed a key and should return a #guint hash value.
586 * The functions g_direct_hash(), g_int_hash() and g_str_hash() provide
587 * hash functions which can be used when the key is a #gpointer, #gint*,
588 * and #gchar* respectively.
590 * g_direct_hash() is also the appropriate hash function for keys
591 * of the form `GINT_TO_POINTER (n)` (or similar macros).
593 * <!-- FIXME: Need more here. --> A good hash functions should produce
594 * hash values that are evenly distributed over a fairly large range.
595 * The modulus is taken with the hash table size (a prime number) to
596 * find the 'bucket' to place each key into. The function should also
597 * be very fast, since it is called for each key lookup.
599 * Note that the hash functions provided by GLib have these qualities,
600 * but are not particularly robust against manufactured keys that
601 * cause hash collisions. Therefore, you should consider choosing
602 * a more secure hash function when using a GHashTable with keys
603 * that originate in untrusted data (such as HTTP requests).
604 * Using g_str_hash() in that situation might make your application
606 * [Algorithmic Complexity Attacks](https://lwn.net/Articles/474912/).
608 * The key to choosing a good hash is unpredictability. Even
609 * cryptographic hashes are very easy to find collisions for when the
610 * remainder is taken modulo a somewhat predictable prime number. There
611 * must be an element of randomness that an attacker is unable to guess.
613 * Returns: the hash value corresponding to the key
620 * The #GHashTable struct is an opaque data structure to represent a
621 * [Hash Table][glib-Hash-Tables]. It should only be accessed via the
622 * following functions.
629 * A GHashTableIter structure represents an iterator that can be used
630 * to iterate over the elements of a #GHashTable. GHashTableIter
631 * structures are typically allocated on the stack and then initialized
632 * with g_hash_table_iter_init().
638 * @data: data which is passed to func when this hook is invoked
639 * @next: pointer to the next hook in the list
640 * @prev: pointer to the previous hook in the list
641 * @ref_count: the reference count of this hook
642 * @hook_id: the id of this hook, which is unique within its list
643 * @flags: flags which are set for this hook. See #GHookFlagMask for
645 * @func: the function to call when this hook is invoked. The possible
646 * signatures for this function are #GHookFunc and #GHookCheckFunc
647 * @destroy: the default @finalize_hook function of a #GHookList calls
648 * this member of the hook that is being finalized
650 * The #GHook struct represents a single hook function in a #GHookList.
656 * @data: the data field of the #GHook is passed to the hook function here
658 * Defines the type of a hook function that can be invoked
659 * by g_hook_list_invoke_check().
661 * Returns: %FALSE if the #GHook should be destroyed
666 * GHookCheckMarshaller:
668 * @marshal_data: user data
670 * Defines the type of function used by g_hook_list_marshal_check().
672 * Returns: %FALSE if @hook should be destroyed
678 * @new_hook: the #GHook being inserted
679 * @sibling: the #GHook to compare with @new_hook
681 * Defines the type of function used to compare #GHook elements in
682 * g_hook_insert_sorted().
684 * Returns: a value <= 0 if @new_hook should be before @sibling
690 * @hook_list: a #GHookList
691 * @hook: the hook in @hook_list that gets finalized
693 * Defines the type of function to be called when a hook in a
694 * list of hooks gets finalized.
701 * @data: user data passed to g_hook_find_func()
703 * Defines the type of the function passed to g_hook_find().
705 * Returns: %TRUE if the required #GHook has been found
711 * @G_HOOK_FLAG_ACTIVE: set if the hook has not been destroyed
712 * @G_HOOK_FLAG_IN_CALL: set if the hook is currently being run
713 * @G_HOOK_FLAG_MASK: A mask covering all bits reserved for
714 * hook flags; see %G_HOOK_FLAG_USER_SHIFT
716 * Flags used internally in the #GHook implementation.
722 * @data: the data field of the #GHook is passed to the hook function here
724 * Defines the type of a hook function that can be invoked
725 * by g_hook_list_invoke().
731 * @seq_id: the next free #GHook id
732 * @hook_size: the size of the #GHookList elements, in bytes
733 * @is_setup: 1 if the #GHookList has been initialized
734 * @hooks: the first #GHook element in the list
736 * @finalize_hook: the function to call to finalize a #GHook element.
737 * The default behaviour is to call the hooks @destroy function
740 * The #GHookList struct represents a list of hook functions.
747 * @marshal_data: user data
749 * Defines the type of function used by g_hook_list_marshal().
755 * @val: a #gint16 value in big-endian byte order
757 * Converts a #gint16 value from big-endian to host byte order.
759 * Returns: @val converted to host byte order
765 * @val: a #gint16 value in little-endian byte order
767 * Converts a #gint16 value from little-endian to host byte order.
769 * Returns: @val converted to host byte order
775 * @val: a #gint16 value in host byte order
777 * Converts a #gint16 value from host byte order to big-endian.
779 * Returns: @val converted to big-endian
785 * @val: a #gint16 value in host byte order
787 * Converts a #gint16 value from host byte order to little-endian.
789 * Returns: @val converted to little-endian
795 * @val: a #gint32 value in big-endian byte order
797 * Converts a #gint32 value from big-endian to host byte order.
799 * Returns: @val converted to host byte order
805 * @val: a #gint32 value in little-endian byte order
807 * Converts a #gint32 value from little-endian to host byte order.
809 * Returns: @val converted to host byte order
815 * @val: a #gint32 value in host byte order
817 * Converts a #gint32 value from host byte order to big-endian.
819 * Returns: @val converted to big-endian
825 * @val: a #gint32 value in host byte order
827 * Converts a #gint32 value from host byte order to little-endian.
829 * Returns: @val converted to little-endian
835 * @val: a #gint64 value in big-endian byte order
837 * Converts a #gint64 value from big-endian to host byte order.
839 * Returns: @val converted to host byte order
845 * @val: a #gint64 value in little-endian byte order
847 * Converts a #gint64 value from little-endian to host byte order.
849 * Returns: @val converted to host byte order
855 * @val: a #gint64 value in host byte order
857 * Converts a #gint64 value from host byte order to big-endian.
859 * Returns: @val converted to big-endian
865 * @val: a #gint64 value in host byte order
867 * Converts a #gint64 value from host byte order to little-endian.
869 * Returns: @val converted to little-endian
875 * @val: a #gint value in big-endian byte order
877 * Converts a #gint value from big-endian to host byte order.
879 * Returns: @val converted to host byte order
885 * @val: a #gint value in little-endian byte order
887 * Converts a #gint value from little-endian to host byte order.
889 * Returns: @val converted to host byte order
895 * @val: a #gint value in host byte order
897 * Converts a #gint value from host byte order to big-endian.
899 * Returns: @val converted to big-endian byte order
905 * @val: a #gint value in host byte order
907 * Converts a #gint value from host byte order to little-endian.
909 * Returns: @val converted to little-endian byte order
915 * @i: integer to stuff into a pointer
917 * Stuffs an integer into a pointer type.
919 * Remember, you may not store pointers in integers. This is not portable
920 * in any way, shape or form. These macros only allow storing integers in
921 * pointers, and only preserve 32 bits of the integer; values outside the
922 * range of a 32-bit integer will be mangled.
929 * A data structure representing an IO Channel. The fields should be
930 * considered private and should only be accessed with the following
937 * @G_IO_CHANNEL_ERROR_FBIG: File too large.
938 * @G_IO_CHANNEL_ERROR_INVAL: Invalid argument.
939 * @G_IO_CHANNEL_ERROR_IO: IO error.
940 * @G_IO_CHANNEL_ERROR_ISDIR: File is a directory.
941 * @G_IO_CHANNEL_ERROR_NOSPC: No space left on device.
942 * @G_IO_CHANNEL_ERROR_NXIO: No such device or address.
943 * @G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype.
944 * @G_IO_CHANNEL_ERROR_PIPE: Broken pipe.
945 * @G_IO_CHANNEL_ERROR_FAILED: Some other error.
947 * Error codes returned by #GIOChannel operations.
953 * @G_IO_IN: There is data to read.
954 * @G_IO_OUT: Data can be written (without blocking).
955 * @G_IO_PRI: There is urgent data to read.
956 * @G_IO_ERR: Error condition.
957 * @G_IO_HUP: Hung up (the connection has been broken, usually for
958 * pipes and sockets).
959 * @G_IO_NVAL: Invalid request. The file descriptor is not open.
961 * A bitwise combination representing a condition to watch for on an
968 * @G_IO_ERROR_NONE: no error
969 * @G_IO_ERROR_AGAIN: an EAGAIN error occurred
970 * @G_IO_ERROR_INVAL: an EINVAL error occurred
971 * @G_IO_ERROR_UNKNOWN: another error occurred
973 * #GIOError is only used by the deprecated functions
974 * g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek().
980 * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND
981 * (see the documentation of the UNIX open() syscall)
982 * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
983 * %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open()
985 * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable.
986 * This flag cannot be changed.
987 * @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable.
988 * This flag cannot be changed.
989 * @G_IO_FLAG_IS_WRITEABLE: a misspelled version of @G_IO_FLAG_IS_WRITABLE
990 * that existed before the spelling was fixed in GLib 2.30. It is kept
991 * here for compatibility reasons. Deprecated since 2.30
992 * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable,
993 * i.e. that g_io_channel_seek_position() can be used on it.
994 * This flag cannot be changed.
995 * @G_IO_FLAG_MASK: the mask that specifies all the valid flags.
996 * @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from
997 * g_io_channel_get_flags()
998 * @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify
999 * with g_io_channel_set_flags()
1001 * Specifies properties of a #GIOChannel. Some of the flags can only be
1002 * read with g_io_channel_get_flags(), but not changed with
1003 * g_io_channel_set_flags().
1009 * @source: the #GIOChannel event source
1010 * @condition: the condition which has been satisfied
1011 * @data: user data set in g_io_add_watch() or g_io_add_watch_full()
1013 * Specifies the type of function passed to g_io_add_watch() or
1014 * g_io_add_watch_full(), which is called when the requested condition
1015 * on a #GIOChannel is satisfied.
1017 * Returns: the function should return %FALSE if the event source
1024 * @io_read: reads raw bytes from the channel. This is called from
1025 * various functions such as g_io_channel_read_chars() to
1026 * read raw bytes from the channel. Encoding and buffering
1027 * issues are dealt with at a higher level.
1028 * @io_write: writes raw bytes to the channel. This is called from
1029 * various functions such as g_io_channel_write_chars() to
1030 * write raw bytes to the channel. Encoding and buffering
1031 * issues are dealt with at a higher level.
1032 * @io_seek: (optional): seeks the channel. This is called from
1033 * g_io_channel_seek() on channels that support it.
1034 * @io_close: closes the channel. This is called from
1035 * g_io_channel_close() after flushing the buffers.
1036 * @io_create_watch: creates a watch on the channel. This call
1037 * corresponds directly to g_io_create_watch().
1038 * @io_free: called from g_io_channel_unref() when the channel needs to
1039 * be freed. This function must free the memory associated
1040 * with the channel, including freeing the #GIOChannel
1041 * structure itself. The channel buffers have been flushed
1042 * and possibly @io_close has been called by the time this
1043 * function is called.
1044 * @io_set_flags: sets the #GIOFlags on the channel. This is called
1045 * from g_io_channel_set_flags() with all flags except
1046 * for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked
1048 * @io_get_flags: gets the #GIOFlags for the channel. This function
1049 * need only return the %G_IO_FLAG_APPEND and
1050 * %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags()
1051 * automatically adds the others as appropriate.
1053 * A table of functions used to handle different types of #GIOChannel
1060 * @G_IO_STATUS_ERROR: An error occurred.
1061 * @G_IO_STATUS_NORMAL: Success.
1062 * @G_IO_STATUS_EOF: End of file.
1063 * @G_IO_STATUS_AGAIN: Resource temporarily unavailable.
1065 * Stati returned by most of the #GIOFuncs functions.
1072 * The GKeyFile struct contains only private data
1073 * and should not be accessed directly.
1079 * @G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in
1080 * an unknown encoding
1081 * @G_KEY_FILE_ERROR_PARSE: document was ill-formed
1082 * @G_KEY_FILE_ERROR_NOT_FOUND: the file was not found
1083 * @G_KEY_FILE_ERROR_KEY_NOT_FOUND: a requested key was not found
1084 * @G_KEY_FILE_ERROR_GROUP_NOT_FOUND: a requested group was not found
1085 * @G_KEY_FILE_ERROR_INVALID_VALUE: a value could not be parsed
1087 * Error codes returned by key file parsing.
1093 * @G_KEY_FILE_NONE: No flags, default behaviour
1094 * @G_KEY_FILE_KEEP_COMMENTS: Use this flag if you plan to write the
1095 * (possibly modified) contents of the key file back to a file;
1096 * otherwise all comments will be lost when the key file is
1098 * @G_KEY_FILE_KEEP_TRANSLATIONS: Use this flag if you plan to write the
1099 * (possibly modified) contents of the key file back to a file;
1100 * otherwise only the translations for the current language will be
1103 * Flags which influence the parsing.
1108 * GLIB_CHECK_VERSION:
1109 * @major: the major version to check for
1110 * @minor: the minor version to check for
1111 * @micro: the micro version to check for
1113 * Checks the version of the GLib library that is being compiled
1114 * against. See glib_check_version() for a runtime check.
1116 * Returns: %TRUE if the version of the GLib header files
1117 * is the same as or newer than the passed-in version.
1122 * GLIB_DISABLE_DEPRECATION_WARNINGS:
1124 * A macro that should be defined before including the glib.h header.
1125 * If it is defined, no compiler warnings will be produced for uses
1126 * of deprecated GLib APIs.
1131 * GLIB_MAJOR_VERSION:
1133 * The major version number of the GLib library.
1135 * Like #glib_major_version, but from the headers used at
1136 * application compile time, rather than from the library
1137 * linked against at application run time.
1142 * GLIB_MICRO_VERSION:
1144 * The micro version number of the GLib library.
1146 * Like #gtk_micro_version, but from the headers used at
1147 * application compile time, rather than from the library
1148 * linked against at application run time.
1153 * GLIB_MINOR_VERSION:
1155 * The minor version number of the GLib library.
1157 * Like #gtk_minor_version, but from the headers used at
1158 * application compile time, rather than from the library
1159 * linked against at application run time.
1165 * @val: a #glong value in big-endian byte order
1167 * Converts a #glong value from big-endian to the host byte order.
1169 * Returns: @val converted to host byte order
1175 * @val: a #glong value in little-endian byte order
1177 * Converts a #glong value from little-endian to host byte order.
1179 * Returns: @val converted to host byte order
1185 * @val: a #glong value in host byte order
1187 * Converts a #glong value from host byte order to big-endian.
1189 * Returns: @val converted to big-endian byte order
1195 * @val: a #glong value in host byte order
1197 * Converts a #glong value from host byte order to little-endian.
1199 * Returns: @val converted to little-endian
1205 * @data: holds the element's data, which can be a pointer to any kind
1206 * of data, or any integer value using the
1207 * [Type Conversion Macros][glib-Type-Conversion-Macros]
1208 * @next: contains the link to the next element in the list
1209 * @prev: contains the link to the previous element in the list
1211 * The #GList struct is used for each element in a doubly-linked list.
1217 * @log_domain: the log domain of the message
1218 * @log_level: the log level of the message (including the
1219 * fatal and recursion flags)
1220 * @message: the message to process
1221 * @user_data: user data, set in g_log_set_handler()
1223 * Specifies the prototype of log handler functions.
1225 * The default log handler, g_log_default_handler(), automatically appends a
1226 * new-line character to @message when printing it. It is advised that any
1227 * custom log handler functions behave similarly, so that logging calls in user
1228 * code do not need modifying to add a new-line character to the message if the
1229 * log handler is changed.
1235 * @G_LOG_FLAG_RECURSION: internal flag
1236 * @G_LOG_FLAG_FATAL: internal flag
1237 * @G_LOG_LEVEL_ERROR: log level for errors, see g_error().
1238 * This level is also used for messages produced by g_assert().
1239 * @G_LOG_LEVEL_CRITICAL: log level for critical warning messages, see
1241 * This level is also used for messages produced by g_return_if_fail()
1242 * and g_return_val_if_fail().
1243 * @G_LOG_LEVEL_WARNING: log level for warnings, see g_warning()
1244 * @G_LOG_LEVEL_MESSAGE: log level for messages, see g_message()
1245 * @G_LOG_LEVEL_INFO: log level for informational messages, see g_info()
1246 * @G_LOG_LEVEL_DEBUG: log level for debug messages, see g_debug()
1247 * @G_LOG_LEVEL_MASK: a mask including all log levels
1249 * Flags specifying the level of log messages.
1251 * It is possible to change how GLib treats messages of the various
1252 * levels using g_log_set_handler() and g_log_set_fatal_mask().
1259 * The #GMappedFile represents a file mapping created with
1260 * g_mapped_file_new(). It has only private members and should
1261 * not be accessed directly.
1266 * GMarkupCollectType:
1267 * @G_MARKUP_COLLECT_INVALID: used to terminate the list of attributes
1269 * @G_MARKUP_COLLECT_STRING: collect the string pointer directly from
1270 * the attribute_values[] array. Expects a parameter of type (const
1271 * char **). If %G_MARKUP_COLLECT_OPTIONAL is specified and the
1272 * attribute isn't present then the pointer will be set to %NULL
1273 * @G_MARKUP_COLLECT_STRDUP: as with %G_MARKUP_COLLECT_STRING, but
1274 * expects a parameter of type (char **) and g_strdup()s the
1275 * returned pointer. The pointer must be freed with g_free()
1276 * @G_MARKUP_COLLECT_BOOLEAN: expects a parameter of type (gboolean *)
1277 * and parses the attribute value as a boolean. Sets %FALSE if the
1278 * attribute isn't present. Valid boolean values consist of
1279 * (case-insensitive) "false", "f", "no", "n", "0" and "true", "t",
1281 * @G_MARKUP_COLLECT_TRISTATE: as with %G_MARKUP_COLLECT_BOOLEAN, but
1282 * in the case of a missing attribute a value is set that compares
1283 * equal to neither %FALSE nor %TRUE G_MARKUP_COLLECT_OPTIONAL is
1285 * @G_MARKUP_COLLECT_OPTIONAL: can be bitwise ORed with the other fields.
1286 * If present, allows the attribute not to appear. A default value
1287 * is set depending on what value type is used
1289 * A mixed enumerated type and flags field. You must specify one type
1290 * (string, strdup, boolean, tristate). Additionally, you may optionally
1291 * bitwise OR the type with the flag %G_MARKUP_COLLECT_OPTIONAL.
1293 * It is likely that this enum will be extended in the future to
1294 * support other types.
1301 * The #GMutex struct is an opaque data structure to represent a mutex
1302 * (mutual exclusion). It can be used to protect data against shared
1305 * Take for example the following function:
1306 * |[<!-- language="C" -->
1308 * give_me_next_number (void)
1310 * static int current_number = 0;
1312 * // now do a very complicated calculation to calculate the new
1313 * // number, this might for example be a random number generator
1314 * current_number = calc_next_number (current_number);
1316 * return current_number;
1319 * It is easy to see that this won't work in a multi-threaded
1320 * application. There current_number must be protected against shared
1321 * access. A #GMutex can be used as a solution to this problem:
1322 * |[<!-- language="C" -->
1324 * give_me_next_number (void)
1326 * static GMutex mutex;
1327 * static int current_number = 0;
1330 * g_mutex_lock (&mutex);
1331 * ret_val = current_number = calc_next_number (current_number);
1332 * g_mutex_unlock (&mutex);
1337 * Notice that the #GMutex is not initialised to any particular value.
1338 * Its placement in static storage ensures that it will be initialised
1339 * to all-zeros, which is appropriate.
1341 * If a #GMutex is placed in other contexts (eg: embedded in a struct)
1342 * then it must be explicitly initialised using g_mutex_init().
1344 * A #GMutex should only be accessed via g_mutex_ functions.
1350 * @data: contains the actual data of the node.
1351 * @next: points to the node's next sibling (a sibling is another
1352 * #GNode with the same parent).
1353 * @prev: points to the node's previous sibling.
1354 * @parent: points to the parent of the #GNode, or is %NULL if the
1355 * #GNode is the root of the tree.
1356 * @children: points to the first child of the #GNode. The other
1357 * children are accessed by using the @next pointer of each
1360 * The #GNode struct represents one node in a [n-ary tree][glib-N-ary-Trees].
1367 * @data: user data passed to g_node_children_foreach().
1369 * Specifies the type of function passed to g_node_children_foreach().
1370 * The function is called with each child node, together with the user
1371 * data passed to g_node_children_foreach().
1376 * GNodeTraverseFunc:
1378 * @data: user data passed to g_node_traverse().
1380 * Specifies the type of function passed to g_node_traverse(). The
1381 * function is called with each of the nodes visited, together with the
1382 * user data passed to g_node_traverse(). If the function returns
1383 * %TRUE, then the traversal is stopped.
1385 * Returns: %TRUE to stop the traversal.
1391 * @status: the status of the #GOnce
1392 * @retval: the value returned by the call to the function, if @status
1393 * is %G_ONCE_STATUS_READY
1395 * A #GOnce struct controls a one-time initialization function. Any
1396 * one-time initialization function must have its own unique #GOnce
1405 * @G_ONCE_STATUS_NOTCALLED: the function has not been called yet.
1406 * @G_ONCE_STATUS_PROGRESS: the function call is currently in progress.
1407 * @G_ONCE_STATUS_READY: the function has been called.
1409 * The possible statuses of a one-time initialization function
1410 * controlled by a #GOnce struct.
1418 * @p: pointer containing an integer
1420 * Extracts an integer from a pointer. The integer must have
1421 * been stored in the pointer with GINT_TO_POINTER().
1423 * Remember, you may not store pointers in integers. This is not portable
1424 * in any way, shape or form. These macros only allow storing integers in
1425 * pointers, and only preserve 32 bits of the integer; values outside the
1426 * range of a 32-bit integer will be mangled.
1432 * @p: pointer to extract a #gsize from
1434 * Extracts a #gsize from a pointer. The #gsize must have
1435 * been stored in the pointer with GSIZE_TO_POINTER().
1441 * @p: pointer to extract an unsigned integer from
1443 * Extracts an unsigned integer from a pointer. The integer must have
1444 * been stored in the pointer with GUINT_TO_POINTER().
1451 * A GPatternSpec struct is the 'compiled' form of a pattern. This
1452 * structure is opaque and its fields cannot be accessed directly.
1459 * The #GPrivate struct is an opaque data structure to represent a
1460 * thread-local data key. It is approximately equivalent to the
1461 * pthread_setspecific()/pthread_getspecific() APIs on POSIX and to
1462 * TlsSetValue()/TlsGetValue() on Windows.
1464 * If you don't already know why you might want this functionality,
1465 * then you probably don't need it.
1467 * #GPrivate is a very limited resource (as far as 128 per program,
1468 * shared between all libraries). It is also not possible to destroy a
1469 * #GPrivate after it has been used. As such, it is only ever acceptable
1470 * to use #GPrivate in static scope, and even then sparingly so.
1472 * See G_PRIVATE_INIT() for a couple of examples.
1474 * The #GPrivate structure should be considered opaque. It should only
1475 * be accessed via the g_private_ functions.
1481 * @pdata: points to the array of pointers, which may be moved when the
1483 * @len: number of pointers in the array
1485 * Contains the public fields of a pointer array.
1492 * A GQuark is a non-zero integer which uniquely identifies a
1493 * particular string. A GQuark value of zero is associated to %NULL.
1500 * The GRWLock struct is an opaque data structure to represent a
1501 * reader-writer lock. It is similar to a #GMutex in that it allows
1502 * multiple threads to coordinate access to a shared resource.
1504 * The difference to a mutex is that a reader-writer lock discriminates
1505 * between read-only ('reader') and full ('writer') access. While only
1506 * one thread at a time is allowed write access (by holding the 'writer'
1507 * lock via g_rw_lock_writer_lock()), multiple threads can gain
1508 * simultaneous read-only access (by holding the 'reader' lock via
1509 * g_rw_lock_reader_lock()).
1511 * Here is an example for an array with access functions:
1512 * |[<!-- language="C" -->
1517 * my_array_get (guint index)
1519 * gpointer retval = NULL;
1524 * g_rw_lock_reader_lock (&lock);
1525 * if (index < array->len)
1526 * retval = g_ptr_array_index (array, index);
1527 * g_rw_lock_reader_unlock (&lock);
1533 * my_array_set (guint index, gpointer data)
1535 * g_rw_lock_writer_lock (&lock);
1538 * array = g_ptr_array_new ();
1540 * if (index >= array->len)
1541 * g_ptr_array_set_size (array, index+1);
1542 * g_ptr_array_index (array, index) = data;
1544 * g_rw_lock_writer_unlock (&lock);
1547 * This example shows an array which can be accessed by many readers
1548 * (the my_array_get() function) simultaneously, whereas the writers
1549 * (the my_array_set() function) will only be allowed one at a time
1550 * and only if no readers currently access the array. This is because
1551 * of the potentially dangerous resizing of the array. Using these
1552 * functions is fully multi-thread safe now.
1554 * If a #GRWLock is allocated in static storage then it can be used
1555 * without initialisation. Otherwise, you should call
1556 * g_rw_lock_init() on it and g_rw_lock_clear() when done.
1558 * A GRWLock should only be accessed with the g_rw_lock_ functions.
1567 * The GRand struct is an opaque data structure. It should only be
1568 * accessed through the g_rand_* functions.
1575 * The GRecMutex struct is an opaque data structure to represent a
1576 * recursive mutex. It is similar to a #GMutex with the difference
1577 * that it is possible to lock a GRecMutex multiple times in the same
1578 * thread without deadlock. When doing so, care has to be taken to
1579 * unlock the recursive mutex as often as it has been locked.
1581 * If a #GRecMutex is allocated in static storage then it can be used
1582 * without initialisation. Otherwise, you should call
1583 * g_rec_mutex_init() on it and g_rec_mutex_clear() when done.
1585 * A GRecMutex should only be accessed with the
1586 * g_rec_mutex_ functions.
1594 * @val: a #gsize value in big-endian byte order
1596 * Converts a #gsize value from big-endian to the host byte order.
1598 * Returns: @val converted to host byte order
1604 * @val: a #gsize value in little-endian byte order
1606 * Converts a #gsize value from little-endian to host byte order.
1608 * Returns: @val converted to host byte order
1614 * @val: a #gsize value in host byte order
1616 * Converts a #gsize value from host byte order to big-endian.
1618 * Returns: @val converted to big-endian byte order
1624 * @val: a #gsize value in host byte order
1626 * Converts a #gsize value from host byte order to little-endian.
1628 * Returns: @val converted to little-endian
1634 * @s: #gsize to stuff into the pointer
1636 * Stuffs a #gsize into a pointer type.
1642 * @data: holds the element's data, which can be a pointer to any kind
1643 * of data, or any integer value using the
1644 * [Type Conversion Macros][glib-Type-Conversion-Macros]
1645 * @next: contains the link to the next element in the list.
1647 * The #GSList struct is used for each element in the singly-linked
1654 * @val: a #gssize value in big-endian byte order
1656 * Converts a #gssize value from big-endian to host byte order.
1658 * Returns: @val converted to host byte order
1664 * @val: a #gssize value in little-endian byte order
1666 * Converts a #gssize value from little-endian to host byte order.
1668 * Returns: @val converted to host byte order
1674 * @val: a #gssize value in host byte order
1676 * Converts a #gssize value from host byte order to big-endian.
1678 * Returns: @val converted to big-endian
1684 * @val: a #gssize value in host byte order
1686 * Converts a #gssize value from host byte order to little-endian.
1688 * Returns: @val converted to little-endian
1694 * @user_data: unused
1695 * @max_parse_errors: unused
1696 * @parse_errors: g_scanner_error() increments this field
1697 * @input_name: name of input stream, featured by the default message handler
1698 * @qdata: quarked data
1699 * @config: link into the scanner configuration
1700 * @token: token parsed by the last g_scanner_get_next_token()
1701 * @value: value of the last token from g_scanner_get_next_token()
1702 * @line: line number of the last token from g_scanner_get_next_token()
1703 * @position: char number of the last token from g_scanner_get_next_token()
1704 * @next_token: token parsed by the last g_scanner_peek_next_token()
1705 * @next_value: value of the last token from g_scanner_peek_next_token()
1706 * @next_line: line number of the last token from g_scanner_peek_next_token()
1707 * @next_position: char number of the last token from g_scanner_peek_next_token()
1708 * @msg_handler: handler function for _warn and _error
1710 * The data structure representing a lexical scanner.
1712 * You should set @input_name after creating the scanner, since
1713 * it is used by the default message handler when displaying
1714 * warnings and errors. If you are scanning a file, the filename
1715 * would be a good choice.
1717 * The @user_data and @max_parse_errors fields are not used.
1718 * If you need to associate extra data with the scanner you
1719 * can place them here.
1721 * If you want to use your own message handler you can set the
1722 * @msg_handler field. The type of the message handler function
1723 * is declared by #GScannerMsgFunc.
1729 * @cset_skip_characters: specifies which characters should be skipped
1730 * by the scanner (the default is the whitespace characters: space,
1731 * tab, carriage-return and line-feed).
1732 * @cset_identifier_first: specifies the characters which can start
1733 * identifiers (the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z).
1734 * @cset_identifier_nth: specifies the characters which can be used
1735 * in identifiers, after the first character (the default is
1736 * #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS,
1738 * @cpair_comment_single: specifies the characters at the start and
1739 * end of single-line comments. The default is "#\n" which means
1740 * that single-line comments start with a '#' and continue until
1741 * a '\n' (end of line).
1742 * @case_sensitive: specifies if symbols are case sensitive (the
1743 * default is %FALSE).
1744 * @skip_comment_multi: specifies if multi-line comments are skipped
1745 * and not returned as tokens (the default is %TRUE).
1746 * @skip_comment_single: specifies if single-line comments are skipped
1747 * and not returned as tokens (the default is %TRUE).
1748 * @scan_comment_multi: specifies if multi-line comments are recognized
1749 * (the default is %TRUE).
1750 * @scan_identifier: specifies if identifiers are recognized (the
1751 * default is %TRUE).
1752 * @scan_identifier_1char: specifies if single-character
1753 * identifiers are recognized (the default is %FALSE).
1754 * @scan_identifier_NULL: specifies if %NULL is reported as
1755 * %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE).
1756 * @scan_symbols: specifies if symbols are recognized (the default
1758 * @scan_binary: specifies if binary numbers are recognized (the
1759 * default is %FALSE).
1760 * @scan_octal: specifies if octal numbers are recognized (the
1761 * default is %TRUE).
1762 * @scan_float: specifies if floating point numbers are recognized
1763 * (the default is %TRUE).
1764 * @scan_hex: specifies if hexadecimal numbers are recognized (the
1765 * default is %TRUE).
1766 * @scan_hex_dollar: specifies if '$' is recognized as a prefix for
1767 * hexadecimal numbers (the default is %FALSE).
1768 * @scan_string_sq: specifies if strings can be enclosed in single
1769 * quotes (the default is %TRUE).
1770 * @scan_string_dq: specifies if strings can be enclosed in double
1771 * quotes (the default is %TRUE).
1772 * @numbers_2_int: specifies if binary, octal and hexadecimal numbers
1773 * are reported as #G_TOKEN_INT (the default is %TRUE).
1774 * @int_2_float: specifies if all numbers are reported as %G_TOKEN_FLOAT
1775 * (the default is %FALSE).
1776 * @identifier_2_string: specifies if identifiers are reported as strings
1777 * (the default is %FALSE).
1778 * @char_2_token: specifies if characters are reported by setting
1779 * `token = ch` or as %G_TOKEN_CHAR (the default is %TRUE).
1780 * @symbol_2_token: specifies if symbols are reported by setting
1781 * `token = v_symbol` or as %G_TOKEN_SYMBOL (the default is %FALSE).
1782 * @scope_0_fallback: specifies if a symbol is searched for in the
1783 * default scope in addition to the current scope (the default is %FALSE).
1784 * @store_int64: use value.v_int64 rather than v_int
1786 * Specifies the #GScanner parser configuration. Most settings can
1787 * be changed during the parsing phase and will affect the lexical
1788 * parsing of the next unpeeked token.
1794 * @scanner: a #GScanner
1795 * @message: the message
1796 * @error: %TRUE if the message signals an error,
1797 * %FALSE if it signals a warning.
1799 * Specifies the type of the message handler function.
1805 * @G_SEEK_CUR: the current position in the file.
1806 * @G_SEEK_SET: the start of the file.
1807 * @G_SEEK_END: the end of the file.
1809 * An enumeration specifying the base position for a
1810 * g_io_channel_seek_position() operation.
1817 * The #GSequence struct is an opaque data type representing a
1818 * [sequence][glib-Sequences] data type.
1825 * The #GSequenceIter struct is an opaque data type representing an
1826 * iterator pointing into a #GSequence.
1831 * GSequenceIterCompareFunc:
1832 * @a: a #GSequenceIter
1833 * @b: a #GSequenceIter
1836 * A #GSequenceIterCompareFunc is a function used to compare iterators.
1837 * It must return zero if the iterators compare equal, a negative value
1838 * if @a comes before @b, and a positive value if @b comes before @a.
1840 * Returns: zero if the iterators are equal, a negative value if @a
1841 * comes before @b, and a positive value if @b comes before @a.
1847 * @G_SHELL_ERROR_BAD_QUOTING: Mismatched or otherwise mangled quoting.
1848 * @G_SHELL_ERROR_EMPTY_STRING: String to be parsed was empty.
1849 * @G_SHELL_ERROR_FAILED: Some other error.
1851 * Error codes returned by shell functions.
1858 * A type corresponding to the appropriate struct type for the stat()
1859 * system call, depending on the platform and/or compiler being used.
1861 * See g_stat() for more information.
1867 * @str: points to the character data. It may move as text is added.
1868 * The @str field is null-terminated and so
1869 * can be used as an ordinary C string.
1870 * @len: contains the length of the string, not including the
1871 * terminating nul byte.
1872 * @allocated_len: the number of bytes that can be stored in the
1873 * string before it needs to be reallocated. May be larger than @len.
1875 * The GString struct contains the public fields of a GString.
1882 * An opaque data structure representing String Chunks.
1883 * It should only be accessed by using the following functions.
1890 * A typedef alias for gchar**. This is mostly useful when used together with
1898 * An opaque structure representing a test case.
1904 * @user_data: the data provided when registering the test
1906 * The type used for test case functions that take an extra pointer
1915 * @G_TEST_DIST: a file that was included in the distribution tarball
1916 * @G_TEST_BUILT: a file that was built on the compiling machine
1918 * The type of file to return the filename for, when used with
1919 * g_test_build_filename().
1921 * These two options correspond rather directly to the 'dist' and
1922 * 'built' terminology that automake uses and are explicitly used to
1923 * distinguish between the 'srcdir' and 'builddir' being separate. All
1924 * files in your project should either be dist (in the
1925 * `DIST_EXTRA` or `dist_schema_DATA`
1926 * sense, in which case they will always be in the srcdir) or built (in
1927 * the `BUILT_SOURCES` sense, in which case they will
1928 * always be in the builddir).
1930 * Note: as a general rule of automake, files that are generated only as
1931 * part of the build-from-git process (but then are distributed with the
1932 * tarball) always go in srcdir (even if doing a srcdir != builddir
1933 * build from git) and are considered as distributed files.
1941 * @fixture: (not nullable): the test fixture
1942 * @user_data: the data provided when registering the test
1944 * The type used for functions that operate on test fixtures. This is
1945 * used for the fixture setup and teardown functions as well as for the
1946 * testcases themselves.
1948 * @user_data is a pointer to the data that was given when registering
1951 * @fixture will be a pointer to the area of memory allocated by the
1952 * test framework, of the size requested. If the requested size was
1953 * zero then @fixture will be equal to @user_data.
1962 * The type used for test case functions.
1969 * GTestSubprocessFlags:
1970 * @G_TEST_SUBPROCESS_INHERIT_STDIN: If this flag is given, the child
1971 * process will inherit the parent's stdin. Otherwise, the child's
1972 * stdin is redirected to `/dev/null`.
1973 * @G_TEST_SUBPROCESS_INHERIT_STDOUT: If this flag is given, the child
1974 * process will inherit the parent's stdout. Otherwise, the child's
1975 * stdout will not be visible, but it will be captured to allow
1976 * later tests with g_test_trap_assert_stdout().
1977 * @G_TEST_SUBPROCESS_INHERIT_STDERR: If this flag is given, the child
1978 * process will inherit the parent's stderr. Otherwise, the child's
1979 * stderr will not be visible, but it will be captured to allow
1980 * later tests with g_test_trap_assert_stderr().
1982 * Flags to pass to g_test_trap_subprocess() to control input and output.
1984 * Note that in contrast with g_test_trap_fork(), the default is to
1985 * not show stdout and stderr.
1992 * An opaque structure representing a test suite.
1998 * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to
1999 * `/dev/null` so it cannot be observed on the console during test
2000 * runs. The actual output is still captured though to allow later
2001 * tests with g_test_trap_assert_stdout().
2002 * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to
2003 * `/dev/null` so it cannot be observed on the console during test
2004 * runs. The actual output is still captured though to allow later
2005 * tests with g_test_trap_assert_stderr().
2006 * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the
2007 * child process is shared with stdin of its parent process.
2008 * It is redirected to `/dev/null` otherwise.
2010 * Test traps are guards around forked tests.
2011 * These flags determine what traps to set.
2013 * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(),
2014 * which is deprecated. g_test_trap_subprocess() uses
2015 * #GTestTrapSubprocessFlags.
2022 * The #GThread struct represents a running thread. This struct
2023 * is returned by g_thread_new() or g_thread_try_new(). You can
2024 * obtain the #GThread struct representing the current thread by
2025 * calling g_thread_self().
2027 * GThread is refcounted, see g_thread_ref() and g_thread_unref().
2028 * The thread represented by it holds a reference while it is running,
2029 * and g_thread_join() consumes the reference that it is given, so
2030 * it is normally not necessary to manage GThread references
2033 * The structure is opaque -- none of its fields may be directly
2040 * @G_THREAD_ERROR_AGAIN: a thread couldn't be created due to resource
2041 * shortage. Try again later.
2043 * Possible errors of thread related functions.
2049 * @data: data passed to the thread
2051 * Specifies the type of the @func functions passed to g_thread_new()
2052 * or g_thread_try_new().
2054 * Returns: the return value of the thread
2060 * @func: the function to execute in the threads of this pool
2061 * @user_data: the user data for the threads of this pool
2062 * @exclusive: are all threads exclusive to this pool
2064 * The #GThreadPool struct represents a thread pool. It has three
2065 * public read-only members, but the underlying struct is bigger,
2066 * so you must not copy this struct.
2073 * Simply a replacement for time_t. It has been deprecated
2074 * since it is not equivalent to time_t on 64-bit platforms
2075 * with a 64-bit time_t. Unrelated to #GTimer.
2077 * Note that #GTime is defined to always be a 32-bit integer,
2078 * unlike time_t which may be 64-bit on some systems. Therefore,
2079 * #GTime will overflow in the year 2038, and you cannot use the
2080 * address of a #GTime variable as argument to the UNIX time()
2083 * Instead, do the following:
2084 * |[<!-- language="C" -->
2089 * gtime = (GTime)ttime;
2097 * @tv_usec: microseconds
2099 * Represents a precise time, with seconds and microseconds.
2100 * Similar to the struct timeval returned by the gettimeofday()
2103 * GLib is attempting to unify around the use of 64bit integers to
2104 * represent microsecond-precision time. As such, this type will be
2105 * removed from a future version of GLib.
2112 * #GTimeZone is an opaque structure whose members cannot be accessed
2122 * Opaque datatype that records a start time.
2128 * @G_TOKEN_EOF: the end of the file
2129 * @G_TOKEN_LEFT_PAREN: a '(' character
2130 * @G_TOKEN_LEFT_CURLY: a '{' character
2131 * @G_TOKEN_LEFT_BRACE: a '[' character
2132 * @G_TOKEN_RIGHT_CURLY: a '}' character
2133 * @G_TOKEN_RIGHT_PAREN: a ')' character
2134 * @G_TOKEN_RIGHT_BRACE: a ']' character
2135 * @G_TOKEN_EQUAL_SIGN: a '=' character
2136 * @G_TOKEN_COMMA: a ',' character
2137 * @G_TOKEN_NONE: not a token
2138 * @G_TOKEN_ERROR: an error occurred
2139 * @G_TOKEN_CHAR: a character
2140 * @G_TOKEN_BINARY: a binary integer
2141 * @G_TOKEN_OCTAL: an octal integer
2142 * @G_TOKEN_INT: an integer
2143 * @G_TOKEN_HEX: a hex integer
2144 * @G_TOKEN_FLOAT: a floating point number
2145 * @G_TOKEN_STRING: a string
2146 * @G_TOKEN_SYMBOL: a symbol
2147 * @G_TOKEN_IDENTIFIER: an identifier
2148 * @G_TOKEN_IDENTIFIER_NULL: a null identifier
2149 * @G_TOKEN_COMMENT_SINGLE: one line comment
2150 * @G_TOKEN_COMMENT_MULTI: multi line comment
2152 * The possible types of token returned from each
2153 * g_scanner_get_next_token() call.
2159 * @v_symbol: token symbol value
2160 * @v_identifier: token identifier value
2161 * @v_binary: token binary integer value
2162 * @v_octal: octal integer value
2163 * @v_int: integer value
2164 * @v_int64: 64-bit integer value
2165 * @v_float: floating point value
2166 * @v_hex: hex integer value
2167 * @v_string: string value
2168 * @v_comment: comment value
2169 * @v_char: character value
2170 * @v_error: error value
2172 * A union holding the value of the token.
2178 * @next: pointer to the previous element of the stack,
2179 * gets stored in the first `sizeof (gpointer)`
2180 * bytes of the element
2182 * Each piece of memory that is pushed onto the stack
2183 * is cast to a GTrashStack*.
2185 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
2191 * @G_TRAVERSE_LEAVES: only leaf nodes should be visited. This name has
2192 * been introduced in 2.6, for older version use
2193 * %G_TRAVERSE_LEAFS.
2194 * @G_TRAVERSE_NON_LEAVES: only non-leaf nodes should be visited. This
2195 * name has been introduced in 2.6, for older
2196 * version use %G_TRAVERSE_NON_LEAFS.
2197 * @G_TRAVERSE_ALL: all nodes should be visited.
2198 * @G_TRAVERSE_MASK: a mask of all traverse flags.
2199 * @G_TRAVERSE_LEAFS: identical to %G_TRAVERSE_LEAVES.
2200 * @G_TRAVERSE_NON_LEAFS: identical to %G_TRAVERSE_NON_LEAVES.
2202 * Specifies which nodes are visited during several of the tree
2203 * functions, including g_node_traverse() and g_node_find().
2209 * @key: a key of a #GTree node
2210 * @value: the value corresponding to the key
2211 * @data: user data passed to g_tree_traverse()
2213 * Specifies the type of function passed to g_tree_traverse(). It is
2214 * passed the key and value of each node, together with the @user_data
2215 * parameter passed to g_tree_traverse(). If the function returns
2216 * %TRUE, the traversal is stopped.
2218 * Returns: %TRUE to stop the traversal
2224 * @G_IN_ORDER: vists a node's left child first, then the node itself,
2225 * then its right child. This is the one to use if you
2226 * want the output sorted according to the compare
2228 * @G_PRE_ORDER: visits a node, then its children.
2229 * @G_POST_ORDER: visits the node's children, then the node itself.
2230 * @G_LEVEL_ORDER: is not implemented for
2231 * [balanced binary trees][glib-Balanced-Binary-Trees].
2232 * For [n-ary trees][glib-N-ary-Trees], it
2233 * vists the root node first, then its children, then
2234 * its grandchildren, and so on. Note that this is less
2235 * efficient than the other orders.
2237 * Specifies the type of traveral performed by g_tree_traverse(),
2238 * g_node_traverse() and g_node_find(). The different orders are
2240 * - In order: A, B, C, D, E, F, G, H, I
2241 * ![](Sorted_binary_tree_inorder.svg)
2242 * - Pre order: F, B, A, D, C, E, G, I, H
2243 * ![](Sorted_binary_tree_preorder.svg)
2244 * - Post order: A, C, E, D, B, H, I, G, F
2245 * ![](Sorted_binary_tree_postorder.svg)
2246 * - Level order: F, B, G, A, D, I, C, E, H
2247 * ![](Sorted_binary_tree_breadth-first_traversal.svg)
2254 * The GTree struct is an opaque data structure representing a
2255 * [balanced binary tree][glib-Balanced-Binary-Trees]. It should be
2256 * accessed only by using the following functions.
2262 * @val: a #guint16 value in big-endian byte order
2264 * Converts a #guint16 value from big-endian to host byte order.
2266 * Returns: @val converted to host byte order
2272 * @val: a #guint16 value in little-endian byte order
2274 * Converts a #guint16 value from little-endian to host byte order.
2276 * Returns: @val converted to host byte order
2281 * GUINT16_SWAP_BE_PDP:
2282 * @val: a #guint16 value in big-endian or pdp-endian byte order
2284 * Converts a #guint16 value between big-endian and pdp-endian byte order.
2285 * The conversion is symmetric so it can be used both ways.
2287 * Returns: @val converted to the opposite byte order
2292 * GUINT16_SWAP_LE_BE:
2293 * @val: a #guint16 value in little-endian or big-endian byte order
2295 * Converts a #guint16 value between little-endian and big-endian byte order.
2296 * The conversion is symmetric so it can be used both ways.
2298 * Returns: @val converted to the opposite byte order
2303 * GUINT16_SWAP_LE_PDP:
2304 * @val: a #guint16 value in little-endian or pdp-endian byte order
2306 * Converts a #guint16 value between little-endian and pdp-endian byte order.
2307 * The conversion is symmetric so it can be used both ways.
2309 * Returns: @val converted to the opposite byte order
2315 * @val: a #guint16 value in host byte order
2317 * Converts a #guint16 value from host byte order to big-endian.
2319 * Returns: @val converted to big-endian
2325 * @val: a #guint16 value in host byte order
2327 * Converts a #guint16 value from host byte order to little-endian.
2329 * Returns: @val converted to little-endian
2335 * @val: a #guint32 value in big-endian byte order
2337 * Converts a #guint32 value from big-endian to host byte order.
2339 * Returns: @val converted to host byte order
2345 * @val: a #guint32 value in little-endian byte order
2347 * Converts a #guint32 value from little-endian to host byte order.
2349 * Returns: @val converted to host byte order
2354 * GUINT32_SWAP_BE_PDP:
2355 * @val: a #guint32 value in big-endian or pdp-endian byte order
2357 * Converts a #guint32 value between big-endian and pdp-endian byte order.
2358 * The conversion is symmetric so it can be used both ways.
2360 * Returns: @val converted to the opposite byte order
2365 * GUINT32_SWAP_LE_BE:
2366 * @val: a #guint32 value in little-endian or big-endian byte order
2368 * Converts a #guint32 value between little-endian and big-endian byte order.
2369 * The conversion is symmetric so it can be used both ways.
2371 * Returns: @val converted to the opposite byte order
2376 * GUINT32_SWAP_LE_PDP:
2377 * @val: a #guint32 value in little-endian or pdp-endian byte order
2379 * Converts a #guint32 value between little-endian and pdp-endian byte order.
2380 * The conversion is symmetric so it can be used both ways.
2382 * Returns: @val converted to the opposite byte order
2388 * @val: a #guint32 value in host byte order
2390 * Converts a #guint32 value from host byte order to big-endian.
2392 * Returns: @val converted to big-endian
2398 * @val: a #guint32 value in host byte order
2400 * Converts a #guint32 value from host byte order to little-endian.
2402 * Returns: @val converted to little-endian
2408 * @val: a #guint64 value in big-endian byte order
2410 * Converts a #guint64 value from big-endian to host byte order.
2412 * Returns: @val converted to host byte order
2418 * @val: a #guint64 value in little-endian byte order
2420 * Converts a #guint64 value from little-endian to host byte order.
2422 * Returns: @val converted to host byte order
2427 * GUINT64_SWAP_LE_BE:
2428 * @val: a #guint64 value in little-endian or big-endian byte order
2430 * Converts a #guint64 value between little-endian and big-endian byte order.
2431 * The conversion is symmetric so it can be used both ways.
2433 * Returns: @val converted to the opposite byte order
2439 * @val: a #guint64 value in host byte order
2441 * Converts a #guint64 value from host byte order to big-endian.
2443 * Returns: @val converted to big-endian
2449 * @val: a #guint64 value in host byte order
2451 * Converts a #guint64 value from host byte order to little-endian.
2453 * Returns: @val converted to little-endian
2459 * @val: a #guint value in big-endian byte order
2461 * Converts a #guint value from big-endian to host byte order.
2463 * Returns: @val converted to host byte order
2469 * @val: a #guint value in little-endian byte order
2471 * Converts a #guint value from little-endian to host byte order.
2473 * Returns: @val converted to host byte order
2479 * @val: a #guint value in host byte order
2481 * Converts a #guint value from host byte order to big-endian.
2483 * Returns: @val converted to big-endian byte order
2489 * @val: a #guint value in host byte order
2491 * Converts a #guint value from host byte order to little-endian.
2493 * Returns: @val converted to little-endian byte order.
2499 * @u: unsigned integer to stuff into the pointer
2501 * Stuffs an unsigned integer into a pointer type.
2507 * @val: a #gulong value in big-endian byte order
2509 * Converts a #gulong value from big-endian to host byte order.
2511 * Returns: @val converted to host byte order
2517 * @val: a #gulong value in little-endian byte order
2519 * Converts a #gulong value from little-endian to host byte order.
2521 * Returns: @val converted to host byte order
2527 * @val: a #gulong value in host byte order
2529 * Converts a #gulong value from host byte order to big-endian.
2531 * Returns: @val converted to big-endian
2537 * @val: a #gulong value in host byte order
2539 * Converts a #gulong value from host byte order to little-endian.
2541 * Returns: @val converted to little-endian
2548 * #GVariant is an opaque data structure and can only be accessed
2549 * using the following functions.
2558 * A utility type for constructing container-type #GVariant instances.
2560 * This is an opaque structure and may only be accessed using the
2561 * following functions.
2563 * #GVariantBuilder is not threadsafe in any way. Do not attempt to
2564 * access it from more than one thread.
2570 * @G_VARIANT_CLASS_BOOLEAN: The #GVariant is a boolean.
2571 * @G_VARIANT_CLASS_BYTE: The #GVariant is a byte.
2572 * @G_VARIANT_CLASS_INT16: The #GVariant is a signed 16 bit integer.
2573 * @G_VARIANT_CLASS_UINT16: The #GVariant is an unsigned 16 bit integer.
2574 * @G_VARIANT_CLASS_INT32: The #GVariant is a signed 32 bit integer.
2575 * @G_VARIANT_CLASS_UINT32: The #GVariant is an unsigned 32 bit integer.
2576 * @G_VARIANT_CLASS_INT64: The #GVariant is a signed 64 bit integer.
2577 * @G_VARIANT_CLASS_UINT64: The #GVariant is an unsigned 64 bit integer.
2578 * @G_VARIANT_CLASS_HANDLE: The #GVariant is a file handle index.
2579 * @G_VARIANT_CLASS_DOUBLE: The #GVariant is a double precision floating
2581 * @G_VARIANT_CLASS_STRING: The #GVariant is a normal string.
2582 * @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a D-Bus object path
2584 * @G_VARIANT_CLASS_SIGNATURE: The #GVariant is a D-Bus signature string.
2585 * @G_VARIANT_CLASS_VARIANT: The #GVariant is a variant.
2586 * @G_VARIANT_CLASS_MAYBE: The #GVariant is a maybe-typed value.
2587 * @G_VARIANT_CLASS_ARRAY: The #GVariant is an array.
2588 * @G_VARIANT_CLASS_TUPLE: The #GVariant is a tuple.
2589 * @G_VARIANT_CLASS_DICT_ENTRY: The #GVariant is a dictionary entry.
2591 * The range of possible top-level types of #GVariant instances.
2600 * #GVariantDict is a mutable interface to #GVariant dictionaries.
2602 * It can be used for doing a sequence of dictionary lookups in an
2603 * efficient way on an existing #GVariant dictionary or it can be used
2604 * to construct new dictionaries with a hashtable-like interface. It
2605 * can also be used for taking existing dictionaries and modifying them
2606 * in order to create new ones.
2608 * #GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT
2611 * It is possible to use #GVariantDict allocated on the stack or on the
2612 * heap. When using a stack-allocated #GVariantDict, you begin with a
2613 * call to g_variant_dict_init() and free the resources with a call to
2614 * g_variant_dict_clear().
2616 * Heap-allocated #GVariantDict follows normal refcounting rules: you
2617 * allocate it with g_variant_dict_new() and use g_variant_dict_ref()
2618 * and g_variant_dict_unref().
2620 * g_variant_dict_end() is used to convert the #GVariantDict back into a
2621 * dictionary-type #GVariant. When used with stack-allocated instances,
2622 * this also implicitly frees all associated memory, but for
2623 * heap-allocated instances, you must still call g_variant_dict_unref()
2626 * You will typically want to use a heap-allocated #GVariantDict when
2627 * you expose it as part of an API. For most other uses, the
2628 * stack-allocated form will be more convenient.
2630 * Consider the following two examples that do the same thing in each
2631 * style: take an existing dictionary and look up the "count" uint32
2632 * key, adding 1 to it if it is found, or returning an error if the
2633 * key is not found. Each returns the new dictionary as a floating
2636 * ## Using a stack-allocated GVariantDict
2638 * |[<!-- language="C" -->
2640 * add_to_count (GVariant *orig,
2643 * GVariantDict dict;
2646 * g_variant_dict_init (&dict, orig);
2647 * if (!g_variant_dict_lookup (&dict, "count", "u", &count))
2649 * g_set_error (...);
2650 * g_variant_dict_clear (&dict);
2654 * g_variant_dict_insert (&dict, "count", "u", count + 1);
2656 * return g_variant_dict_end (&dict);
2660 * ## Using heap-allocated GVariantDict
2662 * |[<!-- language="C" -->
2664 * add_to_count (GVariant *orig,
2667 * GVariantDict *dict;
2671 * dict = g_variant_dict_new (orig);
2673 * if (g_variant_dict_lookup (dict, "count", "u", &count))
2675 * g_variant_dict_insert (dict, "count", "u", count + 1);
2676 * result = g_variant_dict_end (dict);
2680 * g_set_error (...);
2684 * g_variant_dict_unref (dict);
2695 * GVariantIter: (skip)
2697 * #GVariantIter is an opaque data structure and can only be accessed
2698 * using the following functions.
2703 * GVariantParseError:
2704 * @G_VARIANT_PARSE_ERROR_FAILED: generic error (unused)
2705 * @G_VARIANT_PARSE_ERROR_BASIC_TYPE_EXPECTED: a non-basic #GVariantType was given where a basic type was expected
2706 * @G_VARIANT_PARSE_ERROR_CANNOT_INFER_TYPE: cannot infer the #GVariantType
2707 * @G_VARIANT_PARSE_ERROR_DEFINITE_TYPE_EXPECTED: an indefinite #GVariantType was given where a definite type was expected
2708 * @G_VARIANT_PARSE_ERROR_INPUT_NOT_AT_END: extra data after parsing finished
2709 * @G_VARIANT_PARSE_ERROR_INVALID_CHARACTER: invalid character in number or unicode escape
2710 * @G_VARIANT_PARSE_ERROR_INVALID_FORMAT_STRING: not a valid #GVariant format string
2711 * @G_VARIANT_PARSE_ERROR_INVALID_OBJECT_PATH: not a valid object path
2712 * @G_VARIANT_PARSE_ERROR_INVALID_SIGNATURE: not a valid type signature
2713 * @G_VARIANT_PARSE_ERROR_INVALID_TYPE_STRING: not a valid #GVariant type string
2714 * @G_VARIANT_PARSE_ERROR_NO_COMMON_TYPE: could not find a common type for array entries
2715 * @G_VARIANT_PARSE_ERROR_NUMBER_OUT_OF_RANGE: the numerical value is out of range of the given type
2716 * @G_VARIANT_PARSE_ERROR_NUMBER_TOO_BIG: the numerical value is out of range for any type
2717 * @G_VARIANT_PARSE_ERROR_TYPE_ERROR: cannot parse as variant of the specified type
2718 * @G_VARIANT_PARSE_ERROR_UNEXPECTED_TOKEN: an unexpected token was encountered
2719 * @G_VARIANT_PARSE_ERROR_UNKNOWN_KEYWORD: an unknown keyword was encountered
2720 * @G_VARIANT_PARSE_ERROR_UNTERMINATED_STRING_CONSTANT: unterminated string constant
2721 * @G_VARIANT_PARSE_ERROR_VALUE_EXPECTED: no value given
2723 * Error codes returned by parsing text-format GVariants.
2728 * G_ASCII_DTOSTR_BUF_SIZE:
2730 * A good size for a buffer to be passed into g_ascii_dtostr().
2731 * It is guaranteed to be enough for all output of that function
2732 * on systems with 64bit IEEE-compatible doubles.
2734 * The typical usage would be something like:
2735 * |[<!-- language="C" -->
2736 * char buf[G_ASCII_DTOSTR_BUF_SIZE];
2738 * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
2744 * G_ATOMIC_LOCK_FREE:
2746 * This macro is defined if the atomic operations of GLib are
2747 * implemented using real hardware atomic operations. This means that
2748 * the GLib atomic API can be used between processes and safely mixed
2749 * with other (hardware) atomic APIs.
2751 * If this macro is not defined, the atomic operations may be
2752 * emulated using a mutex. In that case, the GLib atomic operations are
2753 * only atomic relative to themselves and within a single process.
2760 * Used (along with #G_END_DECLS) to bracket header files. If the
2761 * compiler in use is a C++ compiler, adds extern "C"
2762 * around the header.
2769 * Specifies one of the possible types of byte order.
2770 * See #G_BYTE_ORDER.
2777 * The host byte order.
2778 * This can be either #G_LITTLE_ENDIAN or #G_BIG_ENDIAN (support for
2779 * #G_PDP_ENDIAN may be added in future.)
2786 * If %G_DISABLE_CONST_RETURNS is defined, this macro expands
2787 * to nothing. By default, the macro expands to const. The macro
2788 * can be used in place of const for functions that return a value
2789 * that should not be modified. The purpose of this macro is to allow
2790 * us to turn on const for returned constant strings by default, while
2791 * allowing programmers who find that annoying to turn it off. This macro
2792 * should only be used for return values and for "out" parameters, it
2793 * doesn't make sense for "in" parameters.
2795 * Deprecated: 2.30: API providers should replace all existing uses with
2796 * const and API consumers should adjust their code accordingly
2803 * The set of uppercase ASCII alphabet characters.
2804 * Used for specifying valid identifier characters
2805 * in #GScannerConfig.
2812 * The set of ASCII digits.
2813 * Used for specifying valid identifier characters
2814 * in #GScannerConfig.
2821 * The set of uppercase ISO 8859-1 alphabet characters
2822 * which are not ASCII characters.
2823 * Used for specifying valid identifier characters
2824 * in #GScannerConfig.
2831 * The set of lowercase ISO 8859-1 alphabet characters
2832 * which are not ASCII characters.
2833 * Used for specifying valid identifier characters
2834 * in #GScannerConfig.
2841 * The set of lowercase ASCII alphabet characters.
2842 * Used for specifying valid identifier characters
2843 * in #GScannerConfig.
2850 * Represents an invalid #GDateDay.
2855 * G_DATE_BAD_JULIAN:
2857 * Represents an invalid Julian day number.
2864 * Represents an invalid year.
2869 * G_DEFINE_AUTOPTR_CLEANUP_FUNC:
2870 * @TypeName: a type name to define a g_autoptr() cleanup function for
2871 * @func: the cleanup function
2873 * Defines the appropriate cleanup function for a pointer type.
2875 * The function will not be called if the variable to be cleaned up
2878 * This will typically be the _free() or _unref() function for the given
2881 * With this definition, it will be possible to use g_autoptr() with
2885 * G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref)
2888 * This macro should be used unconditionally; it is a no-op on compilers
2889 * where cleanup is not supported.
2896 * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC:
2897 * @TypeName: a type name to define a g_auto() cleanup function for
2898 * @func: the clear function
2900 * Defines the appropriate cleanup function for a type.
2902 * This will typically be the _clear() function for the given type.
2904 * With this definition, it will be possible to use g_auto() with
2908 * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear)
2911 * This macro should be used unconditionally; it is a no-op on compilers
2912 * where cleanup is not supported.
2919 * G_DEFINE_AUTO_CLEANUP_FREE_FUNC:
2920 * @TypeName: a type name to define a g_auto() cleanup function for
2921 * @func: the free function
2922 * @none: the "none" value for the type
2924 * Defines the appropriate cleanup function for a type.
2926 * With this definition, it will be possible to use g_auto() with
2929 * This function will be rarely used. It is used with pointer-based
2930 * typedefs and non-pointer types where the value of the variable
2931 * represents a resource that must be freed. Two examples are #GStrv
2932 * and file descriptors.
2934 * @none specifies the "none" value for the type in question. It is
2935 * probably something like %NULL or -1. If the variable is found to
2936 * contain this value then the free function will not be called.
2939 * G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL)
2942 * This macro should be used unconditionally; it is a no-op on compilers
2943 * where cleanup is not supported.
2951 * @QN: the name to return a #GQuark for
2952 * @q_n: prefix for the function name
2954 * A convenience macro which defines a function returning the
2955 * #GQuark for the name @QN. The function will be named
2958 * Note that the quark name will be stringified automatically
2959 * in the macro, so you shouldn't use double quotes.
2968 * This macro is similar to %G_GNUC_DEPRECATED, and can be used to mark
2969 * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED, it is
2970 * meant to be portable across different compilers and must be placed
2971 * before the function declaration.
2979 * @f: the name of the function that this function was deprecated for
2981 * This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark
2982 * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it
2983 * is meant to be portable across different compilers and must be placed
2984 * before the function declaration.
2993 * The directory separator character.
2994 * This is '/' on UNIX machines and '\' under Windows.
2999 * G_DIR_SEPARATOR_S:
3001 * The directory separator as a string.
3002 * This is "/" on UNIX machines and "\" under Windows.
3009 * The base of natural logarithms.
3016 * Used (along with #G_BEGIN_DECLS) to bracket header files. If the
3017 * compiler in use is a C++ compiler, adds extern "C"
3018 * around the header.
3025 * Error domain for file operations. Errors in this domain will
3026 * be from the #GFileError enumeration. See #GError for information
3034 * This is the platform dependent conversion specifier for scanning and
3035 * printing values of type #gint16. It is a string literal, but doesn't
3036 * include the percent-sign, such that you can add precision and length
3037 * modifiers between percent-sign and conversion specifier.
3039 * |[<!-- language="C" -->
3042 * sscanf ("42", "%" G_GINT16_FORMAT, &in)
3044 * g_print ("%" G_GINT32_FORMAT, out);
3050 * G_GINT16_MODIFIER:
3052 * The platform dependent length modifier for conversion specifiers
3053 * for scanning and printing values of type #gint16 or #guint16. It
3054 * is a string literal, but doesn't include the percent-sign, such
3055 * that you can add precision and length modifiers between percent-sign
3056 * and conversion specifier and append a conversion specifier.
3058 * The following example prints "0x7b";
3059 * |[<!-- language="C" -->
3060 * gint16 value = 123;
3061 * g_print ("%#" G_GINT16_MODIFIER "x", value);
3071 * This is the platform dependent conversion specifier for scanning
3072 * and printing values of type #gint32. See also #G_GINT16_FORMAT.
3077 * G_GINT32_MODIFIER:
3079 * The platform dependent length modifier for conversion specifiers
3080 * for scanning and printing values of type #gint32 or #guint32. It
3081 * is a string literal. See also #G_GINT16_MODIFIER.
3088 * G_GINT64_CONSTANT:
3089 * @val: a literal integer value, e.g. 0x1d636b02300a7aa7
3091 * This macro is used to insert 64-bit integer literals
3092 * into the source code.
3099 * This is the platform dependent conversion specifier for scanning
3100 * and printing values of type #gint64. See also #G_GINT16_FORMAT.
3102 * Some platforms do not support scanning and printing 64-bit integers,
3103 * even though the types are supported. On such platforms %G_GINT64_FORMAT
3104 * is not defined. Note that scanf() may not support 64-bit integers, even
3105 * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
3106 * is not recommended for parsing anyway; consider using g_ascii_strtoull()
3112 * G_GINT64_MODIFIER:
3114 * The platform dependent length modifier for conversion specifiers
3115 * for scanning and printing values of type #gint64 or #guint64.
3116 * It is a string literal.
3118 * Some platforms do not support printing 64-bit integers, even
3119 * though the types are supported. On such platforms %G_GINT64_MODIFIER
3129 * This is the platform dependent conversion specifier for scanning
3130 * and printing values of type #gintptr.
3137 * G_GINTPTR_MODIFIER:
3139 * The platform dependent length modifier for conversion specifiers
3140 * for scanning and printing values of type #gintptr or #guintptr.
3141 * It is a string literal.
3148 * G_GNUC_ALLOC_SIZE:
3149 * @x: the index of the argument specifying the allocation size
3151 * Expands to the GNU C alloc_size function attribute if the compiler
3152 * is a new enough gcc. This attribute tells the compiler that the
3153 * function returns a pointer to memory of a size that is specified
3154 * by the @xth function parameter.
3156 * Place the attribute after the function declaration, just before the
3159 * See the GNU C documentation for more details.
3166 * G_GNUC_ALLOC_SIZE2:
3167 * @x: the index of the argument specifying one factor of the allocation size
3168 * @y: the index of the argument specifying the second factor of the allocation size
3170 * Expands to the GNU C alloc_size function attribute if the compiler is a
3171 * new enough gcc. This attribute tells the compiler that the function returns
3172 * a pointer to memory of a size that is specified by the product of two
3173 * function parameters.
3175 * Place the attribute after the function declaration, just before the
3178 * See the GNU C documentation for more details.
3185 * G_GNUC_BEGIN_IGNORE_DEPRECATIONS:
3187 * Tells gcc (if it is a new enough version) to temporarily stop emitting
3188 * warnings when functions marked with %G_GNUC_DEPRECATED or
3189 * %G_GNUC_DEPRECATED_FOR are called. This is useful for when you have
3190 * one deprecated function calling another one, or when you still have
3191 * regression tests for deprecated functions.
3193 * Use %G_GNUC_END_IGNORE_DEPRECATIONS to begin warning again. (If you
3194 * are not compiling with `-Wdeprecated-declarations` then neither macro
3197 * This macro can be used either inside or outside of a function body,
3198 * but must appear on a line by itself.
3205 * G_GNUC_CHECK_VERSION:
3207 * Expands to a a check for a compiler with __GNUC__ defined and a version
3208 * greater than or equal to the major and minor numbers provided. For example,
3209 * the following would only match on compilers such as GCC 4.8 or newer.
3211 * |[<!-- language="C" -->
3212 * #if G_GNUC_CHECK_VERSION(4, 8)
3223 * Expands to the GNU C const function attribute if the compiler is gcc.
3224 * Declaring a function as const enables better optimization of calls to
3225 * the function. A const function doesn't examine any values except its
3226 * parameters, and has no effects except its return value.
3228 * Place the attribute after the declaration, just before the semicolon.
3230 * See the GNU C documentation for more details.
3232 * A function that has pointer arguments and examines the data pointed to
3233 * must not be declared const. Likewise, a function that calls a non-const
3234 * function usually must not be const. It doesn't make sense for a const
3235 * function to return void.
3240 * G_GNUC_DEPRECATED:
3242 * Expands to the GNU C deprecated attribute if the compiler is gcc.
3243 * It can be used to mark typedefs, variables and functions as deprecated.
3244 * When called with the `-Wdeprecated-declarations` option,
3245 * gcc will generate warnings when deprecated interfaces are used.
3247 * Place the attribute after the declaration, just before the semicolon.
3249 * See the GNU C documentation for more details.
3256 * G_GNUC_DEPRECATED_FOR:
3257 * @f: the intended replacement for the deprecated symbol,
3258 * such as the name of a function
3260 * Like %G_GNUC_DEPRECATED, but names the intended replacement for the
3261 * deprecated symbol if the version of gcc in use is new enough to support
3262 * custom deprecation messages.
3264 * Place the attribute after the declaration, just before the semicolon.
3266 * See the GNU C documentation for more details.
3268 * Note that if @f is a macro, it will be expanded in the warning message.
3269 * You can enclose it in quotes to prevent this. (The quotes will show up
3270 * in the warning, but it's better than showing the macro expansion.)
3277 * G_GNUC_END_IGNORE_DEPRECATIONS:
3279 * Undoes the effect of %G_GNUC_BEGIN_IGNORE_DEPRECATIONS, telling
3280 * gcc to begin outputting warnings again (assuming those warnings
3281 * had been enabled to begin with).
3283 * This macro can be used either inside or outside of a function body,
3284 * but must appear on a line by itself.
3293 * Expands to __extension__ when gcc is used as the compiler. This simply
3294 * tells gcc not to warn about the following non-standard code when compiling
3295 * with the `-pedantic` option.
3301 * @arg_idx: the index of the argument
3303 * Expands to the GNU C format_arg function attribute if the compiler
3304 * is gcc. This function attribute specifies that a function takes a
3305 * format string for a printf(), scanf(), strftime() or strfmon() style
3306 * function and modifies it, so that the result can be passed to a printf(),
3307 * scanf(), strftime() or strfmon() style function (with the remaining
3308 * arguments to the format function the same as they would have been
3309 * for the unmodified string).
3311 * Place the attribute after the function declaration, just before the
3314 * See the GNU C documentation for more details.
3316 * |[<!-- language="C" -->
3317 * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
3325 * Expands to "" on all modern compilers, and to __FUNCTION__ on gcc
3326 * version 2.x. Don't use it.
3328 * Deprecated: 2.16: Use G_STRFUNC() instead
3335 * This attribute can be used for marking library functions as being used
3336 * internally to the library only, which may allow the compiler to handle
3337 * function calls more efficiently. Note that static functions do not need
3338 * to be marked as internal in this way. See the GNU C documentation for
3341 * When using a compiler that supports the GNU C hidden visibility attribute,
3342 * this macro expands to __attribute__((visibility("hidden"))).
3343 * When using the Sun Studio compiler, it expands to __hidden.
3345 * Note that for portability, the attribute should be placed before the
3346 * function declaration. While GCC allows the macro after the declaration,
3347 * Sun Studio does not.
3349 * |[<!-- language="C" -->
3351 * void _g_log_fallback_handler (const gchar *log_domain,
3352 * GLogLevelFlags log_level,
3353 * const gchar *message,
3354 * gpointer unused_data);
3364 * Expands to the GNU C malloc function attribute if the compiler is gcc.
3365 * Declaring a function as malloc enables better optimization of the function.
3366 * A function can have the malloc attribute if it returns a pointer which is
3367 * guaranteed to not alias with any other pointer when the function returns
3368 * (in practice, this means newly allocated memory).
3370 * Place the attribute after the declaration, just before the semicolon.
3372 * See the GNU C documentation for more details.
3381 * Expands to the GNU C may_alias type attribute if the compiler is gcc.
3382 * Types with this attribute will not be subjected to type-based alias
3383 * analysis, but are assumed to alias with any other type, just like char.
3385 * See the GNU C documentation for details.
3394 * Expands to the GNU C noreturn function attribute if the compiler is gcc.
3395 * It is used for declaring functions which never return. It enables
3396 * optimization of the function, and avoids possible compiler warnings.
3398 * Place the attribute after the declaration, just before the semicolon.
3400 * See the GNU C documentation for more details.
3405 * G_GNUC_NO_INSTRUMENT:
3407 * Expands to the GNU C no_instrument_function function attribute if the
3408 * compiler is gcc. Functions with this attribute will not be instrumented
3409 * for profiling, when the compiler is called with the
3410 * `-finstrument-functions` option.
3412 * Place the attribute after the declaration, just before the semicolon.
3414 * See the GNU C documentation for more details.
3419 * G_GNUC_NULL_TERMINATED:
3421 * Expands to the GNU C sentinel function attribute if the compiler is gcc.
3422 * This function attribute only applies to variadic functions and instructs
3423 * the compiler to check that the argument list is terminated with an
3426 * Place the attribute after the declaration, just before the semicolon.
3428 * See the GNU C documentation for more details.
3435 * G_GNUC_PRETTY_FUNCTION:
3437 * Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__
3438 * on gcc version 2.x. Don't use it.
3440 * Deprecated: 2.16: Use G_STRFUNC() instead
3446 * @format_idx: the index of the argument corresponding to the
3447 * format string (The arguments are numbered from 1)
3448 * @arg_idx: the index of the first of the format arguments
3450 * Expands to the GNU C format function attribute if the compiler is gcc.
3451 * This is used for declaring functions which take a variable number of
3452 * arguments, with the same syntax as printf(). It allows the compiler
3453 * to type-check the arguments passed to the function.
3455 * Place the attribute after the function declaration, just before the
3458 * See the GNU C documentation for more details.
3460 * |[<!-- language="C" -->
3461 * gint g_snprintf (gchar *string,
3463 * gchar const *format,
3464 * ...) G_GNUC_PRINTF (3, 4);
3472 * Expands to the GNU C pure function attribute if the compiler is gcc.
3473 * Declaring a function as pure enables better optimization of calls to
3474 * the function. A pure function has no effects except its return value
3475 * and the return value depends only on the parameters and/or global
3478 * Place the attribute after the declaration, just before the semicolon.
3480 * See the GNU C documentation for more details.
3486 * @format_idx: the index of the argument corresponding to
3487 * the format string (The arguments are numbered from 1)
3488 * @arg_idx: the index of the first of the format arguments
3490 * Expands to the GNU C format function attribute if the compiler is gcc.
3491 * This is used for declaring functions which take a variable number of
3492 * arguments, with the same syntax as scanf(). It allows the compiler
3493 * to type-check the arguments passed to the function.
3495 * See the GNU C documentation for details.
3502 * Expands to the GNU C unused function attribute if the compiler is gcc.
3503 * It is used for declaring functions and arguments which may never be used.
3504 * It avoids possible compiler warnings.
3506 * For functions, place the attribute after the declaration, just before the
3507 * semicolon. For arguments, place the attribute at the beginning of the
3508 * argument declaration.
3510 * |[<!-- language="C" -->
3511 * void my_unused_function (G_GNUC_UNUSED gint unused_argument,
3512 * gint other_argument) G_GNUC_UNUSED;
3515 * See the GNU C documentation for more details.
3520 * G_GNUC_WARN_UNUSED_RESULT:
3522 * Expands to the GNU C warn_unused_result function attribute if the compiler
3523 * is gcc. This function attribute makes the compiler emit a warning if the
3524 * result of a function call is ignored.
3526 * Place the attribute after the declaration, just before the semicolon.
3528 * See the GNU C documentation for more details.
3535 * G_GOFFSET_CONSTANT:
3536 * @val: a literal integer value, e.g. 0x1d636b02300a7aa7
3538 * This macro is used to insert #goffset 64-bit integer literals
3539 * into the source code.
3541 * See also #G_GINT64_CONSTANT.
3550 * This is the platform dependent conversion specifier for scanning
3551 * and printing values of type #goffset. See also #G_GINT64_FORMAT.
3558 * G_GOFFSET_MODIFIER:
3560 * The platform dependent length modifier for conversion specifiers
3561 * for scanning and printing values of type #goffset. It is a string
3562 * literal. See also #G_GINT64_MODIFIER.
3571 * This is the platform dependent conversion specifier for scanning
3572 * and printing values of type #gsize. See also #G_GINT16_FORMAT.
3581 * The platform dependent length modifier for conversion specifiers
3582 * for scanning and printing values of type #gsize. It
3583 * is a string literal.
3592 * This is the platform dependent conversion specifier for scanning
3593 * and printing values of type #gssize. See also #G_GINT16_FORMAT.
3600 * G_GSSIZE_MODIFIER:
3602 * The platform dependent length modifier for conversion specifiers
3603 * for scanning and printing values of type #gssize. It
3604 * is a string literal.
3613 * This is the platform dependent conversion specifier for scanning
3614 * and printing values of type #guint16. See also #G_GINT16_FORMAT
3621 * This is the platform dependent conversion specifier for scanning
3622 * and printing values of type #guint32. See also #G_GINT16_FORMAT.
3627 * G_GUINT64_CONSTANT:
3628 * @val: a literal integer value, e.g. 0x1d636b02300a7aa7U
3630 * This macro is used to insert 64-bit unsigned integer
3631 * literals into the source code.
3640 * This is the platform dependent conversion specifier for scanning
3641 * and printing values of type #guint64. See also #G_GINT16_FORMAT.
3643 * Some platforms do not support scanning and printing 64-bit integers,
3644 * even though the types are supported. On such platforms %G_GUINT64_FORMAT
3645 * is not defined. Note that scanf() may not support 64-bit integers, even
3646 * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
3647 * is not recommended for parsing anyway; consider using g_ascii_strtoull()
3653 * G_GUINTPTR_FORMAT:
3655 * This is the platform dependent conversion specifier
3656 * for scanning and printing values of type #guintptr.
3663 * G_HAVE_GNUC_VISIBILITY:
3665 * Defined to 1 if gcc-style visibility handling is supported.
3673 * Casts a pointer to a `GHook*`.
3681 * Returns %TRUE if the #GHook is active, which is normally the case
3682 * until the #GHook is destroyed.
3684 * Returns: %TRUE if the #GHook is active
3692 * Gets the flags of a hook.
3697 * G_HOOK_FLAG_USER_SHIFT:
3699 * The position of the first bit which is not reserved for internal
3700 * use be the #GHook implementation, i.e.
3701 * `1 << G_HOOK_FLAG_USER_SHIFT` is the first
3702 * bit which can be used for application-defined flags.
3710 * Returns %TRUE if the #GHook function is currently executing.
3712 * Returns: %TRUE if the #GHook function is currently executing
3717 * G_HOOK_IS_UNLINKED:
3720 * Returns %TRUE if the #GHook is not in a #GHookList.
3722 * Returns: %TRUE if the #GHook is not in a #GHookList
3730 * Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList,
3731 * it is active and it has not been destroyed.
3733 * Returns: %TRUE if the #GHook is valid
3738 * G_IEEE754_DOUBLE_BIAS:
3740 * The bias by which exponents in double-precision floats are offset.
3745 * G_IEEE754_FLOAT_BIAS:
3747 * The bias by which exponents in single-precision floats are offset.
3754 * This macro used to be used to conditionally define inline functions
3755 * in a compatible way before this feature was supported in all
3756 * compilers. These days, GLib requires inlining support from the
3757 * compiler, so your GLib-using programs can safely assume that the
3758 * "inline" keywork works properly.
3760 * Never use this macro anymore. Just say "static inline".
3762 * Deprecated: 2.48: Use "static inline" instead
3767 * G_IO_CHANNEL_ERROR:
3769 * Error domain for #GIOChannel operations. Errors in this domain will
3770 * be from the #GIOChannelError enumeration. See #GError for
3771 * information on error domains.
3776 * G_IS_DIR_SEPARATOR:
3779 * Checks whether a character is a directory
3780 * separator. It returns %TRUE for '/' on UNIX
3781 * machines and for '\' or '/' under Windows.
3788 * G_KEY_FILE_DESKTOP_GROUP:
3790 * The name of the main group of a desktop entry file, as defined in the
3791 * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec).
3792 * Consult the specification for more
3793 * details about the meanings of the keys below.
3800 * G_KEY_FILE_DESKTOP_KEY_ACTIONS:
3802 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string list
3803 * giving the available application actions.
3810 * G_KEY_FILE_DESKTOP_KEY_CATEGORIES:
3812 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list
3813 * of strings giving the categories in which the desktop entry
3814 * should be shown in a menu.
3821 * G_KEY_FILE_DESKTOP_KEY_COMMENT:
3823 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
3824 * string giving the tooltip for the desktop entry.
3831 * G_KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE:
3833 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean set to true
3834 * if the application is D-Bus activatable.
3841 * G_KEY_FILE_DESKTOP_KEY_EXEC:
3843 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
3844 * giving the command line to execute. It is only valid for desktop
3845 * entries with the `Application` type.
3852 * G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME:
3854 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
3855 * string giving the generic name of the desktop entry.
3862 * G_KEY_FILE_DESKTOP_KEY_HIDDEN:
3864 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
3865 * stating whether the desktop entry has been deleted by the user.
3872 * G_KEY_FILE_DESKTOP_KEY_ICON:
3874 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
3875 * string giving the name of the icon to be displayed for the desktop
3883 * G_KEY_FILE_DESKTOP_KEY_MIME_TYPE:
3885 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list
3886 * of strings giving the MIME types supported by this desktop entry.
3893 * G_KEY_FILE_DESKTOP_KEY_NAME:
3895 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
3896 * string giving the specific name of the desktop entry.
3903 * G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN:
3905 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
3906 * strings identifying the environments that should not display the
3914 * G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY:
3916 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
3917 * stating whether the desktop entry should be shown in menus.
3924 * G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN:
3926 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
3927 * strings identifying the environments that should display the
3935 * G_KEY_FILE_DESKTOP_KEY_PATH:
3937 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
3938 * containing the working directory to run the program in. It is only
3939 * valid for desktop entries with the `Application` type.
3946 * G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY:
3948 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
3949 * stating whether the application supports the
3950 * [Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec).
3957 * G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS:
3959 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is string
3960 * identifying the WM class or name hint of a window that the application
3961 * will create, which can be used to emulate Startup Notification with
3962 * older applications.
3969 * G_KEY_FILE_DESKTOP_KEY_TERMINAL:
3971 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
3972 * stating whether the program should be run in a terminal window.
3973 * It is only valid for desktop entries with the
3974 * `Application` type.
3981 * G_KEY_FILE_DESKTOP_KEY_TRY_EXEC:
3983 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
3984 * giving the file name of a binary on disk used to determine if the
3985 * program is actually installed. It is only valid for desktop entries
3986 * with the `Application` type.
3993 * G_KEY_FILE_DESKTOP_KEY_TYPE:
3995 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
3996 * giving the type of the desktop entry. Usually
3997 * #G_KEY_FILE_DESKTOP_TYPE_APPLICATION,
3998 * #G_KEY_FILE_DESKTOP_TYPE_LINK, or
3999 * #G_KEY_FILE_DESKTOP_TYPE_DIRECTORY.
4006 * G_KEY_FILE_DESKTOP_KEY_URL:
4008 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
4009 * giving the URL to access. It is only valid for desktop entries
4010 * with the `Link` type.
4017 * G_KEY_FILE_DESKTOP_KEY_VERSION:
4019 * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
4020 * giving the version of the Desktop Entry Specification used for
4021 * the desktop entry file.
4028 * G_KEY_FILE_DESKTOP_TYPE_APPLICATION:
4030 * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
4031 * entries representing applications.
4038 * G_KEY_FILE_DESKTOP_TYPE_DIRECTORY:
4040 * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
4041 * entries representing directories.
4048 * G_KEY_FILE_DESKTOP_TYPE_LINK:
4050 * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
4051 * entries representing links to documents.
4060 * Error domain for key file parsing. Errors in this domain will
4061 * be from the #GKeyFileError enumeration.
4063 * See #GError for information on error domains.
4069 * @expr: the expression
4071 * Hints the compiler that the expression is likely to evaluate to
4072 * a true value. The compiler may use this information for optimizations.
4074 * |[<!-- language="C" -->
4075 * if (G_LIKELY (random () != 1))
4076 * g_print ("not one");
4079 * Returns: the value of @expr
4087 * Specifies one of the possible types of byte order.
4088 * See #G_BYTE_ORDER.
4095 * The natural logarithm of 10.
4102 * The natural logarithm of 2.
4108 * @name: the name of the lock
4110 * Works like g_mutex_lock(), but for a lock defined with
4117 * @name: the name of the lock
4119 * The #G_LOCK_ macros provide a convenient interface to #GMutex.
4120 * #G_LOCK_DEFINE defines a lock. It can appear in any place where
4121 * variable definitions may appear in programs, i.e. in the first block
4122 * of a function or outside of functions. The @name parameter will be
4123 * mangled to get the name of the #GMutex. This means that you
4124 * can use names of existing variables as the parameter - e.g. the name
4125 * of the variable you intend to protect with the lock. Look at our
4126 * give_me_next_number() example using the #G_LOCK macros:
4128 * Here is an example for using the #G_LOCK convenience macros:
4129 * |[<!-- language="C" -->
4130 * G_LOCK_DEFINE (current_number);
4133 * give_me_next_number (void)
4135 * static int current_number = 0;
4138 * G_LOCK (current_number);
4139 * ret_val = current_number = calc_next_number (current_number);
4140 * G_UNLOCK (current_number);
4149 * G_LOCK_DEFINE_STATIC:
4150 * @name: the name of the lock
4152 * This works like #G_LOCK_DEFINE, but it creates a static object.
4158 * @name: the name of the lock
4160 * This declares a lock, that is defined with #G_LOCK_DEFINE in another
4168 * Multiplying the base 2 exponent by this number yields the base 10 exponent.
4175 * Defines the log domain.
4177 * For applications, this is typically left as the default %NULL
4178 * (or "") domain. Libraries should define this so that any messages
4179 * which they log can be differentiated from messages from other
4180 * libraries and application code. But be careful not to define
4181 * it in any public header files.
4183 * For example, GTK+ uses this in its Makefile.am:
4185 * AM_CPPFLAGS = -DG_LOG_DOMAIN=\"Gtk\"
4193 * GLib log levels that are considered fatal by default.
4198 * G_LOG_LEVEL_USER_SHIFT:
4200 * Log levels below 1<<G_LOG_LEVEL_USER_SHIFT are used by GLib.
4201 * Higher bits can be used for user-defined log levels.
4208 * The maximum value which can be held in a #gdouble.
4215 * The maximum value which can be held in a #gfloat.
4222 * The maximum value which can be held in a #gint.
4229 * The maximum value which can be held in a #gint16.
4238 * The maximum value which can be held in a #gint32.
4247 * The maximum value which can be held in a #gint64.
4254 * The maximum value which can be held in a #gint8.
4263 * The maximum value which can be held in a #glong.
4270 * The maximum value which can be held in a #goffset.
4277 * The maximum value which can be held in a #gshort.
4284 * The maximum value which can be held in a #gsize.
4293 * The maximum value which can be held in a #gssize.
4302 * The maximum value which can be held in a #guint.
4309 * The maximum value which can be held in a #guint16.
4318 * The maximum value which can be held in a #guint32.
4327 * The maximum value which can be held in a #guint64.
4334 * The maximum value which can be held in a #guint8.
4343 * The maximum value which can be held in a #gulong.
4350 * The maximum value which can be held in a #gushort.
4357 * The minimum positive value which can be held in a #gdouble.
4359 * If you are interested in the smallest value which can be held
4360 * in a #gdouble, use -%G_MAXDOUBLE.
4367 * The minimum positive value which can be held in a #gfloat.
4369 * If you are interested in the smallest value which can be held
4370 * in a #gfloat, use -%G_MAXFLOAT.
4377 * The minimum value which can be held in a #gint.
4384 * The minimum value which can be held in a #gint16.
4393 * The minimum value which can be held in a #gint32.
4402 * The minimum value which can be held in a #gint64.
4409 * The minimum value which can be held in a #gint8.
4418 * The minimum value which can be held in a #glong.
4425 * The minimum value which can be held in a #goffset.
4432 * The minimum value which can be held in a #gshort.
4439 * The minimum value which can be held in a #gssize.
4449 * Determines the number of elements in an array. The array must be
4450 * declared so the compiler knows its size at compile-time; this
4451 * macro will not work on an array allocated on the heap, only static
4452 * arrays or arrays on the stack.
4459 * A #GOnce must be initialized with this macro before it can be used.
4461 * |[<!-- language="C" -->
4462 * GOnce my_once = G_ONCE_INIT;
4472 * This macro is defined only on UNIX. So you can bracket
4473 * UNIX-specific code in "\#ifdef G_OS_UNIX".
4480 * This macro is defined only on Windows. So you can bracket
4481 * Windows-specific code in "\#ifdef G_OS_WIN32".
4487 * @identifier1: an identifier
4488 * @identifier2: an identifier
4490 * Yields a new preprocessor pasted identifier
4491 * @identifier1identifier2 from its expanded
4492 * arguments @identifier1 and @identifier2. For example,
4493 * the following code:
4494 * |[<!-- language="C" -->
4495 * #define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller)
4496 * const gchar *name = GET (traveller, name);
4497 * const gchar *quest = GET (traveller, quest);
4498 * GdkColor *favourite = GET (traveller, favourite_colour);
4501 * is transformed by the preprocessor into:
4502 * |[<!-- language="C" -->
4503 * const gchar *name = traveller_get_name (traveller);
4504 * const gchar *quest = traveller_get_quest (traveller);
4505 * GdkColor *favourite = traveller_get_favourite_colour (traveller);
4515 * Specifies one of the possible types of byte order
4516 * (currently unused). See #G_BYTE_ORDER.
4523 * The value of pi (ratio of circle's circumference to its diameter).
4543 * @notify: a #GDestroyNotify
4545 * A macro to assist with the static initialisation of a #GPrivate.
4547 * This macro is useful for the case that a #GDestroyNotify function
4548 * should be associated the key. This is needed when the key will be
4549 * used to point at memory that should be deallocated when the thread
4552 * Additionally, the #GDestroyNotify will also be called on the previous
4553 * value stored in the key when g_private_replace() is used.
4555 * If no #GDestroyNotify is needed, then use of this macro is not
4556 * required -- if the #GPrivate is declared in static scope then it will
4557 * be properly initialised by default (ie: to all zeros). See the
4560 * |[<!-- language="C" -->
4561 * static GPrivate name_key = G_PRIVATE_INIT (g_free);
4563 * // return value should not be freed
4565 * get_local_name (void)
4567 * return g_private_get (&name_key);
4571 * set_local_name (const gchar *name)
4573 * g_private_replace (&name_key, g_strdup (name));
4577 * static GPrivate count_key; // no free function
4580 * get_local_count (void)
4582 * return GPOINTER_TO_INT (g_private_get (&count_key));
4586 * set_local_count (gint count)
4588 * g_private_set (&count_key, GINT_TO_POINTER (count));
4597 * G_SEARCHPATH_SEPARATOR:
4599 * The search path separator character.
4600 * This is ':' on UNIX machines and ';' under Windows.
4605 * G_SEARCHPATH_SEPARATOR_S:
4607 * The search path separator as a string.
4608 * This is ":" on UNIX machines and ";" under Windows.
4615 * Error domain for shell functions. Errors in this domain will be from
4616 * the #GShellError enumeration. See #GError for information on error
4624 * The square root of two.
4630 * @expr: a constant expression
4632 * The G_STATIC_ASSERT() macro lets the programmer check
4633 * a condition at compile time, the condition needs to
4634 * be compile time computable. The macro can be used in
4635 * any place where a typedef is valid.
4637 * A typedef is generally allowed in exactly the same places that
4638 * a variable declaration is allowed. For this reason, you should
4639 * not use G_STATIC_ASSERT() in the middle of blocks of code.
4641 * The macro should only be used once per source code line.
4648 * G_STATIC_ASSERT_EXPR:
4649 * @expr: a constant expression
4651 * The G_STATIC_ASSERT_EXPR() macro lets the programmer check
4652 * a condition at compile time. The condition needs to be
4653 * compile time computable.
4655 * Unlike G_STATIC_ASSERT(), this macro evaluates to an expression
4656 * and, as such, can be used in the middle of other expressions.
4657 * Its value should be ignored. This can be accomplished by placing
4658 * it as the first argument of a comma expression.
4660 * |[<!-- language="C" -->
4661 * #define ADD_ONE_TO_INT(x) \
4662 * (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1))
4672 * Used within multi-statement macros so that they can be used in places
4673 * where only one statement is expected by the compiler.
4680 * Used within multi-statement macros so that they can be used in places
4681 * where only one statement is expected by the compiler.
4688 * Expands to a string identifying the current function.
4696 * @macro_or_string: a macro or a string
4698 * Accepts a macro or a string and converts it into a string after
4699 * preprocessor argument expansion. For example, the following code:
4701 * |[<!-- language="C" -->
4703 * const gchar *greeting = G_STRINGIFY (AGE) " today!";
4706 * is transformed by the preprocessor into (code equivalent to):
4708 * |[<!-- language="C" -->
4709 * const gchar *greeting = "27 today!";
4717 * Expands to a string identifying the current code position.
4723 * @member_type: the type of the struct field
4724 * @struct_p: a pointer to a struct
4725 * @struct_offset: the offset of the field from the start of the struct,
4728 * Returns a member of a structure at a given offset, using the given type.
4730 * Returns: the struct member
4735 * G_STRUCT_MEMBER_P:
4736 * @struct_p: a pointer to a struct
4737 * @struct_offset: the offset from the start of the struct, in bytes
4739 * Returns an untyped pointer to a given offset of a struct.
4741 * Returns: an untyped pointer to @struct_p plus @struct_offset bytes
4747 * @struct_type: a structure type, e.g. #GtkWidget
4748 * @member: a field in the structure, e.g. @window
4750 * Returns the offset, in bytes, of a member of a struct.
4752 * Returns: the offset of @member from the start of @struct_type
4759 * The standard delimiters, used in g_strdelimit().
4766 * The error domain of the GLib thread subsystem.
4772 * @name: the name of the lock
4774 * Works like g_mutex_trylock(), but for a lock defined with
4777 * Returns: %TRUE, if the lock could be locked.
4783 * @maj: the major version that introduced the symbol
4784 * @min: the minor version that introduced the symbol
4786 * This macro can be used to mark a function declaration as unavailable.
4787 * It must be placed before the function declaration. Use of a function
4788 * that has been annotated with this macros will produce a compiler warning.
4796 * @expr: the expression
4798 * Hints the compiler that the expression is unlikely to evaluate to
4799 * a true value. The compiler may use this information for optimizations.
4801 * |[<!-- language="C" -->
4802 * if (G_UNLIKELY (random () == 1))
4803 * g_print ("a random one");
4806 * Returns: the value of @expr
4813 * @name: the name of the lock
4815 * Works like g_mutex_unlock(), but for a lock defined with
4823 * Number of microseconds in one second (1 million).
4824 * This macro is provided for code readability.
4829 * G_VARIANT_PARSE_ERROR:
4831 * Error domain for GVariant text format parsing. Specific error codes
4832 * are not currently defined for this domain. See #GError for
4833 * information on error domains.
4839 * @ap1: the va_list variable to place a copy of @ap2 in
4842 * Portable way to copy va_list variables.
4844 * In order to use this function, you must include string.h yourself,
4845 * because this macro may use memmove() and GLib does not include
4851 * G_WIN32_DLLMAIN_FOR_DLL_NAME:
4852 * @static: empty or "static"
4853 * @dll_name: the name of the (pointer to the) char array where
4854 * the DLL name will be stored. If this is used, you must also
4855 * include `windows.h`. If you need a more complex DLL entry
4856 * point function, you cannot use this
4858 * On Windows, this macro defines a DllMain() function that stores
4859 * the actual DLL name that the code being compiled will be included in.
4861 * On non-Windows platforms, expands to nothing.
4866 * G_WIN32_HAVE_WIDECHAR_API:
4868 * On Windows, this macro defines an expression which evaluates to
4869 * %TRUE if the code is running on a version of Windows where the wide
4870 * character versions of the Win32 API functions, and the wide character
4871 * versions of the C library functions work. (They are always present in
4872 * the DLLs, but don't work on Windows 9x and Me.)
4874 * On non-Windows platforms, it is not defined.
4881 * G_WIN32_IS_NT_BASED:
4883 * On Windows, this macro defines an expression which evaluates to
4884 * %TRUE if the code is running on an NT-based Windows operating system.
4886 * On non-Windows platforms, it is not defined.
4894 * @a: a numeric value
4895 * @b: a numeric value
4897 * Calculates the maximum of @a and @b.
4899 * Returns: the maximum of @a and @b.
4906 * Provided for UNIX emulation on Windows; equivalent to UNIX
4907 * macro %MAXPATHLEN, which is the maximum length of a filename
4908 * (including full path).
4914 * @a: a numeric value
4915 * @b: a numeric value
4917 * Calculates the minimum of @a and @b.
4919 * Returns: the minimum of @a and @b.
4925 * @Context: a message context, must be a string literal
4926 * @String: a message id, must be a string literal
4928 * Only marks a string for translation, with context.
4929 * This is useful in situations where the translated strings can't
4930 * be directly used, e.g. in string array initializers. To get the
4931 * translated string, you should call g_dpgettext2() at runtime.
4933 * |[<!-- language="C" -->
4935 * static const char *messages[] = {
4936 * NC_("some context", "some very meaningful message"),
4937 * NC_("some context", "and another one")
4939 * const char *string;
4942 * = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message")
4943 * : g_dpgettext2 (NULL, "some context", messages[index]);
4950 * If you are using the NC_() macro, you need to make sure that you pass
4951 * `--keyword=NC_:1c,2` to xgettext when extracting messages.
4952 * Note that this only works with GNU gettext >= 0.15. Intltool has support
4953 * for the NC_() macro since version 0.40.1.
4962 * Defines the standard %NULL pointer.
4968 * @String: the string to be translated
4970 * Only marks a string for translation. This is useful in situations
4971 * where the translated strings can't be directly used, e.g. in string
4972 * array initializers. To get the translated string, call gettext()
4974 * |[<!-- language="C" -->
4976 * static const char *messages[] = {
4977 * N_("some very meaningful message"),
4978 * N_("and another one")
4980 * const char *string;
4983 * = index > 1 ? _("a default message") : gettext (messages[index]);
4996 * @String: the string to be translated, with a '|'-separated prefix
4997 * which must not be translated
4999 * Like _(), but handles context in message ids. This has the advantage
5000 * that the string can be adorned with a prefix to guarantee uniqueness
5001 * and provide context to the translator.
5003 * One use case given in the gettext manual is GUI translation, where one
5004 * could e.g. disambiguate two "Open" menu entries as "File|Open" and
5005 * "Printer|Open". Another use case is the string "Russian" which may
5006 * have to be translated differently depending on whether it's the name
5007 * of a character set or a language. This could be solved by using
5008 * "charset|Russian" and "language|Russian".
5010 * See the C_() macro for a different way to mark up translatable strings
5013 * If you are using the Q_() macro, you need to make sure that you pass
5014 * `--keyword=Q_` to xgettext when extracting messages.
5015 * If you are using GNU gettext >= 0.15, you can also use
5016 * `--keyword=Q_:1g` to let xgettext split the context
5017 * string off into a msgctxt line in the po file.
5019 * Returns: the translated message
5027 * @short_description: arrays of arbitrary elements which grow
5028 * automatically as elements are added
5030 * Arrays are similar to standard C arrays, except that they grow
5031 * automatically as elements are added.
5033 * Array elements can be of any size (though all elements of one array
5034 * are the same size), and the array can be automatically cleared to
5035 * '0's and zero-terminated.
5037 * To create a new array use g_array_new().
5039 * To add elements to an array, use g_array_append_val(),
5040 * g_array_append_vals(), g_array_prepend_val(), and
5041 * g_array_prepend_vals().
5043 * To access an element of an array, use g_array_index().
5045 * To set the size of an array, use g_array_set_size().
5047 * To free an array, use g_array_free().
5049 * Here is an example that stores integers in a #GArray:
5050 * |[<!-- language="C" -->
5053 * // We create a new array to store gint values.
5054 * // We don't want it zero-terminated or cleared to 0's.
5055 * garray = g_array_new (FALSE, FALSE, sizeof (gint));
5056 * for (i = 0; i < 10000; i++)
5057 * g_array_append_val (garray, i);
5058 * for (i = 0; i < 10000; i++)
5059 * if (g_array_index (garray, gint, i) != i)
5060 * g_print ("ERROR: got %d instead of %d\n",
5061 * g_array_index (garray, gint, i), i);
5062 * g_array_free (garray, TRUE);
5068 * SECTION:arrays_byte
5069 * @title: Byte Arrays
5070 * @short_description: arrays of bytes
5072 * #GByteArray is a mutable array of bytes based on #GArray, to provide arrays
5073 * of bytes which grow automatically as elements are added.
5075 * To create a new #GByteArray use g_byte_array_new(). To add elements to a
5076 * #GByteArray, use g_byte_array_append(), and g_byte_array_prepend().
5078 * To set the size of a #GByteArray, use g_byte_array_set_size().
5080 * To free a #GByteArray, use g_byte_array_free().
5082 * An example for using a #GByteArray:
5083 * |[<!-- language="C" -->
5084 * GByteArray *gbarray;
5087 * gbarray = g_byte_array_new ();
5088 * for (i = 0; i < 10000; i++)
5089 * g_byte_array_append (gbarray, (guint8*) "abcd", 4);
5091 * for (i = 0; i < 10000; i++)
5093 * g_assert (gbarray->data[4*i] == 'a');
5094 * g_assert (gbarray->data[4*i+1] == 'b');
5095 * g_assert (gbarray->data[4*i+2] == 'c');
5096 * g_assert (gbarray->data[4*i+3] == 'd');
5099 * g_byte_array_free (gbarray, TRUE);
5102 * See #GBytes if you are interested in an immutable object representing a
5103 * sequence of bytes.
5108 * SECTION:arrays_pointer
5109 * @title: Pointer Arrays
5110 * @short_description: arrays of pointers to any type of data, which
5111 * grow automatically as new elements are added
5113 * Pointer Arrays are similar to Arrays but are used only for storing
5116 * If you remove elements from the array, elements at the end of the
5117 * array are moved into the space previously occupied by the removed
5118 * element. This means that you should not rely on the index of particular
5119 * elements remaining the same. You should also be careful when deleting
5120 * elements while iterating over the array.
5122 * To create a pointer array, use g_ptr_array_new().
5124 * To add elements to a pointer array, use g_ptr_array_add().
5126 * To remove elements from a pointer array, use g_ptr_array_remove(),
5127 * g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
5129 * To access an element of a pointer array, use g_ptr_array_index().
5131 * To set the size of a pointer array, use g_ptr_array_set_size().
5133 * To free a pointer array, use g_ptr_array_free().
5135 * An example using a #GPtrArray:
5136 * |[<!-- language="C" -->
5138 * gchar *string1 = "one";
5139 * gchar *string2 = "two";
5140 * gchar *string3 = "three";
5142 * array = g_ptr_array_new ();
5143 * g_ptr_array_add (array, (gpointer) string1);
5144 * g_ptr_array_add (array, (gpointer) string2);
5145 * g_ptr_array_add (array, (gpointer) string3);
5147 * if (g_ptr_array_index (array, 0) != (gpointer) string1)
5148 * g_print ("ERROR: got %p instead of %p\n",
5149 * g_ptr_array_index (array, 0), string1);
5151 * g_ptr_array_free (array, TRUE);
5157 * SECTION:async_queues
5158 * @title: Asynchronous Queues
5159 * @short_description: asynchronous communication between threads
5160 * @see_also: #GThreadPool
5162 * Often you need to communicate between different threads. In general
5163 * it's safer not to do this by shared memory, but by explicit message
5164 * passing. These messages only make sense asynchronously for
5165 * multi-threaded applications though, as a synchronous operation could
5166 * as well be done in the same thread.
5168 * Asynchronous queues are an exception from most other GLib data
5169 * structures, as they can be used simultaneously from multiple threads
5170 * without explicit locking and they bring their own builtin reference
5171 * counting. This is because the nature of an asynchronous queue is that
5172 * it will always be used by at least 2 concurrent threads.
5174 * For using an asynchronous queue you first have to create one with
5175 * g_async_queue_new(). #GAsyncQueue structs are reference counted,
5176 * use g_async_queue_ref() and g_async_queue_unref() to manage your
5179 * A thread which wants to send a message to that queue simply calls
5180 * g_async_queue_push() to push the message to the queue.
5182 * A thread which is expecting messages from an asynchronous queue
5183 * simply calls g_async_queue_pop() for that queue. If no message is
5184 * available in the queue at that point, the thread is now put to sleep
5185 * until a message arrives. The message will be removed from the queue
5186 * and returned. The functions g_async_queue_try_pop() and
5187 * g_async_queue_timeout_pop() can be used to only check for the presence
5188 * of messages or to only wait a certain time for messages respectively.
5190 * For almost every function there exist two variants, one that locks
5191 * the queue and one that doesn't. That way you can hold the queue lock
5192 * (acquire it with g_async_queue_lock() and release it with
5193 * g_async_queue_unlock()) over multiple queue accessing instructions.
5194 * This can be necessary to ensure the integrity of the queue, but should
5195 * only be used when really necessary, as it can make your life harder
5196 * if used unwisely. Normally you should only use the locking function
5197 * variants (those without the _unlocked suffix).
5199 * In many cases, it may be more convenient to use #GThreadPool when
5200 * you need to distribute work to a set of worker threads instead of
5201 * using #GAsyncQueue manually. #GThreadPool uses a GAsyncQueue
5207 * SECTION:atomic_operations
5208 * @title: Atomic Operations
5209 * @short_description: basic atomic integer and pointer operations
5210 * @see_also: #GMutex
5212 * The following is a collection of compiler macros to provide atomic
5213 * access to integer and pointer-sized values.
5215 * The macros that have 'int' in the name will operate on pointers to
5216 * #gint and #guint. The macros with 'pointer' in the name will operate
5217 * on pointers to any pointer-sized value, including #gsize. There is
5218 * no support for 64bit operations on platforms with 32bit pointers
5219 * because it is not generally possible to perform these operations
5222 * The get, set and exchange operations for integers and pointers
5223 * nominally operate on #gint and #gpointer, respectively. Of the
5224 * arithmetic operations, the 'add' operation operates on (and returns)
5225 * signed integer values (#gint and #gssize) and the 'and', 'or', and
5226 * 'xor' operations operate on (and return) unsigned integer values
5227 * (#guint and #gsize).
5229 * All of the operations act as a full compiler and (where appropriate)
5230 * hardware memory barrier. Acquire and release or producer and
5231 * consumer barrier semantics are not available through this API.
5233 * It is very important that all accesses to a particular integer or
5234 * pointer be performed using only this API and that different sizes of
5235 * operation are not mixed or used on overlapping memory regions. Never
5236 * read or assign directly from or to a value -- always use this API.
5238 * For simple reference counting purposes you should use
5239 * g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that
5240 * fall outside of simple reference counting patterns are prone to
5241 * subtle bugs and occasionally undefined behaviour. It is also worth
5242 * noting that since all of these operations require global
5243 * synchronisation of the entire machine, they can be quite slow. In
5244 * the case of performing multiple atomic operations it can often be
5245 * faster to simply acquire a mutex lock around the critical area,
5246 * perform the operations normally and then release the lock.
5252 * @title: Base64 Encoding
5253 * @short_description: encodes and decodes data in Base64 format
5255 * Base64 is an encoding that allows a sequence of arbitrary bytes to be
5256 * encoded as a sequence of printable ASCII characters. For the definition
5258 * [RFC 1421](http://www.ietf.org/rfc/rfc1421.txt)
5260 * [RFC 2045](http://www.ietf.org/rfc/rfc2045.txt).
5261 * Base64 is most commonly used as a MIME transfer encoding
5264 * GLib supports incremental encoding using g_base64_encode_step() and
5265 * g_base64_encode_close(). Incremental decoding can be done with
5266 * g_base64_decode_step(). To encode or decode data in one go, use
5267 * g_base64_encode() or g_base64_decode(). To avoid memory allocation when
5268 * decoding, you can use g_base64_decode_inplace().
5270 * Support for Base64 encoding has been added in GLib 2.12.
5275 * SECTION:bookmarkfile
5276 * @title: Bookmark file parser
5277 * @short_description: parses files containing bookmarks
5279 * GBookmarkFile lets you parse, edit or create files containing bookmarks
5280 * to URI, along with some meta-data about the resource pointed by the URI
5281 * like its MIME type, the application that is registering the bookmark and
5282 * the icon that should be used to represent the bookmark. The data is stored
5284 * [Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec).
5286 * The syntax of the bookmark files is described in detail inside the
5287 * Desktop Bookmark Specification, here is a quick summary: bookmark
5288 * files use a sub-class of the XML Bookmark Exchange Language
5289 * specification, consisting of valid UTF-8 encoded XML, under the
5290 * <xbel> root element; each bookmark is stored inside a
5291 * <bookmark> element, using its URI: no relative paths can
5292 * be used inside a bookmark file. The bookmark may have a user defined
5293 * title and description, to be used instead of the URI. Under the
5294 * <metadata> element, with its owner attribute set to
5295 * `http://freedesktop.org`, is stored the meta-data about a resource
5296 * pointed by its URI. The meta-data consists of the resource's MIME
5297 * type; the applications that have registered a bookmark; the groups
5298 * to which a bookmark belongs to; a visibility flag, used to set the
5299 * bookmark as "private" to the applications and groups that has it
5300 * registered; the URI and MIME type of an icon, to be used when
5301 * displaying the bookmark inside a GUI.
5303 * Here is an example of a bookmark file:
5304 * [bookmarks.xbel](https://git.gnome.org/browse/glib/tree/glib/tests/bookmarks.xbel)
5306 * A bookmark file might contain more than one bookmark; each bookmark
5307 * is accessed through its URI.
5309 * The important caveat of bookmark files is that when you add a new
5310 * bookmark you must also add the application that is registering it, using
5311 * g_bookmark_file_add_application() or g_bookmark_file_set_app_info().
5312 * If a bookmark has no applications then it won't be dumped when creating
5313 * the on disk representation, using g_bookmark_file_to_data() or
5314 * g_bookmark_file_to_file().
5316 * The #GBookmarkFile parser was added in GLib 2.12.
5321 * SECTION:byte_order
5322 * @title: Byte Order Macros
5323 * @short_description: a portable way to convert between different byte orders
5325 * These macros provide a portable way to determine the host byte order
5326 * and to convert values between different byte orders.
5328 * The byte order is the order in which bytes are stored to create larger
5329 * data types such as the #gint and #glong values.
5330 * The host byte order is the byte order used on the current machine.
5332 * Some processors store the most significant bytes (i.e. the bytes that
5333 * hold the largest part of the value) first. These are known as big-endian
5334 * processors. Other processors (notably the x86 family) store the most
5335 * significant byte last. These are known as little-endian processors.
5337 * Finally, to complicate matters, some other processors store the bytes in
5338 * a rather curious order known as PDP-endian. For a 4-byte word, the 3rd
5339 * most significant byte is stored first, then the 4th, then the 1st and
5342 * Obviously there is a problem when these different processors communicate
5343 * with each other, for example over networks or by using binary file formats.
5344 * This is where these macros come in. They are typically used to convert
5345 * values into a byte order which has been agreed on for use when
5346 * communicating between different processors. The Internet uses what is
5347 * known as 'network byte order' as the standard byte order (which is in
5348 * fact the big-endian byte order).
5350 * Note that the byte order conversion macros may evaluate their arguments
5351 * multiple times, thus you should not use them with arguments which have
5357 * SECTION:checkedmath
5358 * @title: Bounds-checking integer arithmetic
5359 * @short_description: a set of helpers for performing checked integer arithmetic
5361 * GLib offers a set of macros for doing additions and multiplications
5362 * of unsigned integers, with checks for overflows.
5364 * The helpers all have three arguments. A pointer to the destination
5365 * is always the first argument and the operands to the operation are
5368 * Following standard GLib convention, the helpers return %TRUE in case
5369 * of success (ie: no overflow).
5371 * The helpers may be macros, normal functions or inlines. They may be
5372 * implemented with inline assembly or compiler intrinsics where
5381 * @title: Data Checksums
5382 * @short_description: computes the checksum for data
5384 * GLib provides a generic API for computing checksums (or "digests")
5385 * for a sequence of arbitrary bytes, using various hashing algorithms
5386 * like MD5, SHA-1 and SHA-256. Checksums are commonly used in various
5387 * environments and specifications.
5389 * GLib supports incremental checksums using the GChecksum data
5390 * structure, by calling g_checksum_update() as long as there's data
5391 * available and then using g_checksum_get_string() or
5392 * g_checksum_get_digest() to compute the checksum and return it either
5393 * as a string in hexadecimal form, or as a raw sequence of bytes. To
5394 * compute the checksum for binary blobs and NUL-terminated strings in
5395 * one go, use the convenience functions g_compute_checksum_for_data()
5396 * and g_compute_checksum_for_string(), respectively.
5398 * Support for checksums has been added in GLib 2.16
5403 * SECTION:conversions
5404 * @title: Character Set Conversion
5405 * @short_description: convert strings between different character sets
5407 * The g_convert() family of function wraps the functionality of iconv().
5408 * In addition to pure character set conversions, GLib has functions to
5409 * deal with the extra complications of encodings for file names.
5411 * ## File Name Encodings
5413 * Historically, UNIX has not had a defined encoding for file names:
5414 * a file name is valid as long as it does not have path separators
5415 * in it ("/"). However, displaying file names may require conversion:
5416 * from the character set in which they were created, to the character
5417 * set in which the application operates. Consider the Spanish file name
5418 * "Presentación.sxi". If the application which created it uses
5419 * ISO-8859-1 for its encoding,
5421 * Character: P r e s e n t a c i ó n . s x i
5422 * Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
5424 * However, if the application use UTF-8, the actual file name on
5425 * disk would look like this:
5427 * Character: P r e s e n t a c i ó n . s x i
5428 * Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
5430 * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use
5431 * Glib do the same thing. If you get a file name from the file system,
5432 * for example, from readdir() or from g_dir_read_name(), and you wish
5433 * to display the file name to the user, you will need to convert it
5434 * into UTF-8. The opposite case is when the user types the name of a
5435 * file he wishes to save: the toolkit will give you that string in
5436 * UTF-8 encoding, and you will need to convert it to the character
5437 * set used for file names before you can create the file with open()
5440 * By default, Glib assumes that file names on disk are in UTF-8
5441 * encoding. This is a valid assumption for file systems which
5442 * were created relatively recently: most applications use UTF-8
5443 * encoding for their strings, and that is also what they use for
5444 * the file names they create. However, older file systems may
5445 * still contain file names created in "older" encodings, such as
5446 * ISO-8859-1. In this case, for compatibility reasons, you may want
5447 * to instruct Glib to use that particular encoding for file names
5448 * rather than UTF-8. You can do this by specifying the encoding for
5449 * file names in the [`G_FILENAME_ENCODING`][G_FILENAME_ENCODING]
5450 * environment variable. For example, if your installation uses
5451 * ISO-8859-1 for file names, you can put this in your `~/.profile`
5453 * export G_FILENAME_ENCODING=ISO-8859-1
5455 * Glib provides the functions g_filename_to_utf8() and
5456 * g_filename_from_utf8() to perform the necessary conversions.
5457 * These functions convert file names from the encoding specified
5458 * in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This
5459 * [diagram][file-name-encodings-diagram] illustrates how
5460 * these functions are used to convert between UTF-8 and the
5461 * encoding for file names in the file system.
5463 * ## Conversion between file name encodings # {#file-name-encodings-diagram)
5465 * ![](file-name-encodings.png)
5467 * ## Checklist for Application Writers
5469 * This section is a practical summary of the detailed
5471 * things to do to make sure your applications process file
5472 * name encodings correctly.
5474 * 1. If you get a file name from the file system from a function
5475 * such as readdir() or gtk_file_chooser_get_filename(), you do
5476 * not need to do any conversion to pass that file name to
5477 * functions like open(), rename(), or fopen() -- those are "raw"
5478 * file names which the file system understands.
5480 * 2. If you need to display a file name, convert it to UTF-8 first
5481 * by using g_filename_to_utf8(). If conversion fails, display a
5482 * string like "Unknown file name". Do not convert this string back
5483 * into the encoding used for file names if you wish to pass it to
5484 * the file system; use the original file name instead.
5486 * For example, the document window of a word processor could display
5487 * "Unknown file name" in its title bar but still let the user save
5488 * the file, as it would keep the raw file name internally. This
5489 * can happen if the user has not set the `G_FILENAME_ENCODING`
5490 * environment variable even though he has files whose names are
5491 * not encoded in UTF-8.
5493 * 3. If your user interface lets the user type a file name for saving
5494 * or renaming, convert it to the encoding used for file names in
5495 * the file system by using g_filename_from_utf8(). Pass the converted
5496 * file name to functions like fopen(). If conversion fails, ask the
5497 * user to enter a different file name. This can happen if the user
5498 * types Japanese characters when `G_FILENAME_ENCODING` is set to
5499 * `ISO-8859-1`, for example.
5505 * @title: Keyed Data Lists
5506 * @short_description: lists of data elements which are accessible by a
5507 * string or GQuark identifier
5509 * Keyed data lists provide lists of arbitrary data elements which can
5510 * be accessed either with a string or with a #GQuark corresponding to
5513 * The #GQuark methods are quicker, since the strings have to be
5514 * converted to #GQuarks anyway.
5516 * Data lists are used for associating arbitrary data with #GObjects,
5517 * using g_object_set_data() and related functions.
5519 * To create a datalist, use g_datalist_init().
5521 * To add data elements to a datalist use g_datalist_id_set_data(),
5522 * g_datalist_id_set_data_full(), g_datalist_set_data() and
5523 * g_datalist_set_data_full().
5525 * To get data elements from a datalist use g_datalist_id_get_data()
5526 * and g_datalist_get_data().
5528 * To iterate over all data elements in a datalist use
5529 * g_datalist_foreach() (not thread-safe).
5531 * To remove data elements from a datalist use
5532 * g_datalist_id_remove_data() and g_datalist_remove_data().
5534 * To remove all data elements from a datalist, use g_datalist_clear().
5541 * @short_description: associate groups of data elements with
5542 * particular memory locations
5544 * Datasets associate groups of data elements with particular memory
5545 * locations. These are useful if you need to associate data with a
5546 * structure returned from an external library. Since you cannot modify
5547 * the structure, you use its location in memory as the key into a
5548 * dataset, where you can associate any number of data elements with it.
5550 * There are two forms of most of the dataset functions. The first form
5551 * uses strings to identify the data elements associated with a
5552 * location. The second form uses #GQuark identifiers, which are
5553 * created with a call to g_quark_from_string() or
5554 * g_quark_from_static_string(). The second form is quicker, since it
5555 * does not require looking up the string in the hash table of #GQuark
5558 * There is no function to create a dataset. It is automatically
5559 * created as soon as you add elements to it.
5561 * To add data elements to a dataset use g_dataset_id_set_data(),
5562 * g_dataset_id_set_data_full(), g_dataset_set_data() and
5563 * g_dataset_set_data_full().
5565 * To get data elements from a dataset use g_dataset_id_get_data() and
5566 * g_dataset_get_data().
5568 * To iterate over all data elements in a dataset use
5569 * g_dataset_foreach() (not thread-safe).
5571 * To remove data elements from a dataset use
5572 * g_dataset_id_remove_data() and g_dataset_remove_data().
5574 * To destroy a dataset, use g_dataset_destroy().
5580 * @title: Date and Time Functions
5581 * @short_description: calendrical calculations and miscellaneous time stuff
5583 * The #GDate data structure represents a day between January 1, Year 1,
5584 * and sometime a few thousand years in the future (right now it will go
5585 * to the year 65535 or so, but g_date_set_parse() only parses up to the
5586 * year 8000 or so - just count on "a few thousand"). #GDate is meant to
5587 * represent everyday dates, not astronomical dates or historical dates
5588 * or ISO timestamps or the like. It extrapolates the current Gregorian
5589 * calendar forward and backward in time; there is no attempt to change
5590 * the calendar to match time periods or locations. #GDate does not store
5591 * time information; it represents a day.
5593 * The #GDate implementation has several nice features; it is only a
5594 * 64-bit struct, so storing large numbers of dates is very efficient. It
5595 * can keep both a Julian and day-month-year representation of the date,
5596 * since some calculations are much easier with one representation or the
5597 * other. A Julian representation is simply a count of days since some
5598 * fixed day in the past; for #GDate the fixed day is January 1, 1 AD.
5599 * ("Julian" dates in the #GDate API aren't really Julian dates in the
5600 * technical sense; technically, Julian dates count from the start of the
5601 * Julian period, Jan 1, 4713 BC).
5603 * #GDate is simple to use. First you need a "blank" date; you can get a
5604 * dynamically allocated date from g_date_new(), or you can declare an
5605 * automatic variable or array and initialize it to a sane state by
5606 * calling g_date_clear(). A cleared date is sane; it's safe to call
5607 * g_date_set_dmy() and the other mutator functions to initialize the
5608 * value of a cleared date. However, a cleared date is initially
5609 * invalid, meaning that it doesn't represent a day that exists.
5610 * It is undefined to call any of the date calculation routines on an
5611 * invalid date. If you obtain a date from a user or other
5612 * unpredictable source, you should check its validity with the
5613 * g_date_valid() predicate. g_date_valid() is also used to check for
5614 * errors with g_date_set_parse() and other functions that can
5615 * fail. Dates can be invalidated by calling g_date_clear() again.
5617 * It is very important to use the API to access the #GDate
5618 * struct. Often only the day-month-year or only the Julian
5619 * representation is valid. Sometimes neither is valid. Use the API.
5621 * GLib also features #GDateTime which represents a precise time.
5628 * @short_description: a structure representing Date and Time
5629 * @see_also: #GTimeZone
5631 * #GDateTime is a structure that combines a Gregorian date and time
5632 * into a single structure. It provides many conversion and methods to
5633 * manipulate dates and times. Time precision is provided down to
5634 * microseconds and the time can range (proleptically) from 0001-01-01
5635 * 00:00:00 to 9999-12-31 23:59:59.999999. #GDateTime follows POSIX
5636 * time in the sense that it is oblivious to leap seconds.
5638 * #GDateTime is an immutable object; once it has been created it cannot
5639 * be modified further. All modifiers will create a new #GDateTime.
5640 * Nearly all such functions can fail due to the date or time going out
5641 * of range, in which case %NULL will be returned.
5643 * #GDateTime is reference counted: the reference count is increased by calling
5644 * g_date_time_ref() and decreased by calling g_date_time_unref(). When the
5645 * reference count drops to 0, the resources allocated by the #GDateTime
5646 * structure are released.
5648 * Many parts of the API may produce non-obvious results. As an
5649 * example, adding two months to January 31st will yield March 31st
5650 * whereas adding one month and then one month again will yield either
5651 * March 28th or March 29th. Also note that adding 24 hours is not
5652 * always the same as adding one day (since days containing daylight
5653 * savings time transitions are either 23 or 25 hours in length).
5655 * #GDateTime is available since GLib 2.26.
5660 * SECTION:error_reporting
5661 * @Title: Error Reporting
5662 * @Short_description: a system for reporting errors
5664 * GLib provides a standard method of reporting errors from a called
5665 * function to the calling code. (This is the same problem solved by
5666 * exceptions in other languages.) It's important to understand that
5667 * this method is both a data type (the #GError struct) and a [set of
5668 * rules][gerror-rules]. If you use #GError incorrectly, then your code will not
5669 * properly interoperate with other code that uses #GError, and users
5670 * of your API will probably get confused. In most cases, [using #GError is
5671 * preferred over numeric error codes][gerror-comparison], but there are
5672 * situations where numeric error codes are useful for performance.
5674 * First and foremost: #GError should only be used to report recoverable
5675 * runtime errors, never to report programming errors. If the programmer
5676 * has screwed up, then you should use g_warning(), g_return_if_fail(),
5677 * g_assert(), g_error(), or some similar facility. (Incidentally,
5678 * remember that the g_error() function should only be used for
5679 * programming errors, it should not be used to print any error
5680 * reportable via #GError.)
5682 * Examples of recoverable runtime errors are "file not found" or
5683 * "failed to parse input." Examples of programming errors are "NULL
5684 * passed to strcmp()" or "attempted to free the same pointer twice."
5685 * These two kinds of errors are fundamentally different: runtime errors
5686 * should be handled or reported to the user, programming errors should
5687 * be eliminated by fixing the bug in the program. This is why most
5688 * functions in GLib and GTK+ do not use the #GError facility.
5690 * Functions that can fail take a return location for a #GError as their
5691 * last argument. On error, a new #GError instance will be allocated and
5692 * returned to the caller via this argument. For example:
5693 * |[<!-- language="C" -->
5694 * gboolean g_file_get_contents (const gchar *filename,
5699 * If you pass a non-%NULL value for the `error` argument, it should
5700 * point to a location where an error can be placed. For example:
5701 * |[<!-- language="C" -->
5703 * GError *err = NULL;
5705 * g_file_get_contents ("foo.txt", &contents, NULL, &err);
5706 * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
5709 * // Report error to user, and free error
5710 * g_assert (contents == NULL);
5711 * fprintf (stderr, "Unable to read file: %s\n", err->message);
5712 * g_error_free (err);
5716 * // Use file contents
5717 * g_assert (contents != NULL);
5720 * Note that `err != NULL` in this example is a reliable indicator
5721 * of whether g_file_get_contents() failed. Additionally,
5722 * g_file_get_contents() returns a boolean which
5723 * indicates whether it was successful.
5725 * Because g_file_get_contents() returns %FALSE on failure, if you
5726 * are only interested in whether it failed and don't need to display
5727 * an error message, you can pass %NULL for the @error argument:
5728 * |[<!-- language="C" -->
5729 * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors
5730 * // no error occurred
5737 * The #GError object contains three fields: @domain indicates the module
5738 * the error-reporting function is located in, @code indicates the specific
5739 * error that occurred, and @message is a user-readable error message with
5740 * as many details as possible. Several functions are provided to deal
5741 * with an error received from a called function: g_error_matches()
5742 * returns %TRUE if the error matches a given domain and code,
5743 * g_propagate_error() copies an error into an error location (so the
5744 * calling function will receive it), and g_clear_error() clears an
5745 * error location by freeing the error and resetting the location to
5746 * %NULL. To display an error to the user, simply display the @message,
5747 * perhaps along with additional context known only to the calling
5748 * function (the file being opened, or whatever - though in the
5749 * g_file_get_contents() case, the @message already contains a filename).
5751 * When implementing a function that can report errors, the basic
5752 * tool is g_set_error(). Typically, if a fatal error occurs you
5753 * want to g_set_error(), then return immediately. g_set_error()
5754 * does nothing if the error location passed to it is %NULL.
5755 * Here's an example:
5756 * |[<!-- language="C" -->
5758 * foo_open_file (GError **error)
5762 * fd = open ("file.txt", O_RDONLY);
5766 * g_set_error (error,
5767 * FOO_ERROR, // error domain
5768 * FOO_ERROR_BLAH, // error code
5769 * "Failed to open file: %s", // error message format string
5770 * g_strerror (errno));
5778 * Things are somewhat more complicated if you yourself call another
5779 * function that can report a #GError. If the sub-function indicates
5780 * fatal errors in some way other than reporting a #GError, such as
5781 * by returning %TRUE on success, you can simply do the following:
5782 * |[<!-- language="C" -->
5784 * my_function_that_can_fail (GError **err)
5786 * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
5788 * if (!sub_function_that_can_fail (err))
5790 * // assert that error was set by the sub-function
5791 * g_assert (err == NULL || *err != NULL);
5795 * // otherwise continue, no error occurred
5796 * g_assert (err == NULL || *err == NULL);
5800 * If the sub-function does not indicate errors other than by
5801 * reporting a #GError (or if its return value does not reliably indicate
5802 * errors) you need to create a temporary #GError
5803 * since the passed-in one may be %NULL. g_propagate_error() is
5804 * intended for use in this case.
5805 * |[<!-- language="C" -->
5807 * my_function_that_can_fail (GError **err)
5809 * GError *tmp_error;
5811 * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
5814 * sub_function_that_can_fail (&tmp_error);
5816 * if (tmp_error != NULL)
5818 * // store tmp_error in err, if err != NULL,
5819 * // otherwise call g_error_free() on tmp_error
5820 * g_propagate_error (err, tmp_error);
5824 * // otherwise continue, no error occurred
5828 * Error pileups are always a bug. For example, this code is incorrect:
5829 * |[<!-- language="C" -->
5831 * my_function_that_can_fail (GError **err)
5833 * GError *tmp_error;
5835 * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
5838 * sub_function_that_can_fail (&tmp_error);
5839 * other_function_that_can_fail (&tmp_error);
5841 * if (tmp_error != NULL)
5843 * g_propagate_error (err, tmp_error);
5848 * @tmp_error should be checked immediately after sub_function_that_can_fail(),
5849 * and either cleared or propagated upward. The rule is: after each error,
5850 * you must either handle the error, or return it to the calling function.
5852 * Note that passing %NULL for the error location is the equivalent
5853 * of handling an error by always doing nothing about it. So the
5854 * following code is fine, assuming errors in sub_function_that_can_fail()
5855 * are not fatal to my_function_that_can_fail():
5856 * |[<!-- language="C" -->
5858 * my_function_that_can_fail (GError **err)
5860 * GError *tmp_error;
5862 * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
5864 * sub_function_that_can_fail (NULL); // ignore errors
5867 * other_function_that_can_fail (&tmp_error);
5869 * if (tmp_error != NULL)
5871 * g_propagate_error (err, tmp_error);
5877 * Note that passing %NULL for the error location ignores errors;
5878 * it's equivalent to
5879 * `try { sub_function_that_can_fail (); } catch (...) {}`
5880 * in C++. It does not mean to leave errors unhandled; it means
5881 * to handle them by doing nothing.
5883 * Error domains and codes are conventionally named as follows:
5885 * - The error domain is called <NAMESPACE>_<MODULE>_ERROR,
5886 * for example %G_SPAWN_ERROR or %G_THREAD_ERROR:
5887 * |[<!-- language="C" -->
5888 * #define G_SPAWN_ERROR g_spawn_error_quark ()
5891 * g_spawn_error_quark (void)
5893 * return g_quark_from_static_string ("g-spawn-error-quark");
5897 * - The quark function for the error domain is called
5898 * <namespace>_<module>_error_quark,
5899 * for example g_spawn_error_quark() or g_thread_error_quark().
5901 * - The error codes are in an enumeration called
5902 * <Namespace><Module>Error;
5903 * for example, #GThreadError or #GSpawnError.
5905 * - Members of the error code enumeration are called
5906 * <NAMESPACE>_<MODULE>_ERROR_<CODE>,
5907 * for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN.
5909 * - If there's a "generic" or "unknown" error code for unrecoverable
5910 * errors it doesn't make sense to distinguish with specific codes,
5911 * it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED,
5912 * for example %G_SPAWN_ERROR_FAILED. In the case of error code
5913 * enumerations that may be extended in future releases, you should
5914 * generally not handle this error code explicitly, but should
5915 * instead treat any unrecognized error code as equivalent to
5918 * ## Comparison of #GError and traditional error handling # {#gerror-comparison}
5920 * #GError has several advantages over traditional numeric error codes:
5921 * importantly, tools like
5922 * [gobject-introspection](https://developer.gnome.org/gi/stable/) understand
5923 * #GErrors and convert them to exceptions in bindings; the message includes
5924 * more information than just a code; and use of a domain helps prevent
5925 * misinterpretation of error codes.
5927 * #GError has disadvantages though: it requires a memory allocation, and
5928 * formatting the error message string has a performance overhead. This makes it
5929 * unsuitable for use in retry loops where errors are a common case, rather than
5930 * being unusual. For example, using %G_IO_ERROR_WOULD_BLOCK means hitting these
5931 * overheads in the normal control flow. String formatting overhead can be
5932 * eliminated by using g_set_error_literal() in some cases.
5934 * These performance issues can be compounded if a function wraps the #GErrors
5935 * returned by the functions it calls: this multiplies the number of allocations
5936 * and string formatting operations. This can be partially mitigated by using
5939 * ## Rules for use of #GError # {#gerror-rules}
5941 * Summary of rules for use of #GError:
5943 * - Do not report programming errors via #GError.
5945 * - The last argument of a function that returns an error should
5946 * be a location where a #GError can be placed (i.e. "#GError** error").
5947 * If #GError is used with varargs, the #GError** should be the last
5948 * argument before the "...".
5950 * - The caller may pass %NULL for the #GError** if they are not interested
5951 * in details of the exact error that occurred.
5953 * - If %NULL is passed for the #GError** argument, then errors should
5954 * not be returned to the caller, but your function should still
5955 * abort and return if an error occurs. That is, control flow should
5956 * not be affected by whether the caller wants to get a #GError.
5958 * - If a #GError is reported, then your function by definition had a
5959 * fatal failure and did not complete whatever it was supposed to do.
5960 * If the failure was not fatal, then you handled it and you should not
5961 * report it. If it was fatal, then you must report it and discontinue
5962 * whatever you were doing immediately.
5964 * - If a #GError is reported, out parameters are not guaranteed to
5965 * be set to any defined value.
5967 * - A #GError* must be initialized to %NULL before passing its address
5968 * to a function that can report errors.
5970 * - "Piling up" errors is always a bug. That is, if you assign a
5971 * new #GError to a #GError* that is non-%NULL, thus overwriting
5972 * the previous error, it indicates that you should have aborted
5973 * the operation instead of continuing. If you were able to continue,
5974 * you should have cleared the previous error with g_clear_error().
5975 * g_set_error() will complain if you pile up errors.
5977 * - By convention, if you return a boolean value indicating success
5978 * then %TRUE means success and %FALSE means failure. Avoid creating
5979 * functions which have a boolean return value and a GError parameter,
5980 * but where the boolean does something other than signal whether the
5981 * GError is set. Among other problems, it requires C callers to allocate
5982 * a temporary error. Instead, provide a "gboolean *" out parameter.
5983 * There are functions in GLib itself such as g_key_file_has_key() that
5984 * are deprecated because of this. If %FALSE is returned, the error must
5985 * be set to a non-%NULL value. One exception to this is that in situations
5986 * that are already considered to be undefined behaviour (such as when a
5987 * g_return_val_if_fail() check fails), the error need not be set.
5988 * Instead of checking separately whether the error is set, callers
5989 * should ensure that they do not provoke undefined behaviour, then
5990 * assume that the error will be set on failure.
5992 * - A %NULL return value is also frequently used to mean that an error
5993 * occurred. You should make clear in your documentation whether %NULL
5994 * is a valid return value in non-error cases; if %NULL is a valid value,
5995 * then users must check whether an error was returned to see if the
5996 * function succeeded.
5998 * - When implementing a function that can report errors, you may want
5999 * to add a check at the top of your function that the error return
6000 * location is either %NULL or contains a %NULL error (e.g.
6001 * `g_return_if_fail (error == NULL || *error == NULL);`).
6007 * @title: File Utilities
6008 * @short_description: various file-related functions
6010 * There is a group of functions which wrap the common POSIX functions
6011 * dealing with filenames (g_open(), g_rename(), g_mkdir(), g_stat(),
6012 * g_unlink(), g_remove(), g_fopen(), g_freopen()). The point of these
6013 * wrappers is to make it possible to handle file names with any Unicode
6014 * characters in them on Windows without having to use ifdefs and the
6015 * wide character API in the application code.
6017 * The pathname argument should be in the GLib file name encoding.
6018 * On POSIX this is the actual on-disk encoding which might correspond
6019 * to the locale settings of the process (or the `G_FILENAME_ENCODING`
6020 * environment variable), or not.
6022 * On Windows the GLib file name encoding is UTF-8. Note that the
6023 * Microsoft C library does not use UTF-8, but has separate APIs for
6024 * current system code page and wide characters (UTF-16). The GLib
6025 * wrappers call the wide character API if present (on modern Windows
6026 * systems), otherwise convert to/from the system code page.
6028 * Another group of functions allows to open and read directories
6029 * in the GLib file name encoding. These are g_dir_open(),
6030 * g_dir_read_name(), g_dir_rewind(), g_dir_close().
6035 * SECTION:ghostutils
6036 * @short_description: Internet hostname utilities
6038 * Functions for manipulating internet hostnames; in particular, for
6039 * converting between Unicode and ASCII-encoded forms of
6040 * Internationalized Domain Names (IDNs).
6043 * [Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt)
6044 * standards allow for the use
6045 * of Unicode domain names in applications, while providing
6046 * backward-compatibility with the old ASCII-only DNS, by defining an
6047 * ASCII-Compatible Encoding of any given Unicode name, which can be
6048 * used with non-IDN-aware applications and protocols. (For example,
6049 * "Παν語.org" maps to "xn--4wa8awb4637h.org".)
6055 * @title: Perl-compatible regular expressions
6056 * @short_description: matches strings against regular expressions
6057 * @see_also: [Regular expression syntax][glib-regex-syntax]
6059 * The g_regex_*() functions implement regular
6060 * expression pattern matching using syntax and semantics similar to
6061 * Perl regular expression.
6063 * Some functions accept a @start_position argument, setting it differs
6064 * from just passing over a shortened string and setting #G_REGEX_MATCH_NOTBOL
6065 * in the case of a pattern that begins with any kind of lookbehind assertion.
6066 * For example, consider the pattern "\Biss\B" which finds occurrences of "iss"
6067 * in the middle of words. ("\B" matches only if the current position in the
6068 * subject is not a word boundary.) When applied to the string "Mississipi"
6069 * from the fourth byte, namely "issipi", it does not match, because "\B" is
6070 * always false at the start of the subject, which is deemed to be a word
6071 * boundary. However, if the entire string is passed , but with
6072 * @start_position set to 4, it finds the second occurrence of "iss" because
6073 * it is able to look behind the starting point to discover that it is
6074 * preceded by a letter.
6076 * Note that, unless you set the #G_REGEX_RAW flag, all the strings passed
6077 * to these functions must be encoded in UTF-8. The lengths and the positions
6078 * inside the strings are in bytes and not in characters, so, for instance,
6079 * "\xc3\xa0" (i.e. "Ã ") is two bytes long but it is treated as a
6080 * single character. If you set #G_REGEX_RAW the strings can be non-valid
6081 * UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two
6082 * bytes and two characters long.
6084 * When matching a pattern, "\n" matches only against a "\n" character in
6085 * the string, and "\r" matches only a "\r" character. To match any newline
6086 * sequence use "\R". This particular group matches either the two-character
6087 * sequence CR + LF ("\r\n"), or one of the single characters LF (linefeed,
6088 * U+000A, "\n"), VT vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"),
6089 * CR (carriage return, U+000D, "\r"), NEL (next line, U+0085), LS (line
6090 * separator, U+2028), or PS (paragraph separator, U+2029).
6092 * The behaviour of the dot, circumflex, and dollar metacharacters are
6093 * affected by newline characters, the default is to recognize any newline
6094 * character (the same characters recognized by "\R"). This can be changed
6095 * with #G_REGEX_NEWLINE_CR, #G_REGEX_NEWLINE_LF and #G_REGEX_NEWLINE_CRLF
6096 * compile options, and with #G_REGEX_MATCH_NEWLINE_ANY,
6097 * #G_REGEX_MATCH_NEWLINE_CR, #G_REGEX_MATCH_NEWLINE_LF and
6098 * #G_REGEX_MATCH_NEWLINE_CRLF match options. These settings are also
6099 * relevant when compiling a pattern if #G_REGEX_EXTENDED is set, and an
6100 * unescaped "#" outside a character class is encountered. This indicates
6101 * a comment that lasts until after the next newline.
6103 * When setting the %G_REGEX_JAVASCRIPT_COMPAT flag, pattern syntax and pattern
6104 * matching is changed to be compatible with the way that regular expressions
6105 * work in JavaScript. More precisely, a lonely ']' character in the pattern
6106 * is a syntax error; the '\x' escape only allows 0 to 2 hexadecimal digits, and
6107 * you must use the '\u' escape sequence with 4 hex digits to specify a unicode
6108 * codepoint instead of '\x' or 'x{....}'. If '\x' or '\u' are not followed by
6109 * the specified number of hex digits, they match 'x' and 'u' literally; also
6110 * '\U' always matches 'U' instead of being an error in the pattern. Finally,
6111 * pattern matching is modified so that back references to an unset subpattern
6112 * group produces a match with the empty string instead of an error. See
6113 * pcreapi(3) for more information.
6115 * Creating and manipulating the same #GRegex structure from different
6116 * threads is not a problem as #GRegex does not modify its internal
6117 * state between creation and destruction, on the other hand #GMatchInfo
6118 * is not threadsafe.
6120 * The regular expressions low-level functionalities are obtained through
6122 * [PCRE](http://www.pcre.org/)
6123 * library written by Philip Hazel.
6129 * @title: UNIX-specific utilities and integration
6130 * @short_description: pipes, signal handling
6131 * @include: glib-unix.h
6133 * Most of GLib is intended to be portable; in contrast, this set of
6134 * functions is designed for programs which explicitly target UNIX,
6135 * or are using it to build higher level abstractions which would be
6136 * conditionally compiled if the platform matches G_OS_UNIX.
6138 * To use these functions, you must explicitly include the
6139 * "glib-unix.h" header.
6145 * @title: URI Functions
6146 * @short_description: manipulating URIs
6148 * Functions for manipulating Universal Resource Identifiers (URIs) as
6150 * [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt).
6151 * It is highly recommended that you have read and
6152 * understand RFC 3986 for understanding this API.
6159 * @short_description: strongly typed value datatype
6160 * @see_also: GVariantType
6162 * #GVariant is a variant datatype; it can contain one or more values
6163 * along with information about the type of the values.
6165 * A #GVariant may contain simple types, like an integer, or a boolean value;
6166 * or complex types, like an array of two strings, or a dictionary of key
6167 * value pairs. A #GVariant is also immutable: once it's been created neither
6168 * its type nor its content can be modified further.
6170 * GVariant is useful whenever data needs to be serialized, for example when
6171 * sending method parameters in DBus, or when saving settings using GSettings.
6173 * When creating a new #GVariant, you pass the data you want to store in it
6174 * along with a string representing the type of data you wish to pass to it.
6176 * For instance, if you want to create a #GVariant holding an integer value you
6179 * |[<!-- language="C" -->
6180 * GVariant *v = g_variant_new ('u', 40);
6183 * The string 'u' in the first argument tells #GVariant that the data passed to
6184 * the constructor (40) is going to be an unsigned integer.
6186 * More advanced examples of #GVariant in use can be found in documentation for
6187 * [GVariant format strings][gvariant-format-strings-pointers].
6189 * The range of possible values is determined by the type.
6191 * The type system used by #GVariant is #GVariantType.
6193 * #GVariant instances always have a type and a value (which are given
6194 * at construction time). The type and value of a #GVariant instance
6195 * can never change other than by the #GVariant itself being
6196 * destroyed. A #GVariant cannot contain a pointer.
6198 * #GVariant is reference counted using g_variant_ref() and
6199 * g_variant_unref(). #GVariant also has floating reference counts --
6200 * see g_variant_ref_sink().
6202 * #GVariant is completely threadsafe. A #GVariant instance can be
6203 * concurrently accessed in any way from any number of threads without
6206 * #GVariant is heavily optimised for dealing with data in serialised
6207 * form. It works particularly well with data located in memory-mapped
6208 * files. It can perform nearly all deserialisation operations in a
6209 * small constant time, usually touching only a single memory page.
6210 * Serialised #GVariant data can also be sent over the network.
6212 * #GVariant is largely compatible with D-Bus. Almost all types of
6213 * #GVariant instances can be sent over D-Bus. See #GVariantType for
6214 * exceptions. (However, #GVariant's serialisation format is not the same
6215 * as the serialisation format of a D-Bus message body: use #GDBusMessage,
6216 * in the gio library, for those.)
6218 * For space-efficiency, the #GVariant serialisation format does not
6219 * automatically include the variant's length, type or endianness,
6220 * which must either be implied from context (such as knowledge that a
6221 * particular file format always contains a little-endian
6222 * %G_VARIANT_TYPE_VARIANT which occupies the whole length of the file)
6223 * or supplied out-of-band (for instance, a length, type and/or endianness
6224 * indicator could be placed at the beginning of a file, network message
6225 * or network stream).
6227 * A #GVariant's size is limited mainly by any lower level operating
6228 * system constraints, such as the number of bits in #gsize. For
6229 * example, it is reasonable to have a 2GB file mapped into memory
6230 * with #GMappedFile, and call g_variant_new_from_data() on it.
6232 * For convenience to C programmers, #GVariant features powerful
6233 * varargs-based value construction and destruction. This feature is
6234 * designed to be embedded in other libraries.
6236 * There is a Python-inspired text language for describing #GVariant
6237 * values. #GVariant includes a printer for this language and a parser
6238 * with type inferencing.
6242 * #GVariant tries to be quite efficient with respect to memory use.
6243 * This section gives a rough idea of how much memory is used by the
6244 * current implementation. The information here is subject to change
6247 * The memory allocated by #GVariant can be grouped into 4 broad
6248 * purposes: memory for serialised data, memory for the type
6249 * information cache, buffer management memory and memory for the
6250 * #GVariant structure itself.
6252 * ## Serialised Data Memory
6254 * This is the memory that is used for storing GVariant data in
6255 * serialised form. This is what would be sent over the network or
6256 * what would end up on disk, not counting any indicator of the
6257 * endianness, or of the length or type of the top-level variant.
6259 * The amount of memory required to store a boolean is 1 byte. 16,
6260 * 32 and 64 bit integers and double precision floating point numbers
6261 * use their "natural" size. Strings (including object path and
6262 * signature strings) are stored with a nul terminator, and as such
6263 * use the length of the string plus 1 byte.
6265 * Maybe types use no space at all to represent the null value and
6266 * use the same amount of space (sometimes plus one byte) as the
6267 * equivalent non-maybe-typed value to represent the non-null case.
6269 * Arrays use the amount of space required to store each of their
6270 * members, concatenated. Additionally, if the items stored in an
6271 * array are not of a fixed-size (ie: strings, other arrays, etc)
6272 * then an additional framing offset is stored for each item. The
6273 * size of this offset is either 1, 2 or 4 bytes depending on the
6274 * overall size of the container. Additionally, extra padding bytes
6275 * are added as required for alignment of child values.
6277 * Tuples (including dictionary entries) use the amount of space
6278 * required to store each of their members, concatenated, plus one
6279 * framing offset (as per arrays) for each non-fixed-sized item in
6280 * the tuple, except for the last one. Additionally, extra padding
6281 * bytes are added as required for alignment of child values.
6283 * Variants use the same amount of space as the item inside of the
6284 * variant, plus 1 byte, plus the length of the type string for the
6285 * item inside the variant.
6287 * As an example, consider a dictionary mapping strings to variants.
6288 * In the case that the dictionary is empty, 0 bytes are required for
6289 * the serialisation.
6291 * If we add an item "width" that maps to the int32 value of 500 then
6292 * we will use 4 byte to store the int32 (so 6 for the variant
6293 * containing it) and 6 bytes for the string. The variant must be
6294 * aligned to 8 after the 6 bytes of the string, so that's 2 extra
6295 * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
6296 * for the dictionary entry. An additional 1 byte is added to the
6297 * array as a framing offset making a total of 15 bytes.
6299 * If we add another entry, "title" that maps to a nullable string
6300 * that happens to have a value of null, then we use 0 bytes for the
6301 * null value (and 3 bytes for the variant to contain it along with
6302 * its type string) plus 6 bytes for the string. Again, we need 2
6303 * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes.
6305 * We now require extra padding between the two items in the array.
6306 * After the 14 bytes of the first item, that's 2 bytes required.
6307 * We now require 2 framing offsets for an extra two
6308 * bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item
6311 * ## Type Information Cache
6313 * For each GVariant type that currently exists in the program a type
6314 * information structure is kept in the type information cache. The
6315 * type information structure is required for rapid deserialisation.
6317 * Continuing with the above example, if a #GVariant exists with the
6318 * type "a{sv}" then a type information struct will exist for
6319 * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type
6320 * will share the same type information. Additionally, all
6321 * single-digit types are stored in read-only static memory and do
6322 * not contribute to the writable memory footprint of a program using
6325 * Aside from the type information structures stored in read-only
6326 * memory, there are two forms of type information. One is used for
6327 * container types where there is a single element type: arrays and
6328 * maybe types. The other is used for container types where there
6329 * are multiple element types: tuples and dictionary entries.
6331 * Array type info structures are 6 * sizeof (void *), plus the
6332 * memory required to store the type string itself. This means that
6333 * on 32-bit systems, the cache entry for "a{sv}" would require 30
6334 * bytes of memory (plus malloc overhead).
6336 * Tuple type info structures are 6 * sizeof (void *), plus 4 *
6337 * sizeof (void *) for each item in the tuple, plus the memory
6338 * required to store the type string itself. A 2-item tuple, for
6339 * example, would have a type information structure that consumed
6340 * writable memory in the size of 14 * sizeof (void *) (plus type
6341 * string) This means that on 32-bit systems, the cache entry for
6342 * "{sv}" would require 61 bytes of memory (plus malloc overhead).
6344 * This means that in total, for our "a{sv}" example, 91 bytes of
6345 * type information would be allocated.
6347 * The type information cache, additionally, uses a #GHashTable to
6348 * store and lookup the cached items and stores a pointer to this
6349 * hash table in static storage. The hash table is freed when there
6350 * are zero items in the type cache.
6352 * Although these sizes may seem large it is important to remember
6353 * that a program will probably only have a very small number of
6354 * different types of values in it and that only one type information
6355 * structure is required for many different values of the same type.
6357 * ## Buffer Management Memory
6359 * #GVariant uses an internal buffer management structure to deal
6360 * with the various different possible sources of serialised data
6361 * that it uses. The buffer is responsible for ensuring that the
6362 * correct call is made when the data is no longer in use by
6363 * #GVariant. This may involve a g_free() or a g_slice_free() or
6364 * even g_mapped_file_unref().
6366 * One buffer management structure is used for each chunk of
6367 * serialised data. The size of the buffer management structure
6368 * is 4 * (void *). On 32-bit systems, that's 16 bytes.
6370 * ## GVariant structure
6372 * The size of a #GVariant structure is 6 * (void *). On 32-bit
6373 * systems, that's 24 bytes.
6375 * #GVariant structures only exist if they are explicitly created
6376 * with API calls. For example, if a #GVariant is constructed out of
6377 * serialised data for the example given above (with the dictionary)
6378 * then although there are 9 individual values that comprise the
6379 * entire dictionary (two keys, two values, two variants containing
6380 * the values, two dictionary entries, plus the dictionary itself),
6381 * only 1 #GVariant instance exists -- the one referring to the
6384 * If calls are made to start accessing the other values then
6385 * #GVariant instances will exist for those values only for as long
6386 * as they are in use (ie: until you call g_variant_unref()). The
6387 * type information is shared. The serialised data and the buffer
6388 * management structure for that serialised data is shared by the
6393 * To put the entire example together, for our dictionary mapping
6394 * strings to variants (with two entries, as given above), we are
6395 * using 91 bytes of memory for type information, 29 byes of memory
6396 * for the serialised data, 16 bytes for buffer management and 24
6397 * bytes for the #GVariant instance, or a total of 160 bytes, plus
6398 * malloc overhead. If we were to use g_variant_get_child_value() to
6399 * access the two dictionary entries, we would use an additional 48
6400 * bytes. If we were to have other dictionaries of the same type, we
6401 * would use more memory for the serialised data and buffer
6402 * management for those dictionaries, but the type information would
6408 * SECTION:gvarianttype
6409 * @title: GVariantType
6410 * @short_description: introduction to the GVariant type system
6411 * @see_also: #GVariantType, #GVariant
6413 * This section introduces the GVariant type system. It is based, in
6414 * large part, on the D-Bus type system, with two major changes and
6415 * some minor lifting of restrictions. The
6416 * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html),
6417 * therefore, provides a significant amount of
6418 * information that is useful when working with GVariant.
6420 * The first major change with respect to the D-Bus type system is the
6421 * introduction of maybe (or "nullable") types. Any type in GVariant can be
6422 * converted to a maybe type, in which case, "nothing" (or "null") becomes a
6423 * valid value. Maybe types have been added by introducing the
6424 * character "m" to type strings.
6426 * The second major change is that the GVariant type system supports the
6427 * concept of "indefinite types" -- types that are less specific than
6428 * the normal types found in D-Bus. For example, it is possible to speak
6429 * of "an array of any type" in GVariant, where the D-Bus type system
6430 * would require you to speak of "an array of integers" or "an array of
6431 * strings". Indefinite types have been added by introducing the
6432 * characters "*", "?" and "r" to type strings.
6434 * Finally, all arbitrary restrictions relating to the complexity of
6435 * types are lifted along with the restriction that dictionary entries
6436 * may only appear nested inside of arrays.
6438 * Just as in D-Bus, GVariant types are described with strings ("type
6439 * strings"). Subject to the differences mentioned above, these strings
6440 * are of the same form as those found in DBus. Note, however: D-Bus
6441 * always works in terms of messages and therefore individual type
6442 * strings appear nowhere in its interface. Instead, "signatures"
6443 * are a concatenation of the strings of the type of each argument in a
6444 * message. GVariant deals with single values directly so GVariant type
6445 * strings always describe the type of exactly one value. This means
6446 * that a D-Bus signature string is generally not a valid GVariant type
6447 * string -- except in the case that it is the signature of a message
6448 * containing exactly one argument.
6450 * An indefinite type is similar in spirit to what may be called an
6451 * abstract type in other type systems. No value can exist that has an
6452 * indefinite type as its type, but values can exist that have types
6453 * that are subtypes of indefinite types. That is to say,
6454 * g_variant_get_type() will never return an indefinite type, but
6455 * calling g_variant_is_of_type() with an indefinite type may return
6456 * %TRUE. For example, you cannot have a value that represents "an
6457 * array of no particular type", but you can have an "array of integers"
6458 * which certainly matches the type of "an array of no particular type",
6459 * since "array of integers" is a subtype of "array of no particular
6462 * This is similar to how instances of abstract classes may not
6463 * directly exist in other type systems, but instances of their
6464 * non-abstract subtypes may. For example, in GTK, no object that has
6465 * the type of #GtkBin can exist (since #GtkBin is an abstract class),
6466 * but a #GtkWindow can certainly be instantiated, and you would say
6467 * that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of
6470 * ## GVariant Type Strings
6472 * A GVariant type string can be any of the following:
6474 * - any basic type string (listed below)
6478 * - one of the characters 'a' or 'm', followed by another type string
6480 * - the character '(', followed by a concatenation of zero or more other
6481 * type strings, followed by the character ')'
6483 * - the character '{', followed by a basic type string (see below),
6484 * followed by another type string, followed by the character '}'
6486 * A basic type string describes a basic type (as per
6487 * g_variant_type_is_basic()) and is always a single character in length.
6488 * The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t",
6489 * "h", "d", "s", "o", "g" and "?".
6491 * The above definition is recursive to arbitrary depth. "aaaaai" and
6492 * "(ui(nq((y)))s)" are both valid type strings, as is
6493 * "a(aa(ui)(qna{ya(yd)}))".
6495 * The meaning of each of the characters is as follows:
6496 * - `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
6497 * - `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte.
6498 * - `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer.
6499 * - `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer.
6500 * - `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer.
6501 * - `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer.
6502 * - `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer.
6503 * - `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer.
6504 * - `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value
6505 * that, by convention, is used as an index into an array of file
6506 * descriptors that are sent alongside a D-Bus message.
6507 * - `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
6508 * floating point value.
6509 * - `s`: the type string of %G_VARIANT_TYPE_STRING; a string.
6510 * - `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form
6511 * of a D-Bus object path.
6512 * - `g`: the type string of %G_VARIANT_TYPE_STRING; a string in the form of
6513 * a D-Bus type signature.
6514 * - `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that
6515 * is a supertype of any of the basic types.
6516 * - `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that
6517 * contain any other type of value.
6518 * - `a`: used as a prefix on another type string to mean an array of that
6519 * type; the type string "ai", for example, is the type of an array of
6520 * signed 32-bit integers.
6521 * - `m`: used as a prefix on another type string to mean a "maybe", or
6522 * "nullable", version of that type; the type string "ms", for example,
6523 * is the type of a value that maybe contains a string, or maybe contains
6525 * - `()`: used to enclose zero or more other concatenated type strings to
6526 * create a tuple type; the type string "(is)", for example, is the type of
6527 * a pair of an integer and a string.
6528 * - `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is
6529 * a supertype of any tuple type, regardless of the number of items.
6530 * - `{}`: used to enclose a basic type string concatenated with another type
6531 * string to create a dictionary entry type, which usually appears inside of
6532 * an array to form a dictionary; the type string "a{sd}", for example, is
6533 * the type of a dictionary that maps strings to double precision floating
6536 * The first type (the basic type) is the key type and the second type is
6537 * the value type. The reason that the first type is restricted to being a
6538 * basic type is so that it can easily be hashed.
6539 * - `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is
6540 * a supertype of all types. Note that, as with all type strings, this
6541 * character represents exactly one type. It cannot be used inside of tuples
6542 * to mean "any number of items".
6544 * Any type string of a container that contains an indefinite type is,
6545 * itself, an indefinite type. For example, the type string "a*"
6546 * (corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type
6547 * that is a supertype of every array type. "(*s)" is a supertype
6548 * of all tuples that contain exactly two items where the second
6551 * "a{?*}" is an indefinite type that is a supertype of all arrays
6552 * containing dictionary entries where the key is any basic type and
6553 * the value is any type at all. This is, by definition, a dictionary,
6554 * so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note
6555 * that, due to the restriction that the key of a dictionary entry must
6556 * be a basic type, "{**}" is not a valid type string.
6561 * SECTION:hash_tables
6562 * @title: Hash Tables
6563 * @short_description: associations between keys and values so that
6564 * given a key the value can be found quickly
6566 * A #GHashTable provides associations between keys and values which is
6567 * optimized so that given a key, the associated value can be found
6570 * Note that neither keys nor values are copied when inserted into the
6571 * #GHashTable, so they must exist for the lifetime of the #GHashTable.
6572 * This means that the use of static strings is OK, but temporary
6573 * strings (i.e. those created in buffers and those returned by GTK+
6574 * widgets) should be copied with g_strdup() before being inserted.
6576 * If keys or values are dynamically allocated, you must be careful to
6577 * ensure that they are freed when they are removed from the
6578 * #GHashTable, and also when they are overwritten by new insertions
6579 * into the #GHashTable. It is also not advisable to mix static strings
6580 * and dynamically-allocated strings in a #GHashTable, because it then
6581 * becomes difficult to determine whether the string should be freed.
6583 * To create a #GHashTable, use g_hash_table_new().
6585 * To insert a key and value into a #GHashTable, use
6586 * g_hash_table_insert().
6588 * To lookup a value corresponding to a given key, use
6589 * g_hash_table_lookup() and g_hash_table_lookup_extended().
6591 * g_hash_table_lookup_extended() can also be used to simply
6592 * check if a key is present in the hash table.
6594 * To remove a key and value, use g_hash_table_remove().
6596 * To call a function for each key and value pair use
6597 * g_hash_table_foreach() or use a iterator to iterate over the
6598 * key/value pairs in the hash table, see #GHashTableIter.
6600 * To destroy a #GHashTable use g_hash_table_destroy().
6602 * A common use-case for hash tables is to store information about a
6603 * set of keys, without associating any particular value with each
6604 * key. GHashTable optimizes one way of doing so: If you store only
6605 * key-value pairs where key == value, then GHashTable does not
6606 * allocate memory to store the values, which can be a considerable
6607 * space saving, if your set is large. The functions
6608 * g_hash_table_add() and g_hash_table_contains() are designed to be
6609 * used when using #GHashTable this way.
6615 * @title: Secure HMAC Digests
6616 * @short_description: computes the HMAC for data
6618 * HMACs should be used when producing a cookie or hash based on data
6619 * and a key. Simple mechanisms for using SHA1 and other algorithms to
6620 * digest a key and data together are vulnerable to various security
6622 * [HMAC](http://en.wikipedia.org/wiki/HMAC)
6623 * uses algorithms like SHA1 in a secure way to produce a digest of a
6626 * Both the key and data are arbitrary byte arrays of bytes or characters.
6628 * Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512
6635 * @title: Hook Functions
6636 * @short_description: support for manipulating lists of hook functions
6638 * The #GHookList, #GHook and their related functions provide support for
6639 * lists of hook functions. Functions can be added and removed from the lists,
6640 * and the list of hook functions can be invoked.
6646 * @title: Internationalization
6647 * @short_description: gettext support macros
6648 * @see_also: the gettext manual
6650 * GLib doesn't force any particular localization method upon its users.
6651 * But since GLib itself is localized using the gettext() mechanism, it seems
6652 * natural to offer the de-facto standard gettext() support macros in an
6655 * In order to use these macros in an application, you must include
6656 * `<glib/gi18n.h>`. For use in a library, you must include
6657 * `<glib/gi18n-lib.h>`
6658 * after defining the %GETTEXT_PACKAGE macro suitably for your library:
6659 * |[<!-- language="C" -->
6660 * #define GETTEXT_PACKAGE "gtk20"
6661 * #include <glib/gi18n-lib.h>
6663 * For an application, note that you also have to call bindtextdomain(),
6664 * bind_textdomain_codeset(), textdomain() and setlocale() early on in your
6665 * main() to make gettext() work. For example:
6666 * |[<!-- language="C" -->
6667 * #include <glib/gi18n.h>
6668 * #include <locale.h>
6671 * main (int argc, char **argv)
6673 * setlocale (LC_ALL, "");
6674 * bindtextdomain (GETTEXT_PACKAGE, DATADIR "/locale");
6675 * bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8");
6676 * textdomain (GETTEXT_PACKAGE);
6678 * // Rest of your application.
6681 * where `DATADIR` is as typically provided by automake.
6683 * For a library, you only have to call bindtextdomain() and
6684 * bind_textdomain_codeset() in your initialization function. If your library
6685 * doesn't have an initialization function, you can call the functions before
6686 * the first translated message.
6689 * [gettext manual](http://www.gnu.org/software/gettext/manual/gettext.html#Maintainers)
6690 * covers details of how to integrate gettext into a project’s build system and
6696 * SECTION:iochannels
6697 * @title: IO Channels
6698 * @short_description: portable support for using files, pipes and sockets
6699 * @see_also: g_io_add_watch(), g_io_add_watch_full(), g_source_remove(),
6702 * The #GIOChannel data type aims to provide a portable method for
6703 * using file descriptors, pipes, and sockets, and integrating them
6704 * into the [main event loop][glib-The-Main-Event-Loop]. Currently,
6705 * full support is available on UNIX platforms, support for Windows
6706 * is only partially complete.
6708 * To create a new #GIOChannel on UNIX systems use
6709 * g_io_channel_unix_new(). This works for plain file descriptors,
6710 * pipes and sockets. Alternatively, a channel can be created for a
6711 * file in a system independent manner using g_io_channel_new_file().
6713 * Once a #GIOChannel has been created, it can be used in a generic
6714 * manner with the functions g_io_channel_read_chars(),
6715 * g_io_channel_write_chars(), g_io_channel_seek_position(), and
6716 * g_io_channel_shutdown().
6718 * To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop],
6719 * use g_io_add_watch() or g_io_add_watch_full(). Here you specify which
6720 * events you are interested in on the #GIOChannel, and provide a
6721 * function to be called whenever these events occur.
6723 * #GIOChannel instances are created with an initial reference count of 1.
6724 * g_io_channel_ref() and g_io_channel_unref() can be used to
6725 * increment or decrement the reference count respectively. When the
6726 * reference count falls to 0, the #GIOChannel is freed. (Though it
6727 * isn't closed automatically, unless it was created using
6728 * g_io_channel_new_file().) Using g_io_add_watch() or
6729 * g_io_add_watch_full() increments a channel's reference count.
6731 * The new functions g_io_channel_read_chars(),
6732 * g_io_channel_read_line(), g_io_channel_read_line_string(),
6733 * g_io_channel_read_to_end(), g_io_channel_write_chars(),
6734 * g_io_channel_seek_position(), and g_io_channel_flush() should not be
6735 * mixed with the deprecated functions g_io_channel_read(),
6736 * g_io_channel_write(), and g_io_channel_seek() on the same channel.
6742 * @title: Key-value file parser
6743 * @short_description: parses .ini-like config files
6745 * #GKeyFile lets you parse, edit or create files containing groups of
6746 * key-value pairs, which we call "key files" for lack of a better name.
6747 * Several freedesktop.org specifications use key files now, e.g the
6748 * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
6750 * [Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec).
6752 * The syntax of key files is described in detail in the
6753 * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec),
6754 * here is a quick summary: Key files
6755 * consists of groups of key-value pairs, interspersed with comments.
6758 * # this is just an example
6759 * # there can be comments before the first group
6763 * Name=Key File Example\tthis value shows\nescaping
6765 * # localized strings are stored in multiple key-value pairs
6768 * Welcome[fr_FR]=Bonjour
6770 * Welcome[be@latin]=Hello
6774 * Numbers=2;20;-200;0
6776 * Booleans=true;false;true;true
6779 * Lines beginning with a '#' and blank lines are considered comments.
6781 * Groups are started by a header line containing the group name enclosed
6782 * in '[' and ']', and ended implicitly by the start of the next group or
6783 * the end of the file. Each key-value pair must be contained in a group.
6785 * Key-value pairs generally have the form `key=value`, with the
6786 * exception of localized strings, which have the form
6787 * `key[locale]=value`, with a locale identifier of the
6788 * form `lang_COUNTRY@MODIFIER` where `COUNTRY` and `MODIFIER`
6790 * Space before and after the '=' character are ignored. Newline, tab,
6791 * carriage return and backslash characters in value are escaped as \n,
6792 * \t, \r, and \\, respectively. To preserve leading spaces in values,
6793 * these can also be escaped as \s.
6795 * Key files can store strings (possibly with localized variants), integers,
6796 * booleans and lists of these. Lists are separated by a separator character,
6797 * typically ';' or ','. To use the list separator character in a value in
6798 * a list, it has to be escaped by prefixing it with a backslash.
6800 * This syntax is obviously inspired by the .ini files commonly met
6801 * on Windows, but there are some important differences:
6803 * - .ini files use the ';' character to begin comments,
6804 * key files use the '#' character.
6806 * - Key files do not allow for ungrouped keys meaning only
6807 * comments can precede the first group.
6809 * - Key files are always encoded in UTF-8.
6811 * - Key and Group names are case-sensitive. For example, a group called
6812 * [GROUP] is a different from [group].
6814 * - .ini files don't have a strongly typed boolean entry type,
6815 * they only have GetProfileInt(). In key files, only
6816 * true and false (in lower case) are allowed.
6818 * Note that in contrast to the
6819 * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec),
6820 * groups in key files may contain the same
6821 * key multiple times; the last entry wins. Key files may also contain
6822 * multiple groups with the same name; they are merged together.
6823 * Another difference is that keys and group names in key files are not
6824 * restricted to ASCII characters.
6829 * SECTION:linked_lists_double
6830 * @title: Doubly-Linked Lists
6831 * @short_description: linked lists that can be iterated over in both directions
6833 * The #GList structure and its associated functions provide a standard
6834 * doubly-linked list data structure.
6836 * Each element in the list contains a piece of data, together with
6837 * pointers which link to the previous and next elements in the list.
6838 * Using these pointers it is possible to move through the list in both
6839 * directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists],
6840 * which only allows movement through the list in the forward direction).
6842 * The double linked list does not keep track of the number of items
6843 * and does not keep track of both the start and end of the list. If
6844 * you want fast access to both the start and the end of the list,
6845 * and/or the number of items in the list, use a
6846 * [GQueue][glib-Double-ended-Queues] instead.
6848 * The data contained in each element can be either integer values, by
6849 * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
6850 * or simply pointers to any type of data.
6852 * List elements are allocated from the [slice allocator][glib-Memory-Slices],
6853 * which is more efficient than allocating elements individually.
6855 * Note that most of the #GList functions expect to be passed a pointer
6856 * to the first element in the list. The functions which insert
6857 * elements return the new start of the list, which may have changed.
6859 * There is no function to create a #GList. %NULL is considered to be
6860 * a valid, empty list so you simply set a #GList* to %NULL to initialize
6863 * To add elements, use g_list_append(), g_list_prepend(),
6864 * g_list_insert() and g_list_insert_sorted().
6866 * To visit all elements in the list, use a loop over the list:
6867 * |[<!-- language="C" -->
6869 * for (l = list; l != NULL; l = l->next)
6871 * // do something with l->data
6875 * To call a function for each element in the list, use g_list_foreach().
6877 * To loop over the list and modify it (e.g. remove a certain element)
6878 * a while loop is more appropriate, for example:
6879 * |[<!-- language="C" -->
6883 * GList *next = l->next;
6884 * if (should_be_removed (l))
6886 * // possibly free l->data
6887 * list = g_list_delete_link (list, l);
6893 * To remove elements, use g_list_remove().
6895 * To navigate in a list, use g_list_first(), g_list_last(),
6896 * g_list_next(), g_list_previous().
6898 * To find elements in the list use g_list_nth(), g_list_nth_data(),
6899 * g_list_find() and g_list_find_custom().
6901 * To find the index of an element use g_list_position() and
6904 * To free the entire list, use g_list_free() or g_list_free_full().
6909 * SECTION:linked_lists_single
6910 * @title: Singly-Linked Lists
6911 * @short_description: linked lists that can be iterated in one direction
6913 * The #GSList structure and its associated functions provide a
6914 * standard singly-linked list data structure.
6916 * Each element in the list contains a piece of data, together with a
6917 * pointer which links to the next element in the list. Using this
6918 * pointer it is possible to move through the list in one direction
6919 * only (unlike the [double-linked lists][glib-Doubly-Linked-Lists],
6920 * which allow movement in both directions).
6922 * The data contained in each element can be either integer values, by
6923 * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
6924 * or simply pointers to any type of data.
6926 * List elements are allocated from the [slice allocator][glib-Memory-Slices],
6927 * which is more efficient than allocating elements individually.
6929 * Note that most of the #GSList functions expect to be passed a
6930 * pointer to the first element in the list. The functions which insert
6931 * elements return the new start of the list, which may have changed.
6933 * There is no function to create a #GSList. %NULL is considered to be
6934 * the empty list so you simply set a #GSList* to %NULL.
6936 * To add elements, use g_slist_append(), g_slist_prepend(),
6937 * g_slist_insert() and g_slist_insert_sorted().
6939 * To remove elements, use g_slist_remove().
6941 * To find elements in the list use g_slist_last(), g_slist_next(),
6942 * g_slist_nth(), g_slist_nth_data(), g_slist_find() and
6943 * g_slist_find_custom().
6945 * To find the index of an element use g_slist_position() and
6948 * To call a function for each element in the list use
6949 * g_slist_foreach().
6951 * To free the entire list, use g_slist_free().
6957 * @title: Standard Macros
6958 * @short_description: commonly-used macros
6960 * These macros provide a few commonly-used features.
6965 * SECTION:macros_misc
6966 * @title: Miscellaneous Macros
6967 * @short_description: specialized macros which are not used often
6969 * These macros provide more specialized features which are not
6970 * needed so often by application programmers.
6976 * @title: The Main Event Loop
6977 * @short_description: manages all available sources of events
6979 * The main event loop manages all the available sources of events for
6980 * GLib and GTK+ applications. These events can come from any number of
6981 * different types of sources such as file descriptors (plain files,
6982 * pipes or sockets) and timeouts. New types of event sources can also
6983 * be added using g_source_attach().
6985 * To allow multiple independent sets of sources to be handled in
6986 * different threads, each source is associated with a #GMainContext.
6987 * A GMainContext can only be running in a single thread, but
6988 * sources can be added to it and removed from it from other threads.
6990 * Each event source is assigned a priority. The default priority,
6991 * #G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities.
6992 * Values greater than 0 denote lower priorities. Events from high priority
6993 * sources are always processed before events from lower priority sources.
6995 * Idle functions can also be added, and assigned a priority. These will
6996 * be run whenever no events with a higher priority are ready to be processed.
6998 * The #GMainLoop data type represents a main event loop. A GMainLoop is
6999 * created with g_main_loop_new(). After adding the initial event sources,
7000 * g_main_loop_run() is called. This continuously checks for new events from
7001 * each of the event sources and dispatches them. Finally, the processing of
7002 * an event from one of the sources leads to a call to g_main_loop_quit() to
7003 * exit the main loop, and g_main_loop_run() returns.
7005 * It is possible to create new instances of #GMainLoop recursively.
7006 * This is often used in GTK+ applications when showing modal dialog
7007 * boxes. Note that event sources are associated with a particular
7008 * #GMainContext, and will be checked and dispatched for all main
7009 * loops associated with that GMainContext.
7011 * GTK+ contains wrappers of some of these functions, e.g. gtk_main(),
7012 * gtk_main_quit() and gtk_events_pending().
7014 * ## Creating new source types
7016 * One of the unusual features of the #GMainLoop functionality
7017 * is that new types of event source can be created and used in
7018 * addition to the builtin type of event source. A new event source
7019 * type is used for handling GDK events. A new source type is created
7020 * by "deriving" from the #GSource structure. The derived type of
7021 * source is represented by a structure that has the #GSource structure
7022 * as a first element, and other elements specific to the new source
7023 * type. To create an instance of the new source type, call
7024 * g_source_new() passing in the size of the derived structure and
7025 * a table of functions. These #GSourceFuncs determine the behavior of
7026 * the new source type.
7028 * New source types basically interact with the main context
7029 * in two ways. Their prepare function in #GSourceFuncs can set a timeout
7030 * to determine the maximum amount of time that the main loop will sleep
7031 * before checking the source again. In addition, or as well, the source
7032 * can add file descriptors to the set that the main context checks using
7033 * g_source_add_poll().
7035 * ## Customizing the main loop iteration
7037 * Single iterations of a #GMainContext can be run with
7038 * g_main_context_iteration(). In some cases, more detailed control
7039 * of exactly how the details of the main loop work is desired, for
7040 * instance, when integrating the #GMainLoop with an external main loop.
7041 * In such cases, you can call the component functions of
7042 * g_main_context_iteration() directly. These functions are
7043 * g_main_context_prepare(), g_main_context_query(),
7044 * g_main_context_check() and g_main_context_dispatch().
7046 * ## State of a Main Context # {#mainloop-states}
7048 * The operation of these functions can best be seen in terms
7049 * of a state diagram, as shown in this image.
7051 * ![](mainloop-states.gif)
7053 * On UNIX, the GLib mainloop is incompatible with fork(). Any program
7054 * using the mainloop must either exec() or exit() from the child
7055 * without returning to the mainloop.
7057 * ## Memory management of sources # {#mainloop-memory-management}
7059 * There are two options for memory management of the user data passed to a
7060 * #GSource to be passed to its callback on invocation. This data is provided
7061 * in calls to g_timeout_add(), g_timeout_add_full(), g_idle_add(), etc. and
7062 * more generally, using g_source_set_callback(). This data is typically an
7063 * object which ‘owns’ the timeout or idle callback, such as a widget or a
7064 * network protocol implementation. In many cases, it is an error for the
7065 * callback to be invoked after this owning object has been destroyed, as that
7066 * results in use of freed memory.
7068 * The first, and preferred, option is to store the source ID returned by
7069 * functions such as g_timeout_add() or g_source_attach(), and explicitly
7070 * remove that source from the main context using g_source_remove() when the
7071 * owning object is finalized. This ensures that the callback can only be
7072 * invoked while the object is still alive.
7074 * The second option is to hold a strong reference to the object in the
7075 * callback, and to release it in the callback’s #GDestroyNotify. This ensures
7076 * that the object is kept alive until after the source is finalized, which is
7077 * guaranteed to be after it is invoked for the final time. The #GDestroyNotify
7078 * is another callback passed to the ‘full’ variants of #GSource functions (for
7079 * example, g_timeout_add_full()). It is called when the source is finalized,
7080 * and is designed for releasing references like this.
7082 * One important caveat of this second approach is that it will keep the object
7083 * alive indefinitely if the main loop is stopped before the #GSource is
7084 * invoked, which may be undesirable.
7090 * @Title: Simple XML Subset Parser
7091 * @Short_description: parses a subset of XML
7092 * @See_also: [XML Specification](http://www.w3.org/TR/REC-xml/)
7094 * The "GMarkup" parser is intended to parse a simple markup format
7095 * that's a subset of XML. This is a small, efficient, easy-to-use
7096 * parser. It should not be used if you expect to interoperate with
7097 * other applications generating full-scale XML. However, it's very
7098 * useful for application data files, config files, etc. where you
7099 * know your application will be the only one writing the file.
7100 * Full-scale XML parsers should be able to parse the subset used by
7101 * GMarkup, so you can easily migrate to full-scale XML at a later
7102 * time if the need arises.
7104 * GMarkup is not guaranteed to signal an error on all invalid XML;
7105 * the parser may accept documents that an XML parser would not.
7106 * However, XML documents which are not well-formed (which is a
7107 * weaker condition than being valid. See the
7108 * [XML specification](http://www.w3.org/TR/REC-xml/)
7109 * for definitions of these terms.) are not considered valid GMarkup
7112 * Simplifications to XML include:
7114 * - Only UTF-8 encoding is allowed
7116 * - No user-defined entities
7118 * - Processing instructions, comments and the doctype declaration
7119 * are "passed through" but are not interpreted in any way
7121 * - No DTD or validation
7123 * The markup format does support:
7129 * - 5 standard entities: & < > " '
7131 * - Character references
7133 * - Sections marked as CDATA
7139 * @Short_Description: general memory-handling
7140 * @Title: Memory Allocation
7142 * These functions provide support for allocating and freeing memory.
7144 * If any call to allocate memory fails, the application is terminated.
7145 * This also means that there is no need to check if the call succeeded.
7147 * It's important to match g_malloc() (and wrappers such as g_new()) with
7148 * g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with
7149 * g_slice_free(), plain malloc() with free(), and (if you're using C++)
7150 * new with delete and new[] with delete[]. Otherwise bad things can happen,
7151 * since these allocators may use different memory pools (and new/delete call
7152 * constructors and destructors).
7157 * SECTION:memory_slices
7158 * @title: Memory Slices
7159 * @short_description: efficient way to allocate groups of equal-sized
7162 * Memory slices provide a space-efficient and multi-processing scalable
7163 * way to allocate equal-sized pieces of memory, just like the original
7164 * #GMemChunks (from GLib 2.8), while avoiding their excessive
7165 * memory-waste, scalability and performance problems.
7167 * To achieve these goals, the slice allocator uses a sophisticated,
7168 * layered design that has been inspired by Bonwick's slab allocator
7169 * ([Bonwick94](http://citeseer.ist.psu.edu/bonwick94slab.html)
7170 * Jeff Bonwick, The slab allocator: An object-caching kernel
7171 * memory allocator. USENIX 1994, and
7172 * [Bonwick01](http://citeseer.ist.psu.edu/bonwick01magazines.html)
7173 * Bonwick and Jonathan Adams, Magazines and vmem: Extending the
7174 * slab allocator to many cpu's and arbitrary resources. USENIX 2001)
7176 * It uses posix_memalign() to optimize allocations of many equally-sized
7177 * chunks, and has per-thread free lists (the so-called magazine layer)
7178 * to quickly satisfy allocation requests of already known structure sizes.
7179 * This is accompanied by extra caching logic to keep freed memory around
7180 * for some time before returning it to the system. Memory that is unused
7181 * due to alignment constraints is used for cache colorization (random
7182 * distribution of chunk addresses) to improve CPU cache utilization. The
7183 * caching layer of the slice allocator adapts itself to high lock contention
7184 * to improve scalability.
7186 * The slice allocator can allocate blocks as small as two pointers, and
7187 * unlike malloc(), it does not reserve extra space per block. For large block
7188 * sizes, g_slice_new() and g_slice_alloc() will automatically delegate to the
7189 * system malloc() implementation. For newly written code it is recommended
7190 * to use the new `g_slice` API instead of g_malloc() and
7191 * friends, as long as objects are not resized during their lifetime and the
7192 * object size used at allocation time is still available when freeing.
7194 * Here is an example for using the slice allocator:
7195 * |[<!-- language="C" -->
7196 * gchar *mem[10000];
7199 * // Allocate 10000 blocks.
7200 * for (i = 0; i < 10000; i++)
7202 * mem[i] = g_slice_alloc (50);
7204 * // Fill in the memory with some junk.
7205 * for (j = 0; j < 50; j++)
7206 * mem[i][j] = i * j;
7209 * // Now free all of the blocks.
7210 * for (i = 0; i < 10000; i++)
7211 * g_slice_free1 (50, mem[i]);
7214 * And here is an example for using the using the slice allocator
7215 * with data structures:
7216 * |[<!-- language="C" -->
7217 * GRealArray *array;
7219 * // Allocate one block, using the g_slice_new() macro.
7220 * array = g_slice_new (GRealArray);
7222 * // We can now use array just like a normal pointer to a structure.
7223 * array->data = NULL;
7226 * array->zero_terminated = (zero_terminated ? 1 : 0);
7227 * array->clear = (clear ? 1 : 0);
7228 * array->elt_size = elt_size;
7230 * // We can free the block, so it can be reused.
7231 * g_slice_free (GRealArray, array);
7238 * @title: Message Logging
7239 * @short_description: versatile support for logging messages
7240 * with different levels of importance
7242 * These functions provide support for logging error messages
7243 * or messages used for debugging.
7245 * There are several built-in levels of messages, defined in
7246 * #GLogLevelFlags. These can be extended with user-defined levels.
7251 * SECTION:misc_utils
7252 * @title: Miscellaneous Utility Functions
7253 * @short_description: a selection of portable utility functions
7255 * These are portable utility functions.
7261 * @title: Numerical Definitions
7262 * @short_description: mathematical constants, and floating point decomposition
7264 * GLib offers mathematical constants such as #G_PI for the value of pi;
7265 * many platforms have these in the C library, but some don't, the GLib
7266 * versions always exist.
7268 * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the
7269 * sign, mantissa and exponent of IEEE floats and doubles. These unions are
7270 * defined as appropriate for a given platform. IEEE floats and doubles are
7271 * supported (used for storage) by at least Intel, PPC and Sparc. See
7272 * [IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float)
7273 * for more information about IEEE number formats.
7279 * @Short_description: parses commandline options
7280 * @Title: Commandline option parser
7282 * The GOption commandline parser is intended to be a simpler replacement
7283 * for the popt library. It supports short and long commandline options,
7284 * as shown in the following example:
7286 * `testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2`
7288 * The example demonstrates a number of features of the GOption
7289 * commandline parser:
7291 * - Options can be single letters, prefixed by a single dash.
7293 * - Multiple short options can be grouped behind a single dash.
7295 * - Long options are prefixed by two consecutive dashes.
7297 * - Options can have an extra argument, which can be a number, a string or
7298 * a filename. For long options, the extra argument can be appended with
7299 * an equals sign after the option name, which is useful if the extra
7300 * argument starts with a dash, which would otherwise cause it to be
7301 * interpreted as another option.
7303 * - Non-option arguments are returned to the application as rest arguments.
7305 * - An argument consisting solely of two dashes turns off further parsing,
7306 * any remaining arguments (even those starting with a dash) are returned
7307 * to the application as rest arguments.
7309 * Another important feature of GOption is that it can automatically
7310 * generate nicely formatted help output. Unless it is explicitly turned
7311 * off with g_option_context_set_help_enabled(), GOption will recognize
7312 * the `--help`, `-?`, `--help-all` and `--help-groupname` options
7313 * (where `groupname` is the name of a #GOptionGroup) and write a text
7314 * similar to the one shown in the following example to stdout.
7318 * testtreemodel [OPTION...] - test tree model performance
7321 * -h, --help Show help options
7322 * --help-all Show all help options
7323 * --help-gtk Show GTK+ Options
7325 * Application Options:
7326 * -r, --repeats=N Average over N repetitions
7327 * -m, --max-size=M Test up to 2^M items
7328 * --display=DISPLAY X display to use
7329 * -v, --verbose Be verbose
7330 * -b, --beep Beep when done
7331 * --rand Randomize the data
7334 * GOption groups options in #GOptionGroups, which makes it easy to
7335 * incorporate options from multiple sources. The intended use for this is
7336 * to let applications collect option groups from the libraries it uses,
7337 * add them to their #GOptionContext, and parse all options by a single call
7338 * to g_option_context_parse(). See gtk_get_option_group() for an example.
7340 * If an option is declared to be of type string or filename, GOption takes
7341 * care of converting it to the right encoding; strings are returned in
7342 * UTF-8, filenames are returned in the GLib filename encoding. Note that
7343 * this only works if setlocale() has been called before
7344 * g_option_context_parse().
7346 * Here is a complete example of setting up GOption to parse the example
7347 * commandline above and produce the example help output.
7348 * |[<!-- language="C" -->
7349 * static gint repeats = 2;
7350 * static gint max_size = 8;
7351 * static gboolean verbose = FALSE;
7352 * static gboolean beep = FALSE;
7353 * static gboolean randomize = FALSE;
7355 * static GOptionEntry entries[] =
7357 * { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" },
7358 * { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" },
7359 * { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL },
7360 * { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL },
7361 * { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL },
7366 * main (int argc, char *argv[])
7368 * GError *error = NULL;
7369 * GOptionContext *context;
7371 * context = g_option_context_new ("- test tree model performance");
7372 * g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
7373 * g_option_context_add_group (context, gtk_get_option_group (TRUE));
7374 * if (!g_option_context_parse (context, &argc, &argv, &error))
7376 * g_print ("option parsing failed: %s\n", error->message);
7385 * On UNIX systems, the argv that is passed to main() has no particular
7386 * encoding, even to the extent that different parts of it may have
7387 * different encodings. In general, normal arguments and flags will be
7388 * in the current locale and filenames should be considered to be opaque
7389 * byte strings. Proper use of %G_OPTION_ARG_FILENAME vs
7390 * %G_OPTION_ARG_STRING is therefore important.
7392 * Note that on Windows, filenames do have an encoding, but using
7393 * #GOptionContext with the argv as passed to main() will result in a
7394 * program that can only accept commandline arguments with characters
7395 * from the system codepage. This can cause problems when attempting to
7396 * deal with filenames containing Unicode characters that fall outside
7399 * A solution to this is to use g_win32_get_command_line() and
7400 * g_option_context_parse_strv() which will properly handle full Unicode
7401 * filenames. If you are using #GApplication, this is done
7402 * automatically for you.
7404 * The following example shows how you can use #GOptionContext directly
7405 * in order to correctly deal with Unicode filenames on Windows:
7407 * |[<!-- language="C" -->
7409 * main (int argc, char **argv)
7411 * GError *error = NULL;
7412 * GOptionContext *context;
7416 * args = g_win32_get_command_line ();
7418 * args = g_strdupv (argv);
7423 * if (!g_option_context_parse_strv (context, &args, &error))
7430 * g_strfreev (args);
7440 * @title: Glob-style pattern matching
7441 * @short_description: matches strings against patterns containing '*'
7442 * (wildcard) and '?' (joker)
7444 * The g_pattern_match* functions match a string
7445 * against a pattern containing '*' and '?' wildcards with similar
7446 * semantics as the standard glob() function: '*' matches an arbitrary,
7447 * possibly empty, string, '?' matches an arbitrary character.
7449 * Note that in contrast to glob(), the '/' character can be matched by
7450 * the wildcards, there are no '[...]' character ranges and '*' and '?'
7451 * can not be escaped to include them literally in a pattern.
7453 * When multiple strings must be matched against the same pattern, it
7454 * is better to compile the pattern to a #GPatternSpec using
7455 * g_pattern_spec_new() and use g_pattern_match_string() instead of
7456 * g_pattern_match_simple(). This avoids the overhead of repeated
7457 * pattern compilation.
7464 * @short_description: a 2-way association between a string and a
7465 * unique integer identifier
7467 * Quarks are associations between strings and integer identifiers.
7468 * Given either the string or the #GQuark identifier it is possible to
7469 * retrieve the other.
7471 * Quarks are used for both [datasets][glib-Datasets] and
7472 * [keyed data lists][glib-Keyed-Data-Lists].
7474 * To create a new quark from a string, use g_quark_from_string() or
7475 * g_quark_from_static_string().
7477 * To find the string corresponding to a given #GQuark, use
7478 * g_quark_to_string().
7480 * To find the #GQuark corresponding to a given string, use
7481 * g_quark_try_string().
7483 * Another use for the string pool maintained for the quark functions
7484 * is string interning, using g_intern_string() or
7485 * g_intern_static_string(). An interned string is a canonical
7486 * representation for a string. One important advantage of interned
7487 * strings is that they can be compared for equality by a simple
7488 * pointer comparison, rather than using strcmp().
7494 * @Title: Double-ended Queues
7495 * @Short_description: double-ended queue data structure
7497 * The #GQueue structure and its associated functions provide a standard
7498 * queue data structure. Internally, GQueue uses the same data structure
7499 * as #GList to store elements.
7501 * The data contained in each element can be either integer values, by
7502 * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
7503 * or simply pointers to any type of data.
7505 * To create a new GQueue, use g_queue_new().
7507 * To initialize a statically-allocated GQueue, use #G_QUEUE_INIT or
7510 * To add elements, use g_queue_push_head(), g_queue_push_head_link(),
7511 * g_queue_push_tail() and g_queue_push_tail_link().
7513 * To remove elements, use g_queue_pop_head() and g_queue_pop_tail().
7515 * To free the entire queue, use g_queue_free().
7520 * SECTION:random_numbers
7521 * @title: Random Numbers
7522 * @short_description: pseudo-random number generator
7524 * The following functions allow you to use a portable, fast and good
7525 * pseudo-random number generator (PRNG).
7527 * Do not use this API for cryptographic purposes such as key
7528 * generation, nonces, salts or one-time pads.
7530 * This PRNG is suitable for non-cryptographic use such as in games
7531 * (shuffling a card deck, generating levels), generating data for
7532 * a test suite, etc. If you need random data for cryptographic
7533 * purposes, it is recommended to use platform-specific APIs such
7534 * as `/dev/random` on UNIX, or CryptGenRandom() on Windows.
7536 * GRand uses the Mersenne Twister PRNG, which was originally
7537 * developed by Makoto Matsumoto and Takuji Nishimura. Further
7538 * information can be found at
7539 * [this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html).
7541 * If you just need a random number, you simply call the g_random_*
7542 * functions, which will create a globally used #GRand and use the
7543 * according g_rand_* functions internally. Whenever you need a
7544 * stream of reproducible random numbers, you better create a
7545 * #GRand yourself and use the g_rand_* functions directly, which
7546 * will also be slightly faster. Initializing a #GRand with a
7547 * certain seed will produce exactly the same series of random
7548 * numbers on all platforms. This can thus be used as a seed for
7551 * The g_rand*_range functions will return high quality equally
7552 * distributed random numbers, whereas for example the
7553 * `(g_random_int()%max)` approach often
7554 * doesn't yield equally distributed numbers.
7556 * GLib changed the seeding algorithm for the pseudo-random number
7557 * generator Mersenne Twister, as used by #GRand. This was necessary,
7558 * because some seeds would yield very bad pseudo-random streams.
7559 * Also the pseudo-random integers generated by g_rand*_int_range()
7560 * will have a slightly better equal distribution with the new
7563 * The original seeding and generation algorithms, as found in
7564 * GLib 2.0.x, can be used instead of the new ones by setting the
7565 * environment variable `G_RANDOM_VERSION` to the value of '2.0'.
7566 * Use the GLib-2.0 algorithms only if you have sequences of numbers
7567 * generated with Glib-2.0 that you need to reproduce exactly.
7573 * @title: Lexical Scanner
7574 * @short_description: a general purpose lexical scanner
7576 * The #GScanner and its associated functions provide a
7577 * general purpose lexical scanner.
7584 * @short_description: scalable lists
7586 * The #GSequence data structure has the API of a list, but is
7587 * implemented internally with a balanced binary tree. This means that
7588 * it is possible to maintain a sorted list of n elements in time O(n log n).
7589 * The data contained in each element can be either integer values, by using
7590 * of the [Type Conversion Macros][glib-Type-Conversion-Macros], or simply
7591 * pointers to any type of data.
7593 * A #GSequence is accessed through "iterators", represented by a
7594 * #GSequenceIter. An iterator represents a position between two
7595 * elements of the sequence. For example, the "begin" iterator
7596 * represents the gap immediately before the first element of the
7597 * sequence, and the "end" iterator represents the gap immediately
7598 * after the last element. In an empty sequence, the begin and end
7599 * iterators are the same.
7601 * Some methods on #GSequence operate on ranges of items. For example
7602 * g_sequence_foreach_range() will call a user-specified function on
7603 * each element with the given range. The range is delimited by the
7604 * gaps represented by the passed-in iterators, so if you pass in the
7605 * begin and end iterators, the range in question is the entire
7608 * The function g_sequence_get() is used with an iterator to access the
7609 * element immediately following the gap that the iterator represents.
7610 * The iterator is said to "point" to that element.
7612 * Iterators are stable across most operations on a #GSequence. For
7613 * example an iterator pointing to some element of a sequence will
7614 * continue to point to that element even after the sequence is sorted.
7615 * Even moving an element to another sequence using for example
7616 * g_sequence_move_range() will not invalidate the iterators pointing
7617 * to it. The only operation that will invalidate an iterator is when
7618 * the element it points to is removed from any sequence.
7624 * @title: Shell-related Utilities
7625 * @short_description: shell-like commandline handling
7627 * GLib provides the functions g_shell_quote() and g_shell_unquote()
7628 * to handle shell-like quoting in strings. The function g_shell_parse_argv()
7629 * parses a string similar to the way a POSIX shell (/bin/sh) would.
7631 * Note that string handling in shells has many obscure and historical
7632 * corner-cases which these functions do not necessarily reproduce. They
7633 * are good enough in practice, though.
7639 * @Short_description: process launching
7640 * @Title: Spawning Processes
7642 * GLib supports spawning of processes with an API that is more
7643 * convenient than the bare UNIX fork() and exec().
7645 * The g_spawn family of functions has synchronous (g_spawn_sync())
7646 * and asynchronous variants (g_spawn_async(), g_spawn_async_with_pipes()),
7647 * as well as convenience variants that take a complete shell-like
7648 * commandline (g_spawn_command_line_sync(), g_spawn_command_line_async()).
7650 * See #GSubprocess in GIO for a higher-level API that provides
7651 * stream interfaces for communication with child processes.
7656 * SECTION:string_chunks
7657 * @title: String Chunks
7658 * @short_description: efficient storage of groups of strings
7660 * String chunks are used to store groups of strings. Memory is
7661 * allocated in blocks, and as strings are added to the #GStringChunk
7662 * they are copied into the next free position in a block. When a block
7663 * is full a new block is allocated.
7665 * When storing a large number of strings, string chunks are more
7666 * efficient than using g_strdup() since fewer calls to malloc() are
7667 * needed, and less memory is wasted in memory allocation overheads.
7669 * By adding strings with g_string_chunk_insert_const() it is also
7670 * possible to remove duplicates.
7672 * To create a new #GStringChunk use g_string_chunk_new().
7674 * To add strings to a #GStringChunk use g_string_chunk_insert().
7676 * To add strings to a #GStringChunk, but without duplicating strings
7677 * which are already in the #GStringChunk, use
7678 * g_string_chunk_insert_const().
7680 * To free the entire #GStringChunk use g_string_chunk_free(). It is
7681 * not possible to free individual strings.
7686 * SECTION:string_utils
7687 * @title: String Utility Functions
7688 * @short_description: various string-related functions
7690 * This section describes a number of utility functions for creating,
7691 * duplicating, and manipulating strings.
7693 * Note that the functions g_printf(), g_fprintf(), g_sprintf(),
7694 * g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf()
7695 * are declared in the header `gprintf.h` which is not included in `glib.h`
7696 * (otherwise using `glib.h` would drag in `stdio.h`), so you'll have to
7697 * explicitly include `<glib/gprintf.h>` in order to use the GLib
7698 * printf() functions.
7700 * ## String precision pitfalls # {#string-precision}
7702 * While you may use the printf() functions to format UTF-8 strings,
7703 * notice that the precision of a \%Ns parameter is interpreted
7704 * as the number of bytes, not characters to print. On top of that,
7705 * the GNU libc implementation of the printf() functions has the
7706 * "feature" that it checks that the string given for the \%Ns
7707 * parameter consists of a whole number of characters in the current
7708 * encoding. So, unless you are sure you are always going to be in an
7709 * UTF-8 locale or your know your text is restricted to ASCII, avoid
7710 * using \%Ns. If your intention is to format strings for a
7711 * certain number of columns, then \%Ns is not a correct solution
7712 * anyway, since it fails to take wide characters (see g_unichar_iswide())
7715 * Note also that there are various printf() parameters which are platform
7716 * dependent. GLib provides platform independent macros for these parameters
7717 * which should be used instead. A common example is %G_GUINT64_FORMAT, which
7718 * should be used instead of `%llu` or similar parameters for formatting
7719 * 64-bit integers. These macros are all named `G_*_FORMAT`; see
7720 * [Basic Types][glib-Basic-Types].
7727 * @short_description: text buffers which grow automatically
7730 * A #GString is an object that handles the memory management of a C
7731 * string for you. The emphasis of #GString is on text, typically
7732 * UTF-8. Crucially, the "str" member of a #GString is guaranteed to
7733 * have a trailing nul character, and it is therefore always safe to
7734 * call functions such as strchr() or g_strdup() on it.
7736 * However, a #GString can also hold arbitrary binary data, because it
7737 * has a "len" member, which includes any possible embedded nul
7738 * characters in the data. Conceptually then, #GString is like a
7739 * #GByteArray with the addition of many convenience methods for text,
7740 * and a guaranteed nul terminator.
7747 * @short_description: a test framework
7748 * @see_also: [gtester][gtester], [gtester-report][gtester-report]
7750 * GLib provides a framework for writing and maintaining unit tests
7751 * in parallel to the code they are testing. The API is designed according
7752 * to established concepts found in the other test frameworks (JUnit, NUnit,
7753 * RUnit), which in turn is based on smalltalk unit testing concepts.
7755 * - Test case: Tests (test methods) are grouped together with their
7756 * fixture into test cases.
7758 * - Fixture: A test fixture consists of fixture data and setup and
7759 * teardown methods to establish the environment for the test
7760 * functions. We use fresh fixtures, i.e. fixtures are newly set
7761 * up and torn down around each test invocation to avoid dependencies
7764 * - Test suite: Test cases can be grouped into test suites, to allow
7765 * subsets of the available tests to be run. Test suites can be
7766 * grouped into other test suites as well.
7768 * The API is designed to handle creation and registration of test suites
7769 * and test cases implicitly. A simple call like
7770 * |[<!-- language="C" -->
7771 * g_test_add_func ("/misc/assertions", test_assertions);
7773 * creates a test suite called "misc" with a single test case named
7774 * "assertions", which consists of running the test_assertions function.
7776 * In addition to the traditional g_assert(), the test framework provides
7777 * an extended set of assertions for comparisons: g_assert_cmpfloat(),
7778 * g_assert_cmpint(), g_assert_cmpuint(), g_assert_cmphex(),
7779 * g_assert_cmpstr(), and g_assert_cmpmem(). The advantage of these
7780 * variants over plain g_assert() is that the assertion messages can be
7781 * more elaborate, and include the values of the compared entities.
7783 * GLib ships with two utilities called [gtester][gtester] and
7784 * [gtester-report][gtester-report] to facilitate running tests and producing
7785 * nicely formatted test reports.
7787 * A full example of creating a test suite with two tests using fixtures:
7788 * |[<!-- language="C" -->
7790 * #include <locale.h>
7794 * OtherObject *helper;
7795 * } MyObjectFixture;
7798 * my_object_fixture_set_up (MyObjectFixture *fixture,
7799 * gconstpointer user_data)
7801 * fixture->obj = my_object_new ();
7802 * my_object_set_prop1 (fixture->obj, "some-value");
7803 * my_object_do_some_complex_setup (fixture->obj, user_data);
7805 * fixture->helper = other_object_new ();
7809 * my_object_fixture_tear_down (MyObjectFixture *fixture,
7810 * gconstpointer user_data)
7812 * g_clear_object (&fixture->helper);
7813 * g_clear_object (&fixture->obj);
7817 * test_my_object_test1 (MyObjectFixture *fixture,
7818 * gconstpointer user_data)
7820 * g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "initial-value");
7824 * test_my_object_test2 (MyObjectFixture *fixture,
7825 * gconstpointer user_data)
7827 * my_object_do_some_work_using_helper (fixture->obj, fixture->helper);
7828 * g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "updated-value");
7832 * main (int argc, char *argv[])
7834 * setlocale (LC_ALL, "");
7836 * g_test_init (&argc, &argv, NULL);
7837 * g_test_bug_base ("http://bugzilla.gnome.org/show_bug.cgi?id=");
7839 * // Define the tests.
7840 * g_test_add ("/my-object/test1", MyObjectFixture, "some-user-data",
7841 * my_object_fixture_set_up, test_my_object_test1,
7842 * my_object_fixture_tear_down);
7843 * g_test_add ("/my-object/test2", MyObjectFixture, "some-user-data",
7844 * my_object_fixture_set_up, test_my_object_test2,
7845 * my_object_fixture_tear_down);
7847 * return g_test_run ();
7854 * SECTION:thread_pools
7855 * @title: Thread Pools
7856 * @short_description: pools of threads to execute work concurrently
7857 * @see_also: #GThread
7859 * Sometimes you wish to asynchronously fork out the execution of work
7860 * and continue working in your own thread. If that will happen often,
7861 * the overhead of starting and destroying a thread each time might be
7862 * too high. In such cases reusing already started threads seems like a
7863 * good idea. And it indeed is, but implementing this can be tedious
7866 * Therefore GLib provides thread pools for your convenience. An added
7867 * advantage is, that the threads can be shared between the different
7868 * subsystems of your program, when they are using GLib.
7870 * To create a new thread pool, you use g_thread_pool_new().
7871 * It is destroyed by g_thread_pool_free().
7873 * If you want to execute a certain task within a thread pool,
7874 * you call g_thread_pool_push().
7876 * To get the current number of running threads you call
7877 * g_thread_pool_get_num_threads(). To get the number of still
7878 * unprocessed tasks you call g_thread_pool_unprocessed(). To control
7879 * the maximal number of threads for a thread pool, you use
7880 * g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads().
7882 * Finally you can control the number of unused threads, that are kept
7883 * alive by GLib for future use. The current number can be fetched with
7884 * g_thread_pool_get_num_unused_threads(). The maximal number can be
7885 * controlled by g_thread_pool_get_max_unused_threads() and
7886 * g_thread_pool_set_max_unused_threads(). All currently unused threads
7887 * can be stopped by calling g_thread_pool_stop_unused_threads().
7894 * @short_description: portable support for threads, mutexes, locks,
7895 * conditions and thread private data
7896 * @see_also: #GThreadPool, #GAsyncQueue
7898 * Threads act almost like processes, but unlike processes all threads
7899 * of one process share the same memory. This is good, as it provides
7900 * easy communication between the involved threads via this shared
7901 * memory, and it is bad, because strange things (so called
7902 * "Heisenbugs") might happen if the program is not carefully designed.
7903 * In particular, due to the concurrent nature of threads, no
7904 * assumptions on the order of execution of code running in different
7905 * threads can be made, unless order is explicitly forced by the
7906 * programmer through synchronization primitives.
7908 * The aim of the thread-related functions in GLib is to provide a
7909 * portable means for writing multi-threaded software. There are
7910 * primitives for mutexes to protect the access to portions of memory
7911 * (#GMutex, #GRecMutex and #GRWLock). There is a facility to use
7912 * individual bits for locks (g_bit_lock()). There are primitives
7913 * for condition variables to allow synchronization of threads (#GCond).
7914 * There are primitives for thread-private data - data that every
7915 * thread has a private instance of (#GPrivate). There are facilities
7916 * for one-time initialization (#GOnce, g_once_init_enter()). Finally,
7917 * there are primitives to create and manage threads (#GThread).
7919 * The GLib threading system used to be initialized with g_thread_init().
7920 * This is no longer necessary. Since version 2.32, the GLib threading
7921 * system is automatically initialized at the start of your program,
7922 * and all thread-creation functions and synchronization primitives
7923 * are available right away.
7925 * Note that it is not safe to assume that your program has no threads
7926 * even if you don't call g_thread_new() yourself. GLib and GIO can
7927 * and will create threads for their own purposes in some cases, such
7928 * as when using g_unix_signal_source_new() or when using GDBus.
7930 * Originally, UNIX did not have threads, and therefore some traditional
7931 * UNIX APIs are problematic in threaded programs. Some notable examples
7934 * - C library functions that return data in statically allocated
7935 * buffers, such as strtok() or strerror(). For many of these,
7936 * there are thread-safe variants with a _r suffix, or you can
7937 * look at corresponding GLib APIs (like g_strsplit() or g_strerror()).
7939 * - The functions setenv() and unsetenv() manipulate the process
7940 * environment in a not thread-safe way, and may interfere with getenv()
7941 * calls in other threads. Note that getenv() calls may be hidden behind
7942 * other APIs. For example, GNU gettext() calls getenv() under the
7943 * covers. In general, it is best to treat the environment as readonly.
7944 * If you absolutely have to modify the environment, do it early in
7945 * main(), when no other threads are around yet.
7947 * - The setlocale() function changes the locale for the entire process,
7948 * affecting all threads. Temporary changes to the locale are often made
7949 * to change the behavior of string scanning or formatting functions
7950 * like scanf() or printf(). GLib offers a number of string APIs
7951 * (like g_ascii_formatd() or g_ascii_strtod()) that can often be
7952 * used as an alternative. Or you can use the uselocale() function
7953 * to change the locale only for the current thread.
7955 * - The fork() function only takes the calling thread into the child's
7956 * copy of the process image. If other threads were executing in critical
7957 * sections they could have left mutexes locked which could easily
7958 * cause deadlocks in the new child. For this reason, you should
7959 * call exit() or exec() as soon as possible in the child and only
7960 * make signal-safe library calls before that.
7962 * - The daemon() function uses fork() in a way contrary to what is
7963 * described above. It should not be used with GLib programs.
7965 * GLib itself is internally completely thread-safe (all global data is
7966 * automatically locked), but individual data structure instances are
7967 * not automatically locked for performance reasons. For example,
7968 * you must coordinate accesses to the same #GHashTable from multiple
7969 * threads. The two notable exceptions from this rule are #GMainLoop
7970 * and #GAsyncQueue, which are thread-safe and need no further
7971 * application-level locking to be accessed from multiple threads.
7972 * Most refcounting functions such as g_object_ref() are also thread-safe.
7974 * A common use for #GThreads is to move a long-running blocking operation out
7975 * of the main thread and into a worker thread. For GLib functions, such as
7976 * single GIO operations, this is not necessary, and complicates the code.
7977 * Instead, the `…_async()` version of the function should be used from the main
7978 * thread, eliminating the need for locking and synchronisation between multiple
7979 * threads. If an operation does need to be moved to a worker thread, consider
7980 * using g_task_run_in_thread(), or a #GThreadPool. #GThreadPool is often a
7981 * better choice than #GThread, as it handles thread reuse and task queueing;
7982 * #GTask uses this internally.
7984 * However, if multiple blocking operations need to be performed in sequence,
7985 * and it is not possible to use #GTask for them, moving them to a worker thread
7986 * can clarify the code.
7993 * @short_description: keep track of elapsed time
7995 * #GTimer records a start time, and counts microseconds elapsed since
7996 * that time. This is done somewhat differently on different platforms,
7997 * and can be tricky to get exactly right, so #GTimer provides a
7998 * portable/convenient interface.
8005 * @short_description: a structure representing a time zone
8006 * @see_also: #GDateTime
8008 * #GTimeZone is a structure that represents a time zone, at no
8009 * particular point in time. It is refcounted and immutable.
8011 * A time zone contains a number of intervals. Each interval has
8012 * an abbreviation to describe it, an offet to UTC and a flag indicating
8013 * if the daylight savings time is in effect during that interval. A
8014 * time zone always has at least one interval -- interval 0.
8016 * Every UTC time is contained within exactly one interval, but a given
8017 * local time may be contained within zero, one or two intervals (due to
8018 * incontinuities associated with daylight savings time).
8020 * An interval may refer to a specific period of time (eg: the duration
8021 * of daylight savings time during 2010) or it may refer to many periods
8022 * of time that share the same properties (eg: all periods of daylight
8023 * savings time). It is also possible (usually for political reasons)
8024 * that some properties (like the abbreviation) change between intervals
8025 * without other properties changing.
8027 * #GTimeZone is available since GLib 2.26.
8032 * SECTION:trash_stack
8033 * @title: Trash Stacks
8034 * @short_description: maintain a stack of unused allocated memory chunks
8036 * A #GTrashStack is an efficient way to keep a stack of unused allocated
8037 * memory chunks. Each memory chunk is required to be large enough to hold
8038 * a #gpointer. This allows the stack to be maintained without any space
8039 * overhead, since the stack pointers can be stored inside the memory chunks.
8041 * There is no function to create a #GTrashStack. A %NULL #GTrashStack*
8042 * is a perfectly valid empty stack.
8044 * There is no longer any good reason to use #GTrashStack. If you have
8045 * extra pieces of memory, free() them and allocate them again later.
8047 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
8052 * SECTION:trees-binary
8053 * @title: Balanced Binary Trees
8054 * @short_description: a sorted collection of key/value pairs optimized
8055 * for searching and traversing in order
8057 * The #GTree structure and its associated functions provide a sorted
8058 * collection of key/value pairs optimized for searching and traversing
8061 * To create a new #GTree use g_tree_new().
8063 * To insert a key/value pair into a #GTree use g_tree_insert().
8065 * To lookup the value corresponding to a given key, use
8066 * g_tree_lookup() and g_tree_lookup_extended().
8068 * To find out the number of nodes in a #GTree, use g_tree_nnodes(). To
8069 * get the height of a #GTree, use g_tree_height().
8071 * To traverse a #GTree, calling a function for each node visited in
8072 * the traversal, use g_tree_foreach().
8074 * To remove a key/value pair use g_tree_remove().
8076 * To destroy a #GTree, use g_tree_destroy().
8081 * SECTION:trees-nary
8082 * @title: N-ary Trees
8083 * @short_description: trees of data with any number of branches
8085 * The #GNode struct and its associated functions provide a N-ary tree
8086 * data structure, where nodes in the tree can contain arbitrary data.
8088 * To create a new tree use g_node_new().
8090 * To insert a node into a tree use g_node_insert(),
8091 * g_node_insert_before(), g_node_append() and g_node_prepend().
8093 * To create a new node and insert it into a tree use
8094 * g_node_insert_data(), g_node_insert_data_after(),
8095 * g_node_insert_data_before(), g_node_append_data()
8096 * and g_node_prepend_data().
8098 * To reverse the children of a node use g_node_reverse_children().
8100 * To find a node use g_node_get_root(), g_node_find(),
8101 * g_node_find_child(), g_node_child_index(), g_node_child_position(),
8102 * g_node_first_child(), g_node_last_child(), g_node_nth_child(),
8103 * g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling()
8104 * or g_node_last_sibling().
8106 * To get information about a node or tree use G_NODE_IS_LEAF(),
8107 * G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(),
8108 * g_node_n_children(), g_node_is_ancestor() or g_node_max_height().
8110 * To traverse a tree, calling a function for each node visited in the
8111 * traversal, use g_node_traverse() or g_node_children_foreach().
8113 * To remove a node or subtree from a tree use g_node_unlink() or
8119 * SECTION:type_conversion
8120 * @title: Type Conversion Macros
8121 * @short_description: portably storing integers in pointer variables
8123 * Many times GLib, GTK+, and other libraries allow you to pass "user
8124 * data" to a callback, in the form of a void pointer. From time to time
8125 * you want to pass an integer instead of a pointer. You could allocate
8126 * an integer, with something like:
8127 * |[<!-- language="C" -->
8128 * int *ip = g_new (int, 1);
8131 * But this is inconvenient, and it's annoying to have to free the
8132 * memory at some later time.
8134 * Pointers are always at least 32 bits in size (on all platforms GLib
8135 * intends to support). Thus you can store at least 32-bit integer values
8136 * in a pointer value. Naively, you might try this, but it's incorrect:
8137 * |[<!-- language="C" -->
8143 * Again, that example was not correct, don't copy it.
8144 * The problem is that on some systems you need to do this:
8145 * |[<!-- language="C" -->
8148 * p = (void*) (long) 42;
8149 * i = (int) (long) p;
8151 * The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care
8152 * to do the right thing on the every platform.
8154 * Warning: You may not store pointers in integers. This is not
8155 * portable in any way, shape or form. These macros only allow storing
8156 * integers in pointers, and only preserve 32 bits of the integer; values
8157 * outside the range of a 32-bit integer will be mangled.
8163 * @title: Basic Types
8164 * @short_description: standard GLib types, defined for ease-of-use
8167 * GLib defines a number of commonly used types, which can be divided
8169 * - New types which are not part of standard C (but are defined in
8170 * various C standard library header files) - #gboolean, #gsize,
8171 * #gssize, #goffset, #gintptr, #guintptr.
8172 * - Integer types which are guaranteed to be the same size across
8173 * all platforms - #gint8, #guint8, #gint16, #guint16, #gint32,
8174 * #guint32, #gint64, #guint64.
8175 * - Types which are easier to use than their standard C counterparts -
8176 * #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
8177 * - Types which correspond exactly to standard C types, but are
8178 * included for completeness - #gchar, #gint, #gshort, #glong,
8179 * #gfloat, #gdouble.
8181 * GLib also defines macros for the limits of some of the standard
8182 * integer and floating point types, as well as macros for suitable
8183 * printf() formats for these types.
8189 * @Title: Unicode Manipulation
8190 * @Short_description: functions operating on Unicode characters and
8192 * @See_also: g_locale_to_utf8(), g_locale_from_utf8()
8194 * This section describes a number of functions for dealing with
8195 * Unicode characters and strings. There are analogues of the
8196 * traditional `ctype.h` character classification and case conversion
8197 * functions, UTF-8 analogues of some string utility functions,
8198 * functions to perform normalization, case conversion and collation
8199 * on UTF-8 strings and finally functions to convert between the UTF-8,
8200 * UTF-16 and UCS-4 encodings of Unicode.
8202 * The implementations of the Unicode functions in GLib are based
8203 * on the Unicode Character Data tables, which are available from
8204 * [www.unicode.org](http://www.unicode.org/).
8205 * GLib 2.8 supports Unicode 4.0, GLib 2.10 supports Unicode 4.1,
8206 * GLib 2.12 supports Unicode 5.0, GLib 2.16.3 supports Unicode 5.1,
8207 * GLib 2.30 supports Unicode 6.0.
8213 * @Title: Version Information
8214 * @Short_description: variables and functions to check the GLib version
8216 * GLib provides version information, primarily useful in configure
8217 * checks for builds that have a configure script. Applications will
8218 * not typically use the features described here.
8220 * The GLib headers annotate deprecated APIs in a way that produces
8221 * compiler warnings if these deprecated APIs are used. The warnings
8222 * can be turned off by defining the macro %GLIB_DISABLE_DEPRECATION_WARNINGS
8223 * before including the glib.h header.
8225 * GLib also provides support for building applications against
8226 * defined subsets of deprecated or new GLib APIs. Define the macro
8227 * %GLIB_VERSION_MIN_REQUIRED to specify up to what version of GLib
8228 * you want to receive warnings about deprecated APIs. Define the
8229 * macro %GLIB_VERSION_MAX_ALLOWED to specify the newest version of
8230 * GLib whose API you want to use.
8236 * @Title: Message Output and Debugging Functions
8237 * @Short_description: functions to output messages and help debug applications
8239 * These functions provide support for outputting messages.
8241 * The g_return family of macros (g_return_if_fail(),
8242 * g_return_val_if_fail(), g_return_if_reached(),
8243 * g_return_val_if_reached()) should only be used for programming
8244 * errors, a typical use case is checking for invalid parameters at
8245 * the beginning of a public function. They should not be used if
8246 * you just mean "if (error) return", they should only be used if
8247 * you mean "if (bug in program) return". The program behavior is
8248 * generally considered undefined after one of these checks fails.
8249 * They are not intended for normal control flow, only to give a
8250 * perhaps-helpful warning before giving up.
8252 * Structured logging output is supported using g_log_structured(). This differs
8253 * from the traditional g_log() API in that log messages are handled as a
8254 * collection of key–value pairs representing individual pieces of information,
8255 * rather than as a single string containing all the information in an arbitrary
8258 * The support for structured logging was motivated by the following needs (some
8259 * of which were supported previously; others weren’t):
8260 * * Support for multiple logging levels.
8261 * * Structured log support with the ability to add `MESSAGE_ID`s (see
8262 * g_log_structured()).
8263 * * Moving the responsibility for filtering log messages from the program to
8264 * the log viewer — instead of libraries and programs installing log handlers
8265 * (with g_log_set_handler()) which filter messages before output, all log
8266 * messages are outputted, and the log viewer program (such as `journalctl`)
8267 * must filter them. This is based on the idea that bugs are sometimes hard
8268 * to reproduce, so it is better to log everything possible and then use
8269 * tools to analyse the logs than it is to not be able to reproduce a bug to
8270 * get additional log data. Code which uses logging in performance-critical
8271 * sections should compile out the g_log_structured() calls in
8272 * release builds, and compile them in in debugging builds.
8273 * * A single writer function which handles all log messages in a process, from
8274 * all libraries and program code; rather than multiple log handlers with
8275 * poorly defined interactions between them. This allows a program to easily
8276 * change its logging policy by changing the writer function, for example to
8277 * log to an additional location or to change what logging output fallbacks
8278 * are used. The log writer functions provided by GLib are exposed publicly
8279 * so they can be used from programs’ log writers. This allows log writer
8280 * policy and implementation to be kept separate.
8281 * * If a library wants to add standard information to all of its log messages
8282 * (such as library state) or to redact private data (such as passwords or
8283 * network credentials), it should use a wrapper function around its
8284 * g_log_structured() calls or implement that in the single log writer
8286 * * If a program wants to pass context data from a g_log_structured() call to
8287 * its log writer function so that, for example, it can use the correct
8288 * server connection to submit logs to, that user data can be passed as a
8289 * zero-length #GLogField to g_log_structured_array().
8290 * * Color output needed to be supported on the terminal, to make reading
8291 * through logs easier.
8297 * @title: Windows Compatibility Functions
8298 * @short_description: UNIX emulation on Windows
8300 * These functions provide some level of UNIX emulation on the
8301 * Windows platform. If your application really needs the POSIX
8302 * APIs, we suggest you try the Cygwin project.
8309 * Defines the %TRUE value for the #gboolean type.
8315 * @String: the string to be translated
8317 * Marks a string for translation, gets replaced with the translated string
8325 * _glib_get_locale_dir:
8327 * Return the path to the share\locale or lib\locale subfolder of the
8328 * GLib installation folder. The path is in the system codepage. We
8329 * have to use system codepage as bindtextdomain() doesn't have a
8337 * A wrapper for the POSIX abort() function.
8339 * On Windows it is a function that makes extra effort (including a call
8340 * to abort()) to ensure that a debugger-catchable exception is thrown
8341 * before the program terminates.
8343 * See your C library manual for more details about abort().
8351 * @filename: (type filename): a pathname in the GLib file name encoding
8352 * (UTF-8 on Windows)
8353 * @mode: as in access()
8355 * A wrapper for the POSIX access() function. This function is used to
8356 * test a pathname for one or several of read, write or execute
8357 * permissions, or just existence.
8359 * On Windows, the file protection mechanism is not at all POSIX-like,
8360 * and the underlying function in the C library only checks the
8361 * FAT-style READONLY attribute, and does not look at the ACL of a
8362 * file at all. This function is this in practise almost useless on
8363 * Windows. Software that needs to handle file permissions on Windows
8364 * more exactly should use the Win32 API.
8366 * See your C library manual for more details about access().
8368 * Returns: zero if the pathname refers to an existing file system
8369 * object that has all the tested permissions, or -1 otherwise
8376 * g_array_append_val:
8378 * @v: the value to append to the #GArray
8380 * Adds the value on to the end of the array. The array will grow in
8381 * size automatically if necessary.
8383 * g_array_append_val() is a macro which uses a reference to the value
8384 * parameter @v. This means that you cannot use it with literal values
8385 * such as "27". You must use variables.
8387 * Returns: the #GArray
8392 * g_array_append_vals:
8394 * @data: (not nullable): a pointer to the elements to append to the end of the array
8395 * @len: the number of elements to append
8397 * Adds @len elements onto the end of the array.
8399 * Returns: the #GArray
8406 * @free_segment: if %TRUE the actual element data is freed as well
8408 * Frees the memory allocated for the #GArray. If @free_segment is
8409 * %TRUE it frees the memory block holding the elements as well and
8410 * also each element if @array has a @element_free_func set. Pass
8411 * %FALSE if you want to free the #GArray wrapper but preserve the
8412 * underlying array for use elsewhere. If the reference count of @array
8413 * is greater than one, the #GArray wrapper is preserved but the size
8414 * of @array will be set to zero.
8416 * If array elements contain dynamically-allocated memory, they should
8417 * be freed separately.
8419 * Returns: the element data if @free_segment is %FALSE, otherwise
8420 * %NULL. The element data should be freed using g_free().
8425 * g_array_get_element_size:
8428 * Gets the size of the elements in @array.
8430 * Returns: Size of each element, in bytes
8438 * @t: the type of the elements
8439 * @i: the index of the element to return
8441 * Returns the element of a #GArray at the given index. The return
8442 * value is cast to the given type.
8444 * This example gets a pointer to an element in a #GArray:
8445 * |[<!-- language="C" -->
8446 * EDayViewEvent *event;
8447 * // This gets a pointer to the 4th element in the array of
8448 * // EDayViewEvent structs.
8449 * event = &g_array_index (events, EDayViewEvent, 3);
8452 * Returns: the element of the #GArray at the index given by @i
8457 * g_array_insert_val:
8459 * @i: the index to place the element at
8460 * @v: the value to insert into the array
8462 * Inserts an element into an array at the given index.
8464 * g_array_insert_val() is a macro which uses a reference to the value
8465 * parameter @v. This means that you cannot use it with literal values
8466 * such as "27". You must use variables.
8468 * Returns: the #GArray
8473 * g_array_insert_vals:
8475 * @index_: the index to place the elements at
8476 * @data: (not nullable): a pointer to the elements to insert
8477 * @len: the number of elements to insert
8479 * Inserts @len elements into a #GArray at the given index.
8481 * Returns: the #GArray
8487 * @zero_terminated: %TRUE if the array should have an extra element at
8488 * the end which is set to 0
8489 * @clear_: %TRUE if #GArray elements should be automatically cleared
8490 * to 0 when they are allocated
8491 * @element_size: the size of each element in bytes
8493 * Creates a new #GArray with a reference count of 1.
8495 * Returns: the new #GArray
8500 * g_array_prepend_val:
8502 * @v: the value to prepend to the #GArray
8504 * Adds the value on to the start of the array. The array will grow in
8505 * size automatically if necessary.
8507 * This operation is slower than g_array_append_val() since the
8508 * existing elements in the array have to be moved to make space for
8511 * g_array_prepend_val() is a macro which uses a reference to the value
8512 * parameter @v. This means that you cannot use it with literal values
8513 * such as "27". You must use variables.
8515 * Returns: the #GArray
8520 * g_array_prepend_vals:
8522 * @data: (not nullable): a pointer to the elements to prepend to the start of the array
8523 * @len: the number of elements to prepend
8525 * Adds @len elements onto the start of the array.
8527 * This operation is slower than g_array_append_vals() since the
8528 * existing elements in the array have to be moved to make space for
8531 * Returns: the #GArray
8539 * Atomically increments the reference count of @array by one.
8540 * This function is MT-safe and may be called from any thread.
8542 * Returns: The passed in #GArray
8548 * g_array_remove_index:
8550 * @index_: the index of the element to remove
8552 * Removes the element at the given index from a #GArray. The following
8553 * elements are moved down one place.
8555 * Returns: the #GArray
8560 * g_array_remove_index_fast:
8562 * @index_: the index of the element to remove
8564 * Removes the element at the given index from a #GArray. The last
8565 * element in the array is used to fill in the space, so this function
8566 * does not preserve the order of the #GArray. But it is faster than
8567 * g_array_remove_index().
8569 * Returns: the #GArray
8574 * g_array_remove_range:
8576 * @index_: the index of the first element to remove
8577 * @length: the number of elements to remove
8579 * Removes the given number of elements starting at the given index
8580 * from a #GArray. The following elements are moved to close the gap.
8582 * Returns: the #GArray
8588 * g_array_set_clear_func:
8590 * @clear_func: a function to clear an element of @array
8592 * Sets a function to clear an element of @array.
8594 * The @clear_func will be called when an element in the array
8595 * data segment is removed and when the array is freed and data
8596 * segment is deallocated as well.
8598 * Note that in contrast with other uses of #GDestroyNotify
8599 * functions, @clear_func is expected to clear the contents of
8600 * the array element it is given, but not free the element itself.
8609 * @length: the new size of the #GArray
8611 * Sets the size of the array, expanding it if necessary. If the array
8612 * was created with @clear_ set to %TRUE, the new elements are set to 0.
8614 * Returns: the #GArray
8619 * g_array_sized_new:
8620 * @zero_terminated: %TRUE if the array should have an extra element at
8621 * the end with all bits cleared
8622 * @clear_: %TRUE if all bits in the array should be cleared to 0 on
8624 * @element_size: size of each element in the array
8625 * @reserved_size: number of elements preallocated
8627 * Creates a new #GArray with @reserved_size elements preallocated and
8628 * a reference count of 1. This avoids frequent reallocation, if you
8629 * are going to add many elements to the array. Note however that the
8630 * size of the array is still 0.
8632 * Returns: the new #GArray
8639 * @compare_func: comparison function
8641 * Sorts a #GArray using @compare_func which should be a qsort()-style
8642 * comparison function (returns less than zero for first arg is less
8643 * than second arg, zero for equal, greater zero if first arg is
8644 * greater than second arg).
8646 * This is guaranteed to be a stable sort since version 2.32.
8651 * g_array_sort_with_data:
8653 * @compare_func: comparison function
8654 * @user_data: data to pass to @compare_func
8656 * Like g_array_sort(), but the comparison function receives an extra
8657 * user data argument.
8659 * This is guaranteed to be a stable sort since version 2.32.
8661 * There used to be a comment here about making the sort stable by
8662 * using the addresses of the elements in the comparison function.
8663 * This did not actually work, so any such code should be removed.
8671 * Atomically decrements the reference count of @array by one. If the
8672 * reference count drops to 0, all memory allocated by the array is
8673 * released. This function is MT-safe and may be called from any
8681 * g_ascii_digit_value:
8682 * @c: an ASCII character
8684 * Determines the numeric value of a character as a decimal digit.
8685 * Differs from g_unichar_digit_value() because it takes a char, so
8686 * there's no worry about sign extension if characters are signed.
8688 * Returns: If @c is a decimal digit (according to g_ascii_isdigit()),
8689 * its numeric value. Otherwise, -1.
8695 * @buffer: A buffer to place the resulting string in
8696 * @buf_len: The length of the buffer.
8697 * @d: The #gdouble to convert
8699 * Converts a #gdouble to a string, using the '.' as
8702 * This function generates enough precision that converting
8703 * the string back using g_ascii_strtod() gives the same machine-number
8704 * (on machines with IEEE compatible 64bit doubles). It is
8705 * guaranteed that the size of the resulting string will never
8706 * be larger than @G_ASCII_DTOSTR_BUF_SIZE bytes, including the terminating
8707 * nul character, which is always added.
8709 * Returns: The pointer to the buffer with the converted string.
8715 * @buffer: A buffer to place the resulting string in
8716 * @buf_len: The length of the buffer.
8717 * @format: The printf()-style format to use for the
8718 * code to use for converting.
8719 * @d: The #gdouble to convert
8721 * Converts a #gdouble to a string, using the '.' as
8722 * decimal point. To format the number you pass in
8723 * a printf()-style format string. Allowed conversion
8724 * specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
8726 * The returned buffer is guaranteed to be nul-terminated.
8728 * If you just want to want to serialize the value into a
8729 * string, use g_ascii_dtostr().
8731 * Returns: The pointer to the buffer with the converted string.
8739 * Determines whether a character is alphanumeric.
8741 * Unlike the standard C library isalnum() function, this only
8742 * recognizes standard ASCII letters and ignores the locale,
8743 * returning %FALSE for all non-ASCII characters. Also, unlike
8744 * the standard library function, this takes a char, not an int,
8745 * so don't call it on %EOF, but no need to cast to #guchar before
8746 * passing a possibly non-ASCII character in.
8748 * Returns: %TRUE if @c is an ASCII alphanumeric character
8756 * Determines whether a character is alphabetic (i.e. a letter).
8758 * Unlike the standard C library isalpha() function, this only
8759 * recognizes standard ASCII letters and ignores the locale,
8760 * returning %FALSE for all non-ASCII characters. Also, unlike
8761 * the standard library function, this takes a char, not an int,
8762 * so don't call it on %EOF, but no need to cast to #guchar before
8763 * passing a possibly non-ASCII character in.
8765 * Returns: %TRUE if @c is an ASCII alphabetic character
8773 * Determines whether a character is a control character.
8775 * Unlike the standard C library iscntrl() function, this only
8776 * recognizes standard ASCII control characters and ignores the
8777 * locale, returning %FALSE for all non-ASCII characters. Also,
8778 * unlike the standard library function, this takes a char, not
8779 * an int, so don't call it on %EOF, but no need to cast to #guchar
8780 * before passing a possibly non-ASCII character in.
8782 * Returns: %TRUE if @c is an ASCII control character.
8790 * Determines whether a character is digit (0-9).
8792 * Unlike the standard C library isdigit() function, this takes
8793 * a char, not an int, so don't call it on %EOF, but no need to
8794 * cast to #guchar before passing a possibly non-ASCII character in.
8796 * Returns: %TRUE if @c is an ASCII digit.
8804 * Determines whether a character is a printing character and not a space.
8806 * Unlike the standard C library isgraph() function, this only
8807 * recognizes standard ASCII characters and ignores the locale,
8808 * returning %FALSE for all non-ASCII characters. Also, unlike
8809 * the standard library function, this takes a char, not an int,
8810 * so don't call it on %EOF, but no need to cast to #guchar before
8811 * passing a possibly non-ASCII character in.
8813 * Returns: %TRUE if @c is an ASCII printing character other than space.
8821 * Determines whether a character is an ASCII lower case letter.
8823 * Unlike the standard C library islower() function, this only
8824 * recognizes standard ASCII letters and ignores the locale,
8825 * returning %FALSE for all non-ASCII characters. Also, unlike
8826 * the standard library function, this takes a char, not an int,
8827 * so don't call it on %EOF, but no need to worry about casting
8828 * to #guchar before passing a possibly non-ASCII character in.
8830 * Returns: %TRUE if @c is an ASCII lower case letter
8838 * Determines whether a character is a printing character.
8840 * Unlike the standard C library isprint() function, this only
8841 * recognizes standard ASCII characters and ignores the locale,
8842 * returning %FALSE for all non-ASCII characters. Also, unlike
8843 * the standard library function, this takes a char, not an int,
8844 * so don't call it on %EOF, but no need to cast to #guchar before
8845 * passing a possibly non-ASCII character in.
8847 * Returns: %TRUE if @c is an ASCII printing character.
8855 * Determines whether a character is a punctuation character.
8857 * Unlike the standard C library ispunct() function, this only
8858 * recognizes standard ASCII letters and ignores the locale,
8859 * returning %FALSE for all non-ASCII characters. Also, unlike
8860 * the standard library function, this takes a char, not an int,
8861 * so don't call it on %EOF, but no need to cast to #guchar before
8862 * passing a possibly non-ASCII character in.
8864 * Returns: %TRUE if @c is an ASCII punctuation character.
8872 * Determines whether a character is a white-space character.
8874 * Unlike the standard C library isspace() function, this only
8875 * recognizes standard ASCII white-space and ignores the locale,
8876 * returning %FALSE for all non-ASCII characters. Also, unlike
8877 * the standard library function, this takes a char, not an int,
8878 * so don't call it on %EOF, but no need to cast to #guchar before
8879 * passing a possibly non-ASCII character in.
8881 * Returns: %TRUE if @c is an ASCII white-space character
8889 * Determines whether a character is an ASCII upper case letter.
8891 * Unlike the standard C library isupper() function, this only
8892 * recognizes standard ASCII letters and ignores the locale,
8893 * returning %FALSE for all non-ASCII characters. Also, unlike
8894 * the standard library function, this takes a char, not an int,
8895 * so don't call it on %EOF, but no need to worry about casting
8896 * to #guchar before passing a possibly non-ASCII character in.
8898 * Returns: %TRUE if @c is an ASCII upper case letter
8906 * Determines whether a character is a hexadecimal-digit character.
8908 * Unlike the standard C library isxdigit() function, this takes
8909 * a char, not an int, so don't call it on %EOF, but no need to
8910 * cast to #guchar before passing a possibly non-ASCII character in.
8912 * Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
8917 * g_ascii_strcasecmp:
8918 * @s1: string to compare with @s2
8919 * @s2: string to compare with @s1
8921 * Compare two strings, ignoring the case of ASCII characters.
8923 * Unlike the BSD strcasecmp() function, this only recognizes standard
8924 * ASCII letters and ignores the locale, treating all non-ASCII
8925 * bytes as if they are not letters.
8927 * This function should be used only on strings that are known to be
8928 * in encodings where the bytes corresponding to ASCII letters always
8929 * represent themselves. This includes UTF-8 and the ISO-8859-*
8930 * charsets, but not for instance double-byte encodings like the
8931 * Windows Codepage 932, where the trailing bytes of double-byte
8932 * characters include all ASCII letters. If you compare two CP932
8933 * strings using this function, you will get false matches.
8935 * Both @s1 and @s2 must be non-%NULL.
8937 * Returns: 0 if the strings match, a negative value if @s1 < @s2,
8938 * or a positive value if @s1 > @s2.
8945 * @len: length of @str in bytes, or -1 if @str is nul-terminated
8947 * Converts all upper case ASCII letters to lower case ASCII letters.
8949 * Returns: a newly-allocated string, with all the upper case
8950 * characters in @str converted to lower case, with semantics that
8951 * exactly match g_ascii_tolower(). (Note that this is unlike the
8952 * old g_strdown(), which modified the string in place.)
8957 * g_ascii_strncasecmp:
8958 * @s1: string to compare with @s2
8959 * @s2: string to compare with @s1
8960 * @n: number of characters to compare
8962 * Compare @s1 and @s2, ignoring the case of ASCII characters and any
8963 * characters after the first @n in each string.
8965 * Unlike the BSD strcasecmp() function, this only recognizes standard
8966 * ASCII letters and ignores the locale, treating all non-ASCII
8967 * characters as if they are not letters.
8969 * The same warning as in g_ascii_strcasecmp() applies: Use this
8970 * function only on strings known to be in encodings where bytes
8971 * corresponding to ASCII letters always represent themselves.
8973 * Returns: 0 if the strings match, a negative value if @s1 < @s2,
8974 * or a positive value if @s1 > @s2.
8980 * @nptr: the string to convert to a numeric value.
8981 * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the
8982 * character after the last character used in the conversion.
8984 * Converts a string to a #gdouble value.
8986 * This function behaves like the standard strtod() function
8987 * does in the C locale. It does this without actually changing
8988 * the current locale, since that would not be thread-safe.
8989 * A limitation of the implementation is that this function
8990 * will still accept localized versions of infinities and NANs.
8992 * This function is typically used when reading configuration
8993 * files or other non-user input that should be locale independent.
8994 * To handle input from the user you should normally use the
8995 * locale-sensitive system strtod() function.
8997 * To convert from a #gdouble to a string in a locale-insensitive
8998 * way, use g_ascii_dtostr().
9000 * If the correct value would cause overflow, plus or minus %HUGE_VAL
9001 * is returned (according to the sign of the value), and %ERANGE is
9002 * stored in %errno. If the correct value would cause underflow,
9003 * zero is returned and %ERANGE is stored in %errno.
9005 * This function resets %errno before calling strtod() so that
9006 * you can reliably detect overflow and underflow.
9008 * Returns: the #gdouble value.
9014 * @nptr: the string to convert to a numeric value.
9015 * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the
9016 * character after the last character used in the conversion.
9017 * @base: to be used for the conversion, 2..36 or 0
9019 * Converts a string to a #gint64 value.
9020 * This function behaves like the standard strtoll() function
9021 * does in the C locale. It does this without actually
9022 * changing the current locale, since that would not be
9025 * This function is typically used when reading configuration
9026 * files or other non-user input that should be locale independent.
9027 * To handle input from the user you should normally use the
9028 * locale-sensitive system strtoll() function.
9030 * If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
9031 * is returned, and `ERANGE` is stored in `errno`.
9032 * If the base is outside the valid range, zero is returned, and
9033 * `EINVAL` is stored in `errno`. If the
9034 * string conversion fails, zero is returned, and @endptr returns @nptr
9035 * (if @endptr is non-%NULL).
9037 * Returns: the #gint64 value or zero on error.
9044 * @nptr: the string to convert to a numeric value.
9045 * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the
9046 * character after the last character used in the conversion.
9047 * @base: to be used for the conversion, 2..36 or 0
9049 * Converts a string to a #guint64 value.
9050 * This function behaves like the standard strtoull() function
9051 * does in the C locale. It does this without actually
9052 * changing the current locale, since that would not be
9055 * This function is typically used when reading configuration
9056 * files or other non-user input that should be locale independent.
9057 * To handle input from the user you should normally use the
9058 * locale-sensitive system strtoull() function.
9060 * If the correct value would cause overflow, %G_MAXUINT64
9061 * is returned, and `ERANGE` is stored in `errno`.
9062 * If the base is outside the valid range, zero is returned, and
9063 * `EINVAL` is stored in `errno`.
9064 * If the string conversion fails, zero is returned, and @endptr returns
9065 * @nptr (if @endptr is non-%NULL).
9067 * Returns: the #guint64 value or zero on error.
9075 * @len: length of @str in bytes, or -1 if @str is nul-terminated
9077 * Converts all lower case ASCII letters to upper case ASCII letters.
9079 * Returns: a newly allocated string, with all the lower case
9080 * characters in @str converted to upper case, with semantics that
9081 * exactly match g_ascii_toupper(). (Note that this is unlike the
9082 * old g_strup(), which modified the string in place.)
9090 * Convert a character to ASCII lower case.
9092 * Unlike the standard C library tolower() function, this only
9093 * recognizes standard ASCII letters and ignores the locale, returning
9094 * all non-ASCII characters unchanged, even if they are lower case
9095 * letters in a particular character set. Also unlike the standard
9096 * library function, this takes and returns a char, not an int, so
9097 * don't call it on %EOF but no need to worry about casting to #guchar
9098 * before passing a possibly non-ASCII character in.
9100 * Returns: the result of converting @c to lower case. If @c is
9101 * not an ASCII upper case letter, @c is returned unchanged.
9109 * Convert a character to ASCII upper case.
9111 * Unlike the standard C library toupper() function, this only
9112 * recognizes standard ASCII letters and ignores the locale, returning
9113 * all non-ASCII characters unchanged, even if they are upper case
9114 * letters in a particular character set. Also unlike the standard
9115 * library function, this takes and returns a char, not an int, so
9116 * don't call it on %EOF but no need to worry about casting to #guchar
9117 * before passing a possibly non-ASCII character in.
9119 * Returns: the result of converting @c to upper case. If @c is not
9120 * an ASCII lower case letter, @c is returned unchanged.
9125 * g_ascii_xdigit_value:
9126 * @c: an ASCII character.
9128 * Determines the numeric value of a character as a hexidecimal
9129 * digit. Differs from g_unichar_xdigit_value() because it takes
9130 * a char, so there's no worry about sign extension if characters
9133 * Returns: If @c is a hex digit (according to g_ascii_isxdigit()),
9134 * its numeric value. Otherwise, -1.
9140 * @expr: the expression to check
9142 * Debugging macro to terminate the application if the assertion
9143 * fails. If the assertion fails (i.e. the expression is not true),
9144 * an error message is logged and the application is terminated.
9146 * The macro can be turned off in final releases of code by defining
9147 * `G_DISABLE_ASSERT` when compiling the application.
9152 * g_assert_cmpfloat:
9153 * @n1: an floating point number
9154 * @cmp: The comparison operator to use.
9155 * One of ==, !=, <, >, <=, >=.
9156 * @n2: another floating point number
9158 * Debugging macro to compare two floating point numbers.
9160 * The effect of `g_assert_cmpfloat (n1, op, n2)` is
9161 * the same as `g_assert_true (n1 op n2)`. The advantage
9162 * of this macro is that it can produce a message that includes the
9163 * actual values of @n1 and @n2.
9171 * @n1: an unsigned integer
9172 * @cmp: The comparison operator to use.
9173 * One of ==, !=, <, >, <=, >=.
9174 * @n2: another unsigned integer
9176 * Debugging macro to compare to unsigned integers.
9178 * This is a variant of g_assert_cmpuint() that displays the numbers
9179 * in hexadecimal notation in the message.
9188 * @cmp: The comparison operator to use.
9189 * One of ==, !=, <, >, <=, >=.
9190 * @n2: another integer
9192 * Debugging macro to compare two integers.
9194 * The effect of `g_assert_cmpint (n1, op, n2)` is
9195 * the same as `g_assert_true (n1 op n2)`. The advantage
9196 * of this macro is that it can produce a message that includes the
9197 * actual values of @n1 and @n2.
9205 * @m1: pointer to a buffer
9206 * @l1: length of @m1
9207 * @m2: pointer to another buffer
9208 * @l2: length of @m2
9210 * Debugging macro to compare memory regions. If the comparison fails,
9211 * an error message is logged and the application is either terminated
9212 * or the testcase marked as failed.
9214 * The effect of `g_assert_cmpmem (m1, l1, m2, l2)` is
9215 * the same as `g_assert_true (l1 == l2 && memcmp (m1, m2, l1) == 0)`.
9216 * The advantage of this macro is that it can produce a message that
9217 * includes the actual values of @l1 and @l2.
9219 * |[<!-- language="C" -->
9220 * g_assert_cmpmem (buf->data, buf->len, expected, sizeof (expected));
9229 * @s1: a string (may be %NULL)
9230 * @cmp: The comparison operator to use.
9231 * One of ==, !=, <, >, <=, >=.
9232 * @s2: another string (may be %NULL)
9234 * Debugging macro to compare two strings. If the comparison fails,
9235 * an error message is logged and the application is either terminated
9236 * or the testcase marked as failed.
9237 * The strings are compared using g_strcmp0().
9239 * The effect of `g_assert_cmpstr (s1, op, s2)` is
9240 * the same as `g_assert_true (g_strcmp0 (s1, s2) op 0)`.
9241 * The advantage of this macro is that it can produce a message that
9242 * includes the actual values of @s1 and @s2.
9244 * |[<!-- language="C" -->
9245 * g_assert_cmpstr (mystring, ==, "fubar");
9254 * @n1: an unsigned integer
9255 * @cmp: The comparison operator to use.
9256 * One of ==, !=, <, >, <=, >=.
9257 * @n2: another unsigned integer
9259 * Debugging macro to compare two unsigned integers.
9261 * The effect of `g_assert_cmpuint (n1, op, n2)` is
9262 * the same as `g_assert_true (n1 op n2)`. The advantage
9263 * of this macro is that it can produce a message that includes the
9264 * actual values of @n1 and @n2.
9272 * @err: a #GError, possibly %NULL
9273 * @dom: the expected error domain (a #GQuark)
9274 * @c: the expected error code
9276 * Debugging macro to check that a method has returned
9277 * the correct #GError.
9279 * The effect of `g_assert_error (err, dom, c)` is
9280 * the same as `g_assert_true (err != NULL && err->domain
9281 * == dom && err->code == c)`. The advantage of this
9282 * macro is that it can produce a message that includes the incorrect
9283 * error message and code.
9285 * This can only be used to test for a specific error. If you want to
9286 * test that @err is set, but don't care what it's set to, just use
9287 * `g_assert (err != NULL)`
9295 * @expr: the expression to check
9297 * Debugging macro to check an expression is false.
9299 * If the assertion fails (i.e. the expression is not false),
9300 * an error message is logged and the application is either
9301 * terminated or the testcase marked as failed.
9303 * See g_test_set_nonfatal_assertions().
9310 * g_assert_no_error:
9311 * @err: a #GError, possibly %NULL
9313 * Debugging macro to check that a #GError is not set.
9315 * The effect of `g_assert_no_error (err)` is
9316 * the same as `g_assert_true (err == NULL)`. The advantage
9317 * of this macro is that it can produce a message that includes
9318 * the error message and code.
9326 * @expr: the expression to check
9328 * Debugging macro to check an expression is not %NULL.
9330 * If the assertion fails (i.e. the expression is %NULL),
9331 * an error message is logged and the application is either
9332 * terminated or the testcase marked as failed.
9334 * See g_test_set_nonfatal_assertions().
9341 * g_assert_not_reached:
9343 * Debugging macro to terminate the application if it is ever
9344 * reached. If it is reached, an error message is logged and the
9345 * application is terminated.
9347 * The macro can be turned off in final releases of code by defining
9348 * `G_DISABLE_ASSERT` when compiling the application.
9354 * @expr: the expression to check
9356 * Debugging macro to check an expression is %NULL.
9358 * If the assertion fails (i.e. the expression is not %NULL),
9359 * an error message is logged and the application is either
9360 * terminated or the testcase marked as failed.
9362 * See g_test_set_nonfatal_assertions().
9370 * @expr: the expression to check
9372 * Debugging macro to check that an expression is true.
9374 * If the assertion fails (i.e. the expression is not true),
9375 * an error message is logged and the application is either
9376 * terminated or the testcase marked as failed.
9378 * See g_test_set_nonfatal_assertions().
9385 * g_assertion_message_expr: (skip)
9386 * @domain: (nullable):
9390 * @expr: (nullable):
9395 * g_async_queue_length:
9396 * @queue: a #GAsyncQueue.
9398 * Returns the length of the queue.
9400 * Actually this function returns the number of data items in
9401 * the queue minus the number of waiting threads, so a negative
9402 * value means waiting threads, and a positive value means available
9403 * entries in the @queue. A return value of 0 could mean n entries
9404 * in the queue and n threads waiting. This can happen due to locking
9405 * of the queue or due to scheduling.
9407 * Returns: the length of the @queue
9412 * g_async_queue_length_unlocked:
9413 * @queue: a #GAsyncQueue
9415 * Returns the length of the queue.
9417 * Actually this function returns the number of data items in
9418 * the queue minus the number of waiting threads, so a negative
9419 * value means waiting threads, and a positive value means available
9420 * entries in the @queue. A return value of 0 could mean n entries
9421 * in the queue and n threads waiting. This can happen due to locking
9422 * of the queue or due to scheduling.
9424 * This function must be called while holding the @queue's lock.
9426 * Returns: the length of the @queue.
9431 * g_async_queue_lock:
9432 * @queue: a #GAsyncQueue
9434 * Acquires the @queue's lock. If another thread is already
9435 * holding the lock, this call will block until the lock
9436 * becomes available.
9438 * Call g_async_queue_unlock() to drop the lock again.
9440 * While holding the lock, you can only call the
9441 * g_async_queue_*_unlocked() functions on @queue. Otherwise,
9442 * deadlock may occur.
9447 * g_async_queue_new:
9449 * Creates a new asynchronous queue.
9451 * Returns: a new #GAsyncQueue. Free with g_async_queue_unref()
9456 * g_async_queue_new_full:
9457 * @item_free_func: function to free queue elements
9459 * Creates a new asynchronous queue and sets up a destroy notify
9460 * function that is used to free any remaining queue items when
9461 * the queue is destroyed after the final unref.
9463 * Returns: a new #GAsyncQueue. Free with g_async_queue_unref()
9469 * g_async_queue_pop:
9470 * @queue: a #GAsyncQueue
9472 * Pops data from the @queue. If @queue is empty, this function
9473 * blocks until data becomes available.
9475 * Returns: data from the queue
9480 * g_async_queue_pop_unlocked:
9481 * @queue: a #GAsyncQueue
9483 * Pops data from the @queue. If @queue is empty, this function
9484 * blocks until data becomes available.
9486 * This function must be called while holding the @queue's lock.
9488 * Returns: data from the queue.
9493 * g_async_queue_push:
9494 * @queue: a #GAsyncQueue
9495 * @data: @data to push into the @queue
9497 * Pushes the @data into the @queue. @data must not be %NULL.
9502 * g_async_queue_push_front:
9503 * @queue: a #GAsyncQueue
9504 * @item: data to push into the @queue
9506 * Pushes the @item into the @queue. @item must not be %NULL.
9507 * In contrast to g_async_queue_push(), this function
9508 * pushes the new item ahead of the items already in the queue,
9509 * so that it will be the next one to be popped off the queue.
9516 * g_async_queue_push_front_unlocked:
9517 * @queue: a #GAsyncQueue
9518 * @item: data to push into the @queue
9520 * Pushes the @item into the @queue. @item must not be %NULL.
9521 * In contrast to g_async_queue_push_unlocked(), this function
9522 * pushes the new item ahead of the items already in the queue,
9523 * so that it will be the next one to be popped off the queue.
9525 * This function must be called while holding the @queue's lock.
9532 * g_async_queue_push_sorted:
9533 * @queue: a #GAsyncQueue
9534 * @data: the @data to push into the @queue
9535 * @func: the #GCompareDataFunc is used to sort @queue
9536 * @user_data: user data passed to @func.
9538 * Inserts @data into @queue using @func to determine the new
9541 * This function requires that the @queue is sorted before pushing on
9542 * new elements, see g_async_queue_sort().
9544 * This function will lock @queue before it sorts the queue and unlock
9545 * it when it is finished.
9547 * For an example of @func see g_async_queue_sort().
9554 * g_async_queue_push_sorted_unlocked:
9555 * @queue: a #GAsyncQueue
9556 * @data: the @data to push into the @queue
9557 * @func: the #GCompareDataFunc is used to sort @queue
9558 * @user_data: user data passed to @func.
9560 * Inserts @data into @queue using @func to determine the new
9563 * The sort function @func is passed two elements of the @queue.
9564 * It should return 0 if they are equal, a negative value if the
9565 * first element should be higher in the @queue or a positive value
9566 * if the first element should be lower in the @queue than the second
9569 * This function requires that the @queue is sorted before pushing on
9570 * new elements, see g_async_queue_sort().
9572 * This function must be called while holding the @queue's lock.
9574 * For an example of @func see g_async_queue_sort().
9581 * g_async_queue_push_unlocked:
9582 * @queue: a #GAsyncQueue
9583 * @data: @data to push into the @queue
9585 * Pushes the @data into the @queue. @data must not be %NULL.
9587 * This function must be called while holding the @queue's lock.
9592 * g_async_queue_ref:
9593 * @queue: a #GAsyncQueue
9595 * Increases the reference count of the asynchronous @queue by 1.
9596 * You do not need to hold the lock to call this function.
9598 * Returns: the @queue that was passed in (since 2.6)
9603 * g_async_queue_ref_unlocked:
9604 * @queue: a #GAsyncQueue
9606 * Increases the reference count of the asynchronous @queue by 1.
9608 * Deprecated: 2.8: Reference counting is done atomically.
9609 * so g_async_queue_ref() can be used regardless of the @queue's
9615 * g_async_queue_remove:
9616 * @queue: a #GAsyncQueue
9617 * @item: the data to remove from the @queue
9619 * Remove an item from the queue.
9621 * Returns: %TRUE if the item was removed
9627 * g_async_queue_remove_unlocked:
9628 * @queue: a #GAsyncQueue
9629 * @item: the data to remove from the @queue
9631 * Remove an item from the queue.
9633 * This function must be called while holding the @queue's lock.
9635 * Returns: %TRUE if the item was removed
9641 * g_async_queue_sort:
9642 * @queue: a #GAsyncQueue
9643 * @func: the #GCompareDataFunc is used to sort @queue
9644 * @user_data: user data passed to @func
9646 * Sorts @queue using @func.
9648 * The sort function @func is passed two elements of the @queue.
9649 * It should return 0 if they are equal, a negative value if the
9650 * first element should be higher in the @queue or a positive value
9651 * if the first element should be lower in the @queue than the second
9654 * This function will lock @queue before it sorts the queue and unlock
9655 * it when it is finished.
9657 * If you were sorting a list of priority numbers to make sure the
9658 * lowest priority would be at the top of the queue, you could use:
9659 * |[<!-- language="C" -->
9663 * id1 = GPOINTER_TO_INT (element1);
9664 * id2 = GPOINTER_TO_INT (element2);
9666 * return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);
9674 * g_async_queue_sort_unlocked:
9675 * @queue: a #GAsyncQueue
9676 * @func: the #GCompareDataFunc is used to sort @queue
9677 * @user_data: user data passed to @func
9679 * Sorts @queue using @func.
9681 * The sort function @func is passed two elements of the @queue.
9682 * It should return 0 if they are equal, a negative value if the
9683 * first element should be higher in the @queue or a positive value
9684 * if the first element should be lower in the @queue than the second
9687 * This function must be called while holding the @queue's lock.
9694 * g_async_queue_timed_pop:
9695 * @queue: a #GAsyncQueue
9696 * @end_time: a #GTimeVal, determining the final time
9698 * Pops data from the @queue. If the queue is empty, blocks until
9699 * @end_time or until data becomes available.
9701 * If no data is received before @end_time, %NULL is returned.
9703 * To easily calculate @end_time, a combination of g_get_current_time()
9704 * and g_time_val_add() can be used.
9706 * Returns: data from the queue or %NULL, when no data is
9707 * received before @end_time.
9708 * Deprecated: use g_async_queue_timeout_pop().
9713 * g_async_queue_timed_pop_unlocked:
9714 * @queue: a #GAsyncQueue
9715 * @end_time: a #GTimeVal, determining the final time
9717 * Pops data from the @queue. If the queue is empty, blocks until
9718 * @end_time or until data becomes available.
9720 * If no data is received before @end_time, %NULL is returned.
9722 * To easily calculate @end_time, a combination of g_get_current_time()
9723 * and g_time_val_add() can be used.
9725 * This function must be called while holding the @queue's lock.
9727 * Returns: data from the queue or %NULL, when no data is
9728 * received before @end_time.
9729 * Deprecated: use g_async_queue_timeout_pop_unlocked().
9734 * g_async_queue_timeout_pop:
9735 * @queue: a #GAsyncQueue
9736 * @timeout: the number of microseconds to wait
9738 * Pops data from the @queue. If the queue is empty, blocks for
9739 * @timeout microseconds, or until data becomes available.
9741 * If no data is received before the timeout, %NULL is returned.
9743 * Returns: data from the queue or %NULL, when no data is
9744 * received before the timeout.
9749 * g_async_queue_timeout_pop_unlocked:
9750 * @queue: a #GAsyncQueue
9751 * @timeout: the number of microseconds to wait
9753 * Pops data from the @queue. If the queue is empty, blocks for
9754 * @timeout microseconds, or until data becomes available.
9756 * If no data is received before the timeout, %NULL is returned.
9758 * This function must be called while holding the @queue's lock.
9760 * Returns: data from the queue or %NULL, when no data is
9761 * received before the timeout.
9766 * g_async_queue_try_pop:
9767 * @queue: a #GAsyncQueue
9769 * Tries to pop data from the @queue. If no data is available,
9770 * %NULL is returned.
9772 * Returns: data from the queue or %NULL, when no data is
9773 * available immediately.
9778 * g_async_queue_try_pop_unlocked:
9779 * @queue: a #GAsyncQueue
9781 * Tries to pop data from the @queue. If no data is available,
9782 * %NULL is returned.
9784 * This function must be called while holding the @queue's lock.
9786 * Returns: data from the queue or %NULL, when no data is
9787 * available immediately.
9792 * g_async_queue_unlock:
9793 * @queue: a #GAsyncQueue
9795 * Releases the queue's lock.
9797 * Calling this function when you have not acquired
9798 * the with g_async_queue_lock() leads to undefined
9804 * g_async_queue_unref:
9805 * @queue: a #GAsyncQueue.
9807 * Decreases the reference count of the asynchronous @queue by 1.
9809 * If the reference count went to 0, the @queue will be destroyed
9810 * and the memory allocated will be freed. So you are not allowed
9811 * to use the @queue afterwards, as it might have disappeared.
9812 * You do not need to hold the lock to call this function.
9817 * g_async_queue_unref_and_unlock:
9818 * @queue: a #GAsyncQueue
9820 * Decreases the reference count of the asynchronous @queue by 1
9821 * and releases the lock. This function must be called while holding
9822 * the @queue's lock. If the reference count went to 0, the @queue
9823 * will be destroyed and the memory allocated will be freed.
9825 * Deprecated: 2.8: Reference counting is done atomically.
9826 * so g_async_queue_unref() can be used regardless of the @queue's
9833 * @func: (scope async): the function to call on normal program termination.
9835 * Specifies a function to be called at normal program termination.
9837 * Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor
9838 * macro that maps to a call to the atexit() function in the C
9839 * library. This means that in case the code that calls g_atexit(),
9840 * i.e. atexit(), is in a DLL, the function will be called when the
9841 * DLL is detached from the program. This typically makes more sense
9842 * than that the function is called when the GLib DLL is detached,
9843 * which happened earlier when g_atexit() was a function in the GLib
9846 * The behaviour of atexit() in the context of dynamically loaded
9847 * modules is not formally specified and varies wildly.
9849 * On POSIX systems, calling g_atexit() (or atexit()) in a dynamically
9850 * loaded module which is unloaded before the program terminates might
9851 * well cause a crash at program exit.
9853 * Some POSIX systems implement atexit() like Windows, and have each
9854 * dynamically loaded module maintain an own atexit chain that is
9855 * called when the module is unloaded.
9857 * On other POSIX systems, before a dynamically loaded module is
9858 * unloaded, the registered atexit functions (if any) residing in that
9859 * module are called, regardless where the code that registered them
9860 * resided. This is presumably the most robust approach.
9862 * As can be seen from the above, for portability it's best to avoid
9863 * calling g_atexit() (or atexit()) except in the main executable of a
9866 * Deprecated: 2.32: It is best to avoid g_atexit().
9872 * @atomic: a pointer to a #gint or #guint
9873 * @val: the value to add
9875 * Atomically adds @val to the value of @atomic.
9877 * Think of this operation as an atomic version of
9878 * `{ tmp = *atomic; *atomic += val; return tmp; }`.
9880 * This call acts as a full compiler and hardware memory barrier.
9882 * Before version 2.30, this function did not return a value
9883 * (but g_atomic_int_exchange_and_add() did, and had the same meaning).
9885 * Returns: the value of @atomic before the add, signed
9892 * @atomic: a pointer to a #gint or #guint
9893 * @val: the value to 'and'
9895 * Performs an atomic bitwise 'and' of the value of @atomic and @val,
9896 * storing the result back in @atomic.
9898 * This call acts as a full compiler and hardware memory barrier.
9900 * Think of this operation as an atomic version of
9901 * `{ tmp = *atomic; *atomic &= val; return tmp; }`.
9903 * Returns: the value of @atomic before the operation, unsigned
9909 * g_atomic_int_compare_and_exchange:
9910 * @atomic: a pointer to a #gint or #guint
9911 * @oldval: the value to compare with
9912 * @newval: the value to conditionally replace with
9914 * Compares @atomic to @oldval and, if equal, sets it to @newval.
9915 * If @atomic was not equal to @oldval then no change occurs.
9917 * This compare and exchange is done atomically.
9919 * Think of this operation as an atomic version of
9920 * `{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`.
9922 * This call acts as a full compiler and hardware memory barrier.
9924 * Returns: %TRUE if the exchange took place
9930 * g_atomic_int_dec_and_test:
9931 * @atomic: a pointer to a #gint or #guint
9933 * Decrements the value of @atomic by 1.
9935 * Think of this operation as an atomic version of
9936 * `{ *atomic -= 1; return (*atomic == 0); }`.
9938 * This call acts as a full compiler and hardware memory barrier.
9940 * Returns: %TRUE if the resultant value is zero
9946 * g_atomic_int_exchange_and_add:
9947 * @atomic: a pointer to a #gint
9948 * @val: the value to add
9950 * This function existed before g_atomic_int_add() returned the prior
9951 * value of the integer (which it now does). It is retained only for
9952 * compatibility reasons. Don't use this function in new code.
9954 * Returns: the value of @atomic before the add, signed
9956 * Deprecated: 2.30: Use g_atomic_int_add() instead.
9962 * @atomic: a pointer to a #gint or #guint
9964 * Gets the current value of @atomic.
9966 * This call acts as a full compiler and hardware
9967 * memory barrier (before the get).
9969 * Returns: the value of the integer
9976 * @atomic: a pointer to a #gint or #guint
9978 * Increments the value of @atomic by 1.
9980 * Think of this operation as an atomic version of `{ *atomic += 1; }`.
9982 * This call acts as a full compiler and hardware memory barrier.
9990 * @atomic: a pointer to a #gint or #guint
9991 * @val: the value to 'or'
9993 * Performs an atomic bitwise 'or' of the value of @atomic and @val,
9994 * storing the result back in @atomic.
9996 * Think of this operation as an atomic version of
9997 * `{ tmp = *atomic; *atomic |= val; return tmp; }`.
9999 * This call acts as a full compiler and hardware memory barrier.
10001 * Returns: the value of @atomic before the operation, unsigned
10007 * g_atomic_int_set:
10008 * @atomic: a pointer to a #gint or #guint
10009 * @newval: a new value to store
10011 * Sets the value of @atomic to @newval.
10013 * This call acts as a full compiler and hardware
10014 * memory barrier (after the set).
10021 * g_atomic_int_xor:
10022 * @atomic: a pointer to a #gint or #guint
10023 * @val: the value to 'xor'
10025 * Performs an atomic bitwise 'xor' of the value of @atomic and @val,
10026 * storing the result back in @atomic.
10028 * Think of this operation as an atomic version of
10029 * `{ tmp = *atomic; *atomic ^= val; return tmp; }`.
10031 * This call acts as a full compiler and hardware memory barrier.
10033 * Returns: the value of @atomic before the operation, unsigned
10039 * g_atomic_pointer_add:
10040 * @atomic: (not nullable): a pointer to a #gpointer-sized value
10041 * @val: the value to add
10043 * Atomically adds @val to the value of @atomic.
10045 * Think of this operation as an atomic version of
10046 * `{ tmp = *atomic; *atomic += val; return tmp; }`.
10048 * This call acts as a full compiler and hardware memory barrier.
10050 * Returns: the value of @atomic before the add, signed
10056 * g_atomic_pointer_and:
10057 * @atomic: (not nullable): a pointer to a #gpointer-sized value
10058 * @val: the value to 'and'
10060 * Performs an atomic bitwise 'and' of the value of @atomic and @val,
10061 * storing the result back in @atomic.
10063 * Think of this operation as an atomic version of
10064 * `{ tmp = *atomic; *atomic &= val; return tmp; }`.
10066 * This call acts as a full compiler and hardware memory barrier.
10068 * Returns: the value of @atomic before the operation, unsigned
10074 * g_atomic_pointer_compare_and_exchange:
10075 * @atomic: (not nullable): a pointer to a #gpointer-sized value
10076 * @oldval: the value to compare with
10077 * @newval: the value to conditionally replace with
10079 * Compares @atomic to @oldval and, if equal, sets it to @newval.
10080 * If @atomic was not equal to @oldval then no change occurs.
10082 * This compare and exchange is done atomically.
10084 * Think of this operation as an atomic version of
10085 * `{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`.
10087 * This call acts as a full compiler and hardware memory barrier.
10089 * Returns: %TRUE if the exchange took place
10095 * g_atomic_pointer_get:
10096 * @atomic: (not nullable): a pointer to a #gpointer-sized value
10098 * Gets the current value of @atomic.
10100 * This call acts as a full compiler and hardware
10101 * memory barrier (before the get).
10103 * Returns: the value of the pointer
10109 * g_atomic_pointer_or:
10110 * @atomic: (not nullable): a pointer to a #gpointer-sized value
10111 * @val: the value to 'or'
10113 * Performs an atomic bitwise 'or' of the value of @atomic and @val,
10114 * storing the result back in @atomic.
10116 * Think of this operation as an atomic version of
10117 * `{ tmp = *atomic; *atomic |= val; return tmp; }`.
10119 * This call acts as a full compiler and hardware memory barrier.
10121 * Returns: the value of @atomic before the operation, unsigned
10127 * g_atomic_pointer_set:
10128 * @atomic: (not nullable): a pointer to a #gpointer-sized value
10129 * @newval: a new value to store
10131 * Sets the value of @atomic to @newval.
10133 * This call acts as a full compiler and hardware
10134 * memory barrier (after the set).
10141 * g_atomic_pointer_xor:
10142 * @atomic: (not nullable): a pointer to a #gpointer-sized value
10143 * @val: the value to 'xor'
10145 * Performs an atomic bitwise 'xor' of the value of @atomic and @val,
10146 * storing the result back in @atomic.
10148 * Think of this operation as an atomic version of
10149 * `{ tmp = *atomic; *atomic ^= val; return tmp; }`.
10151 * This call acts as a full compiler and hardware memory barrier.
10153 * Returns: the value of @atomic before the operation, unsigned
10160 * @TypeName: a supported variable type
10162 * Helper to declare a variable with automatic cleanup.
10164 * The variable is cleaned up in a way appropriate to its type when the
10165 * variable goes out of scope. The type must support this.
10167 * This feature is only supported on GCC and clang. This macro is not
10168 * defined on other compilers and should not be used in programs that
10169 * are intended to be portable to those compilers.
10171 * This is meant to be used with stack-allocated structures and
10172 * non-pointer types. For the (more commonly used) pointer version, see
10175 * This macro can be used to avoid having to do explicit cleanups of
10176 * local variables when exiting functions. It often vastly simplifies
10177 * handling of error conditions, removing the need for various tricks
10178 * such as 'goto out' or repeating of cleanup code. It is also helpful
10179 * for non-error cases.
10181 * Consider the following example:
10187 * g_auto(GQueue) queue = G_QUEUE_INIT;
10188 * g_auto(GVariantBuilder) builder;
10189 * g_auto(GStrv) strv;
10191 * g_variant_builder_init (&builder, G_VARIANT_TYPE_VARDICT);
10192 * strv = g_strsplit("a:b:c", ":", -1);
10196 * if (error_condition)
10201 * return g_variant_builder_end (&builder);
10205 * You must initialize the variable in some way -- either by use of an
10206 * initialiser or by ensuring that an _init function will be called on
10207 * it unconditionally before it goes out of scope.
10216 * Macro to add an attribute to pointer variable to ensure automatic
10217 * cleanup using g_free().
10219 * This macro differs from g_autoptr() in that it is an attribute supplied
10220 * before the type name, rather than wrapping the type definition. Instead
10221 * of using a type-specific lookup, this macro always calls g_free() directly.
10223 * This means it's useful for any type that is returned from
10226 * Otherwise, this macro has similar constraints as g_autoptr() - only
10227 * supported on GCC and clang, the variable must be initialized, etc.
10231 * operate_on_malloc_buf (void)
10233 * g_autofree guint8* membuf = NULL;
10235 * membuf = g_malloc (8192);
10237 * /* Some computation on membuf
10243 * @TypeName: a supported variable type
10245 * Helper to declare a pointer variable with automatic cleanup.
10247 * The variable is cleaned up in a way appropriate to its type when the
10248 * variable goes out of scope. The type must support this.
10250 * This feature is only supported on GCC and clang. This macro is not
10251 * defined on other compilers and should not be used in programs that
10252 * are intended to be portable to those compilers.
10254 * This is meant to be used to declare pointers to types with cleanup
10255 * functions. The type of the variable is a pointer to @TypeName. You
10256 * must not add your own '*'.
10258 * This macro can be used to avoid having to do explicit cleanups of
10259 * local variables when exiting functions. It often vastly simplifies
10260 * handling of error conditions, removing the need for various tricks
10261 * such as 'goto out' or repeating of cleanup code. It is also helpful
10262 * for non-error cases.
10264 * Consider the following example:
10268 * check_exists(GVariant *dict)
10270 * g_autoptr(GVariant) dirname, basename = NULL;
10271 * g_autofree gchar *path = NULL;
10273 * dirname = g_variant_lookup_value (dict, "dirname", G_VARIANT_TYPE_STRING);
10275 * if (dirname == NULL)
10278 * basename = g_variant_lookup_value (dict, "basename", G_VARIANT_TYPE_STRING);
10280 * if (basename == NULL)
10283 * path = g_build_filename (g_variant_get_string (dirname, NULL),
10284 * g_variant_get_string (basename, NULL),
10287 * return g_access (path, R_OK) == 0;
10291 * You must initialise the variable in some way -- either by use of an
10292 * initialiser or by ensuring that it is assigned to unconditionally
10293 * before it goes out of scope.
10295 * See also g_auto(), g_autofree() and g_steal_pointer().
10303 * @text: zero-terminated string with base64 text to decode
10304 * @out_len: (out): The length of the decoded data is written here
10306 * Decode a sequence of Base-64 encoded text into binary data. Note
10307 * that the returned binary data is not necessarily zero-terminated,
10308 * so it should not be used as a character string.
10310 * Returns: (transfer full) (array length=out_len) (element-type guint8):
10311 * newly allocated buffer containing the binary data
10312 * that @text represents. The returned buffer must
10313 * be freed with g_free().
10319 * g_base64_decode_inplace:
10320 * @text: (inout) (array length=out_len) (element-type guint8): zero-terminated
10321 * string with base64 text to decode
10322 * @out_len: (inout): The length of the decoded data is written here
10324 * Decode a sequence of Base-64 encoded text into binary data
10325 * by overwriting the input data.
10327 * Returns: (transfer none): The binary data that @text responds. This pointer
10328 * is the same as the input @text.
10334 * g_base64_decode_step:
10335 * @in: (array length=len) (element-type guint8): binary input data
10336 * @len: max length of @in data to decode
10337 * @out: (out) (array) (element-type guint8): output buffer
10338 * @state: (inout): Saved state between steps, initialize to 0
10339 * @save: (inout): Saved state between steps, initialize to 0
10341 * Incrementally decode a sequence of binary data from its Base-64 stringified
10342 * representation. By calling this function multiple times you can convert
10343 * data in chunks to avoid having to have the full encoded data in memory.
10345 * The output buffer must be large enough to fit all the data that will
10346 * be written to it. Since base64 encodes 3 bytes in 4 chars you need
10347 * at least: (@len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero
10350 * Returns: The number of bytes of output that was written
10357 * @data: (array length=len) (element-type guint8): the binary data to encode
10358 * @len: the length of @data
10360 * Encode a sequence of binary data into its Base-64 stringified
10363 * Returns: (transfer full): a newly allocated, zero-terminated Base-64
10364 * encoded string representing @data. The returned string must
10365 * be freed with g_free().
10371 * g_base64_encode_close:
10372 * @break_lines: whether to break long lines
10373 * @out: (out) (array) (element-type guint8): pointer to destination buffer
10374 * @state: (inout): Saved state from g_base64_encode_step()
10375 * @save: (inout): Saved state from g_base64_encode_step()
10377 * Flush the status from a sequence of calls to g_base64_encode_step().
10379 * The output buffer must be large enough to fit all the data that will
10380 * be written to it. It will need up to 4 bytes, or up to 5 bytes if
10381 * line-breaking is enabled.
10383 * Returns: The number of bytes of output that was written
10389 * g_base64_encode_step:
10390 * @in: (array length=len) (element-type guint8): the binary data to encode
10391 * @len: the length of @in
10392 * @break_lines: whether to break long lines
10393 * @out: (out) (array) (element-type guint8): pointer to destination buffer
10394 * @state: (inout): Saved state between steps, initialize to 0
10395 * @save: (inout): Saved state between steps, initialize to 0
10397 * Incrementally encode a sequence of binary data into its Base-64 stringified
10398 * representation. By calling this function multiple times you can convert
10399 * data in chunks to avoid having to have the full encoded data in memory.
10401 * When all of the data has been converted you must call
10402 * g_base64_encode_close() to flush the saved state.
10404 * The output buffer must be large enough to fit all the data that will
10405 * be written to it. Due to the way base64 encodes you will need
10406 * at least: (@len / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of
10407 * non-zero state). If you enable line-breaking you will need at least:
10408 * ((@len / 3 + 1) * 4 + 4) / 72 + 1 bytes of extra space.
10410 * @break_lines is typically used when putting base64-encoded data in emails.
10411 * It breaks the lines at 72 columns instead of putting all of the text on
10412 * the same line. This avoids problems with long lines in the email system.
10413 * Note however that it breaks the lines with `LF` characters, not
10414 * `CR LF` sequences, so the result cannot be passed directly to SMTP
10415 * or certain other protocols.
10417 * Returns: The number of bytes of output that was written
10424 * @file_name: (type filename): the name of the file
10426 * Gets the name of the file without any leading directory
10427 * components. It returns a pointer into the given file name
10430 * Returns: (type filename): the name of the file without any leading
10431 * directory components
10432 * Deprecated: 2.2: Use g_path_get_basename() instead, but notice
10433 * that g_path_get_basename() allocates new memory for the
10434 * returned string, unlike this function which returns a pointer
10435 * into the argument.
10441 * @address: a pointer to an integer
10442 * @lock_bit: a bit value between 0 and 31
10444 * Sets the indicated @lock_bit in @address. If the bit is already
10445 * set, this call will block until g_bit_unlock() unsets the
10446 * corresponding bit.
10448 * Attempting to lock on two different bits within the same integer is
10449 * not supported and will very probably cause deadlocks.
10451 * The value of the bit that is set is (1u << @bit). If @bit is not
10452 * between 0 and 31 then the result is undefined.
10454 * This function accesses @address atomically. All other accesses to
10455 * @address must be atomic in order for this function to work
10464 * @mask: a #gulong containing flags
10465 * @nth_bit: the index of the bit to start the search from
10467 * Find the position of the first bit set in @mask, searching
10468 * from (but not including) @nth_bit upwards. Bits are numbered
10469 * from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
10470 * usually). To start searching from the 0th bit, set @nth_bit to -1.
10472 * Returns: the index of the first bit set which is higher than @nth_bit, or -1
10473 * if no higher bits are set
10479 * @mask: a #gulong containing flags
10480 * @nth_bit: the index of the bit to start the search from
10482 * Find the position of the first bit set in @mask, searching
10483 * from (but not including) @nth_bit downwards. Bits are numbered
10484 * from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
10485 * usually). To start searching from the last bit, set @nth_bit to
10486 * -1 or GLIB_SIZEOF_LONG * 8.
10488 * Returns: the index of the first bit set which is lower than @nth_bit, or -1
10489 * if no lower bits are set
10495 * @number: a #guint
10497 * Gets the number of bits used to hold @number,
10498 * e.g. if @number is 4, 3 bits are needed.
10500 * Returns: the number of bits used to hold @number
10506 * @address: a pointer to an integer
10507 * @lock_bit: a bit value between 0 and 31
10509 * Sets the indicated @lock_bit in @address, returning %TRUE if
10510 * successful. If the bit is already set, returns %FALSE immediately.
10512 * Attempting to lock on two different bits within the same integer is
10515 * The value of the bit that is set is (1u << @bit). If @bit is not
10516 * between 0 and 31 then the result is undefined.
10518 * This function accesses @address atomically. All other accesses to
10519 * @address must be atomic in order for this function to work
10522 * Returns: %TRUE if the lock was acquired
10529 * @address: a pointer to an integer
10530 * @lock_bit: a bit value between 0 and 31
10532 * Clears the indicated @lock_bit in @address. If another thread is
10533 * currently blocked in g_bit_lock() on this same bit then it will be
10536 * This function accesses @address atomically. All other accesses to
10537 * @address must be atomic in order for this function to work
10545 * g_bookmark_file_add_application:
10546 * @bookmark: a #GBookmarkFile
10547 * @uri: a valid URI
10548 * @name: (allow-none): the name of the application registering the bookmark
10550 * @exec: (allow-none): command line to be used to launch the bookmark or %NULL
10552 * Adds the application with @name and @exec to the list of
10553 * applications that have registered a bookmark for @uri into
10556 * Every bookmark inside a #GBookmarkFile must have at least an
10557 * application registered. Each application must provide a name, a
10558 * command line useful for launching the bookmark, the number of times
10559 * the bookmark has been registered by the application and the last
10560 * time the application registered this bookmark.
10562 * If @name is %NULL, the name of the application will be the
10563 * same returned by g_get_application_name(); if @exec is %NULL, the
10564 * command line will be a composition of the program name as
10565 * returned by g_get_prgname() and the "\%u" modifier, which will be
10566 * expanded to the bookmark's URI.
10568 * This function will automatically take care of updating the
10569 * registrations count and timestamping in case an application
10570 * with the same @name had already registered a bookmark for
10571 * @uri inside @bookmark.
10573 * If no bookmark for @uri is found, one is created.
10580 * g_bookmark_file_add_group:
10581 * @bookmark: a #GBookmarkFile
10582 * @uri: a valid URI
10583 * @group: the group name to be added
10585 * Adds @group to the list of groups to which the bookmark for @uri
10588 * If no bookmark for @uri is found then it is created.
10595 * g_bookmark_file_free:
10596 * @bookmark: a #GBookmarkFile
10598 * Frees a #GBookmarkFile.
10605 * g_bookmark_file_get_added:
10606 * @bookmark: a #GBookmarkFile
10607 * @uri: a valid URI
10608 * @error: return location for a #GError, or %NULL
10610 * Gets the time the bookmark for @uri was added to @bookmark
10612 * In the event the URI cannot be found, -1 is returned and
10613 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10615 * Returns: a timestamp
10621 * g_bookmark_file_get_app_info:
10622 * @bookmark: a #GBookmarkFile
10623 * @uri: a valid URI
10624 * @name: an application's name
10625 * @exec: (allow-none) (out): return location for the command line of the application, or %NULL
10626 * @count: (allow-none) (out): return location for the registration count, or %NULL
10627 * @stamp: (allow-none) (out): return location for the last registration time, or %NULL
10628 * @error: return location for a #GError, or %NULL
10630 * Gets the registration informations of @app_name for the bookmark for
10631 * @uri. See g_bookmark_file_set_app_info() for more informations about
10632 * the returned data.
10634 * The string returned in @app_exec must be freed.
10636 * In the event the URI cannot be found, %FALSE is returned and
10637 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
10638 * event that no application with name @app_name has registered a bookmark
10639 * for @uri, %FALSE is returned and error is set to
10640 * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting
10641 * the command line fails, an error of the #G_SHELL_ERROR domain is
10642 * set and %FALSE is returned.
10644 * Returns: %TRUE on success.
10650 * g_bookmark_file_get_applications:
10651 * @bookmark: a #GBookmarkFile
10652 * @uri: a valid URI
10653 * @length: (allow-none) (out): return location of the length of the returned list, or %NULL
10654 * @error: return location for a #GError, or %NULL
10656 * Retrieves the names of the applications that have registered the
10657 * bookmark for @uri.
10659 * In the event the URI cannot be found, %NULL is returned and
10660 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10662 * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings.
10663 * Use g_strfreev() to free it.
10669 * g_bookmark_file_get_description:
10670 * @bookmark: a #GBookmarkFile
10671 * @uri: a valid URI
10672 * @error: return location for a #GError, or %NULL
10674 * Retrieves the description of the bookmark for @uri.
10676 * In the event the URI cannot be found, %NULL is returned and
10677 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10679 * Returns: a newly allocated string or %NULL if the specified
10680 * URI cannot be found.
10686 * g_bookmark_file_get_groups:
10687 * @bookmark: a #GBookmarkFile
10688 * @uri: a valid URI
10689 * @length: (allow-none) (out): return location for the length of the returned string, or %NULL
10690 * @error: return location for a #GError, or %NULL
10692 * Retrieves the list of group names of the bookmark for @uri.
10694 * In the event the URI cannot be found, %NULL is returned and
10695 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10697 * The returned array is %NULL terminated, so @length may optionally
10700 * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of group names.
10701 * Use g_strfreev() to free it.
10707 * g_bookmark_file_get_icon:
10708 * @bookmark: a #GBookmarkFile
10709 * @uri: a valid URI
10710 * @href: (allow-none) (out): return location for the icon's location or %NULL
10711 * @mime_type: (allow-none) (out): return location for the icon's MIME type or %NULL
10712 * @error: return location for a #GError or %NULL
10714 * Gets the icon of the bookmark for @uri.
10716 * In the event the URI cannot be found, %FALSE is returned and
10717 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10719 * Returns: %TRUE if the icon for the bookmark for the URI was found.
10720 * You should free the returned strings.
10726 * g_bookmark_file_get_is_private:
10727 * @bookmark: a #GBookmarkFile
10728 * @uri: a valid URI
10729 * @error: return location for a #GError, or %NULL
10731 * Gets whether the private flag of the bookmark for @uri is set.
10733 * In the event the URI cannot be found, %FALSE is returned and
10734 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
10735 * event that the private flag cannot be found, %FALSE is returned and
10736 * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
10738 * Returns: %TRUE if the private flag is set, %FALSE otherwise.
10744 * g_bookmark_file_get_mime_type:
10745 * @bookmark: a #GBookmarkFile
10746 * @uri: a valid URI
10747 * @error: return location for a #GError, or %NULL
10749 * Retrieves the MIME type of the resource pointed by @uri.
10751 * In the event the URI cannot be found, %NULL is returned and
10752 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
10753 * event that the MIME type cannot be found, %NULL is returned and
10754 * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
10756 * Returns: a newly allocated string or %NULL if the specified
10757 * URI cannot be found.
10763 * g_bookmark_file_get_modified:
10764 * @bookmark: a #GBookmarkFile
10765 * @uri: a valid URI
10766 * @error: return location for a #GError, or %NULL
10768 * Gets the time when the bookmark for @uri was last modified.
10770 * In the event the URI cannot be found, -1 is returned and
10771 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10773 * Returns: a timestamp
10779 * g_bookmark_file_get_size:
10780 * @bookmark: a #GBookmarkFile
10782 * Gets the number of bookmarks inside @bookmark.
10784 * Returns: the number of bookmarks
10790 * g_bookmark_file_get_title:
10791 * @bookmark: a #GBookmarkFile
10792 * @uri: (allow-none): a valid URI or %NULL
10793 * @error: return location for a #GError, or %NULL
10795 * Returns the title of the bookmark for @uri.
10797 * If @uri is %NULL, the title of @bookmark is returned.
10799 * In the event the URI cannot be found, %NULL is returned and
10800 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10802 * Returns: a newly allocated string or %NULL if the specified
10803 * URI cannot be found.
10809 * g_bookmark_file_get_uris:
10810 * @bookmark: a #GBookmarkFile
10811 * @length: (allow-none) (out): return location for the number of returned URIs, or %NULL
10813 * Returns all URIs of the bookmarks in the bookmark file @bookmark.
10814 * The array of returned URIs will be %NULL-terminated, so @length may
10815 * optionally be %NULL.
10817 * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings.
10818 * Use g_strfreev() to free it.
10824 * g_bookmark_file_get_visited:
10825 * @bookmark: a #GBookmarkFile
10826 * @uri: a valid URI
10827 * @error: return location for a #GError, or %NULL
10829 * Gets the time the bookmark for @uri was last visited.
10831 * In the event the URI cannot be found, -1 is returned and
10832 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10834 * Returns: a timestamp.
10840 * g_bookmark_file_has_application:
10841 * @bookmark: a #GBookmarkFile
10842 * @uri: a valid URI
10843 * @name: the name of the application
10844 * @error: return location for a #GError or %NULL
10846 * Checks whether the bookmark for @uri inside @bookmark has been
10847 * registered by application @name.
10849 * In the event the URI cannot be found, %FALSE is returned and
10850 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10852 * Returns: %TRUE if the application @name was found
10858 * g_bookmark_file_has_group:
10859 * @bookmark: a #GBookmarkFile
10860 * @uri: a valid URI
10861 * @group: the group name to be searched
10862 * @error: return location for a #GError, or %NULL
10864 * Checks whether @group appears in the list of groups to which
10865 * the bookmark for @uri belongs to.
10867 * In the event the URI cannot be found, %FALSE is returned and
10868 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10870 * Returns: %TRUE if @group was found.
10876 * g_bookmark_file_has_item:
10877 * @bookmark: a #GBookmarkFile
10878 * @uri: a valid URI
10880 * Looks whether the desktop bookmark has an item with its URI set to @uri.
10882 * Returns: %TRUE if @uri is inside @bookmark, %FALSE otherwise
10888 * g_bookmark_file_load_from_data:
10889 * @bookmark: an empty #GBookmarkFile struct
10890 * @data: desktop bookmarks loaded in memory
10891 * @length: the length of @data in bytes
10892 * @error: return location for a #GError, or %NULL
10894 * Loads a bookmark file from memory into an empty #GBookmarkFile
10895 * structure. If the object cannot be created then @error is set to a
10896 * #GBookmarkFileError.
10898 * Returns: %TRUE if a desktop bookmark could be loaded.
10904 * g_bookmark_file_load_from_data_dirs:
10905 * @bookmark: a #GBookmarkFile
10906 * @file: (type filename): a relative path to a filename to open and parse
10907 * @full_path: (type filename) (allow-none): return location for a string
10908 * containing the full path of the file, or %NULL
10909 * @error: return location for a #GError, or %NULL
10911 * This function looks for a desktop bookmark file named @file in the
10912 * paths returned from g_get_user_data_dir() and g_get_system_data_dirs(),
10913 * loads the file into @bookmark and returns the file's full path in
10914 * @full_path. If the file could not be loaded then an %error is
10915 * set to either a #GFileError or #GBookmarkFileError.
10917 * Returns: %TRUE if a key file could be loaded, %FALSE otherwise
10923 * g_bookmark_file_load_from_file:
10924 * @bookmark: an empty #GBookmarkFile struct
10925 * @filename: (type filename): the path of a filename to load, in the
10926 * GLib file name encoding
10927 * @error: return location for a #GError, or %NULL
10929 * Loads a desktop bookmark file into an empty #GBookmarkFile structure.
10930 * If the file could not be loaded then @error is set to either a #GFileError
10931 * or #GBookmarkFileError.
10933 * Returns: %TRUE if a desktop bookmark file could be loaded
10939 * g_bookmark_file_move_item:
10940 * @bookmark: a #GBookmarkFile
10941 * @old_uri: a valid URI
10942 * @new_uri: (allow-none): a valid URI, or %NULL
10943 * @error: return location for a #GError or %NULL
10945 * Changes the URI of a bookmark item from @old_uri to @new_uri. Any
10946 * existing bookmark for @new_uri will be overwritten. If @new_uri is
10947 * %NULL, then the bookmark is removed.
10949 * In the event the URI cannot be found, %FALSE is returned and
10950 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10952 * Returns: %TRUE if the URI was successfully changed
10958 * g_bookmark_file_new:
10960 * Creates a new empty #GBookmarkFile object.
10962 * Use g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data()
10963 * or g_bookmark_file_load_from_data_dirs() to read an existing bookmark
10966 * Returns: an empty #GBookmarkFile
10972 * g_bookmark_file_remove_application:
10973 * @bookmark: a #GBookmarkFile
10974 * @uri: a valid URI
10975 * @name: the name of the application
10976 * @error: return location for a #GError or %NULL
10978 * Removes application registered with @name from the list of applications
10979 * that have registered a bookmark for @uri inside @bookmark.
10981 * In the event the URI cannot be found, %FALSE is returned and
10982 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
10983 * In the event that no application with name @app_name has registered
10984 * a bookmark for @uri, %FALSE is returned and error is set to
10985 * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED.
10987 * Returns: %TRUE if the application was successfully removed.
10993 * g_bookmark_file_remove_group:
10994 * @bookmark: a #GBookmarkFile
10995 * @uri: a valid URI
10996 * @group: the group name to be removed
10997 * @error: return location for a #GError, or %NULL
10999 * Removes @group from the list of groups to which the bookmark
11000 * for @uri belongs to.
11002 * In the event the URI cannot be found, %FALSE is returned and
11003 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
11004 * In the event no group was defined, %FALSE is returned and
11005 * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
11007 * Returns: %TRUE if @group was successfully removed.
11013 * g_bookmark_file_remove_item:
11014 * @bookmark: a #GBookmarkFile
11015 * @uri: a valid URI
11016 * @error: return location for a #GError, or %NULL
11018 * Removes the bookmark for @uri from the bookmark file @bookmark.
11020 * Returns: %TRUE if the bookmark was removed successfully.
11026 * g_bookmark_file_set_added:
11027 * @bookmark: a #GBookmarkFile
11028 * @uri: a valid URI
11029 * @added: a timestamp or -1 to use the current time
11031 * Sets the time the bookmark for @uri was added into @bookmark.
11033 * If no bookmark for @uri is found then it is created.
11040 * g_bookmark_file_set_app_info:
11041 * @bookmark: a #GBookmarkFile
11042 * @uri: a valid URI
11043 * @name: an application's name
11044 * @exec: an application's command line
11045 * @count: the number of registrations done for this application
11046 * @stamp: the time of the last registration for this application
11047 * @error: return location for a #GError or %NULL
11049 * Sets the meta-data of application @name inside the list of
11050 * applications that have registered a bookmark for @uri inside
11053 * You should rarely use this function; use g_bookmark_file_add_application()
11054 * and g_bookmark_file_remove_application() instead.
11056 * @name can be any UTF-8 encoded string used to identify an
11058 * @exec can have one of these two modifiers: "\%f", which will
11059 * be expanded as the local file name retrieved from the bookmark's
11060 * URI; "\%u", which will be expanded as the bookmark's URI.
11061 * The expansion is done automatically when retrieving the stored
11062 * command line using the g_bookmark_file_get_app_info() function.
11063 * @count is the number of times the application has registered the
11064 * bookmark; if is < 0, the current registration count will be increased
11065 * by one, if is 0, the application with @name will be removed from
11066 * the list of registered applications.
11067 * @stamp is the Unix time of the last registration; if it is -1, the
11068 * current time will be used.
11070 * If you try to remove an application by setting its registration count to
11071 * zero, and no bookmark for @uri is found, %FALSE is returned and
11072 * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly,
11073 * in the event that no application @name has registered a bookmark
11074 * for @uri, %FALSE is returned and error is set to
11075 * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark
11076 * for @uri is found, one is created.
11078 * Returns: %TRUE if the application's meta-data was successfully
11085 * g_bookmark_file_set_description:
11086 * @bookmark: a #GBookmarkFile
11087 * @uri: (allow-none): a valid URI or %NULL
11088 * @description: a string
11090 * Sets @description as the description of the bookmark for @uri.
11092 * If @uri is %NULL, the description of @bookmark is set.
11094 * If a bookmark for @uri cannot be found then it is created.
11101 * g_bookmark_file_set_groups:
11102 * @bookmark: a #GBookmarkFile
11103 * @uri: an item's URI
11104 * @groups: (allow-none): an array of group names, or %NULL to remove all groups
11105 * @length: number of group name values in @groups
11107 * Sets a list of group names for the item with URI @uri. Each previously
11108 * set group name list is removed.
11110 * If @uri cannot be found then an item for it is created.
11117 * g_bookmark_file_set_icon:
11118 * @bookmark: a #GBookmarkFile
11119 * @uri: a valid URI
11120 * @href: (allow-none): the URI of the icon for the bookmark, or %NULL
11121 * @mime_type: the MIME type of the icon for the bookmark
11123 * Sets the icon for the bookmark for @uri. If @href is %NULL, unsets
11124 * the currently set icon. @href can either be a full URL for the icon
11125 * file or the icon name following the Icon Naming specification.
11127 * If no bookmark for @uri is found one is created.
11134 * g_bookmark_file_set_is_private:
11135 * @bookmark: a #GBookmarkFile
11136 * @uri: a valid URI
11137 * @is_private: %TRUE if the bookmark should be marked as private
11139 * Sets the private flag of the bookmark for @uri.
11141 * If a bookmark for @uri cannot be found then it is created.
11148 * g_bookmark_file_set_mime_type:
11149 * @bookmark: a #GBookmarkFile
11150 * @uri: a valid URI
11151 * @mime_type: a MIME type
11153 * Sets @mime_type as the MIME type of the bookmark for @uri.
11155 * If a bookmark for @uri cannot be found then it is created.
11162 * g_bookmark_file_set_modified:
11163 * @bookmark: a #GBookmarkFile
11164 * @uri: a valid URI
11165 * @modified: a timestamp or -1 to use the current time
11167 * Sets the last time the bookmark for @uri was last modified.
11169 * If no bookmark for @uri is found then it is created.
11171 * The "modified" time should only be set when the bookmark's meta-data
11172 * was actually changed. Every function of #GBookmarkFile that
11173 * modifies a bookmark also changes the modification time, except for
11174 * g_bookmark_file_set_visited().
11181 * g_bookmark_file_set_title:
11182 * @bookmark: a #GBookmarkFile
11183 * @uri: (allow-none): a valid URI or %NULL
11184 * @title: a UTF-8 encoded string
11186 * Sets @title as the title of the bookmark for @uri inside the
11187 * bookmark file @bookmark.
11189 * If @uri is %NULL, the title of @bookmark is set.
11191 * If a bookmark for @uri cannot be found then it is created.
11198 * g_bookmark_file_set_visited:
11199 * @bookmark: a #GBookmarkFile
11200 * @uri: a valid URI
11201 * @visited: a timestamp or -1 to use the current time
11203 * Sets the time the bookmark for @uri was last visited.
11205 * If no bookmark for @uri is found then it is created.
11207 * The "visited" time should only be set if the bookmark was launched,
11208 * either using the command line retrieved by g_bookmark_file_get_app_info()
11209 * or by the default application for the bookmark's MIME type, retrieved
11210 * using g_bookmark_file_get_mime_type(). Changing the "visited" time
11211 * does not affect the "modified" time.
11218 * g_bookmark_file_to_data:
11219 * @bookmark: a #GBookmarkFile
11220 * @length: (allow-none) (out): return location for the length of the returned string, or %NULL
11221 * @error: return location for a #GError, or %NULL
11223 * This function outputs @bookmark as a string.
11225 * Returns: a newly allocated string holding
11226 * the contents of the #GBookmarkFile
11232 * g_bookmark_file_to_file:
11233 * @bookmark: a #GBookmarkFile
11234 * @filename: (type filename): path of the output file
11235 * @error: return location for a #GError, or %NULL
11237 * This function outputs @bookmark into a file. The write process is
11238 * guaranteed to be atomic by using g_file_set_contents() internally.
11240 * Returns: %TRUE if the file was successfully written.
11246 * g_build_filename:
11247 * @first_element: (type filename): the first element in the path
11248 * @...: remaining elements in path, terminated by %NULL
11250 * Creates a filename from a series of elements using the correct
11251 * separator for filenames.
11253 * On Unix, this function behaves identically to `g_build_path
11254 * (G_DIR_SEPARATOR_S, first_element, ....)`.
11256 * On Windows, it takes into account that either the backslash
11257 * (`\` or slash (`/`) can be used as separator in filenames, but
11258 * otherwise behaves as on UNIX. When file pathname separators need
11259 * to be inserted, the one that last previously occurred in the
11260 * parameters (reading from left to right) is used.
11262 * No attempt is made to force the resulting filename to be an absolute
11263 * path. If the first element is a relative path, the result will
11264 * be a relative path.
11266 * Returns: (type filename): a newly-allocated string that must be freed with
11272 * g_build_filenamev:
11273 * @args: (array zero-terminated=1) (element-type filename): %NULL-terminated
11274 * array of strings containing the path elements.
11276 * Behaves exactly like g_build_filename(), but takes the path elements
11277 * as a string array, instead of varargs. This function is mainly
11278 * meant for language bindings.
11280 * Returns: (type filename): a newly-allocated string that must be freed
11288 * @separator: (type filename): a string used to separator the elements of the path.
11289 * @first_element: (type filename): the first element in the path
11290 * @...: remaining elements in path, terminated by %NULL
11292 * Creates a path from a series of elements using @separator as the
11293 * separator between elements. At the boundary between two elements,
11294 * any trailing occurrences of separator in the first element, or
11295 * leading occurrences of separator in the second element are removed
11296 * and exactly one copy of the separator is inserted.
11298 * Empty elements are ignored.
11300 * The number of leading copies of the separator on the result is
11301 * the same as the number of leading copies of the separator on
11302 * the first non-empty element.
11304 * The number of trailing copies of the separator on the result is
11305 * the same as the number of trailing copies of the separator on
11306 * the last non-empty element. (Determination of the number of
11307 * trailing copies is done without stripping leading copies, so
11308 * if the separator is `ABA`, then `ABABA` has 1 trailing copy.)
11310 * However, if there is only a single non-empty element, and there
11311 * are no characters in that element not part of the leading or
11312 * trailing separators, then the result is exactly the original value
11315 * Other than for determination of the number of leading and trailing
11316 * copies of the separator, elements consisting only of copies
11317 * of the separator are ignored.
11319 * Returns: (type filename): a newly-allocated string that must be freed with
11326 * @separator: a string used to separator the elements of the path.
11327 * @args: (array zero-terminated=1) (element-type filename): %NULL-terminated
11328 * array of strings containing the path elements.
11330 * Behaves exactly like g_build_path(), but takes the path elements
11331 * as a string array, instead of varargs. This function is mainly
11332 * meant for language bindings.
11334 * Returns: (type filename): a newly-allocated string that must be freed
11341 * g_byte_array_append:
11342 * @array: a #GByteArray
11343 * @data: the byte data to be added
11344 * @len: the number of bytes to add
11346 * Adds the given bytes to the end of the #GByteArray.
11347 * The array will grow in size automatically if necessary.
11349 * Returns: the #GByteArray
11354 * g_byte_array_free:
11355 * @array: a #GByteArray
11356 * @free_segment: if %TRUE the actual byte data is freed as well
11358 * Frees the memory allocated by the #GByteArray. If @free_segment is
11359 * %TRUE it frees the actual byte data. If the reference count of
11360 * @array is greater than one, the #GByteArray wrapper is preserved but
11361 * the size of @array will be set to zero.
11363 * Returns: the element data if @free_segment is %FALSE, otherwise
11364 * %NULL. The element data should be freed using g_free().
11369 * g_byte_array_free_to_bytes:
11370 * @array: (transfer full): a #GByteArray
11372 * Transfers the data from the #GByteArray into a new immutable #GBytes.
11374 * The #GByteArray is freed unless the reference count of @array is greater
11375 * than one, the #GByteArray wrapper is preserved but the size of @array
11376 * will be set to zero.
11378 * This is identical to using g_bytes_new_take() and g_byte_array_free()
11382 * Returns: (transfer full): a new immutable #GBytes representing same
11383 * byte data that was in the array
11388 * g_byte_array_new:
11390 * Creates a new #GByteArray with a reference count of 1.
11392 * Returns: (transfer full): the new #GByteArray
11397 * g_byte_array_new_take:
11398 * @data: (transfer full) (array length=len): byte data for the array
11399 * @len: length of @data
11401 * Create byte array containing the data. The data will be owned by the array
11402 * and will be freed with g_free(), i.e. it could be allocated using g_strdup().
11405 * Returns: (transfer full): a new #GByteArray
11410 * g_byte_array_prepend:
11411 * @array: a #GByteArray
11412 * @data: the byte data to be added
11413 * @len: the number of bytes to add
11415 * Adds the given data to the start of the #GByteArray.
11416 * The array will grow in size automatically if necessary.
11418 * Returns: the #GByteArray
11423 * g_byte_array_ref:
11424 * @array: A #GByteArray
11426 * Atomically increments the reference count of @array by one.
11427 * This function is thread-safe and may be called from any thread.
11429 * Returns: The passed in #GByteArray
11435 * g_byte_array_remove_index:
11436 * @array: a #GByteArray
11437 * @index_: the index of the byte to remove
11439 * Removes the byte at the given index from a #GByteArray.
11440 * The following bytes are moved down one place.
11442 * Returns: the #GByteArray
11447 * g_byte_array_remove_index_fast:
11448 * @array: a #GByteArray
11449 * @index_: the index of the byte to remove
11451 * Removes the byte at the given index from a #GByteArray. The last
11452 * element in the array is used to fill in the space, so this function
11453 * does not preserve the order of the #GByteArray. But it is faster
11454 * than g_byte_array_remove_index().
11456 * Returns: the #GByteArray
11461 * g_byte_array_remove_range:
11462 * @array: a @GByteArray
11463 * @index_: the index of the first byte to remove
11464 * @length: the number of bytes to remove
11466 * Removes the given number of bytes starting at the given index from a
11467 * #GByteArray. The following elements are moved to close the gap.
11469 * Returns: the #GByteArray
11475 * g_byte_array_set_size:
11476 * @array: a #GByteArray
11477 * @length: the new size of the #GByteArray
11479 * Sets the size of the #GByteArray, expanding it if necessary.
11481 * Returns: the #GByteArray
11486 * g_byte_array_sized_new:
11487 * @reserved_size: number of bytes preallocated
11489 * Creates a new #GByteArray with @reserved_size bytes preallocated.
11490 * This avoids frequent reallocation, if you are going to add many
11491 * bytes to the array. Note however that the size of the array is still
11494 * Returns: the new #GByteArray
11499 * g_byte_array_sort:
11500 * @array: a #GByteArray
11501 * @compare_func: comparison function
11503 * Sorts a byte array, using @compare_func which should be a
11504 * qsort()-style comparison function (returns less than zero for first
11505 * arg is less than second arg, zero for equal, greater than zero if
11506 * first arg is greater than second arg).
11508 * If two array elements compare equal, their order in the sorted array
11509 * is undefined. If you want equal elements to keep their order (i.e.
11510 * you want a stable sort) you can write a comparison function that,
11511 * if two elements would otherwise compare equal, compares them by
11517 * g_byte_array_sort_with_data:
11518 * @array: a #GByteArray
11519 * @compare_func: comparison function
11520 * @user_data: data to pass to @compare_func
11522 * Like g_byte_array_sort(), but the comparison function takes an extra
11523 * user data argument.
11528 * g_byte_array_unref:
11529 * @array: A #GByteArray
11531 * Atomically decrements the reference count of @array by one. If the
11532 * reference count drops to 0, all memory allocated by the array is
11533 * released. This function is thread-safe and may be called from any
11542 * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
11543 * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
11545 * Compares the two #GBytes values.
11547 * This function can be used to sort GBytes instances in lexographical order.
11549 * Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is
11550 * greater, and zero if bytes2 is equal to bytes1
11557 * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
11558 * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
11560 * Compares the two #GBytes values being pointed to and returns
11561 * %TRUE if they are equal.
11563 * This function can be passed to g_hash_table_new() as the @key_equal_func
11564 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
11566 * Returns: %TRUE if the two keys match.
11572 * g_bytes_get_data:
11573 * @bytes: a #GBytes
11574 * @size: (out) (optional): location to return size of byte data
11576 * Get the byte data in the #GBytes. This data should not be modified.
11578 * This function will always return the same pointer for a given #GBytes.
11580 * %NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes
11581 * may represent an empty string with @data non-%NULL and @size as 0. %NULL will
11582 * not be returned if @size is non-zero.
11584 * Returns: (transfer none) (array length=size) (element-type guint8) (nullable):
11585 * a pointer to the byte data, or %NULL
11591 * g_bytes_get_size:
11592 * @bytes: a #GBytes
11594 * Get the size of the byte data in the #GBytes.
11596 * This function will always return the same value for a given #GBytes.
11598 * Returns: the size
11605 * @bytes: (type GLib.Bytes): a pointer to a #GBytes key
11607 * Creates an integer hash code for the byte data in the #GBytes.
11609 * This function can be passed to g_hash_table_new() as the @key_hash_func
11610 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
11612 * Returns: a hash value corresponding to the key.
11619 * @data: (transfer none) (array length=size) (element-type guint8) (nullable):
11620 * the data to be used for the bytes
11621 * @size: the size of @data
11623 * Creates a new #GBytes from @data.
11625 * @data is copied. If @size is 0, @data may be %NULL.
11627 * Returns: (transfer full): a new #GBytes
11633 * g_bytes_new_from_bytes:
11634 * @bytes: a #GBytes
11635 * @offset: offset which subsection starts at
11636 * @length: length of subsection
11638 * Creates a #GBytes which is a subsection of another #GBytes. The @offset +
11639 * @length may not be longer than the size of @bytes.
11641 * A reference to @bytes will be held by the newly created #GBytes until
11642 * the byte data is no longer needed.
11644 * Returns: (transfer full): a new #GBytes
11650 * g_bytes_new_static: (skip)
11651 * @data: (transfer full) (array length=size) (element-type guint8) (nullable):
11652 * the data to be used for the bytes
11653 * @size: the size of @data
11655 * Creates a new #GBytes from static data.
11657 * @data must be static (ie: never modified or freed). It may be %NULL if @size
11660 * Returns: (transfer full): a new #GBytes
11666 * g_bytes_new_take:
11667 * @data: (transfer full) (array length=size) (element-type guint8) (nullable):
11668 * the data to be used for the bytes
11669 * @size: the size of @data
11671 * Creates a new #GBytes from @data.
11673 * After this call, @data belongs to the bytes and may no longer be
11674 * modified by the caller. g_free() will be called on @data when the
11675 * bytes is no longer in use. Because of this @data must have been created by
11676 * a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many
11677 * functions that wrap these calls (such as g_new(), g_strdup(), etc).
11679 * For creating #GBytes with memory from other allocators, see
11680 * g_bytes_new_with_free_func().
11682 * @data may be %NULL if @size is 0.
11684 * Returns: (transfer full): a new #GBytes
11690 * g_bytes_new_with_free_func: (skip)
11691 * @data: (array length=size) (element-type guint8) (nullable):
11692 * the data to be used for the bytes
11693 * @size: the size of @data
11694 * @free_func: the function to call to release the data
11695 * @user_data: data to pass to @free_func
11697 * Creates a #GBytes from @data.
11699 * When the last reference is dropped, @free_func will be called with the
11700 * @user_data argument.
11702 * @data must not be modified after this call is made until @free_func has
11703 * been called to indicate that the bytes is no longer in use.
11705 * @data may be %NULL if @size is 0.
11707 * Returns: (transfer full): a new #GBytes
11714 * @bytes: a #GBytes
11716 * Increase the reference count on @bytes.
11718 * Returns: the #GBytes
11725 * @bytes: (nullable): a #GBytes
11727 * Releases a reference on @bytes. This may result in the bytes being
11735 * g_bytes_unref_to_array:
11736 * @bytes: (transfer full): a #GBytes
11738 * Unreferences the bytes, and returns a new mutable #GByteArray containing
11739 * the same byte data.
11741 * As an optimization, the byte data is transferred to the array without copying
11742 * if this was the last reference to bytes and bytes was created with
11743 * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all
11744 * other cases the data is copied.
11746 * Returns: (transfer full): a new mutable #GByteArray containing the same byte data
11752 * g_bytes_unref_to_data:
11753 * @bytes: (transfer full): a #GBytes
11754 * @size: (out): location to place the length of the returned data
11756 * Unreferences the bytes, and returns a pointer the same byte data
11759 * As an optimization, the byte data is returned without copying if this was
11760 * the last reference to bytes and bytes was created with g_bytes_new(),
11761 * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
11764 * Returns: (transfer full) (array length=size) (element-type guint8) (not nullable): a pointer to the same byte data, which should be
11765 * freed with g_free()
11772 * @path: (type filename): a pathname in the GLib file name encoding
11773 * (UTF-8 on Windows)
11775 * A wrapper for the POSIX chdir() function. The function changes the
11776 * current directory of the process to @path.
11778 * See your C library manual for more details about chdir().
11780 * Returns: 0 on success, -1 if an error occurred.
11787 * @checksum: the #GChecksum to copy
11789 * Copies a #GChecksum. If @checksum has been closed, by calling
11790 * g_checksum_get_string() or g_checksum_get_digest(), the copied
11791 * checksum will be closed as well.
11793 * Returns: the copy of the passed #GChecksum. Use g_checksum_free()
11794 * when finished using it.
11801 * @checksum: a #GChecksum
11803 * Frees the memory allocated for @checksum.
11810 * g_checksum_get_digest: (skip)
11811 * @checksum: a #GChecksum
11812 * @buffer: output buffer
11813 * @digest_len: an inout parameter. The caller initializes it to the size of @buffer.
11814 * After the call it contains the length of the digest.
11816 * Gets the digest from @checksum as a raw binary vector and places it
11817 * into @buffer. The size of the digest depends on the type of checksum.
11819 * Once this function has been called, the #GChecksum is closed and can
11820 * no longer be updated with g_checksum_update().
11827 * g_checksum_get_string:
11828 * @checksum: a #GChecksum
11830 * Gets the digest as an hexadecimal string.
11832 * Once this function has been called the #GChecksum can no longer be
11833 * updated with g_checksum_update().
11835 * The hexadecimal characters will be lower case.
11837 * Returns: the hexadecimal representation of the checksum. The
11838 * returned string is owned by the checksum and should not be modified
11846 * @checksum_type: the desired type of checksum
11848 * Creates a new #GChecksum, using the checksum algorithm @checksum_type.
11849 * If the @checksum_type is not known, %NULL is returned.
11850 * A #GChecksum can be used to compute the checksum, or digest, of an
11851 * arbitrary binary blob, using different hashing algorithms.
11853 * A #GChecksum works by feeding a binary blob through g_checksum_update()
11854 * until there is data to be checked; the digest can then be extracted
11855 * using g_checksum_get_string(), which will return the checksum as a
11856 * hexadecimal string; or g_checksum_get_digest(), which will return a
11857 * vector of raw bytes. Once either g_checksum_get_string() or
11858 * g_checksum_get_digest() have been called on a #GChecksum, the checksum
11859 * will be closed and it won't be possible to call g_checksum_update()
11862 * Returns: (transfer full): the newly created #GChecksum, or %NULL.
11863 * Use g_checksum_free() to free the memory allocated by it.
11869 * g_checksum_reset:
11870 * @checksum: the #GChecksum to reset
11872 * Resets the state of the @checksum back to its initial state.
11879 * g_checksum_type_get_length:
11880 * @checksum_type: a #GChecksumType
11882 * Gets the length in bytes of digests of type @checksum_type
11884 * Returns: the checksum length, or -1 if @checksum_type is
11891 * g_checksum_update:
11892 * @checksum: a #GChecksum
11893 * @data: (array length=length) (element-type guint8): buffer used to compute the checksum
11894 * @length: size of the buffer, or -1 if it is a null-terminated string.
11896 * Feeds @data into an existing #GChecksum. The checksum must still be
11897 * open, that is g_checksum_get_string() or g_checksum_get_digest() must
11898 * not have been called on @checksum.
11905 * g_child_watch_add:
11906 * @pid: process id to watch. On POSIX the positive pid of a child
11907 * process. On Windows a handle for a process (which doesn't have to be
11909 * @function: function to call
11910 * @data: data to pass to @function
11912 * Sets a function to be called when the child indicated by @pid
11913 * exits, at a default priority, #G_PRIORITY_DEFAULT.
11915 * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes()
11916 * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to
11917 * the spawn function for the child watching to work.
11919 * Note that on platforms where #GPid must be explicitly closed
11920 * (see g_spawn_close_pid()) @pid must not be closed while the
11921 * source is still active. Typically, you will want to call
11922 * g_spawn_close_pid() in the callback function for the source.
11924 * GLib supports only a single callback per process id.
11926 * This internally creates a main loop source using
11927 * g_child_watch_source_new() and attaches it to the main loop context
11928 * using g_source_attach(). You can do these steps manually if you
11929 * need greater control.
11931 * Returns: the ID (greater than 0) of the event source.
11937 * g_child_watch_add_full: (rename-to g_child_watch_add)
11938 * @priority: the priority of the idle source. Typically this will be in the
11939 * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
11940 * @pid: process to watch. On POSIX the positive pid of a child process. On
11941 * Windows a handle for a process (which doesn't have to be a child).
11942 * @function: function to call
11943 * @data: data to pass to @function
11944 * @notify: (allow-none): function to call when the idle is removed, or %NULL
11946 * Sets a function to be called when the child indicated by @pid
11947 * exits, at the priority @priority.
11949 * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes()
11950 * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to
11951 * the spawn function for the child watching to work.
11953 * In many programs, you will want to call g_spawn_check_exit_status()
11954 * in the callback to determine whether or not the child exited
11957 * Also, note that on platforms where #GPid must be explicitly closed
11958 * (see g_spawn_close_pid()) @pid must not be closed while the source
11959 * is still active. Typically, you should invoke g_spawn_close_pid()
11960 * in the callback function for the source.
11962 * GLib supports only a single callback per process id.
11964 * This internally creates a main loop source using
11965 * g_child_watch_source_new() and attaches it to the main loop context
11966 * using g_source_attach(). You can do these steps manually if you
11967 * need greater control.
11969 * Returns: the ID (greater than 0) of the event source.
11975 * g_child_watch_source_new:
11976 * @pid: process to watch. On POSIX the positive pid of a child process. On
11977 * Windows a handle for a process (which doesn't have to be a child).
11979 * Creates a new child_watch source.
11981 * The source will not initially be associated with any #GMainContext
11982 * and must be added to one with g_source_attach() before it will be
11985 * Note that child watch sources can only be used in conjunction with
11986 * `g_spawn...` when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used.
11988 * Note that on platforms where #GPid must be explicitly closed
11989 * (see g_spawn_close_pid()) @pid must not be closed while the
11990 * source is still active. Typically, you will want to call
11991 * g_spawn_close_pid() in the callback function for the source.
11993 * Note further that using g_child_watch_source_new() is not
11994 * compatible with calling `waitpid` with a nonpositive first
11995 * argument in the application. Calling waitpid() for individual
11996 * pids will still work fine.
11998 * Similarly, on POSIX platforms, the @pid passed to this function must
11999 * be greater than 0 (i.e. this function must wait for a specific child,
12000 * and cannot wait for one of many children by using a nonpositive argument).
12002 * Returns: the newly-created child watch source
12009 * @filename: (type filename): a pathname in the GLib file name encoding
12010 * (UTF-8 on Windows)
12011 * @mode: as in chmod()
12013 * A wrapper for the POSIX chmod() function. The chmod() function is
12014 * used to set the permissions of a file system object.
12016 * On Windows the file protection mechanism is not at all POSIX-like,
12017 * and the underlying chmod() function in the C library just sets or
12018 * clears the FAT-style READONLY attribute. It does not touch any
12019 * ACL. Software that needs to manage file permissions on Windows
12020 * exactly should use the Win32 API.
12022 * See your C library manual for more details about chmod().
12024 * Returns: 0 if the operation succeeded, -1 on error
12031 * @err: a #GError return location
12033 * If @err or *@err is %NULL, does nothing. Otherwise,
12034 * calls g_error_free() on *@err and sets *@err to %NULL.
12039 * g_clear_pointer: (skip)
12040 * @pp: (not nullable): a pointer to a variable, struct member etc. holding a
12042 * @destroy: a function to which a gpointer can be passed, to destroy *@pp
12044 * Clears a reference to a variable.
12046 * @pp must not be %NULL.
12048 * If the reference is %NULL then this function does nothing.
12049 * Otherwise, the variable is destroyed using @destroy and the
12050 * pointer is set to %NULL.
12052 * A macro is also included that allows this function to be used without
12061 * @fd: A file descriptor
12062 * @error: a #GError
12064 * This wraps the close() call; in case of error, %errno will be
12065 * preserved, but the error will also be stored as a #GError in @error.
12067 * Besides using #GError, there is another major reason to prefer this
12068 * function over the call provided by the system; on Unix, it will
12069 * attempt to correctly handle %EINTR, which has platform-specific
12072 * Returns: %TRUE on success, %FALSE if there was an error.
12078 * g_compute_checksum_for_bytes:
12079 * @checksum_type: a #GChecksumType
12080 * @data: binary blob to compute the digest of
12082 * Computes the checksum for a binary @data. This is a
12083 * convenience wrapper for g_checksum_new(), g_checksum_get_string()
12084 * and g_checksum_free().
12086 * The hexadecimal string returned will be in lower case.
12088 * Returns: the digest of the binary data as a string in hexadecimal.
12089 * The returned string should be freed with g_free() when done using it.
12095 * g_compute_checksum_for_data:
12096 * @checksum_type: a #GChecksumType
12097 * @data: (array length=length) (element-type guint8): binary blob to compute the digest of
12098 * @length: length of @data
12100 * Computes the checksum for a binary @data of @length. This is a
12101 * convenience wrapper for g_checksum_new(), g_checksum_get_string()
12102 * and g_checksum_free().
12104 * The hexadecimal string returned will be in lower case.
12106 * Returns: the digest of the binary data as a string in hexadecimal.
12107 * The returned string should be freed with g_free() when done using it.
12113 * g_compute_checksum_for_string:
12114 * @checksum_type: a #GChecksumType
12115 * @str: the string to compute the checksum of
12116 * @length: the length of the string, or -1 if the string is null-terminated.
12118 * Computes the checksum of a string.
12120 * The hexadecimal string returned will be in lower case.
12122 * Returns: the checksum as a hexadecimal string. The returned string
12123 * should be freed with g_free() when done using it.
12129 * g_compute_hmac_for_bytes:
12130 * @digest_type: a #GChecksumType to use for the HMAC
12131 * @key: the key to use in the HMAC
12132 * @data: binary blob to compute the HMAC of
12134 * Computes the HMAC for a binary @data. This is a
12135 * convenience wrapper for g_hmac_new(), g_hmac_get_string()
12136 * and g_hmac_unref().
12138 * The hexadecimal string returned will be in lower case.
12140 * Returns: the HMAC of the binary data as a string in hexadecimal.
12141 * The returned string should be freed with g_free() when done using it.
12147 * g_compute_hmac_for_data:
12148 * @digest_type: a #GChecksumType to use for the HMAC
12149 * @key: (array length=key_len): the key to use in the HMAC
12150 * @key_len: the length of the key
12151 * @data: (array length=length): binary blob to compute the HMAC of
12152 * @length: length of @data
12154 * Computes the HMAC for a binary @data of @length. This is a
12155 * convenience wrapper for g_hmac_new(), g_hmac_get_string()
12156 * and g_hmac_unref().
12158 * The hexadecimal string returned will be in lower case.
12160 * Returns: the HMAC of the binary data as a string in hexadecimal.
12161 * The returned string should be freed with g_free() when done using it.
12167 * g_compute_hmac_for_string:
12168 * @digest_type: a #GChecksumType to use for the HMAC
12169 * @key: (array length=key_len): the key to use in the HMAC
12170 * @key_len: the length of the key
12171 * @str: the string to compute the HMAC for
12172 * @length: the length of the string, or -1 if the string is nul-terminated
12174 * Computes the HMAC for a string.
12176 * The hexadecimal string returned will be in lower case.
12178 * Returns: the HMAC as a hexadecimal string.
12179 * The returned string should be freed with g_free()
12180 * when done using it.
12186 * g_cond_broadcast:
12189 * If threads are waiting for @cond, all of them are unblocked.
12190 * If no threads are waiting for @cond, this function has no effect.
12191 * It is good practice to lock the same mutex as the waiting threads
12192 * while calling this function, though not required.
12198 * @cond: an initialised #GCond
12200 * Frees the resources allocated to a #GCond with g_cond_init().
12202 * This function should not be used with a #GCond that has been
12203 * statically allocated.
12205 * Calling g_cond_clear() for a #GCond on which threads are
12206 * blocking leads to undefined behaviour.
12214 * @cond: an uninitialized #GCond
12216 * Initialises a #GCond so that it can be used.
12218 * This function is useful to initialise a #GCond that has been
12219 * allocated as part of a larger structure. It is not necessary to
12220 * initialise a #GCond that has been statically allocated.
12222 * To undo the effect of g_cond_init() when a #GCond is no longer
12223 * needed, use g_cond_clear().
12225 * Calling g_cond_init() on an already-initialised #GCond leads
12226 * to undefined behaviour.
12236 * If threads are waiting for @cond, at least one of them is unblocked.
12237 * If no threads are waiting for @cond, this function has no effect.
12238 * It is good practice to hold the same lock as the waiting thread
12239 * while calling this function, though not required.
12246 * @mutex: a #GMutex that is currently locked
12248 * Atomically releases @mutex and waits until @cond is signalled.
12249 * When this function returns, @mutex is locked again and owned by the
12252 * When using condition variables, it is possible that a spurious wakeup
12253 * may occur (ie: g_cond_wait() returns even though g_cond_signal() was
12254 * not called). It's also possible that a stolen wakeup may occur.
12255 * This is when g_cond_signal() is called, but another thread acquires
12256 * @mutex before this thread and modifies the state of the program in
12257 * such a way that when g_cond_wait() is able to return, the expected
12258 * condition is no longer met.
12260 * For this reason, g_cond_wait() must always be used in a loop. See
12261 * the documentation for #GCond for a complete example.
12266 * g_cond_wait_until:
12268 * @mutex: a #GMutex that is currently locked
12269 * @end_time: the monotonic time to wait until
12271 * Waits until either @cond is signalled or @end_time has passed.
12273 * As with g_cond_wait() it is possible that a spurious or stolen wakeup
12274 * could occur. For that reason, waiting on a condition variable should
12275 * always be in a loop, based on an explicitly-checked predicate.
12277 * %TRUE is returned if the condition variable was signalled (or in the
12278 * case of a spurious wakeup). %FALSE is returned if @end_time has
12281 * The following code shows how to correctly perform a timed wait on a
12282 * condition variable (extending the example presented in the
12283 * documentation for #GCond):
12285 * |[<!-- language="C" -->
12287 * pop_data_timed (void)
12292 * g_mutex_lock (&data_mutex);
12294 * end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND;
12295 * while (!current_data)
12296 * if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
12298 * // timeout has passed.
12299 * g_mutex_unlock (&data_mutex);
12303 * // there is data for us
12304 * data = current_data;
12305 * current_data = NULL;
12307 * g_mutex_unlock (&data_mutex);
12313 * Notice that the end time is calculated once, before entering the
12314 * loop and reused. This is the motivation behind the use of absolute
12315 * time on this API -- if a relative time of 5 seconds were passed
12316 * directly to the call and a spurious wakeup occurred, the program would
12317 * have to start over waiting again (which would lead to a total wait
12318 * time of more than 5 seconds).
12320 * Returns: %TRUE on a signal, %FALSE on a timeout
12327 * @str: the string to convert
12328 * @len: the length of the string in bytes, or -1 if the string is
12329 * nul-terminated (Note that some encodings may allow nul
12330 * bytes to occur inside strings. In that case, using -1
12331 * for the @len parameter is unsafe)
12332 * @to_codeset: name of character set into which to convert @str
12333 * @from_codeset: character set of @str.
12334 * @bytes_read: (out): location to store the number of bytes in the
12335 * input string that were successfully converted, or %NULL.
12336 * Even if the conversion was successful, this may be
12337 * less than @len if there were partial characters
12338 * at the end of the input. If the error
12339 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
12340 * stored will the byte offset after the last valid
12342 * @bytes_written: (out): the number of bytes stored in the output buffer (not
12343 * including the terminating nul).
12344 * @error: location to store the error occurring, or %NULL to ignore
12345 * errors. Any of the errors in #GConvertError may occur.
12347 * Converts a string from one character set to another.
12349 * Note that you should use g_iconv() for streaming conversions.
12350 * Despite the fact that @byes_read can return information about partial
12351 * characters, the g_convert_... functions are not generally suitable
12352 * for streaming. If the underlying converter maintains internal state,
12353 * then this won't be preserved across successive calls to g_convert(),
12354 * g_convert_with_iconv() or g_convert_with_fallback(). (An example of
12355 * this is the GNU C converter for CP1255 which does not emit a base
12356 * character until it knows that the next character is not a mark that
12357 * could combine with the base character.)
12359 * Using extensions such as "//TRANSLIT" may not work (or may not work
12360 * well) on many platforms. Consider using g_str_to_ascii() instead.
12362 * Returns: If the conversion was successful, a newly allocated
12363 * nul-terminated string, which must be freed with
12364 * g_free(). Otherwise %NULL and @error will be set.
12369 * g_convert_with_fallback:
12370 * @str: the string to convert
12371 * @len: the length of the string in bytes, or -1 if the string is
12372 * nul-terminated (Note that some encodings may allow nul
12373 * bytes to occur inside strings. In that case, using -1
12374 * for the @len parameter is unsafe)
12375 * @to_codeset: name of character set into which to convert @str
12376 * @from_codeset: character set of @str.
12377 * @fallback: UTF-8 string to use in place of character not
12378 * present in the target encoding. (The string must be
12379 * representable in the target encoding).
12380 * If %NULL, characters not in the target encoding will
12381 * be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
12382 * @bytes_read: location to store the number of bytes in the
12383 * input string that were successfully converted, or %NULL.
12384 * Even if the conversion was successful, this may be
12385 * less than @len if there were partial characters
12386 * at the end of the input.
12387 * @bytes_written: the number of bytes stored in the output buffer (not
12388 * including the terminating nul).
12389 * @error: location to store the error occurring, or %NULL to ignore
12390 * errors. Any of the errors in #GConvertError may occur.
12392 * Converts a string from one character set to another, possibly
12393 * including fallback sequences for characters not representable
12394 * in the output. Note that it is not guaranteed that the specification
12395 * for the fallback sequences in @fallback will be honored. Some
12396 * systems may do an approximate conversion from @from_codeset
12397 * to @to_codeset in their iconv() functions,
12398 * in which case GLib will simply return that approximate conversion.
12400 * Note that you should use g_iconv() for streaming conversions.
12401 * Despite the fact that @byes_read can return information about partial
12402 * characters, the g_convert_... functions are not generally suitable
12403 * for streaming. If the underlying converter maintains internal state,
12404 * then this won't be preserved across successive calls to g_convert(),
12405 * g_convert_with_iconv() or g_convert_with_fallback(). (An example of
12406 * this is the GNU C converter for CP1255 which does not emit a base
12407 * character until it knows that the next character is not a mark that
12408 * could combine with the base character.)
12410 * Returns: If the conversion was successful, a newly allocated
12411 * nul-terminated string, which must be freed with
12412 * g_free(). Otherwise %NULL and @error will be set.
12417 * g_convert_with_iconv:
12418 * @str: the string to convert
12419 * @len: the length of the string in bytes, or -1 if the string is
12420 * nul-terminated (Note that some encodings may allow nul
12421 * bytes to occur inside strings. In that case, using -1
12422 * for the @len parameter is unsafe)
12423 * @converter: conversion descriptor from g_iconv_open()
12424 * @bytes_read: location to store the number of bytes in the
12425 * input string that were successfully converted, or %NULL.
12426 * Even if the conversion was successful, this may be
12427 * less than @len if there were partial characters
12428 * at the end of the input. If the error
12429 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
12430 * stored will the byte offset after the last valid
12432 * @bytes_written: the number of bytes stored in the output buffer (not
12433 * including the terminating nul).
12434 * @error: location to store the error occurring, or %NULL to ignore
12435 * errors. Any of the errors in #GConvertError may occur.
12437 * Converts a string from one character set to another.
12439 * Note that you should use g_iconv() for streaming conversions.
12440 * Despite the fact that @byes_read can return information about partial
12441 * characters, the g_convert_... functions are not generally suitable
12442 * for streaming. If the underlying converter maintains internal state,
12443 * then this won't be preserved across successive calls to g_convert(),
12444 * g_convert_with_iconv() or g_convert_with_fallback(). (An example of
12445 * this is the GNU C converter for CP1255 which does not emit a base
12446 * character until it knows that the next character is not a mark that
12447 * could combine with the base character.)
12449 * Returns: If the conversion was successful, a newly allocated
12450 * nul-terminated string, which must be freed with
12451 * g_free(). Otherwise %NULL and @error will be set.
12457 * @filename: (type filename): a pathname in the GLib file name encoding
12458 * (UTF-8 on Windows)
12459 * @mode: as in creat()
12461 * A wrapper for the POSIX creat() function. The creat() function is
12462 * used to convert a pathname into a file descriptor, creating a file
12465 * On POSIX systems file descriptors are implemented by the operating
12466 * system. On Windows, it's the C library that implements creat() and
12467 * file descriptors. The actual Windows API for opening files is
12468 * different, see MSDN documentation for CreateFile(). The Win32 API
12469 * uses file handles, which are more randomish integers, not small
12470 * integers like file descriptors.
12472 * Because file descriptors are specific to the C library on Windows,
12473 * the file descriptor returned by this function makes sense only to
12474 * functions in the same C library. Thus if the GLib-using code uses a
12475 * different C library than GLib does, the file descriptor returned by
12476 * this function cannot be passed to C library functions like write()
12479 * See your C library manual for more details about creat().
12481 * Returns: a new file descriptor, or -1 if an error occurred.
12482 * The return value can be used exactly like the return value
12490 * @...: format string, followed by parameters to insert
12491 * into the format string (as with printf())
12493 * Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL).
12494 * It's more or less application-defined what constitutes
12495 * a critical vs. a regular warning. You could call
12496 * g_log_set_always_fatal() to make critical warnings exit
12497 * the program, then use g_critical() for fatal errors, for
12500 * You can also make critical warnings fatal at runtime by
12501 * setting the `G_DEBUG` environment variable (see
12502 * [Running GLib Applications](glib-running.html)).
12504 * If g_log_default_handler() is used as the log handler function, a new-line
12505 * character will automatically be appended to @..., and need not be entered
12511 * g_datalist_clear:
12512 * @datalist: a datalist.
12514 * Frees all the data elements of the datalist.
12515 * The data elements' destroy functions are called
12516 * if they have been set.
12521 * g_datalist_foreach:
12522 * @datalist: a datalist.
12523 * @func: the function to call for each data element.
12524 * @user_data: user data to pass to the function.
12526 * Calls the given function for each data element of the datalist. The
12527 * function is called with each data element's #GQuark id and data,
12528 * together with the given @user_data parameter. Note that this
12529 * function is NOT thread-safe. So unless @datalist can be protected
12530 * from any modifications during invocation of this function, it should
12536 * g_datalist_get_data:
12537 * @datalist: a datalist.
12538 * @key: the string identifying a data element.
12540 * Gets a data element, using its string identifier. This is slower than
12541 * g_datalist_id_get_data() because it compares strings.
12543 * Returns: the data element, or %NULL if it is not found.
12548 * g_datalist_get_flags:
12549 * @datalist: pointer to the location that holds a list
12551 * Gets flags values packed in together with the datalist.
12552 * See g_datalist_set_flags().
12554 * Returns: the flags of the datalist
12560 * g_datalist_id_dup_data:
12561 * @datalist: location of a datalist
12562 * @key_id: the #GQuark identifying a data element
12563 * @dup_func: (allow-none): function to duplicate the old value
12564 * @user_data: (allow-none): passed as user_data to @dup_func
12566 * This is a variant of g_datalist_id_get_data() which
12567 * returns a 'duplicate' of the value. @dup_func defines the
12568 * meaning of 'duplicate' in this context, it could e.g.
12569 * take a reference on a ref-counted object.
12571 * If the @key_id is not set in the datalist then @dup_func
12572 * will be called with a %NULL argument.
12574 * Note that @dup_func is called while the datalist is locked, so it
12575 * is not allowed to read or modify the datalist.
12577 * This function can be useful to avoid races when multiple
12578 * threads are using the same datalist and the same key.
12580 * Returns: the result of calling @dup_func on the value
12581 * associated with @key_id in @datalist, or %NULL if not set.
12582 * If @dup_func is %NULL, the value is returned unmodified.
12588 * g_datalist_id_get_data:
12589 * @datalist: a datalist.
12590 * @key_id: the #GQuark identifying a data element.
12592 * Retrieves the data element corresponding to @key_id.
12594 * Returns: the data element, or %NULL if it is not found.
12599 * g_datalist_id_remove_data:
12601 * @q: the #GQuark identifying the data element.
12603 * Removes an element, using its #GQuark identifier.
12608 * g_datalist_id_remove_no_notify:
12609 * @datalist: a datalist.
12610 * @key_id: the #GQuark identifying a data element.
12612 * Removes an element, without calling its destroy notification
12615 * Returns: the data previously stored at @key_id, or %NULL if none.
12620 * g_datalist_id_replace_data:
12621 * @datalist: location of a datalist
12622 * @key_id: the #GQuark identifying a data element
12623 * @oldval: (allow-none): the old value to compare against
12624 * @newval: (allow-none): the new value to replace it with
12625 * @destroy: (allow-none): destroy notify for the new value
12626 * @old_destroy: (allow-none): destroy notify for the existing value
12628 * Compares the member that is associated with @key_id in
12629 * @datalist to @oldval, and if they are the same, replace
12630 * @oldval with @newval.
12632 * This is like a typical atomic compare-and-exchange
12633 * operation, for a member of @datalist.
12635 * If the previous value was replaced then ownership of the
12636 * old value (@oldval) is passed to the caller, including
12637 * the registred destroy notify for it (passed out in @old_destroy).
12638 * Its up to the caller to free this as he wishes, which may
12639 * or may not include using @old_destroy as sometimes replacement
12640 * should not destroy the object in the normal way.
12642 * Returns: %TRUE if the existing value for @key_id was replaced
12643 * by @newval, %FALSE otherwise.
12649 * g_datalist_id_set_data:
12651 * @q: the #GQuark to identify the data element.
12652 * @d: (allow-none): the data element, or %NULL to remove any previous element
12653 * corresponding to @q.
12655 * Sets the data corresponding to the given #GQuark id. Any previous
12656 * data with the same key is removed, and its destroy function is
12662 * g_datalist_id_set_data_full:
12663 * @datalist: a datalist.
12664 * @key_id: the #GQuark to identify the data element.
12665 * @data: (allow-none): the data element or %NULL to remove any previous element
12666 * corresponding to @key_id.
12667 * @destroy_func: the function to call when the data element is
12668 * removed. This function will be called with the data
12669 * element and can be used to free any memory allocated
12670 * for it. If @data is %NULL, then @destroy_func must
12673 * Sets the data corresponding to the given #GQuark id, and the
12674 * function to be called when the element is removed from the datalist.
12675 * Any previous data with the same key is removed, and its destroy
12676 * function is called.
12682 * @datalist: a pointer to a pointer to a datalist.
12684 * Resets the datalist to %NULL. It does not free any memory or call
12685 * any destroy functions.
12690 * g_datalist_remove_data:
12692 * @k: the string identifying the data element.
12694 * Removes an element using its string identifier. The data element's
12695 * destroy function is called if it has been set.
12700 * g_datalist_remove_no_notify:
12702 * @k: the string identifying the data element.
12704 * Removes an element, without calling its destroy notifier.
12709 * g_datalist_set_data:
12711 * @k: the string to identify the data element.
12712 * @d: (allow-none): the data element, or %NULL to remove any previous element
12713 * corresponding to @k.
12715 * Sets the data element corresponding to the given string identifier.
12720 * g_datalist_set_data_full:
12722 * @k: the string to identify the data element.
12723 * @d: (allow-none): the data element, or %NULL to remove any previous element
12724 * corresponding to @k.
12725 * @f: the function to call when the data element is removed. This
12726 * function will be called with the data element and can be used to
12727 * free any memory allocated for it. If @d is %NULL, then @f must
12730 * Sets the data element corresponding to the given string identifier,
12731 * and the function to be called when the data element is removed.
12736 * g_datalist_set_flags:
12737 * @datalist: pointer to the location that holds a list
12738 * @flags: the flags to turn on. The values of the flags are
12739 * restricted by %G_DATALIST_FLAGS_MASK (currently
12740 * 3; giving two possible boolean flags).
12741 * A value for @flags that doesn't fit within the mask is
12744 * Turns on flag values for a data list. This function is used
12745 * to keep a small number of boolean flags in an object with
12746 * a data list without using any additional space. It is
12747 * not generally useful except in circumstances where space
12748 * is very tight. (It is used in the base #GObject type, for
12756 * g_datalist_unset_flags:
12757 * @datalist: pointer to the location that holds a list
12758 * @flags: the flags to turn off. The values of the flags are
12759 * restricted by %G_DATALIST_FLAGS_MASK (currently
12760 * 3: giving two possible boolean flags).
12761 * A value for @flags that doesn't fit within the mask is
12764 * Turns off flag values for a data list. See g_datalist_unset_flags()
12771 * g_dataset_destroy:
12772 * @dataset_location: (not nullable): the location identifying the dataset.
12774 * Destroys the dataset, freeing all memory allocated, and calling any
12775 * destroy functions set for data elements.
12780 * g_dataset_foreach:
12781 * @dataset_location: (not nullable): the location identifying the dataset.
12782 * @func: the function to call for each data element.
12783 * @user_data: user data to pass to the function.
12785 * Calls the given function for each data element which is associated
12786 * with the given location. Note that this function is NOT thread-safe.
12787 * So unless @datalist can be protected from any modifications during
12788 * invocation of this function, it should not be called.
12793 * g_dataset_get_data:
12794 * @l: the location identifying the dataset.
12795 * @k: the string identifying the data element.
12797 * Gets the data element corresponding to a string.
12799 * Returns: the data element corresponding to the string, or %NULL if
12805 * g_dataset_id_get_data:
12806 * @dataset_location: (not nullable): the location identifying the dataset.
12807 * @key_id: the #GQuark id to identify the data element.
12809 * Gets the data element corresponding to a #GQuark.
12811 * Returns: the data element corresponding to the #GQuark, or %NULL if
12817 * g_dataset_id_remove_data:
12818 * @l: the location identifying the dataset.
12819 * @k: the #GQuark id identifying the data element.
12821 * Removes a data element from a dataset. The data element's destroy
12822 * function is called if it has been set.
12827 * g_dataset_id_remove_no_notify:
12828 * @dataset_location: (not nullable): the location identifying the dataset.
12829 * @key_id: the #GQuark ID identifying the data element.
12831 * Removes an element, without calling its destroy notification
12834 * Returns: the data previously stored at @key_id, or %NULL if none.
12839 * g_dataset_id_set_data:
12840 * @l: the location identifying the dataset.
12841 * @k: the #GQuark id to identify the data element.
12842 * @d: the data element.
12844 * Sets the data element associated with the given #GQuark id. Any
12845 * previous data with the same key is removed, and its destroy function
12851 * g_dataset_id_set_data_full:
12852 * @dataset_location: (not nullable): the location identifying the dataset.
12853 * @key_id: the #GQuark id to identify the data element.
12854 * @data: the data element.
12855 * @destroy_func: the function to call when the data element is
12856 * removed. This function will be called with the data
12857 * element and can be used to free any memory allocated
12860 * Sets the data element associated with the given #GQuark id, and also
12861 * the function to call when the data element is destroyed. Any
12862 * previous data with the same key is removed, and its destroy function
12868 * g_dataset_remove_data:
12869 * @l: the location identifying the dataset.
12870 * @k: the string identifying the data element.
12872 * Removes a data element corresponding to a string. Its destroy
12873 * function is called if it has been set.
12878 * g_dataset_remove_no_notify:
12879 * @l: the location identifying the dataset.
12880 * @k: the string identifying the data element.
12882 * Removes an element, without calling its destroy notifier.
12887 * g_dataset_set_data:
12888 * @l: the location identifying the dataset.
12889 * @k: the string to identify the data element.
12890 * @d: the data element.
12892 * Sets the data corresponding to the given string identifier.
12897 * g_dataset_set_data_full:
12898 * @l: the location identifying the dataset.
12899 * @k: the string to identify the data element.
12900 * @d: the data element.
12901 * @f: the function to call when the data element is removed. This
12902 * function will be called with the data element and can be used to
12903 * free any memory allocated for it.
12905 * Sets the data corresponding to the given string identifier, and the
12906 * function to call when the data element is destroyed.
12912 * @date: a #GDate to increment
12913 * @n_days: number of days to move the date forward
12915 * Increments a date some number of days.
12916 * To move forward by weeks, add weeks*7 days.
12917 * The date must be valid.
12922 * g_date_add_months:
12923 * @date: a #GDate to increment
12924 * @n_months: number of months to move forward
12926 * Increments a date by some number of months.
12927 * If the day of the month is greater than 28,
12928 * this routine may change the day of the month
12929 * (because the destination month may not have
12930 * the current day in it). The date must be valid.
12935 * g_date_add_years:
12936 * @date: a #GDate to increment
12937 * @n_years: number of years to move forward
12939 * Increments a date by some number of years.
12940 * If the date is February 29, and the destination
12941 * year is not a leap year, the date will be changed
12942 * to February 28. The date must be valid.
12948 * @date: a #GDate to clamp
12949 * @min_date: minimum accepted value for @date
12950 * @max_date: maximum accepted value for @date
12952 * If @date is prior to @min_date, sets @date equal to @min_date.
12953 * If @date falls after @max_date, sets @date equal to @max_date.
12954 * Otherwise, @date is unchanged.
12955 * Either of @min_date and @max_date may be %NULL.
12956 * All non-%NULL dates must be valid.
12962 * @date: pointer to one or more dates to clear
12963 * @n_dates: number of dates to clear
12965 * Initializes one or more #GDate structs to a sane but invalid
12966 * state. The cleared dates will not represent an existing date, but will
12967 * not contain garbage. Useful to init a date declared on the stack.
12968 * Validity can be tested with g_date_valid().
12974 * @lhs: first date to compare
12975 * @rhs: second date to compare
12977 * qsort()-style comparison function for dates.
12978 * Both dates must be valid.
12980 * Returns: 0 for equal, less than zero if @lhs is less than @rhs,
12981 * greater than zero if @lhs is greater than @rhs
12986 * g_date_days_between:
12987 * @date1: the first date
12988 * @date2: the second date
12990 * Computes the number of days between two dates.
12991 * If @date2 is prior to @date1, the returned value is negative.
12992 * Both dates must be valid.
12994 * Returns: the number of days between @date1 and @date2
13000 * @date: a #GDate to free
13002 * Frees a #GDate returned from g_date_new().
13008 * @date: a #GDate to extract the day of the month from
13010 * Returns the day of the month. The date must be valid.
13012 * Returns: day of the month
13017 * g_date_get_day_of_year:
13018 * @date: a #GDate to extract day of year from
13020 * Returns the day of the year, where Jan 1 is the first day of the
13021 * year. The date must be valid.
13023 * Returns: day of the year
13028 * g_date_get_days_in_month:
13032 * Returns the number of days in a month, taking leap
13033 * years into account.
13035 * Returns: number of days in @month during the @year
13040 * g_date_get_iso8601_week_of_year:
13041 * @date: a valid #GDate
13043 * Returns the week of the year, where weeks are interpreted according
13046 * Returns: ISO 8601 week number of the year.
13052 * g_date_get_julian:
13053 * @date: a #GDate to extract the Julian day from
13055 * Returns the Julian day or "serial number" of the #GDate. The
13056 * Julian day is simply the number of days since January 1, Year 1; i.e.,
13057 * January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2,
13058 * etc. The date must be valid.
13060 * Returns: Julian day
13065 * g_date_get_monday_week_of_year:
13068 * Returns the week of the year, where weeks are understood to start on
13069 * Monday. If the date is before the first Monday of the year, return 0.
13070 * The date must be valid.
13072 * Returns: week of the year
13077 * g_date_get_monday_weeks_in_year:
13080 * Returns the number of weeks in the year, where weeks
13081 * are taken to start on Monday. Will be 52 or 53. The
13082 * date must be valid. (Years always have 52 7-day periods,
13083 * plus 1 or 2 extra days depending on whether it's a leap
13084 * year. This function is basically telling you how many
13085 * Mondays are in the year, i.e. there are 53 Mondays if
13086 * one of the extra days happens to be a Monday.)
13088 * Returns: number of Mondays in the year
13093 * g_date_get_month:
13094 * @date: a #GDate to get the month from
13096 * Returns the month of the year. The date must be valid.
13098 * Returns: month of the year as a #GDateMonth
13103 * g_date_get_sunday_week_of_year:
13106 * Returns the week of the year during which this date falls, if
13107 * weeks are understood to begin on Sunday. The date must be valid.
13108 * Can return 0 if the day is before the first Sunday of the year.
13110 * Returns: week number
13115 * g_date_get_sunday_weeks_in_year:
13116 * @year: year to count weeks in
13118 * Returns the number of weeks in the year, where weeks
13119 * are taken to start on Sunday. Will be 52 or 53. The
13120 * date must be valid. (Years always have 52 7-day periods,
13121 * plus 1 or 2 extra days depending on whether it's a leap
13122 * year. This function is basically telling you how many
13123 * Sundays are in the year, i.e. there are 53 Sundays if
13124 * one of the extra days happens to be a Sunday.)
13126 * Returns: the number of weeks in @year
13131 * g_date_get_weekday:
13134 * Returns the day of the week for a #GDate. The date must be valid.
13136 * Returns: day of the week as a #GDateWeekday.
13144 * Returns the year of a #GDate. The date must be valid.
13146 * Returns: year in which the date falls
13151 * g_date_is_first_of_month:
13152 * @date: a #GDate to check
13154 * Returns %TRUE if the date is on the first of a month.
13155 * The date must be valid.
13157 * Returns: %TRUE if the date is the first of the month
13162 * g_date_is_last_of_month:
13163 * @date: a #GDate to check
13165 * Returns %TRUE if the date is the last day of the month.
13166 * The date must be valid.
13168 * Returns: %TRUE if the date is the last day of the month
13173 * g_date_is_leap_year:
13174 * @year: year to check
13176 * Returns %TRUE if the year is a leap year.
13178 * For the purposes of this function, leap year is every year
13179 * divisible by 4 unless that year is divisible by 100. If it
13180 * is divisible by 100 it would be a leap year only if that year
13181 * is also divisible by 400.
13183 * Returns: %TRUE if the year is a leap year
13190 * Allocates a #GDate and initializes
13191 * it to a sane state. The new date will
13192 * be cleared (as if you'd called g_date_clear()) but invalid (it won't
13193 * represent an existing day). Free the return value with g_date_free().
13195 * Returns: a newly-allocated #GDate
13201 * @day: day of the month
13202 * @month: month of the year
13205 * Like g_date_new(), but also sets the value of the date. Assuming the
13206 * day-month-year triplet you pass in represents an existing day, the
13207 * returned date will be valid.
13209 * Returns: a newly-allocated #GDate initialized with @day, @month, and @year
13214 * g_date_new_julian:
13215 * @julian_day: days since January 1, Year 1
13217 * Like g_date_new(), but also sets the value of the date. Assuming the
13218 * Julian day number you pass in is valid (greater than 0, less than an
13219 * unreasonably large number), the returned date will be valid.
13221 * Returns: a newly-allocated #GDate initialized with @julian_day
13227 * @date1: the first date
13228 * @date2: the second date
13230 * Checks if @date1 is less than or equal to @date2,
13231 * and swap the values if this is not the case.
13240 * Sets the day of the month for a #GDate. If the resulting
13241 * day-month-year triplet is invalid, the date will be invalid.
13252 * Sets the value of a #GDate from a day, month, and year.
13253 * The day-month-year triplet must be valid; if you aren't
13254 * sure it is, call g_date_valid_dmy() to check before you
13260 * g_date_set_julian:
13262 * @julian_date: Julian day number (days since January 1, Year 1)
13264 * Sets the value of a #GDate from a Julian day number.
13269 * g_date_set_month:
13271 * @month: month to set
13273 * Sets the month of the year for a #GDate. If the resulting
13274 * day-month-year triplet is invalid, the date will be invalid.
13279 * g_date_set_parse:
13280 * @date: a #GDate to fill in
13281 * @str: string to parse
13283 * Parses a user-inputted string @str, and try to figure out what date it
13284 * represents, taking the [current locale][setlocale] into account. If the
13285 * string is successfully parsed, the date will be valid after the call.
13286 * Otherwise, it will be invalid. You should check using g_date_valid()
13287 * to see whether the parsing succeeded.
13289 * This function is not appropriate for file formats and the like; it
13290 * isn't very precise, and its exact behavior varies with the locale.
13291 * It's intended to be a heuristic routine that guesses what the user
13292 * means by a given string (and it does work pretty well in that
13300 * @time_: #GTime value to set.
13302 * Sets the value of a date from a #GTime value.
13303 * The time to date conversion is done using the user's current timezone.
13305 * Deprecated: 2.10: Use g_date_set_time_t() instead.
13310 * g_date_set_time_t:
13312 * @timet: time_t value to set
13314 * Sets the value of a date to the date corresponding to a time
13315 * specified as a time_t. The time to date conversion is done using
13316 * the user's current timezone.
13318 * To set the value of a date to the current day, you could write:
13319 * |[<!-- language="C" -->
13320 * g_date_set_time_t (date, time (NULL));
13328 * g_date_set_time_val:
13330 * @timeval: #GTimeVal value to set
13332 * Sets the value of a date from a #GTimeVal value. Note that the
13333 * @tv_usec member is ignored, because #GDate can't make use of the
13334 * additional precision.
13336 * The time to date conversion is done using the user's current timezone.
13345 * @year: year to set
13347 * Sets the year for a #GDate. If the resulting day-month-year
13348 * triplet is invalid, the date will be invalid.
13354 * @s: destination buffer
13355 * @slen: buffer size
13356 * @format: format string
13357 * @date: valid #GDate
13359 * Generates a printed representation of the date, in a
13360 * [locale][setlocale]-specific way.
13361 * Works just like the platform's C library strftime() function,
13362 * but only accepts date-related formats; time-related formats
13363 * give undefined results. Date must be valid. Unlike strftime()
13364 * (which uses the locale encoding), works on a UTF-8 format
13365 * string and stores a UTF-8 result.
13367 * This function does not provide any conversion specifiers in
13368 * addition to those implemented by the platform's C library.
13369 * For example, don't expect that using g_date_strftime() would
13370 * make the \%F provided by the C99 strftime() work on Windows
13371 * where the C library only complies to C89.
13373 * Returns: number of characters written to the buffer, or 0 the buffer was too small
13378 * g_date_subtract_days:
13379 * @date: a #GDate to decrement
13380 * @n_days: number of days to move
13382 * Moves a date some number of days into the past.
13383 * To move by weeks, just move by weeks*7 days.
13384 * The date must be valid.
13389 * g_date_subtract_months:
13390 * @date: a #GDate to decrement
13391 * @n_months: number of months to move
13393 * Moves a date some number of months into the past.
13394 * If the current day of the month doesn't exist in
13395 * the destination month, the day of the month
13396 * may change. The date must be valid.
13401 * g_date_subtract_years:
13402 * @date: a #GDate to decrement
13403 * @n_years: number of years to move
13405 * Moves a date some number of years into the past.
13406 * If the current day doesn't exist in the destination
13407 * year (i.e. it's February 29 and you move to a non-leap-year)
13408 * then the day is changed to February 29. The date
13415 * @datetime: a #GDateTime
13416 * @timespan: a #GTimeSpan
13418 * Creates a copy of @datetime and adds the specified timespan to the copy.
13420 * Returns: the newly created #GDateTime which should be freed with
13421 * g_date_time_unref().
13427 * g_date_time_add_days:
13428 * @datetime: a #GDateTime
13429 * @days: the number of days
13431 * Creates a copy of @datetime and adds the specified number of days to the
13432 * copy. Add negative values to subtract days.
13434 * Returns: the newly created #GDateTime which should be freed with
13435 * g_date_time_unref().
13441 * g_date_time_add_full:
13442 * @datetime: a #GDateTime
13443 * @years: the number of years to add
13444 * @months: the number of months to add
13445 * @days: the number of days to add
13446 * @hours: the number of hours to add
13447 * @minutes: the number of minutes to add
13448 * @seconds: the number of seconds to add
13450 * Creates a new #GDateTime adding the specified values to the current date and
13451 * time in @datetime. Add negative values to subtract.
13453 * Returns: the newly created #GDateTime that should be freed with
13454 * g_date_time_unref().
13460 * g_date_time_add_hours:
13461 * @datetime: a #GDateTime
13462 * @hours: the number of hours to add
13464 * Creates a copy of @datetime and adds the specified number of hours.
13465 * Add negative values to subtract hours.
13467 * Returns: the newly created #GDateTime which should be freed with
13468 * g_date_time_unref().
13474 * g_date_time_add_minutes:
13475 * @datetime: a #GDateTime
13476 * @minutes: the number of minutes to add
13478 * Creates a copy of @datetime adding the specified number of minutes.
13479 * Add negative values to subtract minutes.
13481 * Returns: the newly created #GDateTime which should be freed with
13482 * g_date_time_unref().
13488 * g_date_time_add_months:
13489 * @datetime: a #GDateTime
13490 * @months: the number of months
13492 * Creates a copy of @datetime and adds the specified number of months to the
13493 * copy. Add negative values to subtract months.
13495 * Returns: the newly created #GDateTime which should be freed with
13496 * g_date_time_unref().
13502 * g_date_time_add_seconds:
13503 * @datetime: a #GDateTime
13504 * @seconds: the number of seconds to add
13506 * Creates a copy of @datetime and adds the specified number of seconds.
13507 * Add negative values to subtract seconds.
13509 * Returns: the newly created #GDateTime which should be freed with
13510 * g_date_time_unref().
13516 * g_date_time_add_weeks:
13517 * @datetime: a #GDateTime
13518 * @weeks: the number of weeks
13520 * Creates a copy of @datetime and adds the specified number of weeks to the
13521 * copy. Add negative values to subtract weeks.
13523 * Returns: the newly created #GDateTime which should be freed with
13524 * g_date_time_unref().
13530 * g_date_time_add_years:
13531 * @datetime: a #GDateTime
13532 * @years: the number of years
13534 * Creates a copy of @datetime and adds the specified number of years to the
13535 * copy. Add negative values to subtract years.
13537 * Returns: the newly created #GDateTime which should be freed with
13538 * g_date_time_unref().
13544 * g_date_time_compare:
13545 * @dt1: (not nullable): first #GDateTime to compare
13546 * @dt2: (not nullable): second #GDateTime to compare
13548 * A comparison function for #GDateTimes that is suitable
13549 * as a #GCompareFunc. Both #GDateTimes must be non-%NULL.
13551 * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater
13558 * g_date_time_difference:
13559 * @end: a #GDateTime
13560 * @begin: a #GDateTime
13562 * Calculates the difference in time between @end and @begin. The
13563 * #GTimeSpan that is returned is effectively @end - @begin (ie:
13564 * positive if the first parameter is larger).
13566 * Returns: the difference between the two #GDateTime, as a time
13567 * span expressed in microseconds.
13573 * g_date_time_equal:
13574 * @dt1: (not nullable): a #GDateTime
13575 * @dt2: (not nullable): a #GDateTime
13577 * Checks to see if @dt1 and @dt2 are equal.
13579 * Equal here means that they represent the same moment after converting
13580 * them to the same time zone.
13582 * Returns: %TRUE if @dt1 and @dt2 are equal
13588 * g_date_time_format:
13589 * @datetime: A #GDateTime
13590 * @format: a valid UTF-8 string, containing the format for the
13593 * Creates a newly allocated string representing the requested @format.
13595 * The format strings understood by this function are a subset of the
13596 * strftime() format language as specified by C99. The \%D, \%U and \%W
13597 * conversions are not supported, nor is the 'E' modifier. The GNU
13598 * extensions \%k, \%l, \%s and \%P are supported, however, as are the
13599 * '0', '_' and '-' modifiers.
13601 * In contrast to strftime(), this function always produces a UTF-8
13602 * string, regardless of the current locale. Note that the rendering of
13603 * many formats is locale-dependent and may not match the strftime()
13606 * The following format specifiers are supported:
13608 * - \%a: the abbreviated weekday name according to the current locale
13609 * - \%A: the full weekday name according to the current locale
13610 * - \%b: the abbreviated month name according to the current locale
13611 * - \%B: the full month name according to the current locale
13612 * - \%c: the preferred date and time representation for the current locale
13613 * - \%C: the century number (year/100) as a 2-digit integer (00-99)
13614 * - \%d: the day of the month as a decimal number (range 01 to 31)
13615 * - \%e: the day of the month as a decimal number (range 1 to 31)
13616 * - \%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format)
13617 * - \%g: the last two digits of the ISO 8601 week-based year as a
13618 * decimal number (00-99). This works well with \%V and \%u.
13619 * - \%G: the ISO 8601 week-based year as a decimal number. This works
13620 * well with \%V and \%u.
13621 * - \%h: equivalent to \%b
13622 * - \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23)
13623 * - \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12)
13624 * - \%j: the day of the year as a decimal number (range 001 to 366)
13625 * - \%k: the hour (24-hour clock) as a decimal number (range 0 to 23);
13626 * single digits are preceded by a blank
13627 * - \%l: the hour (12-hour clock) as a decimal number (range 1 to 12);
13628 * single digits are preceded by a blank
13629 * - \%m: the month as a decimal number (range 01 to 12)
13630 * - \%M: the minute as a decimal number (range 00 to 59)
13631 * - \%p: either "AM" or "PM" according to the given time value, or the
13632 * corresponding strings for the current locale. Noon is treated as
13633 * "PM" and midnight as "AM".
13634 * - \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for
13635 * the current locale
13636 * - \%r: the time in a.m. or p.m. notation
13637 * - \%R: the time in 24-hour notation (\%H:\%M)
13638 * - \%s: the number of seconds since the Epoch, that is, since 1970-01-01
13640 * - \%S: the second as a decimal number (range 00 to 60)
13641 * - \%t: a tab character
13642 * - \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S)
13643 * - \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
13644 * Monday being 1. This works well with \%G and \%V.
13645 * - \%V: the ISO 8601 standard week number of the current year as a decimal
13646 * number, range 01 to 53, where week 1 is the first week that has at
13647 * least 4 days in the new year. See g_date_time_get_week_of_year().
13648 * This works well with \%G and \%u.
13649 * - \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0.
13650 * This is not the ISO 8601 standard format -- use \%u instead.
13651 * - \%x: the preferred date representation for the current locale without
13653 * - \%X: the preferred time representation for the current locale without
13655 * - \%y: the year as a decimal number without the century
13656 * - \%Y: the year as a decimal number including the century
13657 * - \%z: the time zone as an offset from UTC (+hhmm)
13658 * - \%:z: the time zone as an offset from UTC (+hh:mm).
13659 * This is a gnulib strftime() extension. Since: 2.38
13660 * - \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a
13661 * gnulib strftime() extension. Since: 2.38
13662 * - \%:::z: the time zone as an offset from UTC, with : to necessary
13663 * precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38
13664 * - \%Z: the time zone or name or abbreviation
13665 * - \%\%: a literal \% character
13667 * Some conversion specifications can be modified by preceding the
13668 * conversion specifier by one or more modifier characters. The
13669 * following modifiers are supported for many of the numeric
13672 * - O: Use alternative numeric symbols, if the current locale supports those.
13673 * - _: Pad a numeric result with spaces. This overrides the default padding
13674 * for the specifier.
13675 * - -: Do not pad a numeric result. This overrides the default padding
13676 * for the specifier.
13677 * - 0: Pad a numeric result with zeros. This overrides the default padding
13678 * for the specifier.
13680 * Returns: a newly allocated string formatted to the requested format
13681 * or %NULL in the case that there was an error. The string
13682 * should be freed with g_free().
13688 * g_date_time_get_day_of_month:
13689 * @datetime: a #GDateTime
13691 * Retrieves the day of the month represented by @datetime in the gregorian
13694 * Returns: the day of the month
13700 * g_date_time_get_day_of_week:
13701 * @datetime: a #GDateTime
13703 * Retrieves the ISO 8601 day of the week on which @datetime falls (1 is
13704 * Monday, 2 is Tuesday... 7 is Sunday).
13706 * Returns: the day of the week
13712 * g_date_time_get_day_of_year:
13713 * @datetime: a #GDateTime
13715 * Retrieves the day of the year represented by @datetime in the Gregorian
13718 * Returns: the day of the year
13724 * g_date_time_get_hour:
13725 * @datetime: a #GDateTime
13727 * Retrieves the hour of the day represented by @datetime
13729 * Returns: the hour of the day
13735 * g_date_time_get_microsecond:
13736 * @datetime: a #GDateTime
13738 * Retrieves the microsecond of the date represented by @datetime
13740 * Returns: the microsecond of the second
13746 * g_date_time_get_minute:
13747 * @datetime: a #GDateTime
13749 * Retrieves the minute of the hour represented by @datetime
13751 * Returns: the minute of the hour
13757 * g_date_time_get_month:
13758 * @datetime: a #GDateTime
13760 * Retrieves the month of the year represented by @datetime in the Gregorian
13763 * Returns: the month represented by @datetime
13769 * g_date_time_get_second:
13770 * @datetime: a #GDateTime
13772 * Retrieves the second of the minute represented by @datetime
13774 * Returns: the second represented by @datetime
13780 * g_date_time_get_seconds:
13781 * @datetime: a #GDateTime
13783 * Retrieves the number of seconds since the start of the last minute,
13784 * including the fractional part.
13786 * Returns: the number of seconds
13792 * g_date_time_get_timezone_abbreviation:
13793 * @datetime: a #GDateTime
13795 * Determines the time zone abbreviation to be used at the time and in
13796 * the time zone of @datetime.
13798 * For example, in Toronto this is currently "EST" during the winter
13799 * months and "EDT" during the summer months when daylight savings
13800 * time is in effect.
13802 * Returns: (transfer none): the time zone abbreviation. The returned
13803 * string is owned by the #GDateTime and it should not be
13804 * modified or freed
13810 * g_date_time_get_utc_offset:
13811 * @datetime: a #GDateTime
13813 * Determines the offset to UTC in effect at the time and in the time
13814 * zone of @datetime.
13816 * The offset is the number of microseconds that you add to UTC time to
13817 * arrive at local time for the time zone (ie: negative numbers for time
13818 * zones west of GMT, positive numbers for east).
13820 * If @datetime represents UTC time, then the offset is always zero.
13822 * Returns: the number of microseconds that should be added to UTC to
13823 * get the local time
13829 * g_date_time_get_week_numbering_year:
13830 * @datetime: a #GDateTime
13832 * Returns the ISO 8601 week-numbering year in which the week containing
13835 * This function, taken together with g_date_time_get_week_of_year() and
13836 * g_date_time_get_day_of_week() can be used to determine the full ISO
13837 * week date on which @datetime falls.
13839 * This is usually equal to the normal Gregorian year (as returned by
13840 * g_date_time_get_year()), except as detailed below:
13842 * For Thursday, the week-numbering year is always equal to the usual
13843 * calendar year. For other days, the number is such that every day
13844 * within a complete week (Monday to Sunday) is contained within the
13845 * same week-numbering year.
13847 * For Monday, Tuesday and Wednesday occurring near the end of the year,
13848 * this may mean that the week-numbering year is one greater than the
13849 * calendar year (so that these days have the same week-numbering year
13850 * as the Thursday occurring early in the next year).
13852 * For Friday, Saturday and Sunday occurring near the start of the year,
13853 * this may mean that the week-numbering year is one less than the
13854 * calendar year (so that these days have the same week-numbering year
13855 * as the Thursday occurring late in the previous year).
13857 * An equivalent description is that the week-numbering year is equal to
13858 * the calendar year containing the majority of the days in the current
13859 * week (Monday to Sunday).
13861 * Note that January 1 0001 in the proleptic Gregorian calendar is a
13862 * Monday, so this function never returns 0.
13864 * Returns: the ISO 8601 week-numbering year for @datetime
13870 * g_date_time_get_week_of_year:
13871 * @datetime: a #GDateTime
13873 * Returns the ISO 8601 week number for the week containing @datetime.
13874 * The ISO 8601 week number is the same for every day of the week (from
13875 * Moday through Sunday). That can produce some unusual results
13876 * (described below).
13878 * The first week of the year is week 1. This is the week that contains
13879 * the first Thursday of the year. Equivalently, this is the first week
13880 * that has more than 4 of its days falling within the calendar year.
13882 * The value 0 is never returned by this function. Days contained
13883 * within a year but occurring before the first ISO 8601 week of that
13884 * year are considered as being contained in the last week of the
13885 * previous year. Similarly, the final days of a calendar year may be
13886 * considered as being part of the first ISO 8601 week of the next year
13887 * if 4 or more days of that week are contained within the new year.
13889 * Returns: the ISO 8601 week number for @datetime.
13895 * g_date_time_get_year:
13896 * @datetime: A #GDateTime
13898 * Retrieves the year represented by @datetime in the Gregorian calendar.
13900 * Returns: the year represented by @datetime
13906 * g_date_time_get_ymd:
13907 * @datetime: a #GDateTime.
13908 * @year: (out) (allow-none): the return location for the gregorian year, or %NULL.
13909 * @month: (out) (allow-none): the return location for the month of the year, or %NULL.
13910 * @day: (out) (allow-none): the return location for the day of the month, or %NULL.
13912 * Retrieves the Gregorian day, month, and year of a given #GDateTime.
13919 * g_date_time_hash:
13920 * @datetime: (not nullable): a #GDateTime
13922 * Hashes @datetime into a #guint, suitable for use within #GHashTable.
13924 * Returns: a #guint containing the hash
13930 * g_date_time_is_daylight_savings:
13931 * @datetime: a #GDateTime
13933 * Determines if daylight savings time is in effect at the time and in
13934 * the time zone of @datetime.
13936 * Returns: %TRUE if daylight savings time is in effect
13943 * @tz: a #GTimeZone
13944 * @year: the year component of the date
13945 * @month: the month component of the date
13946 * @day: the day component of the date
13947 * @hour: the hour component of the date
13948 * @minute: the minute component of the date
13949 * @seconds: the number of seconds past the minute
13951 * Creates a new #GDateTime corresponding to the given date and time in
13952 * the time zone @tz.
13954 * The @year must be between 1 and 9999, @month between 1 and 12 and @day
13955 * between 1 and 28, 29, 30 or 31 depending on the month and the year.
13957 * @hour must be between 0 and 23 and @minute must be between 0 and 59.
13959 * @seconds must be at least 0.0 and must be strictly less than 60.0.
13960 * It will be rounded down to the nearest microsecond.
13962 * If the given time is not representable in the given time zone (for
13963 * example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
13964 * time) then the time will be rounded up to the nearest existing time
13965 * (in this case, 03:00). If this matters to you then you should verify
13966 * the return value for containing the same as the numbers you gave.
13968 * In the case that the given time is ambiguous in the given time zone
13969 * (for example, 01:30 on November 7th 2010 in Toronto, due to daylight
13970 * savings time) then the time falling within standard (ie:
13971 * non-daylight) time is taken.
13973 * It not considered a programmer error for the values to this function
13974 * to be out of range, but in the case that they are, the function will
13977 * You should release the return value by calling g_date_time_unref()
13978 * when you are done with it.
13980 * Returns: a new #GDateTime, or %NULL
13986 * g_date_time_new_from_timeval_local:
13989 * Creates a #GDateTime corresponding to the given #GTimeVal @tv in the
13992 * The time contained in a #GTimeVal is always stored in the form of
13993 * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the
13994 * local time offset.
13996 * This call can fail (returning %NULL) if @tv represents a time outside
13997 * of the supported range of #GDateTime.
13999 * You should release the return value by calling g_date_time_unref()
14000 * when you are done with it.
14002 * Returns: a new #GDateTime, or %NULL
14008 * g_date_time_new_from_timeval_utc:
14011 * Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC.
14013 * The time contained in a #GTimeVal is always stored in the form of
14014 * seconds elapsed since 1970-01-01 00:00:00 UTC.
14016 * This call can fail (returning %NULL) if @tv represents a time outside
14017 * of the supported range of #GDateTime.
14019 * You should release the return value by calling g_date_time_unref()
14020 * when you are done with it.
14022 * Returns: a new #GDateTime, or %NULL
14028 * g_date_time_new_from_unix_local:
14029 * @t: the Unix time
14031 * Creates a #GDateTime corresponding to the given Unix time @t in the
14034 * Unix time is the number of seconds that have elapsed since 1970-01-01
14035 * 00:00:00 UTC, regardless of the local time offset.
14037 * This call can fail (returning %NULL) if @t represents a time outside
14038 * of the supported range of #GDateTime.
14040 * You should release the return value by calling g_date_time_unref()
14041 * when you are done with it.
14043 * Returns: a new #GDateTime, or %NULL
14049 * g_date_time_new_from_unix_utc:
14050 * @t: the Unix time
14052 * Creates a #GDateTime corresponding to the given Unix time @t in UTC.
14054 * Unix time is the number of seconds that have elapsed since 1970-01-01
14057 * This call can fail (returning %NULL) if @t represents a time outside
14058 * of the supported range of #GDateTime.
14060 * You should release the return value by calling g_date_time_unref()
14061 * when you are done with it.
14063 * Returns: a new #GDateTime, or %NULL
14069 * g_date_time_new_local:
14070 * @year: the year component of the date
14071 * @month: the month component of the date
14072 * @day: the day component of the date
14073 * @hour: the hour component of the date
14074 * @minute: the minute component of the date
14075 * @seconds: the number of seconds past the minute
14077 * Creates a new #GDateTime corresponding to the given date and time in
14078 * the local time zone.
14080 * This call is equivalent to calling g_date_time_new() with the time
14081 * zone returned by g_time_zone_new_local().
14083 * Returns: a #GDateTime, or %NULL
14089 * g_date_time_new_now:
14090 * @tz: a #GTimeZone
14092 * Creates a #GDateTime corresponding to this exact instant in the given
14093 * time zone @tz. The time is as accurate as the system allows, to a
14094 * maximum accuracy of 1 microsecond.
14096 * This function will always succeed unless the system clock is set to
14097 * truly insane values (or unless GLib is still being used after the
14100 * You should release the return value by calling g_date_time_unref()
14101 * when you are done with it.
14103 * Returns: a new #GDateTime, or %NULL
14109 * g_date_time_new_now_local:
14111 * Creates a #GDateTime corresponding to this exact instant in the local
14114 * This is equivalent to calling g_date_time_new_now() with the time
14115 * zone returned by g_time_zone_new_local().
14117 * Returns: a new #GDateTime, or %NULL
14123 * g_date_time_new_now_utc:
14125 * Creates a #GDateTime corresponding to this exact instant in UTC.
14127 * This is equivalent to calling g_date_time_new_now() with the time
14128 * zone returned by g_time_zone_new_utc().
14130 * Returns: a new #GDateTime, or %NULL
14136 * g_date_time_new_utc:
14137 * @year: the year component of the date
14138 * @month: the month component of the date
14139 * @day: the day component of the date
14140 * @hour: the hour component of the date
14141 * @minute: the minute component of the date
14142 * @seconds: the number of seconds past the minute
14144 * Creates a new #GDateTime corresponding to the given date and time in
14147 * This call is equivalent to calling g_date_time_new() with the time
14148 * zone returned by g_time_zone_new_utc().
14150 * Returns: a #GDateTime, or %NULL
14157 * @datetime: a #GDateTime
14159 * Atomically increments the reference count of @datetime by one.
14161 * Returns: the #GDateTime with the reference count increased
14167 * g_date_time_to_local:
14168 * @datetime: a #GDateTime
14170 * Creates a new #GDateTime corresponding to the same instant in time as
14171 * @datetime, but in the local time zone.
14173 * This call is equivalent to calling g_date_time_to_timezone() with the
14174 * time zone returned by g_time_zone_new_local().
14176 * Returns: the newly created #GDateTime
14182 * g_date_time_to_timeval:
14183 * @datetime: a #GDateTime
14184 * @tv: a #GTimeVal to modify
14186 * Stores the instant in time that @datetime represents into @tv.
14188 * The time contained in a #GTimeVal is always stored in the form of
14189 * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time
14190 * zone associated with @datetime.
14192 * On systems where 'long' is 32bit (ie: all 32bit systems and all
14193 * Windows systems), a #GTimeVal is incapable of storing the entire
14194 * range of values that #GDateTime is capable of expressing. On those
14195 * systems, this function returns %FALSE to indicate that the time is
14198 * On systems where 'long' is 64bit, this function never fails.
14200 * Returns: %TRUE if successful, else %FALSE
14206 * g_date_time_to_timezone:
14207 * @datetime: a #GDateTime
14208 * @tz: the new #GTimeZone
14210 * Create a new #GDateTime corresponding to the same instant in time as
14211 * @datetime, but in the time zone @tz.
14213 * This call can fail in the case that the time goes out of bounds. For
14214 * example, converting 0001-01-01 00:00:00 UTC to a time zone west of
14215 * Greenwich will fail (due to the year 0 being out of range).
14217 * You should release the return value by calling g_date_time_unref()
14218 * when you are done with it.
14220 * Returns: a new #GDateTime, or %NULL
14226 * g_date_time_to_unix:
14227 * @datetime: a #GDateTime
14229 * Gives the Unix time corresponding to @datetime, rounding down to the
14232 * Unix time is the number of seconds that have elapsed since 1970-01-01
14233 * 00:00:00 UTC, regardless of the time zone associated with @datetime.
14235 * Returns: the Unix time corresponding to @datetime
14241 * g_date_time_to_utc:
14242 * @datetime: a #GDateTime
14244 * Creates a new #GDateTime corresponding to the same instant in time as
14245 * @datetime, but in UTC.
14247 * This call is equivalent to calling g_date_time_to_timezone() with the
14248 * time zone returned by g_time_zone_new_utc().
14250 * Returns: the newly created #GDateTime
14256 * g_date_time_unref:
14257 * @datetime: a #GDateTime
14259 * Atomically decrements the reference count of @datetime by one.
14261 * When the reference count reaches zero, the resources allocated by
14262 * @datetime are freed
14269 * g_date_to_struct_tm:
14270 * @date: a #GDate to set the struct tm from
14271 * @tm: (not nullable): struct tm to fill
14273 * Fills in the date-related bits of a struct tm using the @date value.
14274 * Initializes the non-date parts with something sane but meaningless.
14280 * @date: a #GDate to check
14282 * Returns %TRUE if the #GDate represents an existing day. The date must not
14283 * contain garbage; it should have been initialized with g_date_clear()
14284 * if it wasn't allocated by one of the g_date_new() variants.
14286 * Returns: Whether the date is valid
14291 * g_date_valid_day:
14292 * @day: day to check
14294 * Returns %TRUE if the day of the month is valid (a day is valid if it's
14295 * between 1 and 31 inclusive).
14297 * Returns: %TRUE if the day is valid
14302 * g_date_valid_dmy:
14307 * Returns %TRUE if the day-month-year triplet forms a valid, existing day
14308 * in the range of days #GDate understands (Year 1 or later, no more than
14309 * a few thousand years in the future).
14311 * Returns: %TRUE if the date is a valid one
14316 * g_date_valid_julian:
14317 * @julian_date: Julian day to check
14319 * Returns %TRUE if the Julian day is valid. Anything greater than zero
14320 * is basically a valid Julian, though there is a 32-bit limit.
14322 * Returns: %TRUE if the Julian day is valid
14327 * g_date_valid_month:
14330 * Returns %TRUE if the month value is valid. The 12 #GDateMonth
14331 * enumeration values are the only valid months.
14333 * Returns: %TRUE if the month is valid
14338 * g_date_valid_weekday:
14339 * @weekday: weekday
14341 * Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration
14342 * values are the only valid weekdays.
14344 * Returns: %TRUE if the weekday is valid
14349 * g_date_valid_year:
14352 * Returns %TRUE if the year is valid. Any year greater than 0 is valid,
14353 * though there is a 16-bit limit to what #GDate will understand.
14355 * Returns: %TRUE if the year is valid
14361 * @domain: (allow-none): the translation domain to use, or %NULL to use
14362 * the domain set with textdomain()
14363 * @msgid: message to translate
14364 * @category: a locale category
14366 * This is a variant of g_dgettext() that allows specifying a locale
14367 * category instead of always using `LC_MESSAGES`. See g_dgettext() for
14368 * more information about how this functions differs from calling
14369 * dcgettext() directly.
14371 * Returns: the translated string for the given locale category
14378 * @...: format string, followed by parameters to insert
14379 * into the format string (as with printf())
14381 * A convenience function/macro to log a debug message.
14383 * If g_log_default_handler() is used as the log handler function, a new-line
14384 * character will automatically be appended to @..., and need not be entered
14387 * Such messages are suppressed by the g_log_default_handler() unless
14388 * the G_MESSAGES_DEBUG environment variable is set appropriately.
14396 * @domain: (allow-none): the translation domain to use, or %NULL to use
14397 * the domain set with textdomain()
14398 * @msgid: message to translate
14400 * This function is a wrapper of dgettext() which does not translate
14401 * the message if the default domain as set with textdomain() has no
14402 * translations for the current locale.
14404 * The advantage of using this function over dgettext() proper is that
14405 * libraries using this function (like GTK+) will not use translations
14406 * if the application using the library does not have translations for
14407 * the current locale. This results in a consistent English-only
14408 * interface instead of one having partial translations. For this
14409 * feature to work, the call to textdomain() and setlocale() should
14410 * precede any g_dgettext() invocations. For GTK+, it means calling
14411 * textdomain() before gtk_init or its variants.
14413 * This function disables translations if and only if upon its first
14414 * call all the following conditions hold:
14416 * - @domain is not %NULL
14418 * - textdomain() has been called to set a default text domain
14420 * - there is no translations available for the default text domain
14421 * and the current locale
14423 * - current locale is not "C" or any English locales (those
14424 * starting with "en_")
14426 * Note that this behavior may not be desired for example if an application
14427 * has its untranslated messages in a language other than English. In those
14428 * cases the application should call textdomain() after initializing GTK+.
14430 * Applications should normally not use this function directly,
14431 * but use the _() macro for translations.
14433 * Returns: The translated string
14440 * @dir: a #GDir* created by g_dir_open()
14442 * Closes the directory and deallocates all related resources.
14448 * @tmpl: (type filename) (allow-none): Template for directory name,
14449 * as in g_mkdtemp(), basename only, or %NULL for a default template
14450 * @error: return location for a #GError
14452 * Creates a subdirectory in the preferred directory for temporary
14453 * files (as returned by g_get_tmp_dir()).
14455 * @tmpl should be a string in the GLib file name encoding containing
14456 * a sequence of six 'X' characters, as the parameter to g_mkstemp().
14457 * However, unlike these functions, the template should only be a
14458 * basename, no directory components are allowed. If template is
14459 * %NULL, a default template is used.
14461 * Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not
14462 * modified, and might thus be a read-only literal string.
14464 * Returns: (type filename): The actual name used. This string
14465 * should be freed with g_free() when not needed any longer and is
14466 * is in the GLib file name encoding. In case of errors, %NULL is
14467 * returned and @error will be set.
14474 * @path: the path to the directory you are interested in. On Unix
14475 * in the on-disk encoding. On Windows in UTF-8
14476 * @flags: Currently must be set to 0. Reserved for future use.
14477 * @error: return location for a #GError, or %NULL.
14478 * If non-%NULL, an error will be set if and only if
14479 * g_dir_open() fails.
14481 * Opens a directory for reading. The names of the files in the
14482 * directory can then be retrieved using g_dir_read_name(). Note
14483 * that the ordering is not defined.
14485 * Returns: a newly allocated #GDir on success, %NULL on failure.
14486 * If non-%NULL, you must free the result with g_dir_close()
14487 * when you are finished with it.
14493 * @dir: a #GDir* created by g_dir_open()
14495 * Retrieves the name of another entry in the directory, or %NULL.
14496 * The order of entries returned from this function is not defined,
14497 * and may vary by file system or other operating-system dependent
14500 * %NULL may also be returned in case of errors. On Unix, you can
14501 * check `errno` to find out if %NULL was returned because of an error.
14503 * On Unix, the '.' and '..' entries are omitted, and the returned
14504 * name is in the on-disk encoding.
14506 * On Windows, as is true of all GLib functions which operate on
14507 * filenames, the returned name is in UTF-8.
14509 * Returns: (type filename): The entry's name or %NULL if there are no
14510 * more entries. The return value is owned by GLib and
14511 * must not be modified or freed.
14517 * @dir: a #GDir* created by g_dir_open()
14519 * Resets the given directory. The next call to g_dir_read_name()
14520 * will return the first entry again.
14526 * @v1: (nullable): a key
14527 * @v2: (nullable): a key to compare with @v1
14529 * Compares two #gpointer arguments and returns %TRUE if they are equal.
14530 * It can be passed to g_hash_table_new() as the @key_equal_func
14531 * parameter, when using opaque pointers compared by pointer value as
14532 * keys in a #GHashTable.
14534 * This equality function is also appropriate for keys that are integers
14535 * stored in pointers, such as `GINT_TO_POINTER (n)`.
14537 * Returns: %TRUE if the two keys match.
14543 * @v: (nullable): a #gpointer key
14545 * Converts a gpointer to a hash value.
14546 * It can be passed to g_hash_table_new() as the @hash_func parameter,
14547 * when using opaque pointers compared by pointer value as keys in a
14550 * This hash function is also appropriate for keys that are integers
14551 * stored in pointers, such as `GINT_TO_POINTER (n)`.
14553 * Returns: a hash value corresponding to the key.
14559 * @file_name: (type filename): the name of the file
14561 * Gets the directory components of a file name.
14563 * If the file name has no directory components "." is returned.
14564 * The returned string should be freed when no longer needed.
14566 * Returns: (type filename): the directory components of the file
14567 * Deprecated: use g_path_get_dirname() instead
14573 * @domain: (allow-none): the translation domain to use, or %NULL to use
14574 * the domain set with textdomain()
14575 * @msgid: message to translate
14576 * @msgid_plural: plural form of the message
14577 * @n: the quantity for which translation is needed
14579 * This function is a wrapper of dngettext() which does not translate
14580 * the message if the default domain as set with textdomain() has no
14581 * translations for the current locale.
14583 * See g_dgettext() for details of how this differs from dngettext()
14586 * Returns: The translated string
14593 * @v1: (not nullable): a pointer to a #gdouble key
14594 * @v2: (not nullable): a pointer to a #gdouble key to compare with @v1
14596 * Compares the two #gdouble values being pointed to and returns
14597 * %TRUE if they are equal.
14598 * It can be passed to g_hash_table_new() as the @key_equal_func
14599 * parameter, when using non-%NULL pointers to doubles as keys in a
14602 * Returns: %TRUE if the two keys match.
14609 * @v: (not nullable): a pointer to a #gdouble key
14611 * Converts a pointer to a #gdouble to a hash value.
14612 * It can be passed to g_hash_table_new() as the @hash_func parameter,
14613 * It can be passed to g_hash_table_new() as the @hash_func parameter,
14614 * when using non-%NULL pointers to doubles as keys in a #GHashTable.
14616 * Returns: a hash value corresponding to the key.
14623 * @domain: (allow-none): the translation domain to use, or %NULL to use
14624 * the domain set with textdomain()
14625 * @msgctxtid: a combined message context and message id, separated
14626 * by a \004 character
14627 * @msgidoffset: the offset of the message id in @msgctxid
14629 * This function is a variant of g_dgettext() which supports
14630 * a disambiguating message context. GNU gettext uses the
14631 * '\004' character to separate the message context and
14632 * message id in @msgctxtid.
14633 * If 0 is passed as @msgidoffset, this function will fall back to
14634 * trying to use the deprecated convention of using "|" as a separation
14637 * This uses g_dgettext() internally. See that functions for differences
14638 * with dgettext() proper.
14640 * Applications should normally not use this function directly,
14641 * but use the C_() macro for translations with context.
14643 * Returns: The translated string
14650 * @domain: (allow-none): the translation domain to use, or %NULL to use
14651 * the domain set with textdomain()
14652 * @context: the message context
14653 * @msgid: the message
14655 * This function is a variant of g_dgettext() which supports
14656 * a disambiguating message context. GNU gettext uses the
14657 * '\004' character to separate the message context and
14658 * message id in @msgctxtid.
14660 * This uses g_dgettext() internally. See that functions for differences
14661 * with dgettext() proper.
14663 * This function differs from C_() in that it is not a macro and
14664 * thus you may use non-string-literals as context and msgid arguments.
14666 * Returns: The translated string
14672 * g_environ_getenv:
14673 * @envp: (allow-none) (array zero-terminated=1) (transfer none): an environment
14674 * list (eg, as returned from g_get_environ()), or %NULL
14675 * for an empty environment list
14676 * @variable: the environment variable to get
14678 * Returns the value of the environment variable @variable in the
14679 * provided list @envp.
14681 * Returns: the value of the environment variable, or %NULL if
14682 * the environment variable is not set in @envp. The returned
14683 * string is owned by @envp, and will be freed if @variable is
14684 * set or unset again.
14690 * g_environ_setenv:
14691 * @envp: (allow-none) (array zero-terminated=1) (transfer full): an
14692 * environment list that can be freed using g_strfreev() (e.g., as
14693 * returned from g_get_environ()), or %NULL for an empty
14695 * @variable: the environment variable to set, must not contain '='
14696 * @value: the value for to set the variable to
14697 * @overwrite: whether to change the variable if it already exists
14699 * Sets the environment variable @variable in the provided list
14702 * Returns: (array zero-terminated=1) (transfer full): the
14703 * updated environment list. Free it using g_strfreev().
14709 * g_environ_unsetenv:
14710 * @envp: (allow-none) (array zero-terminated=1) (transfer full): an environment
14711 * list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()),
14712 * or %NULL for an empty environment list
14713 * @variable: the environment variable to remove, must not contain '='
14715 * Removes the environment variable @variable from the provided
14716 * environment @envp.
14718 * Returns: (array zero-terminated=1) (transfer full): the
14719 * updated environment list. Free it using g_strfreev().
14726 * @...: format string, followed by parameters to insert
14727 * into the format string (as with printf())
14729 * A convenience function/macro to log an error message.
14731 * This is not intended for end user error reporting. Use of #GError is
14732 * preferred for that instead, as it allows calling functions to perform actions
14733 * conditional on the type of error.
14735 * Error messages are always fatal, resulting in a call to
14736 * abort() to terminate the application. This function will
14737 * result in a core dump; don't use it for errors you expect.
14738 * Using this function indicates a bug in your program, i.e.
14739 * an assertion failure.
14741 * If g_log_default_handler() is used as the log handler function, a new-line
14742 * character will automatically be appended to @..., and need not be entered
14749 * @error: a #GError
14751 * Makes a copy of @error.
14753 * Returns: a new #GError
14759 * @error: a #GError
14761 * Frees a #GError and associated resources.
14767 * @error: (nullable): a #GError
14768 * @domain: an error domain
14769 * @code: an error code
14771 * Returns %TRUE if @error matches @domain and @code, %FALSE
14772 * otherwise. In particular, when @error is %NULL, %FALSE will
14775 * If @domain contains a `FAILED` (or otherwise generic) error code,
14776 * you should generally not check for it explicitly, but should
14777 * instead treat any not-explicitly-recognized error code as being
14778 * equivalent to the `FAILED` code. This way, if the domain is
14779 * extended in the future to provide a more specific error code for
14780 * a certain case, your code will still work.
14782 * Returns: whether @error has @domain and @code
14788 * @domain: error domain
14789 * @code: error code
14790 * @format: printf()-style format for error message
14791 * @...: parameters for message format
14793 * Creates a new #GError with the given @domain and @code,
14794 * and a message formatted with @format.
14796 * Returns: a new #GError
14801 * g_error_new_literal:
14802 * @domain: error domain
14803 * @code: error code
14804 * @message: error message
14806 * Creates a new #GError; unlike g_error_new(), @message is
14807 * not a printf()-style format string. Use this function if
14808 * @message contains text you don't have control over,
14809 * that could include printf() escape sequences.
14811 * Returns: a new #GError
14816 * g_error_new_valist:
14817 * @domain: error domain
14818 * @code: error code
14819 * @format: printf()-style format for error message
14820 * @args: #va_list of parameters for the message format
14822 * Creates a new #GError with the given @domain and @code,
14823 * and a message formatted with @format.
14825 * Returns: a new #GError
14831 * g_file_error_from_errno:
14832 * @err_no: an "errno" value
14834 * Gets a #GFileError constant based on the passed-in @err_no.
14835 * For example, if you pass in `EEXIST` this function returns
14836 * #G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably
14837 * assume that all #GFileError values will exist.
14839 * Normally a #GFileError value goes into a #GError returned
14840 * from a function that manipulates files. So you would use
14841 * g_file_error_from_errno() when constructing a #GError.
14843 * Returns: #GFileError corresponding to the given @errno
14848 * g_file_get_contents:
14849 * @filename: (type filename): name of a file to read contents from, in the GLib file name encoding
14850 * @contents: (out) (array length=length) (element-type guint8): location to store an allocated string, use g_free() to free
14851 * the returned string
14852 * @length: (allow-none): location to store length in bytes of the contents, or %NULL
14853 * @error: return location for a #GError, or %NULL
14855 * Reads an entire file into allocated memory, with good error
14858 * If the call was successful, it returns %TRUE and sets @contents to the file
14859 * contents and @length to the length of the file contents in bytes. The string
14860 * stored in @contents will be nul-terminated, so for text files you can pass
14861 * %NULL for the @length argument. If the call was not successful, it returns
14862 * %FALSE and sets @error. The error domain is #G_FILE_ERROR. Possible error
14863 * codes are those in the #GFileError enumeration. In the error case,
14864 * @contents is set to %NULL and @length is set to zero.
14866 * Returns: %TRUE on success, %FALSE if an error occurred
14872 * @tmpl: (type filename) (allow-none): Template for file name, as in
14873 * g_mkstemp(), basename only, or %NULL for a default template
14874 * @name_used: (out) (type filename): location to store actual name used,
14876 * @error: return location for a #GError
14878 * Opens a file for writing in the preferred directory for temporary
14879 * files (as returned by g_get_tmp_dir()).
14881 * @tmpl should be a string in the GLib file name encoding containing
14882 * a sequence of six 'X' characters, as the parameter to g_mkstemp().
14883 * However, unlike these functions, the template should only be a
14884 * basename, no directory components are allowed. If template is
14885 * %NULL, a default template is used.
14887 * Note that in contrast to g_mkstemp() (and mkstemp()) @tmpl is not
14888 * modified, and might thus be a read-only literal string.
14890 * Upon success, and if @name_used is non-%NULL, the actual name used
14891 * is returned in @name_used. This string should be freed with g_free()
14892 * when not needed any longer. The returned name is in the GLib file
14895 * Returns: A file handle (as from open()) to the file opened for
14896 * reading and writing. The file is opened in binary mode on platforms
14897 * where there is a difference. The file handle should be closed with
14898 * close(). In case of errors, -1 is returned and @error will be set.
14903 * g_file_read_link:
14904 * @filename: (type filename): the symbolic link
14905 * @error: return location for a #GError
14907 * Reads the contents of the symbolic link @filename like the POSIX
14908 * readlink() function. The returned string is in the encoding used
14909 * for filenames. Use g_filename_to_utf8() to convert it to UTF-8.
14911 * Returns: (type filename): A newly-allocated string with the contents of
14912 * the symbolic link, or %NULL if an error occurred.
14918 * g_file_set_contents:
14919 * @filename: (type filename): name of a file to write @contents to, in the GLib file name
14921 * @contents: (array length=length) (element-type guint8): string to write to the file
14922 * @length: length of @contents, or -1 if @contents is a nul-terminated string
14923 * @error: return location for a #GError, or %NULL
14925 * Writes all of @contents to a file named @filename, with good error checking.
14926 * If a file called @filename already exists it will be overwritten.
14928 * This write is atomic in the sense that it is first written to a temporary
14929 * file which is then renamed to the final name. Notes:
14931 * - On UNIX, if @filename already exists hard links to @filename will break.
14932 * Also since the file is recreated, existing permissions, access control
14933 * lists, metadata etc. may be lost. If @filename is a symbolic link,
14934 * the link itself will be replaced, not the linked file.
14936 * - On Windows renaming a file will not remove an existing file with the
14937 * new name, so on Windows there is a race condition between the existing
14938 * file being removed and the temporary file being renamed.
14940 * - On Windows there is no way to remove a file that is open to some
14941 * process, or mapped into memory. Thus, this function will fail if
14942 * @filename already exists and is open.
14944 * If the call was successful, it returns %TRUE. If the call was not successful,
14945 * it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR.
14946 * Possible error codes are those in the #GFileError enumeration.
14948 * Note that the name for the temporary file is constructed by appending up
14949 * to 7 characters to @filename.
14951 * Returns: %TRUE on success, %FALSE if an error occurred
14958 * @filename: (type filename): a filename to test in the
14959 * GLib file name encoding
14960 * @test: bitfield of #GFileTest flags
14962 * Returns %TRUE if any of the tests in the bitfield @test are
14963 * %TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)`
14964 * will return %TRUE if the file exists; the check whether it's a
14965 * directory doesn't matter since the existence test is %TRUE. With
14966 * the current set of available tests, there's no point passing in
14967 * more than one test at a time.
14969 * Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links,
14970 * so for a symbolic link to a regular file g_file_test() will return
14971 * %TRUE for both %G_FILE_TEST_IS_SYMLINK and %G_FILE_TEST_IS_REGULAR.
14973 * Note, that for a dangling symbolic link g_file_test() will return
14974 * %TRUE for %G_FILE_TEST_IS_SYMLINK and %FALSE for all other flags.
14976 * You should never use g_file_test() to test whether it is safe
14977 * to perform an operation, because there is always the possibility
14978 * of the condition changing before you actually perform the operation.
14979 * For example, you might think you could use %G_FILE_TEST_IS_SYMLINK
14980 * to know whether it is safe to write to a file without being
14981 * tricked into writing into a different location. It doesn't work!
14982 * |[<!-- language="C" -->
14984 * if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
14986 * fd = g_open (filename, O_WRONLY);
14991 * Another thing to note is that %G_FILE_TEST_EXISTS and
14992 * %G_FILE_TEST_IS_EXECUTABLE are implemented using the access()
14993 * system call. This usually doesn't matter, but if your program
14994 * is setuid or setgid it means that these tests will give you
14995 * the answer for the real user ID and group ID, rather than the
14996 * effective user ID and group ID.
14998 * On Windows, there are no symlinks, so testing for
14999 * %G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for
15000 * %G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and
15001 * its name indicates that it is executable, checking for well-known
15002 * extensions and those listed in the `PATHEXT` environment variable.
15004 * Returns: whether a test was %TRUE
15009 * g_filename_display_basename:
15010 * @filename: (type filename): an absolute pathname in the
15011 * GLib file name encoding
15013 * Returns the display basename for the particular filename, guaranteed
15014 * to be valid UTF-8. The display name might not be identical to the filename,
15015 * for instance there might be problems converting it to UTF-8, and some files
15016 * can be translated in the display.
15018 * If GLib cannot make sense of the encoding of @filename, as a last resort it
15019 * replaces unknown characters with U+FFFD, the Unicode replacement character.
15020 * You can search the result for the UTF-8 encoding of this character (which is
15021 * "\357\277\275" in octal notation) to find out if @filename was in an invalid
15024 * You must pass the whole absolute pathname to this functions so that
15025 * translation of well known locations can be done.
15027 * This function is preferred over g_filename_display_name() if you know the
15028 * whole path, as it allows translation.
15030 * Returns: a newly allocated string containing
15031 * a rendition of the basename of the filename in valid UTF-8
15037 * g_filename_display_name:
15038 * @filename: (type filename): a pathname hopefully in the
15039 * GLib file name encoding
15041 * Converts a filename into a valid UTF-8 string. The conversion is
15042 * not necessarily reversible, so you should keep the original around
15043 * and use the return value of this function only for display purposes.
15044 * Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL
15045 * even if the filename actually isn't in the GLib file name encoding.
15047 * If GLib cannot make sense of the encoding of @filename, as a last resort it
15048 * replaces unknown characters with U+FFFD, the Unicode replacement character.
15049 * You can search the result for the UTF-8 encoding of this character (which is
15050 * "\357\277\275" in octal notation) to find out if @filename was in an invalid
15053 * If you know the whole pathname of the file you should use
15054 * g_filename_display_basename(), since that allows location-based
15055 * translation of filenames.
15057 * Returns: a newly allocated string containing
15058 * a rendition of the filename in valid UTF-8
15064 * g_filename_from_uri:
15065 * @uri: a uri describing a filename (escaped, encoded in ASCII).
15066 * @hostname: (out) (optional) (nullable): Location to store hostname for the
15068 * If there is no hostname in the URI, %NULL will be
15069 * stored in this location.
15070 * @error: location to store the error occurring, or %NULL to ignore
15071 * errors. Any of the errors in #GConvertError may occur.
15073 * Converts an escaped ASCII-encoded URI to a local filename in the
15074 * encoding used for filenames.
15076 * Returns: (type filename): a newly-allocated string holding
15077 * the resulting filename, or %NULL on an error.
15082 * g_filename_from_utf8:
15083 * @utf8string: a UTF-8 encoded string.
15084 * @len: the length of the string, or -1 if the string is
15086 * @bytes_read: (out) (optional): location to store the number of bytes in
15087 * the input string that were successfully converted, or %NULL.
15088 * Even if the conversion was successful, this may be
15089 * less than @len if there were partial characters
15090 * at the end of the input. If the error
15091 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
15092 * stored will the byte offset after the last valid
15094 * @bytes_written: (out): the number of bytes stored in the output buffer (not
15095 * including the terminating nul).
15096 * @error: location to store the error occurring, or %NULL to ignore
15097 * errors. Any of the errors in #GConvertError may occur.
15099 * Converts a string from UTF-8 to the encoding GLib uses for
15100 * filenames. Note that on Windows GLib uses UTF-8 for filenames;
15101 * on other platforms, this function indirectly depends on the
15102 * [current locale][setlocale].
15104 * Returns: (array length=bytes_written) (element-type guint8) (transfer full):
15105 * The converted string, or %NULL on an error.
15110 * g_filename_to_uri:
15111 * @filename: (type filename): an absolute filename specified in the GLib file
15112 * name encoding, which is the on-disk file name bytes on Unix, and UTF-8
15114 * @hostname: (allow-none): A UTF-8 encoded hostname, or %NULL for none.
15115 * @error: location to store the error occurring, or %NULL to ignore
15116 * errors. Any of the errors in #GConvertError may occur.
15118 * Converts an absolute filename to an escaped ASCII-encoded URI, with the path
15119 * component following Section 3.3. of RFC 2396.
15121 * Returns: a newly-allocated string holding the resulting
15122 * URI, or %NULL on an error.
15127 * g_filename_to_utf8:
15128 * @opsysstring: (type filename): a string in the encoding for filenames
15129 * @len: the length of the string, or -1 if the string is
15130 * nul-terminated (Note that some encodings may allow nul
15131 * bytes to occur inside strings. In that case, using -1
15132 * for the @len parameter is unsafe)
15133 * @bytes_read: (out) (optional): location to store the number of bytes in the
15134 * input string that were successfully converted, or %NULL.
15135 * Even if the conversion was successful, this may be
15136 * less than @len if there were partial characters
15137 * at the end of the input. If the error
15138 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
15139 * stored will the byte offset after the last valid
15141 * @bytes_written: (out) (optional): the number of bytes stored in the output
15142 * buffer (not including the terminating nul).
15143 * @error: location to store the error occurring, or %NULL to ignore
15144 * errors. Any of the errors in #GConvertError may occur.
15146 * Converts a string which is in the encoding used by GLib for
15147 * filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
15148 * for filenames; on other platforms, this function indirectly depends on
15149 * the [current locale][setlocale].
15151 * Returns: The converted string, or %NULL on an error.
15156 * g_find_program_in_path:
15157 * @program: (type filename): a program name in the GLib file name encoding
15159 * Locates the first executable named @program in the user's path, in the
15160 * same way that execvp() would locate it. Returns an allocated string
15161 * with the absolute path name, or %NULL if the program is not found in
15162 * the path. If @program is already an absolute path, returns a copy of
15163 * @program if @program exists and is executable, and %NULL otherwise.
15165 * On Windows, if @program does not have a file type suffix, tries
15166 * with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
15167 * the `PATHEXT` environment variable.
15169 * On Windows, it looks for the file in the same way as CreateProcess()
15170 * would. This means first in the directory where the executing
15171 * program was loaded from, then in the current directory, then in the
15172 * Windows 32-bit system directory, then in the Windows directory, and
15173 * finally in the directories in the `PATH` environment variable. If
15174 * the program is found, the return value contains the full name
15175 * including the type suffix.
15177 * Returns: (type filename): a newly-allocated string with the absolute path,
15184 * @filename: (type filename): a pathname in the GLib file name encoding
15185 * (UTF-8 on Windows)
15186 * @mode: a string describing the mode in which the file should be opened
15188 * A wrapper for the stdio fopen() function. The fopen() function
15189 * opens a file and associates a new stream with it.
15191 * Because file descriptors are specific to the C library on Windows,
15192 * and a file descriptor is part of the FILE struct, the FILE* returned
15193 * by this function makes sense only to functions in the same C library.
15194 * Thus if the GLib-using code uses a different C library than GLib does,
15195 * the FILE* returned by this function cannot be passed to C library
15196 * functions like fprintf() or fread().
15198 * See your C library manual for more details about fopen().
15200 * Returns: A FILE* if the file was successfully opened, or %NULL if
15201 * an error occurred
15208 * @size: a size in bytes
15210 * Formats a size (for example the size of a file) into a human readable
15211 * string. Sizes are rounded to the nearest size prefix (kB, MB, GB)
15212 * and are displayed rounded to the nearest tenth. E.g. the file size
15213 * 3292528 bytes will be converted into the string "3.2 MB".
15215 * The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).
15217 * This string should be freed with g_free() when not needed any longer.
15219 * See g_format_size_full() for more options about how the size might be
15222 * Returns: a newly-allocated formatted string containing a human readable
15229 * g_format_size_for_display:
15230 * @size: a size in bytes
15232 * Formats a size (for example the size of a file) into a human
15233 * readable string. Sizes are rounded to the nearest size prefix
15234 * (KB, MB, GB) and are displayed rounded to the nearest tenth.
15235 * E.g. the file size 3292528 bytes will be converted into the
15238 * The prefix units base is 1024 (i.e. 1 KB is 1024 bytes).
15240 * This string should be freed with g_free() when not needed any longer.
15242 * Returns: a newly-allocated formatted string containing a human
15243 * readable file size
15245 * Deprecated: 2.30: This function is broken due to its use of SI
15246 * suffixes to denote IEC units. Use g_format_size() instead.
15251 * g_format_size_full:
15252 * @size: a size in bytes
15253 * @flags: #GFormatSizeFlags to modify the output
15257 * This function is similar to g_format_size() but allows for flags
15258 * that modify the output. See #GFormatSizeFlags.
15260 * Returns: a newly-allocated formatted string containing a human
15261 * readable file size
15268 * @file: (not nullable): the stream to write to.
15269 * @format: a standard printf() format string, but notice
15270 * [string precision pitfalls][string-precision]
15271 * @...: the arguments to insert in the output.
15273 * An implementation of the standard fprintf() function which supports
15274 * positional parameters, as specified in the Single Unix Specification.
15276 * Returns: the number of bytes printed.
15283 * @mem: (allow-none): the memory to free
15285 * Frees the memory pointed to by @mem.
15287 * If @mem is %NULL it simply returns, so there is no need to check @mem
15288 * against %NULL before calling this function.
15294 * @filename: (type filename): a pathname in the GLib file name encoding
15295 * (UTF-8 on Windows)
15296 * @mode: a string describing the mode in which the file should be opened
15297 * @stream: (allow-none): an existing stream which will be reused, or %NULL
15299 * A wrapper for the POSIX freopen() function. The freopen() function
15300 * opens a file and associates it with an existing stream.
15302 * See your C library manual for more details about freopen().
15304 * Returns: A FILE* if the file was successfully opened, or %NULL if
15305 * an error occurred.
15311 * g_get_application_name:
15313 * Gets a human-readable name for the application, as set by
15314 * g_set_application_name(). This name should be localized if
15315 * possible, and is intended for display to the user. Contrast with
15316 * g_get_prgname(), which gets a non-localized name. If
15317 * g_set_application_name() has not been called, returns the result of
15318 * g_get_prgname() (which may be %NULL if g_set_prgname() has also not
15321 * Returns: human-readable application name. may return %NULL
15328 * @charset: (out) (optional) (transfer none): return location for character set
15331 * Obtains the character set for the [current locale][setlocale]; you
15332 * might use this character set as an argument to g_convert(), to convert
15333 * from the current locale's encoding to some other encoding. (Frequently
15334 * g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.)
15336 * On Windows the character set returned by this function is the
15337 * so-called system default ANSI code-page. That is the character set
15338 * used by the "narrow" versions of C library and Win32 functions that
15339 * handle file names. It might be different from the character set
15340 * used by the C library's current locale.
15342 * The return value is %TRUE if the locale's encoding is UTF-8, in that
15343 * case you can perhaps avoid calling g_convert().
15345 * The string returned in @charset is not allocated, and should not be
15348 * Returns: %TRUE if the returned charset is UTF-8
15355 * Gets the character set for the current locale.
15357 * Returns: a newly allocated string containing the name
15358 * of the character set. This string must be freed with g_free().
15363 * g_get_current_dir:
15365 * Gets the current directory.
15367 * The returned string should be freed when no longer needed.
15368 * The encoding of the returned string is system defined.
15369 * On Windows, it is always UTF-8.
15371 * Since GLib 2.40, this function will return the value of the "PWD"
15372 * environment variable if it is set and it happens to be the same as
15373 * the current directory. This can make a difference in the case that
15374 * the current directory is the target of a symbolic link.
15376 * Returns: (type filename): the current directory
15381 * g_get_current_time:
15382 * @result: #GTimeVal structure in which to store current time.
15384 * Equivalent to the UNIX gettimeofday() function, but portable.
15386 * You may find g_get_real_time() to be more convenient.
15393 * Gets the list of environment variables for the current process.
15395 * The list is %NULL terminated and each item in the list is of the
15396 * form 'NAME=VALUE'.
15398 * This is equivalent to direct access to the 'environ' global variable,
15401 * The return value is freshly allocated and it should be freed with
15402 * g_strfreev() when it is no longer needed.
15404 * Returns: (array zero-terminated=1) (transfer full): the list of
15405 * environment variables
15411 * g_get_filename_charsets:
15412 * @charsets: return location for the %NULL-terminated list of encoding names
15414 * Determines the preferred character sets used for filenames.
15415 * The first character set from the @charsets is the filename encoding, the
15416 * subsequent character sets are used when trying to generate a displayable
15417 * representation of a filename, see g_filename_display_name().
15419 * On Unix, the character sets are determined by consulting the
15420 * environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`.
15421 * On Windows, the character set used in the GLib API is always UTF-8
15422 * and said environment variables have no effect.
15424 * `G_FILENAME_ENCODING` may be set to a comma-separated list of
15425 * character set names. The special token "\@locale" is taken
15426 * to mean the character set for the [current locale][setlocale].
15427 * If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is,
15428 * the character set of the current locale is taken as the filename
15429 * encoding. If neither environment variable is set, UTF-8 is taken
15430 * as the filename encoding, but the character set of the current locale
15431 * is also put in the list of encodings.
15433 * The returned @charsets belong to GLib and must not be freed.
15435 * Note that on Unix, regardless of the locale character set or
15436 * `G_FILENAME_ENCODING` value, the actual file names present
15437 * on a system might be in any random encoding or just gibberish.
15439 * Returns: %TRUE if the filename encoding is UTF-8.
15447 * Gets the current user's home directory.
15449 * As with most UNIX tools, this function will return the value of the
15450 * `HOME` environment variable if it is set to an existing absolute path
15451 * name, falling back to the `passwd` file in the case that it is unset.
15453 * If the path given in `HOME` is non-absolute, does not exist, or is
15454 * not a directory, the result is undefined.
15456 * Before version 2.36 this function would ignore the `HOME` environment
15457 * variable, taking the value from the `passwd` database instead. This was
15458 * changed to increase the compatibility of GLib with other programs (and
15459 * the XDG basedir specification) and to increase testability of programs
15460 * based on GLib (by making it easier to run them from test frameworks).
15462 * If your program has a strong requirement for either the new or the
15463 * old behaviour (and if you don't wish to increase your GLib
15464 * dependency to ensure that the new behaviour is in effect) then you
15465 * should either directly check the `HOME` environment variable yourself
15466 * or unset it before calling any functions in GLib.
15468 * Returns: (type filename): the current user's home directory
15475 * Return a name for the machine.
15477 * The returned name is not necessarily a fully-qualified domain name,
15478 * or even present in DNS or some other name service at all. It need
15479 * not even be unique on your local network or site, but usually it
15480 * is. Callers should not rely on the return value having any specific
15481 * properties like uniqueness for security purposes. Even if the name
15482 * of the machine is changed while an application is running, the
15483 * return value from this function does not change. The returned
15484 * string is owned by GLib and should not be modified or freed. If no
15485 * name can be determined, a default fixed string "localhost" is
15488 * Returns: the host name of the machine.
15494 * g_get_language_names:
15496 * Computes a list of applicable locale names, which can be used to
15497 * e.g. construct locale-dependent filenames or search paths. The returned
15498 * list is sorted from most desirable to least desirable and always contains
15499 * the default locale "C".
15501 * For example, if LANGUAGE=de:en_US, then the returned list is
15502 * "de", "en_US", "en", "C".
15504 * This function consults the environment variables `LANGUAGE`, `LC_ALL`,
15505 * `LC_MESSAGES` and `LANG` to find the list of locales specified by the
15508 * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib
15509 * that must not be modified or freed.
15515 * g_get_locale_variants:
15516 * @locale: a locale identifier
15518 * Returns a list of derived variants of @locale, which can be used to
15519 * e.g. construct locale-dependent filenames or search paths. The returned
15520 * list is sorted from most desirable to least desirable.
15521 * This function handles territory, charset and extra locale modifiers.
15523 * For example, if @locale is "fr_BE", then the returned list
15524 * is "fr_BE", "fr".
15526 * If you need the list of variants for the current locale,
15527 * use g_get_language_names().
15529 * Returns: (transfer full) (array zero-terminated=1) (element-type utf8): a newly
15530 * allocated array of newly allocated strings with the locale variants. Free with
15537 * g_get_monotonic_time:
15539 * Queries the system monotonic time.
15541 * The monotonic clock will always increase and doesn't suffer
15542 * discontinuities when the user (or NTP) changes the system time. It
15543 * may or may not continue to tick during times where the machine is
15546 * We try to use the clock that corresponds as closely as possible to
15547 * the passage of time as measured by system calls such as poll() but it
15548 * may not always be possible to do this.
15550 * Returns: the monotonic time, in microseconds
15556 * g_get_num_processors:
15558 * Determine the approximate number of threads that the system will
15559 * schedule simultaneously for this process. This is intended to be
15560 * used as a parameter to g_thread_pool_new() for CPU bound tasks and
15563 * Returns: Number of schedulable threads, always greater than 0
15571 * Gets the name of the program. This name should not be localized,
15572 * in contrast to g_get_application_name().
15574 * If you are using GDK or GTK+ the program name is set in gdk_init(),
15575 * which is called by gtk_init(). The program name is found by taking
15576 * the last component of @argv[0].
15578 * Returns: the name of the program. The returned string belongs
15579 * to GLib and must not be modified or freed.
15586 * Gets the real name of the user. This usually comes from the user's
15587 * entry in the `passwd` file. The encoding of the returned string is
15588 * system-defined. (On Windows, it is, however, always UTF-8.) If the
15589 * real user name cannot be determined, the string "Unknown" is
15592 * Returns: (type filename): the user's real name.
15599 * Queries the system wall-clock time.
15601 * This call is functionally equivalent to g_get_current_time() except
15602 * that the return value is often more convenient than dealing with a
15605 * You should only use this call if you are actually interested in the real
15606 * wall-clock time. g_get_monotonic_time() is probably more useful for
15607 * measuring intervals.
15609 * Returns: the number of microseconds since January 1, 1970 UTC.
15615 * g_get_system_config_dirs:
15617 * Returns an ordered list of base directories in which to access
15618 * system-wide configuration information.
15620 * On UNIX platforms this is determined using the mechanisms described
15622 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
15623 * In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`.
15625 * On Windows is the directory that contains application data for all users.
15626 * A typical path is C:\Documents and Settings\All Users\Application Data.
15627 * This folder is used for application data that is not user specific.
15628 * For example, an application can store a spell-check dictionary, a database
15629 * of clip art, or a log file in the CSIDL_COMMON_APPDATA folder.
15630 * This information will not roam and is available to anyone using the computer.
15632 * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
15633 * a %NULL-terminated array of strings owned by GLib that must not be
15634 * modified or freed.
15640 * g_get_system_data_dirs:
15642 * Returns an ordered list of base directories in which to access
15643 * system-wide application data.
15645 * On UNIX platforms this is determined using the mechanisms described
15647 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec)
15648 * In this case the list of directories retrieved will be XDG_DATA_DIRS.
15650 * On Windows the first elements in the list are the Application Data
15651 * and Documents folders for All Users. (These can be determined only
15652 * on Windows 2000 or later and are not present in the list on other
15653 * Windows versions.) See documentation for CSIDL_COMMON_APPDATA and
15654 * CSIDL_COMMON_DOCUMENTS.
15656 * Then follows the "share" subfolder in the installation folder for
15657 * the package containing the DLL that calls this function, if it can
15660 * Finally the list contains the "share" subfolder in the installation
15661 * folder for GLib, and in the installation folder for the package the
15662 * application's .exe file belongs to.
15664 * The installation folders above are determined by looking up the
15665 * folder where the module (DLL or EXE) in question is located. If the
15666 * folder's name is "bin", its parent is used, otherwise the folder
15669 * Note that on Windows the returned list can vary depending on where
15670 * this function is called.
15672 * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
15673 * a %NULL-terminated array of strings owned by GLib that must not be
15674 * modified or freed.
15682 * Gets the directory to use for temporary files.
15684 * On UNIX, this is taken from the `TMPDIR` environment variable.
15685 * If the variable is not set, `P_tmpdir` is
15686 * used, as defined by the system C library. Failing that, a
15687 * hard-coded default of "/tmp" is returned.
15689 * On Windows, the `TEMP` environment variable is used, with the
15690 * root directory of the Windows installation (eg: "C:\") used
15693 * The encoding of the returned string is system-defined. On Windows,
15694 * it is always UTF-8. The return value is never %NULL or the empty
15697 * Returns: (type filename): the directory to use for temporary files.
15702 * g_get_user_cache_dir:
15704 * Returns a base directory in which to store non-essential, cached
15705 * data specific to particular user.
15707 * On UNIX platforms this is determined using the mechanisms described
15709 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
15710 * In this case the directory retrieved will be XDG_CACHE_HOME.
15712 * On Windows is the directory that serves as a common repository for
15713 * temporary Internet files. A typical path is
15714 * C:\Documents and Settings\username\Local Settings\Temporary Internet Files.
15715 * See documentation for CSIDL_INTERNET_CACHE.
15717 * Returns: (type filename): a string owned by GLib that must not be modified
15724 * g_get_user_config_dir:
15726 * Returns a base directory in which to store user-specific application
15727 * configuration information such as user preferences and settings.
15729 * On UNIX platforms this is determined using the mechanisms described
15731 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
15732 * In this case the directory retrieved will be `XDG_CONFIG_HOME`.
15734 * On Windows this is the folder to use for local (as opposed to
15735 * roaming) application data. See documentation for
15736 * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
15737 * what g_get_user_data_dir() returns.
15739 * Returns: (type filename): a string owned by GLib that must not be modified
15746 * g_get_user_data_dir:
15748 * Returns a base directory in which to access application data such
15749 * as icons that is customized for a particular user.
15751 * On UNIX platforms this is determined using the mechanisms described
15753 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
15754 * In this case the directory retrieved will be `XDG_DATA_HOME`.
15756 * On Windows this is the folder to use for local (as opposed to
15757 * roaming) application data. See documentation for
15758 * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
15759 * what g_get_user_config_dir() returns.
15761 * Returns: (type filename): a string owned by GLib that must not be modified
15770 * Gets the user name of the current user. The encoding of the returned
15771 * string is system-defined. On UNIX, it might be the preferred file name
15772 * encoding, or something else, and there is no guarantee that it is even
15773 * consistent on a machine. On Windows, it is always UTF-8.
15775 * Returns: (type filename): the user name of the current user.
15780 * g_get_user_runtime_dir:
15782 * Returns a directory that is unique to the current user on the local
15785 * On UNIX platforms this is determined using the mechanisms described
15787 * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
15788 * This is the directory
15789 * specified in the `XDG_RUNTIME_DIR` environment variable.
15790 * In the case that this variable is not set, we return the value of
15791 * g_get_user_cache_dir(), after verifying that it exists.
15793 * On Windows this is the folder to use for local (as opposed to
15794 * roaming) application data. See documentation for
15795 * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
15796 * what g_get_user_config_dir() returns.
15798 * Returns: (type filename): a string owned by GLib that must not be
15799 * modified or freed.
15805 * g_get_user_special_dir:
15806 * @directory: the logical id of special directory
15808 * Returns the full path of a special directory using its logical id.
15810 * On UNIX this is done using the XDG special user directories.
15811 * For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP
15812 * falls back to `$HOME/Desktop` when XDG special user directories have
15815 * Depending on the platform, the user might be able to change the path
15816 * of the special directory without requiring the session to restart; GLib
15817 * will not reflect any change once the special directories are loaded.
15819 * Returns: (type filename): the path to the specified special directory, or
15820 * %NULL if the logical id was not found. The returned string is owned by
15821 * GLib and should not be modified or freed.
15828 * @variable: the environment variable to get
15830 * Returns the value of an environment variable.
15832 * On UNIX, the name and value are byte strings which might or might not
15833 * be in some consistent character set and encoding. On Windows, they are
15835 * On Windows, in case the environment variable's value contains
15836 * references to other environment variables, they are expanded.
15838 * Returns: the value of the environment variable, or %NULL if
15839 * the environment variable is not found. The returned string
15840 * may be overwritten by the next call to g_getenv(), g_setenv()
15846 * g_hash_table_add:
15847 * @hash_table: a #GHashTable
15848 * @key: a key to insert
15850 * This is a convenience function for using a #GHashTable as a set. It
15851 * is equivalent to calling g_hash_table_replace() with @key as both the
15852 * key and the value.
15854 * When a hash table only ever contains keys that have themselves as the
15855 * corresponding value it is able to be stored more efficiently. See
15856 * the discussion in the section description.
15858 * Returns: %TRUE if the key did not exist yet
15864 * g_hash_table_contains:
15865 * @hash_table: a #GHashTable
15866 * @key: a key to check
15868 * Checks if @key is in @hash_table.
15870 * Returns: %TRUE if @key is in @hash_table, %FALSE otherwise.
15876 * g_hash_table_destroy:
15877 * @hash_table: a #GHashTable
15879 * Destroys all keys and values in the #GHashTable and decrements its
15880 * reference count by 1. If keys and/or values are dynamically allocated,
15881 * you should either free them first or create the #GHashTable with destroy
15882 * notifiers using g_hash_table_new_full(). In the latter case the destroy
15883 * functions you supplied will be called on all keys and values during the
15884 * destruction phase.
15889 * g_hash_table_find:
15890 * @hash_table: a #GHashTable
15891 * @predicate: function to test the key/value pairs for a certain property
15892 * @user_data: user data to pass to the function
15894 * Calls the given function for key/value pairs in the #GHashTable
15895 * until @predicate returns %TRUE. The function is passed the key
15896 * and value of each pair, and the given @user_data parameter. The
15897 * hash table may not be modified while iterating over it (you can't
15898 * add/remove items).
15900 * Note, that hash tables are really only optimized for forward
15901 * lookups, i.e. g_hash_table_lookup(). So code that frequently issues
15902 * g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of
15903 * once per every entry in a hash table) should probably be reworked
15904 * to use additional or different data structures for reverse lookups
15905 * (keep in mind that an O(n) find/foreach operation issued for all n
15906 * values in a hash table ends up needing O(n*n) operations).
15908 * Returns: (nullable): The value of the first key/value pair is returned,
15909 * for which @predicate evaluates to %TRUE. If no pair with the
15910 * requested property is found, %NULL is returned.
15916 * g_hash_table_foreach:
15917 * @hash_table: a #GHashTable
15918 * @func: the function to call for each key/value pair
15919 * @user_data: user data to pass to the function
15921 * Calls the given function for each of the key/value pairs in the
15922 * #GHashTable. The function is passed the key and value of each
15923 * pair, and the given @user_data parameter. The hash table may not
15924 * be modified while iterating over it (you can't add/remove
15925 * items). To remove all items matching a predicate, use
15926 * g_hash_table_foreach_remove().
15928 * See g_hash_table_find() for performance caveats for linear
15929 * order searches in contrast to g_hash_table_lookup().
15934 * g_hash_table_foreach_remove:
15935 * @hash_table: a #GHashTable
15936 * @func: the function to call for each key/value pair
15937 * @user_data: user data to pass to the function
15939 * Calls the given function for each key/value pair in the
15940 * #GHashTable. If the function returns %TRUE, then the key/value
15941 * pair is removed from the #GHashTable. If you supplied key or
15942 * value destroy functions when creating the #GHashTable, they are
15943 * used to free the memory allocated for the removed keys and values.
15945 * See #GHashTableIter for an alternative way to loop over the
15946 * key/value pairs in the hash table.
15948 * Returns: the number of key/value pairs removed
15953 * g_hash_table_foreach_steal:
15954 * @hash_table: a #GHashTable
15955 * @func: the function to call for each key/value pair
15956 * @user_data: user data to pass to the function
15958 * Calls the given function for each key/value pair in the
15959 * #GHashTable. If the function returns %TRUE, then the key/value
15960 * pair is removed from the #GHashTable, but no key or value
15961 * destroy functions are called.
15963 * See #GHashTableIter for an alternative way to loop over the
15964 * key/value pairs in the hash table.
15966 * Returns: the number of key/value pairs removed.
15971 * g_hash_table_freeze:
15972 * @hash_table: a #GHashTable
15974 * This function is deprecated and will be removed in the next major
15975 * release of GLib. It does nothing.
15980 * g_hash_table_get_keys:
15981 * @hash_table: a #GHashTable
15983 * Retrieves every key inside @hash_table. The returned data is valid
15984 * until changes to the hash release those keys.
15986 * This iterates over every entry in the hash table to build its return value.
15987 * To iterate over the entries in a #GHashTable more efficiently, use a
15990 * Returns: (transfer container): a #GList containing all the keys
15991 * inside the hash table. The content of the list is owned by the
15992 * hash table and should not be modified or freed. Use g_list_free()
15993 * when done using the list.
15999 * g_hash_table_get_keys_as_array:
16000 * @hash_table: a #GHashTable
16001 * @length: (out): the length of the returned array
16003 * Retrieves every key inside @hash_table, as an array.
16005 * The returned array is %NULL-terminated but may contain %NULL as a
16006 * key. Use @length to determine the true length if it's possible that
16007 * %NULL was used as the value for a key.
16009 * Note: in the common case of a string-keyed #GHashTable, the return
16010 * value of this function can be conveniently cast to (const gchar **).
16012 * This iterates over every entry in the hash table to build its return value.
16013 * To iterate over the entries in a #GHashTable more efficiently, use a
16016 * You should always free the return result with g_free(). In the
16017 * above-mentioned case of a string-keyed hash table, it may be
16018 * appropriate to use g_strfreev() if you call g_hash_table_steal_all()
16019 * first to transfer ownership of the keys.
16021 * Returns: (array length=length) (transfer container): a
16022 * %NULL-terminated array containing each key from the table.
16028 * g_hash_table_get_values:
16029 * @hash_table: a #GHashTable
16031 * Retrieves every value inside @hash_table. The returned data
16032 * is valid until @hash_table is modified.
16034 * This iterates over every entry in the hash table to build its return value.
16035 * To iterate over the entries in a #GHashTable more efficiently, use a
16038 * Returns: (transfer container): a #GList containing all the values
16039 * inside the hash table. The content of the list is owned by the
16040 * hash table and should not be modified or freed. Use g_list_free()
16041 * when done using the list.
16047 * g_hash_table_insert:
16048 * @hash_table: a #GHashTable
16049 * @key: a key to insert
16050 * @value: the value to associate with the key
16052 * Inserts a new key and value into a #GHashTable.
16054 * If the key already exists in the #GHashTable its current
16055 * value is replaced with the new value. If you supplied a
16056 * @value_destroy_func when creating the #GHashTable, the old
16057 * value is freed using that function. If you supplied a
16058 * @key_destroy_func when creating the #GHashTable, the passed
16059 * key is freed using that function.
16061 * Returns: %TRUE if the key did not exist yet
16066 * g_hash_table_iter_get_hash_table:
16067 * @iter: an initialized #GHashTableIter
16069 * Returns the #GHashTable associated with @iter.
16071 * Returns: the #GHashTable associated with @iter.
16077 * g_hash_table_iter_init:
16078 * @iter: an uninitialized #GHashTableIter
16079 * @hash_table: a #GHashTable
16081 * Initializes a key/value pair iterator and associates it with
16082 * @hash_table. Modifying the hash table after calling this function
16083 * invalidates the returned iterator.
16084 * |[<!-- language="C" -->
16085 * GHashTableIter iter;
16086 * gpointer key, value;
16088 * g_hash_table_iter_init (&iter, hash_table);
16089 * while (g_hash_table_iter_next (&iter, &key, &value))
16091 * // do something with key and value
16100 * g_hash_table_iter_next:
16101 * @iter: an initialized #GHashTableIter
16102 * @key: (out) (optional): a location to store the key
16103 * @value: (out) (nullable) (optional): a location to store the value
16105 * Advances @iter and retrieves the key and/or value that are now
16106 * pointed to as a result of this advancement. If %FALSE is returned,
16107 * @key and @value are not set, and the iterator becomes invalid.
16109 * Returns: %FALSE if the end of the #GHashTable has been reached.
16115 * g_hash_table_iter_remove:
16116 * @iter: an initialized #GHashTableIter
16118 * Removes the key/value pair currently pointed to by the iterator
16119 * from its associated #GHashTable. Can only be called after
16120 * g_hash_table_iter_next() returned %TRUE, and cannot be called
16121 * more than once for the same key/value pair.
16123 * If the #GHashTable was created using g_hash_table_new_full(),
16124 * the key and value are freed using the supplied destroy functions,
16125 * otherwise you have to make sure that any dynamically allocated
16126 * values are freed yourself.
16128 * It is safe to continue iterating the #GHashTable afterward:
16129 * |[<!-- language="C" -->
16130 * while (g_hash_table_iter_next (&iter, &key, &value))
16133 * g_hash_table_iter_remove (&iter);
16142 * g_hash_table_iter_replace:
16143 * @iter: an initialized #GHashTableIter
16144 * @value: the value to replace with
16146 * Replaces the value currently pointed to by the iterator
16147 * from its associated #GHashTable. Can only be called after
16148 * g_hash_table_iter_next() returned %TRUE.
16150 * If you supplied a @value_destroy_func when creating the
16151 * #GHashTable, the old value is freed using that function.
16158 * g_hash_table_iter_steal:
16159 * @iter: an initialized #GHashTableIter
16161 * Removes the key/value pair currently pointed to by the
16162 * iterator from its associated #GHashTable, without calling
16163 * the key and value destroy functions. Can only be called
16164 * after g_hash_table_iter_next() returned %TRUE, and cannot
16165 * be called more than once for the same key/value pair.
16172 * g_hash_table_lookup:
16173 * @hash_table: a #GHashTable
16174 * @key: the key to look up
16176 * Looks up a key in a #GHashTable. Note that this function cannot
16177 * distinguish between a key that is not present and one which is present
16178 * and has the value %NULL. If you need this distinction, use
16179 * g_hash_table_lookup_extended().
16181 * Returns: (nullable): the associated value, or %NULL if the key is not found
16186 * g_hash_table_lookup_extended:
16187 * @hash_table: a #GHashTable
16188 * @lookup_key: the key to look up
16189 * @orig_key: (out) (optional) (nullable): return location for the original key
16190 * @value: (out) (optional) (nullable): return location for the value associated
16193 * Looks up a key in the #GHashTable, returning the original key and the
16194 * associated value and a #gboolean which is %TRUE if the key was found. This
16195 * is useful if you need to free the memory allocated for the original key,
16196 * for example before calling g_hash_table_remove().
16198 * You can actually pass %NULL for @lookup_key to test
16199 * whether the %NULL key exists, provided the hash and equal functions
16200 * of @hash_table are %NULL-safe.
16202 * Returns: %TRUE if the key was found in the #GHashTable
16207 * g_hash_table_new:
16208 * @hash_func: a function to create a hash value from a key
16209 * @key_equal_func: a function to check two keys for equality
16211 * Creates a new #GHashTable with a reference count of 1.
16213 * Hash values returned by @hash_func are used to determine where keys
16214 * are stored within the #GHashTable data structure. The g_direct_hash(),
16215 * g_int_hash(), g_int64_hash(), g_double_hash() and g_str_hash()
16216 * functions are provided for some common types of keys.
16217 * If @hash_func is %NULL, g_direct_hash() is used.
16219 * @key_equal_func is used when looking up keys in the #GHashTable.
16220 * The g_direct_equal(), g_int_equal(), g_int64_equal(), g_double_equal()
16221 * and g_str_equal() functions are provided for the most common types
16222 * of keys. If @key_equal_func is %NULL, keys are compared directly in
16223 * a similar fashion to g_direct_equal(), but without the overhead of
16226 * Returns: a new #GHashTable
16231 * g_hash_table_new_full:
16232 * @hash_func: a function to create a hash value from a key
16233 * @key_equal_func: a function to check two keys for equality
16234 * @key_destroy_func: (nullable): a function to free the memory allocated for the key
16235 * used when removing the entry from the #GHashTable, or %NULL
16236 * if you don't want to supply such a function.
16237 * @value_destroy_func: (nullable): a function to free the memory allocated for the
16238 * value used when removing the entry from the #GHashTable, or %NULL
16239 * if you don't want to supply such a function.
16241 * Creates a new #GHashTable like g_hash_table_new() with a reference
16242 * count of 1 and allows to specify functions to free the memory
16243 * allocated for the key and value that get called when removing the
16244 * entry from the #GHashTable.
16246 * Since version 2.42 it is permissible for destroy notify functions to
16247 * recursively remove further items from the hash table. This is only
16248 * permissible if the application still holds a reference to the hash table.
16249 * This means that you may need to ensure that the hash table is empty by
16250 * calling g_hash_table_remove_all before releasing the last reference using
16251 * g_hash_table_unref().
16253 * Returns: a new #GHashTable
16258 * g_hash_table_ref:
16259 * @hash_table: a valid #GHashTable
16261 * Atomically increments the reference count of @hash_table by one.
16262 * This function is MT-safe and may be called from any thread.
16264 * Returns: the passed in #GHashTable
16270 * g_hash_table_remove:
16271 * @hash_table: a #GHashTable
16272 * @key: the key to remove
16274 * Removes a key and its associated value from a #GHashTable.
16276 * If the #GHashTable was created using g_hash_table_new_full(), the
16277 * key and value are freed using the supplied destroy functions, otherwise
16278 * you have to make sure that any dynamically allocated values are freed
16281 * Returns: %TRUE if the key was found and removed from the #GHashTable
16286 * g_hash_table_remove_all:
16287 * @hash_table: a #GHashTable
16289 * Removes all keys and their associated values from a #GHashTable.
16291 * If the #GHashTable was created using g_hash_table_new_full(),
16292 * the keys and values are freed using the supplied destroy functions,
16293 * otherwise you have to make sure that any dynamically allocated
16294 * values are freed yourself.
16301 * g_hash_table_replace:
16302 * @hash_table: a #GHashTable
16303 * @key: a key to insert
16304 * @value: the value to associate with the key
16306 * Inserts a new key and value into a #GHashTable similar to
16307 * g_hash_table_insert(). The difference is that if the key
16308 * already exists in the #GHashTable, it gets replaced by the
16309 * new key. If you supplied a @value_destroy_func when creating
16310 * the #GHashTable, the old value is freed using that function.
16311 * If you supplied a @key_destroy_func when creating the
16312 * #GHashTable, the old key is freed using that function.
16314 * Returns: %TRUE if the key did not exist yet
16319 * g_hash_table_size:
16320 * @hash_table: a #GHashTable
16322 * Returns the number of elements contained in the #GHashTable.
16324 * Returns: the number of key/value pairs in the #GHashTable.
16329 * g_hash_table_steal:
16330 * @hash_table: a #GHashTable
16331 * @key: the key to remove
16333 * Removes a key and its associated value from a #GHashTable without
16334 * calling the key and value destroy functions.
16336 * Returns: %TRUE if the key was found and removed from the #GHashTable
16341 * g_hash_table_steal_all:
16342 * @hash_table: a #GHashTable
16344 * Removes all keys and their associated values from a #GHashTable
16345 * without calling the key and value destroy functions.
16352 * g_hash_table_thaw:
16353 * @hash_table: a #GHashTable
16355 * This function is deprecated and will be removed in the next major
16356 * release of GLib. It does nothing.
16361 * g_hash_table_unref:
16362 * @hash_table: a valid #GHashTable
16364 * Atomically decrements the reference count of @hash_table by one.
16365 * If the reference count drops to 0, all keys and values will be
16366 * destroyed, and all memory allocated by the hash table is released.
16367 * This function is MT-safe and may be called from any thread.
16375 * @hmac: the #GHmac to copy
16377 * Copies a #GHmac. If @hmac has been closed, by calling
16378 * g_hmac_get_string() or g_hmac_get_digest(), the copied
16379 * HMAC will be closed as well.
16381 * Returns: the copy of the passed #GHmac. Use g_hmac_unref()
16382 * when finished using it.
16388 * g_hmac_get_digest:
16390 * @buffer: output buffer
16391 * @digest_len: an inout parameter. The caller initializes it to the
16392 * size of @buffer. After the call it contains the length of the digest
16394 * Gets the digest from @checksum as a raw binary array and places it
16395 * into @buffer. The size of the digest depends on the type of checksum.
16397 * Once this function has been called, the #GHmac is closed and can
16398 * no longer be updated with g_checksum_update().
16405 * g_hmac_get_string:
16408 * Gets the HMAC as an hexadecimal string.
16410 * Once this function has been called the #GHmac can no longer be
16411 * updated with g_hmac_update().
16413 * The hexadecimal characters will be lower case.
16415 * Returns: the hexadecimal representation of the HMAC. The
16416 * returned string is owned by the HMAC and should not be modified
16424 * @digest_type: the desired type of digest
16425 * @key: (array length=key_len): the key for the HMAC
16426 * @key_len: the length of the keys
16428 * Creates a new #GHmac, using the digest algorithm @digest_type.
16429 * If the @digest_type is not known, %NULL is returned.
16430 * A #GHmac can be used to compute the HMAC of a key and an
16431 * arbitrary binary blob, using different hashing algorithms.
16433 * A #GHmac works by feeding a binary blob through g_hmac_update()
16434 * until the data is complete; the digest can then be extracted
16435 * using g_hmac_get_string(), which will return the checksum as a
16436 * hexadecimal string; or g_hmac_get_digest(), which will return a
16437 * array of raw bytes. Once either g_hmac_get_string() or
16438 * g_hmac_get_digest() have been called on a #GHmac, the HMAC
16439 * will be closed and it won't be possible to call g_hmac_update()
16442 * Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42.
16444 * Returns: the newly created #GHmac, or %NULL.
16445 * Use g_hmac_unref() to free the memory allocated by it.
16452 * @hmac: a valid #GHmac
16454 * Atomically increments the reference count of @hmac by one.
16456 * This function is MT-safe and may be called from any thread.
16458 * Returns: the passed in #GHmac.
16467 * Atomically decrements the reference count of @hmac by one.
16469 * If the reference count drops to 0, all keys and values will be
16470 * destroyed, and all memory allocated by the hash table is released.
16471 * This function is MT-safe and may be called from any thread.
16472 * Frees the memory allocated for @hmac.
16481 * @data: (array length=length): buffer used to compute the checksum
16482 * @length: size of the buffer, or -1 if it is a nul-terminated string
16484 * Feeds @data into an existing #GHmac.
16486 * The HMAC must still be open, that is g_hmac_get_string() or
16487 * g_hmac_get_digest() must not have been called on @hmac.
16495 * @hook_list: a #GHookList
16497 * Allocates space for a #GHook and initializes it.
16499 * Returns: a new #GHook
16505 * @hook_list: a #GHookList
16506 * @hook: the #GHook to add to the end of @hook_list
16508 * Appends a #GHook onto the end of a #GHookList.
16513 * g_hook_compare_ids:
16514 * @new_hook: a #GHook
16515 * @sibling: a #GHook to compare with @new_hook
16517 * Compares the ids of two #GHook elements, returning a negative value
16518 * if the second id is greater than the first.
16520 * Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook
16526 * @hook_list: a #GHookList
16527 * @hook_id: a hook ID
16529 * Destroys a #GHook, given its ID.
16531 * Returns: %TRUE if the #GHook was found in the #GHookList and destroyed
16536 * g_hook_destroy_link:
16537 * @hook_list: a #GHookList
16538 * @hook: the #GHook to remove
16540 * Removes one #GHook from a #GHookList, marking it
16541 * inactive and calling g_hook_unref() on it.
16547 * @hook_list: a #GHookList
16548 * @need_valids: %TRUE if #GHook elements which have been destroyed
16549 * should be skipped
16550 * @func: the function to call for each #GHook, which should return
16551 * %TRUE when the #GHook has been found
16552 * @data: the data to pass to @func
16554 * Finds a #GHook in a #GHookList using the given function to
16555 * test for a match.
16557 * Returns: the found #GHook or %NULL if no matching #GHook is found
16562 * g_hook_find_data:
16563 * @hook_list: a #GHookList
16564 * @need_valids: %TRUE if #GHook elements which have been destroyed
16565 * should be skipped
16566 * @data: the data to find
16568 * Finds a #GHook in a #GHookList with the given data.
16570 * Returns: the #GHook with the given @data or %NULL if no matching
16576 * g_hook_find_func:
16577 * @hook_list: a #GHookList
16578 * @need_valids: %TRUE if #GHook elements which have been destroyed
16579 * should be skipped
16580 * @func: the function to find
16582 * Finds a #GHook in a #GHookList with the given function.
16584 * Returns: the #GHook with the given @func or %NULL if no matching
16590 * g_hook_find_func_data:
16591 * @hook_list: a #GHookList
16592 * @need_valids: %TRUE if #GHook elements which have been destroyed
16593 * should be skipped
16594 * @func: (not nullable): the function to find
16595 * @data: the data to find
16597 * Finds a #GHook in a #GHookList with the given function and data.
16599 * Returns: the #GHook with the given @func and @data or %NULL if
16600 * no matching #GHook is found
16605 * g_hook_first_valid:
16606 * @hook_list: a #GHookList
16607 * @may_be_in_call: %TRUE if hooks which are currently running
16608 * (e.g. in another thread) are considered valid. If set to %FALSE,
16609 * these are skipped
16611 * Returns the first #GHook in a #GHookList which has not been destroyed.
16612 * The reference count for the #GHook is incremented, so you must call
16613 * g_hook_unref() to restore it when no longer needed. (Or call
16614 * g_hook_next_valid() if you are stepping through the #GHookList.)
16616 * Returns: the first valid #GHook, or %NULL if none are valid
16622 * @hook_list: a #GHookList
16623 * @hook: the #GHook to free
16625 * Calls the #GHookList @finalize_hook function if it exists,
16626 * and frees the memory allocated for the #GHook.
16632 * @hook_list: a #GHookList
16633 * @hook_id: a hook id
16635 * Returns the #GHook with the given id, or %NULL if it is not found.
16637 * Returns: the #GHook with the given id, or %NULL if it is not found
16642 * g_hook_insert_before:
16643 * @hook_list: a #GHookList
16644 * @sibling: (nullable): the #GHook to insert the new #GHook before
16645 * @hook: the #GHook to insert
16647 * Inserts a #GHook into a #GHookList, before a given #GHook.
16652 * g_hook_insert_sorted:
16653 * @hook_list: a #GHookList
16654 * @hook: the #GHook to insert
16655 * @func: the comparison function used to sort the #GHook elements
16657 * Inserts a #GHook into a #GHookList, sorted by the given function.
16662 * g_hook_list_clear:
16663 * @hook_list: a #GHookList
16665 * Removes all the #GHook elements from a #GHookList.
16670 * g_hook_list_init:
16671 * @hook_list: a #GHookList
16672 * @hook_size: the size of each element in the #GHookList,
16673 * typically `sizeof (GHook)`.
16675 * Initializes a #GHookList.
16676 * This must be called before the #GHookList is used.
16681 * g_hook_list_invoke:
16682 * @hook_list: a #GHookList
16683 * @may_recurse: %TRUE if functions which are already running
16684 * (e.g. in another thread) can be called. If set to %FALSE,
16685 * these are skipped
16687 * Calls all of the #GHook functions in a #GHookList.
16692 * g_hook_list_invoke_check:
16693 * @hook_list: a #GHookList
16694 * @may_recurse: %TRUE if functions which are already running
16695 * (e.g. in another thread) can be called. If set to %FALSE,
16696 * these are skipped
16698 * Calls all of the #GHook functions in a #GHookList.
16699 * Any function which returns %FALSE is removed from the #GHookList.
16704 * g_hook_list_marshal:
16705 * @hook_list: a #GHookList
16706 * @may_recurse: %TRUE if hooks which are currently running
16707 * (e.g. in another thread) are considered valid. If set to %FALSE,
16708 * these are skipped
16709 * @marshaller: the function to call for each #GHook
16710 * @marshal_data: data to pass to @marshaller
16712 * Calls a function on each valid #GHook.
16717 * g_hook_list_marshal_check:
16718 * @hook_list: a #GHookList
16719 * @may_recurse: %TRUE if hooks which are currently running
16720 * (e.g. in another thread) are considered valid. If set to %FALSE,
16721 * these are skipped
16722 * @marshaller: the function to call for each #GHook
16723 * @marshal_data: data to pass to @marshaller
16725 * Calls a function on each valid #GHook and destroys it if the
16726 * function returns %FALSE.
16731 * g_hook_next_valid:
16732 * @hook_list: a #GHookList
16733 * @hook: the current #GHook
16734 * @may_be_in_call: %TRUE if hooks which are currently running
16735 * (e.g. in another thread) are considered valid. If set to %FALSE,
16736 * these are skipped
16738 * Returns the next #GHook in a #GHookList which has not been destroyed.
16739 * The reference count for the #GHook is incremented, so you must call
16740 * g_hook_unref() to restore it when no longer needed. (Or continue to call
16741 * g_hook_next_valid() until %NULL is returned.)
16743 * Returns: the next valid #GHook, or %NULL if none are valid
16749 * @hook_list: a #GHookList
16750 * @hook: the #GHook to add to the start of @hook_list
16752 * Prepends a #GHook on the start of a #GHookList.
16758 * @hook_list: a #GHookList
16759 * @hook: the #GHook to increment the reference count of
16761 * Increments the reference count for a #GHook.
16763 * Returns: the @hook that was passed in (since 2.6)
16769 * @hook_list: a #GHookList
16770 * @hook: the #GHook to unref
16772 * Decrements the reference count of a #GHook.
16773 * If the reference count falls to 0, the #GHook is removed
16774 * from the #GHookList and g_hook_free() is called to free it.
16779 * g_hostname_is_ascii_encoded:
16780 * @hostname: a hostname
16782 * Tests if @hostname contains segments with an ASCII-compatible
16783 * encoding of an Internationalized Domain Name. If this returns
16784 * %TRUE, you should decode the hostname with g_hostname_to_unicode()
16785 * before displaying it to the user.
16787 * Note that a hostname might contain a mix of encoded and unencoded
16788 * segments, and so it is possible for g_hostname_is_non_ascii() and
16789 * g_hostname_is_ascii_encoded() to both return %TRUE for a name.
16791 * Returns: %TRUE if @hostname contains any ASCII-encoded
16798 * g_hostname_is_ip_address:
16799 * @hostname: a hostname (or IP address in string form)
16801 * Tests if @hostname is the string form of an IPv4 or IPv6 address.
16802 * (Eg, "192.168.0.1".)
16804 * Returns: %TRUE if @hostname is an IP address
16810 * g_hostname_is_non_ascii:
16811 * @hostname: a hostname
16813 * Tests if @hostname contains Unicode characters. If this returns
16814 * %TRUE, you need to encode the hostname with g_hostname_to_ascii()
16815 * before using it in non-IDN-aware contexts.
16817 * Note that a hostname might contain a mix of encoded and unencoded
16818 * segments, and so it is possible for g_hostname_is_non_ascii() and
16819 * g_hostname_is_ascii_encoded() to both return %TRUE for a name.
16821 * Returns: %TRUE if @hostname contains any non-ASCII characters
16827 * g_hostname_to_ascii:
16828 * @hostname: a valid UTF-8 or ASCII hostname
16830 * Converts @hostname to its canonical ASCII form; an ASCII-only
16831 * string containing no uppercase letters and not ending with a
16834 * Returns: an ASCII hostname, which must be freed, or %NULL if
16835 * @hostname is in some way invalid.
16841 * g_hostname_to_unicode:
16842 * @hostname: a valid UTF-8 or ASCII hostname
16844 * Converts @hostname to its canonical presentation form; a UTF-8
16845 * string in Unicode normalization form C, containing no uppercase
16846 * letters, no forbidden characters, and no ASCII-encoded segments,
16847 * and not ending with a trailing dot.
16849 * Of course if @hostname is not an internationalized hostname, then
16850 * the canonical presentation form will be entirely ASCII.
16852 * Returns: a UTF-8 hostname, which must be freed, or %NULL if
16853 * @hostname is in some way invalid.
16860 * @val: a 32-bit integer value in host byte order
16862 * Converts a 32-bit integer value from host to network byte order.
16864 * Returns: @val converted to network byte order
16870 * @val: a 16-bit integer value in host byte order
16872 * Converts a 16-bit integer value from host to network byte order.
16874 * Returns: @val converted to network byte order
16880 * @converter: conversion descriptor from g_iconv_open()
16881 * @inbuf: bytes to convert
16882 * @inbytes_left: inout parameter, bytes remaining to convert in @inbuf
16883 * @outbuf: converted output bytes
16884 * @outbytes_left: inout parameter, bytes available to fill in @outbuf
16886 * Same as the standard UNIX routine iconv(), but
16887 * may be implemented via libiconv on UNIX flavors that lack
16888 * a native implementation.
16890 * GLib provides g_convert() and g_locale_to_utf8() which are likely
16891 * more convenient than the raw iconv wrappers.
16893 * Returns: count of non-reversible conversions, or -1 on error
16899 * @converter: a conversion descriptor from g_iconv_open()
16901 * Same as the standard UNIX routine iconv_close(), but
16902 * may be implemented via libiconv on UNIX flavors that lack
16903 * a native implementation. Should be called to clean up
16904 * the conversion descriptor from g_iconv_open() when
16905 * you are done converting things.
16907 * GLib provides g_convert() and g_locale_to_utf8() which are likely
16908 * more convenient than the raw iconv wrappers.
16910 * Returns: -1 on error, 0 on success
16916 * @to_codeset: destination codeset
16917 * @from_codeset: source codeset
16919 * Same as the standard UNIX routine iconv_open(), but
16920 * may be implemented via libiconv on UNIX flavors that lack
16921 * a native implementation.
16923 * GLib provides g_convert() and g_locale_to_utf8() which are likely
16924 * more convenient than the raw iconv wrappers.
16926 * Returns: a "conversion descriptor", or (GIConv)-1 if
16927 * opening the converter failed.
16933 * @function: function to call
16934 * @data: data to pass to @function.
16936 * Adds a function to be called whenever there are no higher priority
16937 * events pending to the default main loop. The function is given the
16938 * default idle priority, #G_PRIORITY_DEFAULT_IDLE. If the function
16939 * returns %FALSE it is automatically removed from the list of event
16940 * sources and will not be called again.
16942 * See [memory management of sources][mainloop-memory-management] for details
16943 * on how to handle the return value and memory management of @data.
16945 * This internally creates a main loop source using g_idle_source_new()
16946 * and attaches it to the global #GMainContext using g_source_attach(), so
16947 * the callback will be invoked in whichever thread is running that main
16948 * context. You can do these steps manually if you need greater control or to
16949 * use a custom main context.
16951 * Returns: the ID (greater than 0) of the event source.
16956 * g_idle_add_full: (rename-to g_idle_add)
16957 * @priority: the priority of the idle source. Typically this will be in the
16958 * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
16959 * @function: function to call
16960 * @data: data to pass to @function
16961 * @notify: (allow-none): function to call when the idle is removed, or %NULL
16963 * Adds a function to be called whenever there are no higher priority
16964 * events pending. If the function returns %FALSE it is automatically
16965 * removed from the list of event sources and will not be called again.
16967 * See [memory management of sources][mainloop-memory-management] for details
16968 * on how to handle the return value and memory management of @data.
16970 * This internally creates a main loop source using g_idle_source_new()
16971 * and attaches it to the global #GMainContext using g_source_attach(), so
16972 * the callback will be invoked in whichever thread is running that main
16973 * context. You can do these steps manually if you need greater control or to
16974 * use a custom main context.
16976 * Returns: the ID (greater than 0) of the event source.
16981 * g_idle_remove_by_data:
16982 * @data: the data for the idle source's callback.
16984 * Removes the idle function with the given data.
16986 * Returns: %TRUE if an idle source was found and removed.
16991 * g_idle_source_new:
16993 * Creates a new idle source.
16995 * The source will not initially be associated with any #GMainContext
16996 * and must be added to one with g_source_attach() before it will be
16997 * executed. Note that the default priority for idle sources is
16998 * %G_PRIORITY_DEFAULT_IDLE, as compared to other sources which
16999 * have a default priority of %G_PRIORITY_DEFAULT.
17001 * Returns: the newly-created idle source
17007 * @...: format string, followed by parameters to insert
17008 * into the format string (as with printf())
17010 * A convenience function/macro to log an informational message. Seldom used.
17012 * If g_log_default_handler() is used as the log handler function, a new-line
17013 * character will automatically be appended to @..., and need not be entered
17016 * Such messages are suppressed by the g_log_default_handler() unless
17017 * the G_MESSAGES_DEBUG environment variable is set appropriately.
17025 * @v1: (not nullable): a pointer to a #gint64 key
17026 * @v2: (not nullable): a pointer to a #gint64 key to compare with @v1
17028 * Compares the two #gint64 values being pointed to and returns
17029 * %TRUE if they are equal.
17030 * It can be passed to g_hash_table_new() as the @key_equal_func
17031 * parameter, when using non-%NULL pointers to 64-bit integers as keys in a
17034 * Returns: %TRUE if the two keys match.
17041 * @v: (not nullable): a pointer to a #gint64 key
17043 * Converts a pointer to a #gint64 to a hash value.
17045 * It can be passed to g_hash_table_new() as the @hash_func parameter,
17046 * when using non-%NULL pointers to 64-bit integer values as keys in a
17049 * Returns: a hash value corresponding to the key.
17056 * @v1: (not nullable): a pointer to a #gint key
17057 * @v2: (not nullable): a pointer to a #gint key to compare with @v1
17059 * Compares the two #gint values being pointed to and returns
17060 * %TRUE if they are equal.
17061 * It can be passed to g_hash_table_new() as the @key_equal_func
17062 * parameter, when using non-%NULL pointers to integers as keys in a
17065 * Note that this function acts on pointers to #gint, not on #gint
17066 * directly: if your hash table's keys are of the form
17067 * `GINT_TO_POINTER (n)`, use g_direct_equal() instead.
17069 * Returns: %TRUE if the two keys match.
17075 * @v: (not nullable): a pointer to a #gint key
17077 * Converts a pointer to a #gint to a hash value.
17078 * It can be passed to g_hash_table_new() as the @hash_func parameter,
17079 * when using non-%NULL pointers to integer values as keys in a #GHashTable.
17081 * Note that this function acts on pointers to #gint, not on #gint
17082 * directly: if your hash table's keys are of the form
17083 * `GINT_TO_POINTER (n)`, use g_direct_hash() instead.
17085 * Returns: a hash value corresponding to the key.
17090 * g_intern_static_string:
17091 * @string: (allow-none): a static string
17093 * Returns a canonical representation for @string. Interned strings
17094 * can be compared for equality by comparing the pointers, instead of
17095 * using strcmp(). g_intern_static_string() does not copy the string,
17096 * therefore @string must not be freed or modified.
17098 * Returns: a canonical representation for the string
17105 * @string: (allow-none): a string
17107 * Returns a canonical representation for @string. Interned strings
17108 * can be compared for equality by comparing the pointers, instead of
17111 * Returns: a canonical representation for the string
17118 * @channel: a #GIOChannel
17119 * @condition: the condition to watch for
17120 * @func: the function to call when the condition is satisfied
17121 * @user_data: user data to pass to @func
17123 * Adds the #GIOChannel into the default main loop context
17124 * with the default priority.
17126 * Returns: the event source id
17131 * g_io_add_watch_full: (rename-to g_io_add_watch)
17132 * @channel: a #GIOChannel
17133 * @priority: the priority of the #GIOChannel source
17134 * @condition: the condition to watch for
17135 * @func: the function to call when the condition is satisfied
17136 * @user_data: user data to pass to @func
17137 * @notify: the function to call when the source is removed
17139 * Adds the #GIOChannel into the default main loop context
17140 * with the given priority.
17142 * This internally creates a main loop source using g_io_create_watch()
17143 * and attaches it to the main loop context with g_source_attach().
17144 * You can do these steps manually if you need greater control.
17146 * Returns: the event source id
17151 * g_io_channel_close:
17152 * @channel: A #GIOChannel
17154 * Close an IO channel. Any pending data to be written will be
17155 * flushed, ignoring errors. The channel will not be freed until the
17156 * last reference is dropped using g_io_channel_unref().
17158 * Deprecated: 2.2: Use g_io_channel_shutdown() instead.
17163 * g_io_channel_error_from_errno:
17164 * @en: an `errno` error number, e.g. `EINVAL`
17166 * Converts an `errno` error number to a #GIOChannelError.
17168 * Returns: a #GIOChannelError error number, e.g.
17169 * %G_IO_CHANNEL_ERROR_INVAL.
17174 * g_io_channel_flush:
17175 * @channel: a #GIOChannel
17176 * @error: location to store an error of type #GIOChannelError
17178 * Flushes the write buffer for the GIOChannel.
17180 * Returns: the status of the operation: One of
17181 * #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or
17182 * #G_IO_STATUS_ERROR.
17187 * g_io_channel_get_buffer_condition:
17188 * @channel: A #GIOChannel
17190 * This function returns a #GIOCondition depending on whether there
17191 * is data to be read/space to write data in the internal buffers in
17192 * the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set.
17194 * Returns: A #GIOCondition
17199 * g_io_channel_get_buffer_size:
17200 * @channel: a #GIOChannel
17202 * Gets the buffer size.
17204 * Returns: the size of the buffer.
17209 * g_io_channel_get_buffered:
17210 * @channel: a #GIOChannel
17212 * Returns whether @channel is buffered.
17214 * Returns: %TRUE if the @channel is buffered.
17219 * g_io_channel_get_close_on_unref:
17220 * @channel: a #GIOChannel.
17222 * Returns whether the file/socket/whatever associated with @channel
17223 * will be closed when @channel receives its final unref and is
17224 * destroyed. The default value of this is %TRUE for channels created
17225 * by g_io_channel_new_file (), and %FALSE for all other channels.
17227 * Returns: Whether the channel will be closed on the final unref of
17228 * the GIOChannel data structure.
17233 * g_io_channel_get_encoding:
17234 * @channel: a #GIOChannel
17236 * Gets the encoding for the input/output of the channel.
17237 * The internal encoding is always UTF-8. The encoding %NULL
17238 * makes the channel safe for binary data.
17240 * Returns: A string containing the encoding, this string is
17241 * owned by GLib and must not be freed.
17246 * g_io_channel_get_flags:
17247 * @channel: a #GIOChannel
17249 * Gets the current flags for a #GIOChannel, including read-only
17250 * flags such as %G_IO_FLAG_IS_READABLE.
17252 * The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITABLE
17253 * are cached for internal use by the channel when it is created.
17254 * If they should change at some later point (e.g. partial shutdown
17255 * of a socket with the UNIX shutdown() function), the user
17256 * should immediately call g_io_channel_get_flags() to update
17257 * the internal values of these flags.
17259 * Returns: the flags which are set on the channel
17264 * g_io_channel_get_line_term:
17265 * @channel: a #GIOChannel
17266 * @length: a location to return the length of the line terminator
17268 * This returns the string that #GIOChannel uses to determine
17269 * where in the file a line break occurs. A value of %NULL
17270 * indicates autodetection.
17272 * Returns: The line termination string. This value
17273 * is owned by GLib and must not be freed.
17278 * g_io_channel_init:
17279 * @channel: a #GIOChannel
17281 * Initializes a #GIOChannel struct.
17283 * This is called by each of the above functions when creating a
17284 * #GIOChannel, and so is not often needed by the application
17285 * programmer (unless you are creating a new type of #GIOChannel).
17290 * g_io_channel_new_file:
17291 * @filename: (type filename): A string containing the name of a file
17292 * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have
17293 * the same meaning as in fopen()
17294 * @error: A location to return an error of type %G_FILE_ERROR
17296 * Open a file @filename as a #GIOChannel using mode @mode. This
17297 * channel will be closed when the last reference to it is dropped,
17298 * so there is no need to call g_io_channel_close() (though doing
17299 * so will not cause problems, as long as no attempt is made to
17300 * access the channel after it is closed).
17302 * Returns: A #GIOChannel on success, %NULL on failure.
17307 * g_io_channel_read:
17308 * @channel: a #GIOChannel
17309 * @buf: a buffer to read the data into (which should be at least
17310 * count bytes long)
17311 * @count: the number of bytes to read from the #GIOChannel
17312 * @bytes_read: returns the number of bytes actually read
17314 * Reads data from a #GIOChannel.
17316 * Returns: %G_IO_ERROR_NONE if the operation was successful.
17317 * Deprecated: 2.2: Use g_io_channel_read_chars() instead.
17322 * g_io_channel_read_chars:
17323 * @channel: a #GIOChannel
17324 * @buf: (out caller-allocates) (array length=count) (element-type guint8):
17325 * a buffer to read data into
17326 * @count: (in): the size of the buffer. Note that the buffer may not be
17327 * complelely filled even if there is data in the buffer if the
17328 * remaining data is not a complete character.
17329 * @bytes_read: (allow-none) (out): The number of bytes read. This may be
17330 * zero even on success if count < 6 and the channel's encoding
17331 * is non-%NULL. This indicates that the next UTF-8 character is
17332 * too wide for the buffer.
17333 * @error: a location to return an error of type #GConvertError
17334 * or #GIOChannelError.
17336 * Replacement for g_io_channel_read() with the new API.
17338 * Returns: the status of the operation.
17343 * g_io_channel_read_line:
17344 * @channel: a #GIOChannel
17345 * @str_return: (out): The line read from the #GIOChannel, including the
17346 * line terminator. This data should be freed with g_free()
17347 * when no longer needed. This is a nul-terminated string.
17348 * If a @length of zero is returned, this will be %NULL instead.
17349 * @length: (allow-none) (out): location to store length of the read data, or %NULL
17350 * @terminator_pos: (allow-none) (out): location to store position of line terminator, or %NULL
17351 * @error: A location to return an error of type #GConvertError
17352 * or #GIOChannelError
17354 * Reads a line, including the terminating character(s),
17355 * from a #GIOChannel into a newly-allocated string.
17356 * @str_return will contain allocated memory if the return
17357 * is %G_IO_STATUS_NORMAL.
17359 * Returns: the status of the operation.
17364 * g_io_channel_read_line_string:
17365 * @channel: a #GIOChannel
17366 * @buffer: a #GString into which the line will be written.
17367 * If @buffer already contains data, the old data will
17369 * @terminator_pos: (allow-none): location to store position of line terminator, or %NULL
17370 * @error: a location to store an error of type #GConvertError
17371 * or #GIOChannelError
17373 * Reads a line from a #GIOChannel, using a #GString as a buffer.
17375 * Returns: the status of the operation.
17380 * g_io_channel_read_to_end:
17381 * @channel: a #GIOChannel
17382 * @str_return: (out) (array length=length) (element-type guint8): Location to
17383 * store a pointer to a string holding the remaining data in the
17384 * #GIOChannel. This data should be freed with g_free() when no
17385 * longer needed. This data is terminated by an extra nul
17386 * character, but there may be other nuls in the intervening data.
17387 * @length: (out): location to store length of the data
17388 * @error: location to return an error of type #GConvertError
17389 * or #GIOChannelError
17391 * Reads all the remaining data from the file.
17393 * Returns: %G_IO_STATUS_NORMAL on success.
17394 * This function never returns %G_IO_STATUS_EOF.
17399 * g_io_channel_read_unichar:
17400 * @channel: a #GIOChannel
17401 * @thechar: (out): a location to return a character
17402 * @error: a location to return an error of type #GConvertError
17403 * or #GIOChannelError
17405 * Reads a Unicode character from @channel.
17406 * This function cannot be called on a channel with %NULL encoding.
17408 * Returns: a #GIOStatus
17413 * g_io_channel_ref:
17414 * @channel: a #GIOChannel
17416 * Increments the reference count of a #GIOChannel.
17418 * Returns: the @channel that was passed in (since 2.6)
17423 * g_io_channel_seek:
17424 * @channel: a #GIOChannel
17425 * @offset: an offset, in bytes, which is added to the position specified
17427 * @type: the position in the file, which can be %G_SEEK_CUR (the current
17428 * position), %G_SEEK_SET (the start of the file), or %G_SEEK_END
17429 * (the end of the file)
17431 * Sets the current position in the #GIOChannel, similar to the standard
17432 * library function fseek().
17434 * Returns: %G_IO_ERROR_NONE if the operation was successful.
17435 * Deprecated: 2.2: Use g_io_channel_seek_position() instead.
17440 * g_io_channel_seek_position:
17441 * @channel: a #GIOChannel
17442 * @offset: The offset in bytes from the position specified by @type
17443 * @type: a #GSeekType. The type %G_SEEK_CUR is only allowed in those
17444 * cases where a call to g_io_channel_set_encoding ()
17445 * is allowed. See the documentation for
17446 * g_io_channel_set_encoding () for details.
17447 * @error: A location to return an error of type #GIOChannelError
17449 * Replacement for g_io_channel_seek() with the new API.
17451 * Returns: the status of the operation.
17456 * g_io_channel_set_buffer_size:
17457 * @channel: a #GIOChannel
17458 * @size: the size of the buffer, or 0 to let GLib pick a good size
17460 * Sets the buffer size.
17465 * g_io_channel_set_buffered:
17466 * @channel: a #GIOChannel
17467 * @buffered: whether to set the channel buffered or unbuffered
17469 * The buffering state can only be set if the channel's encoding
17470 * is %NULL. For any other encoding, the channel must be buffered.
17472 * A buffered channel can only be set unbuffered if the channel's
17473 * internal buffers have been flushed. Newly created channels or
17474 * channels which have returned %G_IO_STATUS_EOF
17475 * not require such a flush. For write-only channels, a call to
17476 * g_io_channel_flush () is sufficient. For all other channels,
17477 * the buffers may be flushed by a call to g_io_channel_seek_position ().
17478 * This includes the possibility of seeking with seek type %G_SEEK_CUR
17479 * and an offset of zero. Note that this means that socket-based
17480 * channels cannot be set unbuffered once they have had data
17483 * On unbuffered channels, it is safe to mix read and write
17484 * calls from the new and old APIs, if this is necessary for
17485 * maintaining old code.
17487 * The default state of the channel is buffered.
17492 * g_io_channel_set_close_on_unref:
17493 * @channel: a #GIOChannel
17494 * @do_close: Whether to close the channel on the final unref of
17495 * the GIOChannel data structure. The default value of
17496 * this is %TRUE for channels created by g_io_channel_new_file (),
17497 * and %FALSE for all other channels.
17499 * Setting this flag to %TRUE for a channel you have already closed
17500 * can cause problems.
17505 * g_io_channel_set_encoding:
17506 * @channel: a #GIOChannel
17507 * @encoding: (allow-none): the encoding type
17508 * @error: location to store an error of type #GConvertError
17510 * Sets the encoding for the input/output of the channel.
17511 * The internal encoding is always UTF-8. The default encoding
17512 * for the external file is UTF-8.
17514 * The encoding %NULL is safe to use with binary data.
17516 * The encoding can only be set if one of the following conditions
17519 * - The channel was just created, and has not been written to or read from yet.
17521 * - The channel is write-only.
17523 * - The channel is a file, and the file pointer was just repositioned
17524 * by a call to g_io_channel_seek_position(). (This flushes all the
17525 * internal buffers.)
17527 * - The current encoding is %NULL or UTF-8.
17529 * - One of the (new API) read functions has just returned %G_IO_STATUS_EOF
17530 * (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL).
17532 * - One of the functions g_io_channel_read_chars() or
17533 * g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or
17534 * %G_IO_STATUS_ERROR. This may be useful in the case of
17535 * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
17536 * Returning one of these statuses from g_io_channel_read_line(),
17537 * g_io_channel_read_line_string(), or g_io_channel_read_to_end()
17538 * does not guarantee that the encoding can be changed.
17540 * Channels which do not meet one of the above conditions cannot call
17541 * g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if
17542 * they are "seekable", cannot call g_io_channel_write_chars() after
17543 * calling one of the API "read" functions.
17545 * Returns: %G_IO_STATUS_NORMAL if the encoding was successfully set
17550 * g_io_channel_set_flags:
17551 * @channel: a #GIOChannel
17552 * @flags: the flags to set on the IO channel
17553 * @error: A location to return an error of type #GIOChannelError
17555 * Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK).
17557 * Returns: the status of the operation.
17562 * g_io_channel_set_line_term:
17563 * @channel: a #GIOChannel
17564 * @line_term: (allow-none): The line termination string. Use %NULL for
17565 * autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0",
17566 * and the Unicode paragraph separator. Autodetection should not be
17567 * used for anything other than file-based channels.
17568 * @length: The length of the termination string. If -1 is passed, the
17569 * string is assumed to be nul-terminated. This option allows
17570 * termination strings with embedded nuls.
17572 * This sets the string that #GIOChannel uses to determine
17573 * where in the file a line break occurs.
17578 * g_io_channel_shutdown:
17579 * @channel: a #GIOChannel
17580 * @flush: if %TRUE, flush pending
17581 * @err: location to store a #GIOChannelError
17583 * Close an IO channel. Any pending data to be written will be
17584 * flushed if @flush is %TRUE. The channel will not be freed until the
17585 * last reference is dropped using g_io_channel_unref().
17587 * Returns: the status of the operation.
17592 * g_io_channel_unix_get_fd:
17593 * @channel: a #GIOChannel, created with g_io_channel_unix_new().
17595 * Returns the file descriptor of the #GIOChannel.
17597 * On Windows this function returns the file descriptor or socket of
17600 * Returns: the file descriptor of the #GIOChannel.
17605 * g_io_channel_unix_new:
17606 * @fd: a file descriptor.
17608 * Creates a new #GIOChannel given a file descriptor. On UNIX systems
17609 * this works for plain files, pipes, and sockets.
17611 * The returned #GIOChannel has a reference count of 1.
17613 * The default encoding for #GIOChannel is UTF-8. If your application
17614 * is reading output from a command using via pipe, you may need to set
17615 * the encoding to the encoding of the current locale (see
17616 * g_get_charset()) with the g_io_channel_set_encoding() function.
17618 * If you want to read raw binary data without interpretation, then
17619 * call the g_io_channel_set_encoding() function with %NULL for the
17620 * encoding argument.
17622 * This function is available in GLib on Windows, too, but you should
17623 * avoid using it on Windows. The domain of file descriptors and
17624 * sockets overlap. There is no way for GLib to know which one you mean
17625 * in case the argument you pass to this function happens to be both a
17626 * valid file descriptor and socket. If that happens a warning is
17627 * issued, and GLib assumes that it is the file descriptor you mean.
17629 * Returns: a new #GIOChannel.
17634 * g_io_channel_unref:
17635 * @channel: a #GIOChannel
17637 * Decrements the reference count of a #GIOChannel.
17642 * g_io_channel_win32_new_fd:
17643 * @fd: a C library file descriptor.
17645 * Creates a new #GIOChannel given a file descriptor on Windows. This
17646 * works for file descriptors from the C runtime.
17648 * This function works for file descriptors as returned by the open(),
17649 * creat(), pipe() and fileno() calls in the Microsoft C runtime. In
17650 * order to meaningfully use this function your code should use the
17651 * same C runtime as GLib uses, which is msvcrt.dll. Note that in
17652 * current Microsoft compilers it is near impossible to convince it to
17653 * build code that would use msvcrt.dll. The last Microsoft compiler
17654 * version that supported using msvcrt.dll as the C runtime was version
17655 * 6. The GNU compiler and toolchain for Windows, also known as Mingw,
17656 * fully supports msvcrt.dll.
17658 * If you have created a #GIOChannel for a file descriptor and started
17659 * watching (polling) it, you shouldn't call read() on the file
17660 * descriptor. This is because adding polling for a file descriptor is
17661 * implemented in GLib on Windows by starting a thread that sits
17662 * blocked in a read() from the file descriptor most of the time. All
17663 * reads from the file descriptor should be done by this internal GLib
17664 * thread. Your code should call only g_io_channel_read().
17666 * This function is available only in GLib on Windows.
17668 * Returns: a new #GIOChannel.
17673 * g_io_channel_win32_new_messages:
17674 * @hwnd: a window handle.
17676 * Creates a new #GIOChannel given a window handle on Windows.
17678 * This function creates a #GIOChannel that can be used to poll for
17679 * Windows messages for the window in question.
17681 * Returns: a new #GIOChannel.
17686 * g_io_channel_win32_new_socket:
17687 * @socket: a Winsock socket
17689 * Creates a new #GIOChannel given a socket on Windows.
17691 * This function works for sockets created by Winsock. It's available
17692 * only in GLib on Windows.
17694 * Polling a #GSource created to watch a channel for a socket puts the
17695 * socket in non-blocking mode. This is a side-effect of the
17696 * implementation and unavoidable.
17698 * Returns: a new #GIOChannel
17703 * g_io_channel_write:
17704 * @channel: a #GIOChannel
17705 * @buf: the buffer containing the data to write
17706 * @count: the number of bytes to write
17707 * @bytes_written: the number of bytes actually written
17709 * Writes data to a #GIOChannel.
17711 * Returns: %G_IO_ERROR_NONE if the operation was successful.
17712 * Deprecated: 2.2: Use g_io_channel_write_chars() instead.
17717 * g_io_channel_write_chars:
17718 * @channel: a #GIOChannel
17719 * @buf: (array) (element-type guint8): a buffer to write data from
17720 * @count: the size of the buffer. If -1, the buffer
17721 * is taken to be a nul-terminated string.
17722 * @bytes_written: (out): The number of bytes written. This can be nonzero
17723 * even if the return value is not %G_IO_STATUS_NORMAL.
17724 * If the return value is %G_IO_STATUS_NORMAL and the
17725 * channel is blocking, this will always be equal
17726 * to @count if @count >= 0.
17727 * @error: a location to return an error of type #GConvertError
17728 * or #GIOChannelError
17730 * Replacement for g_io_channel_write() with the new API.
17732 * On seekable channels with encodings other than %NULL or UTF-8, generic
17733 * mixing of reading and writing is not allowed. A call to g_io_channel_write_chars ()
17734 * may only be made on a channel from which data has been read in the
17735 * cases described in the documentation for g_io_channel_set_encoding ().
17737 * Returns: the status of the operation.
17742 * g_io_channel_write_unichar:
17743 * @channel: a #GIOChannel
17744 * @thechar: a character
17745 * @error: location to return an error of type #GConvertError
17746 * or #GIOChannelError
17748 * Writes a Unicode character to @channel.
17749 * This function cannot be called on a channel with %NULL encoding.
17751 * Returns: a #GIOStatus
17756 * g_io_create_watch:
17757 * @channel: a #GIOChannel to watch
17758 * @condition: conditions to watch for
17760 * Creates a #GSource that's dispatched when @condition is met for the
17761 * given @channel. For example, if condition is #G_IO_IN, the source will
17762 * be dispatched when there's data available for reading.
17764 * g_io_add_watch() is a simpler interface to this same functionality, for
17765 * the case where you want to add the source to the default main loop context
17766 * at the default priority.
17768 * On Windows, polling a #GSource created to watch a channel for a socket
17769 * puts the socket in non-blocking mode. This is a side-effect of the
17770 * implementation and unavoidable.
17772 * Returns: a new #GSource
17777 * g_key_file_free: (skip)
17778 * @key_file: a #GKeyFile
17780 * Clears all keys and groups from @key_file, and decreases the
17781 * reference count by 1. If the reference count reaches zero,
17782 * frees the key file and all its allocated memory.
17789 * g_key_file_get_boolean:
17790 * @key_file: a #GKeyFile
17791 * @group_name: a group name
17793 * @error: return location for a #GError
17795 * Returns the value associated with @key under @group_name as a
17798 * If @key cannot be found then %FALSE is returned and @error is set
17799 * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value
17800 * associated with @key cannot be interpreted as a boolean then %FALSE
17801 * is returned and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
17803 * Returns: the value associated with the key as a boolean,
17804 * or %FALSE if the key was not found or could not be parsed.
17810 * g_key_file_get_boolean_list:
17811 * @key_file: a #GKeyFile
17812 * @group_name: a group name
17814 * @length: (out): the number of booleans returned
17815 * @error: return location for a #GError
17817 * Returns the values associated with @key under @group_name as
17820 * If @key cannot be found then %NULL is returned and @error is set to
17821 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
17822 * with @key cannot be interpreted as booleans then %NULL is returned
17823 * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
17825 * Returns: (array length=length) (element-type gboolean) (transfer container):
17826 * the values associated with the key as a list of booleans, or %NULL if the
17827 * key was not found or could not be parsed. The returned list of booleans
17828 * should be freed with g_free() when no longer needed.
17834 * g_key_file_get_comment:
17835 * @key_file: a #GKeyFile
17836 * @group_name: (allow-none): a group name, or %NULL
17838 * @error: return location for a #GError
17840 * Retrieves a comment above @key from @group_name.
17841 * If @key is %NULL then @comment will be read from above
17842 * @group_name. If both @key and @group_name are %NULL, then
17843 * @comment will be read from above the first group in the file.
17845 * Note that the returned string includes the '#' comment markers.
17847 * Returns: a comment that should be freed with g_free()
17853 * g_key_file_get_double:
17854 * @key_file: a #GKeyFile
17855 * @group_name: a group name
17857 * @error: return location for a #GError
17859 * Returns the value associated with @key under @group_name as a
17860 * double. If @group_name is %NULL, the start_group is used.
17862 * If @key cannot be found then 0.0 is returned and @error is set to
17863 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
17864 * with @key cannot be interpreted as a double then 0.0 is returned
17865 * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
17867 * Returns: the value associated with the key as a double, or
17868 * 0.0 if the key was not found or could not be parsed.
17874 * g_key_file_get_double_list:
17875 * @key_file: a #GKeyFile
17876 * @group_name: a group name
17878 * @length: (out): the number of doubles returned
17879 * @error: return location for a #GError
17881 * Returns the values associated with @key under @group_name as
17884 * If @key cannot be found then %NULL is returned and @error is set to
17885 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
17886 * with @key cannot be interpreted as doubles then %NULL is returned
17887 * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
17889 * Returns: (array length=length) (element-type gdouble) (transfer container):
17890 * the values associated with the key as a list of doubles, or %NULL if the
17891 * key was not found or could not be parsed. The returned list of doubles
17892 * should be freed with g_free() when no longer needed.
17898 * g_key_file_get_groups:
17899 * @key_file: a #GKeyFile
17900 * @length: (out) (allow-none): return location for the number of returned groups, or %NULL
17902 * Returns all groups in the key file loaded with @key_file.
17903 * The array of returned groups will be %NULL-terminated, so
17904 * @length may optionally be %NULL.
17906 * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings.
17907 * Use g_strfreev() to free it.
17913 * g_key_file_get_int64:
17914 * @key_file: a non-%NULL #GKeyFile
17915 * @group_name: a non-%NULL group name
17916 * @key: a non-%NULL key
17917 * @error: return location for a #GError
17919 * Returns the value associated with @key under @group_name as a signed
17920 * 64-bit integer. This is similar to g_key_file_get_integer() but can return
17921 * 64-bit results without truncation.
17923 * Returns: the value associated with the key as a signed 64-bit integer, or
17924 * 0 if the key was not found or could not be parsed.
17930 * g_key_file_get_integer:
17931 * @key_file: a #GKeyFile
17932 * @group_name: a group name
17934 * @error: return location for a #GError
17936 * Returns the value associated with @key under @group_name as an
17939 * If @key cannot be found then 0 is returned and @error is set to
17940 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
17941 * with @key cannot be interpreted as an integer then 0 is returned
17942 * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
17944 * Returns: the value associated with the key as an integer, or
17945 * 0 if the key was not found or could not be parsed.
17951 * g_key_file_get_integer_list:
17952 * @key_file: a #GKeyFile
17953 * @group_name: a group name
17955 * @length: (out): the number of integers returned
17956 * @error: return location for a #GError
17958 * Returns the values associated with @key under @group_name as
17961 * If @key cannot be found then %NULL is returned and @error is set to
17962 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
17963 * with @key cannot be interpreted as integers then %NULL is returned
17964 * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
17966 * Returns: (array length=length) (element-type gint) (transfer container):
17967 * the values associated with the key as a list of integers, or %NULL if
17968 * the key was not found or could not be parsed. The returned list of
17969 * integers should be freed with g_free() when no longer needed.
17975 * g_key_file_get_keys:
17976 * @key_file: a #GKeyFile
17977 * @group_name: a group name
17978 * @length: (out) (allow-none): return location for the number of keys returned, or %NULL
17979 * @error: return location for a #GError, or %NULL
17981 * Returns all keys for the group name @group_name. The array of
17982 * returned keys will be %NULL-terminated, so @length may
17983 * optionally be %NULL. In the event that the @group_name cannot
17984 * be found, %NULL is returned and @error is set to
17985 * #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
17987 * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings.
17988 * Use g_strfreev() to free it.
17994 * g_key_file_get_locale_string:
17995 * @key_file: a #GKeyFile
17996 * @group_name: a group name
17998 * @locale: (allow-none): a locale identifier or %NULL
17999 * @error: return location for a #GError, or %NULL
18001 * Returns the value associated with @key under @group_name
18002 * translated in the given @locale if available. If @locale is
18003 * %NULL then the current locale is assumed.
18005 * If @key cannot be found then %NULL is returned and @error is set
18006 * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated
18007 * with @key cannot be interpreted or no suitable translation can
18008 * be found then the untranslated value is returned.
18010 * Returns: a newly allocated string or %NULL if the specified
18011 * key cannot be found.
18017 * g_key_file_get_locale_string_list:
18018 * @key_file: a #GKeyFile
18019 * @group_name: a group name
18021 * @locale: (allow-none): a locale identifier or %NULL
18022 * @length: (out) (allow-none): return location for the number of returned strings or %NULL
18023 * @error: return location for a #GError or %NULL
18025 * Returns the values associated with @key under @group_name
18026 * translated in the given @locale if available. If @locale is
18027 * %NULL then the current locale is assumed.
18029 * If @key cannot be found then %NULL is returned and @error is set
18030 * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated
18031 * with @key cannot be interpreted or no suitable translations
18032 * can be found then the untranslated values are returned. The
18033 * returned array is %NULL-terminated, so @length may optionally
18036 * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): a newly allocated %NULL-terminated string array
18037 * or %NULL if the key isn't found. The string array should be freed
18038 * with g_strfreev().
18044 * g_key_file_get_start_group:
18045 * @key_file: a #GKeyFile
18047 * Returns the name of the start group of the file.
18049 * Returns: The start group of the key file.
18055 * g_key_file_get_string:
18056 * @key_file: a #GKeyFile
18057 * @group_name: a group name
18059 * @error: return location for a #GError, or %NULL
18061 * Returns the string value associated with @key under @group_name.
18062 * Unlike g_key_file_get_value(), this function handles escape sequences
18065 * In the event the key cannot be found, %NULL is returned and
18066 * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
18067 * event that the @group_name cannot be found, %NULL is returned
18068 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
18070 * Returns: a newly allocated string or %NULL if the specified
18071 * key cannot be found.
18077 * g_key_file_get_string_list:
18078 * @key_file: a #GKeyFile
18079 * @group_name: a group name
18081 * @length: (out) (allow-none): return location for the number of returned strings, or %NULL
18082 * @error: return location for a #GError, or %NULL
18084 * Returns the values associated with @key under @group_name.
18086 * In the event the key cannot be found, %NULL is returned and
18087 * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
18088 * event that the @group_name cannot be found, %NULL is returned
18089 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
18091 * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full):
18092 * a %NULL-terminated string array or %NULL if the specified
18093 * key cannot be found. The array should be freed with g_strfreev().
18099 * g_key_file_get_uint64:
18100 * @key_file: a non-%NULL #GKeyFile
18101 * @group_name: a non-%NULL group name
18102 * @key: a non-%NULL key
18103 * @error: return location for a #GError
18105 * Returns the value associated with @key under @group_name as an unsigned
18106 * 64-bit integer. This is similar to g_key_file_get_integer() but can return
18107 * large positive results without truncation.
18109 * Returns: the value associated with the key as an unsigned 64-bit integer,
18110 * or 0 if the key was not found or could not be parsed.
18116 * g_key_file_get_value:
18117 * @key_file: a #GKeyFile
18118 * @group_name: a group name
18120 * @error: return location for a #GError, or %NULL
18122 * Returns the raw value associated with @key under @group_name.
18123 * Use g_key_file_get_string() to retrieve an unescaped UTF-8 string.
18125 * In the event the key cannot be found, %NULL is returned and
18126 * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
18127 * event that the @group_name cannot be found, %NULL is returned
18128 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
18130 * Returns: a newly allocated string or %NULL if the specified
18131 * key cannot be found.
18137 * g_key_file_has_group:
18138 * @key_file: a #GKeyFile
18139 * @group_name: a group name
18141 * Looks whether the key file has the group @group_name.
18143 * Returns: %TRUE if @group_name is a part of @key_file, %FALSE
18150 * g_key_file_has_key: (skip)
18151 * @key_file: a #GKeyFile
18152 * @group_name: a group name
18154 * @error: return location for a #GError
18156 * Looks whether the key file has the key @key in the group
18159 * Note that this function does not follow the rules for #GError strictly;
18160 * the return value both carries meaning and signals an error. To use
18161 * this function, you must pass a #GError pointer in @error, and check
18162 * whether it is not %NULL to see if an error occurred.
18164 * Language bindings should use g_key_file_get_value() to test whether
18165 * or not a key exists.
18167 * Returns: %TRUE if @key is a part of @group_name, %FALSE otherwise
18173 * g_key_file_load_from_bytes:
18174 * @key_file: an empty #GKeyFile struct
18175 * @bytes: a #GBytes
18176 * @flags: flags from #GKeyFileFlags
18177 * @error: return location for a #GError, or %NULL
18179 * Loads a key file from the data in @bytes into an empty #GKeyFile structure.
18180 * If the object cannot be created then %error is set to a #GKeyFileError.
18182 * Returns: %TRUE if a key file could be loaded, %FALSE otherwise
18188 * g_key_file_load_from_data:
18189 * @key_file: an empty #GKeyFile struct
18190 * @data: key file loaded in memory
18191 * @length: the length of @data in bytes (or (gsize)-1 if data is nul-terminated)
18192 * @flags: flags from #GKeyFileFlags
18193 * @error: return location for a #GError, or %NULL
18195 * Loads a key file from memory into an empty #GKeyFile structure.
18196 * If the object cannot be created then %error is set to a #GKeyFileError.
18198 * Returns: %TRUE if a key file could be loaded, %FALSE otherwise
18204 * g_key_file_load_from_data_dirs:
18205 * @key_file: an empty #GKeyFile struct
18206 * @file: (type filename): a relative path to a filename to open and parse
18207 * @full_path: (out) (type filename) (allow-none): return location for a string containing the full path
18208 * of the file, or %NULL
18209 * @flags: flags from #GKeyFileFlags
18210 * @error: return location for a #GError, or %NULL
18212 * This function looks for a key file named @file in the paths
18213 * returned from g_get_user_data_dir() and g_get_system_data_dirs(),
18214 * loads the file into @key_file and returns the file's full path in
18215 * @full_path. If the file could not be loaded then an %error is
18216 * set to either a #GFileError or #GKeyFileError.
18218 * Returns: %TRUE if a key file could be loaded, %FALSE othewise
18224 * g_key_file_load_from_dirs:
18225 * @key_file: an empty #GKeyFile struct
18226 * @file: (type filename): a relative path to a filename to open and parse
18227 * @search_dirs: (array zero-terminated=1) (element-type filename): %NULL-terminated array of directories to search
18228 * @full_path: (out) (type filename) (allow-none): return location for a string containing the full path
18229 * of the file, or %NULL
18230 * @flags: flags from #GKeyFileFlags
18231 * @error: return location for a #GError, or %NULL
18233 * This function looks for a key file named @file in the paths
18234 * specified in @search_dirs, loads the file into @key_file and
18235 * returns the file's full path in @full_path. If the file could not
18236 * be loaded then an %error is set to either a #GFileError or
18239 * Returns: %TRUE if a key file could be loaded, %FALSE otherwise
18245 * g_key_file_load_from_file:
18246 * @key_file: an empty #GKeyFile struct
18247 * @file: (type filename): the path of a filename to load, in the GLib filename encoding
18248 * @flags: flags from #GKeyFileFlags
18249 * @error: return location for a #GError, or %NULL
18251 * Loads a key file into an empty #GKeyFile structure.
18252 * If the file could not be loaded then @error is set to
18253 * either a #GFileError or #GKeyFileError.
18255 * Returns: %TRUE if a key file could be loaded, %FALSE otherwise
18263 * Creates a new empty #GKeyFile object. Use
18264 * g_key_file_load_from_file(), g_key_file_load_from_data(),
18265 * g_key_file_load_from_dirs() or g_key_file_load_from_data_dirs() to
18266 * read an existing key file.
18268 * Returns: (transfer full): an empty #GKeyFile.
18274 * g_key_file_ref: (skip)
18275 * @key_file: a #GKeyFile
18277 * Increases the reference count of @key_file.
18279 * Returns: the same @key_file.
18285 * g_key_file_remove_comment:
18286 * @key_file: a #GKeyFile
18287 * @group_name: (allow-none): a group name, or %NULL
18288 * @key: (allow-none): a key
18289 * @error: return location for a #GError
18291 * Removes a comment above @key from @group_name.
18292 * If @key is %NULL then @comment will be removed above @group_name.
18293 * If both @key and @group_name are %NULL, then @comment will
18294 * be removed above the first group in the file.
18296 * Returns: %TRUE if the comment was removed, %FALSE otherwise
18302 * g_key_file_remove_group:
18303 * @key_file: a #GKeyFile
18304 * @group_name: a group name
18305 * @error: return location for a #GError or %NULL
18307 * Removes the specified group, @group_name,
18308 * from the key file.
18310 * Returns: %TRUE if the group was removed, %FALSE otherwise
18316 * g_key_file_remove_key:
18317 * @key_file: a #GKeyFile
18318 * @group_name: a group name
18319 * @key: a key name to remove
18320 * @error: return location for a #GError or %NULL
18322 * Removes @key in @group_name from the key file.
18324 * Returns: %TRUE if the key was removed, %FALSE otherwise
18330 * g_key_file_save_to_file:
18331 * @key_file: a #GKeyFile
18332 * @filename: the name of the file to write to
18333 * @error: a pointer to a %NULL #GError, or %NULL
18335 * Writes the contents of @key_file to @filename using
18336 * g_file_set_contents().
18338 * This function can fail for any of the reasons that
18339 * g_file_set_contents() may fail.
18341 * Returns: %TRUE if successful, else %FALSE with @error set
18347 * g_key_file_set_boolean:
18348 * @key_file: a #GKeyFile
18349 * @group_name: a group name
18351 * @value: %TRUE or %FALSE
18353 * Associates a new boolean value with @key under @group_name.
18354 * If @key cannot be found then it is created.
18361 * g_key_file_set_boolean_list:
18362 * @key_file: a #GKeyFile
18363 * @group_name: a group name
18365 * @list: (array length=length): an array of boolean values
18366 * @length: length of @list
18368 * Associates a list of boolean values with @key under @group_name.
18369 * If @key cannot be found then it is created.
18370 * If @group_name is %NULL, the start_group is used.
18377 * g_key_file_set_comment:
18378 * @key_file: a #GKeyFile
18379 * @group_name: (allow-none): a group name, or %NULL
18380 * @key: (allow-none): a key
18381 * @comment: a comment
18382 * @error: return location for a #GError
18384 * Places a comment above @key from @group_name.
18386 * If @key is %NULL then @comment will be written above @group_name.
18387 * If both @key and @group_name are %NULL, then @comment will be
18388 * written above the first group in the file.
18390 * Note that this function prepends a '#' comment marker to
18391 * each line of @comment.
18393 * Returns: %TRUE if the comment was written, %FALSE otherwise
18399 * g_key_file_set_double:
18400 * @key_file: a #GKeyFile
18401 * @group_name: a group name
18403 * @value: an double value
18405 * Associates a new double value with @key under @group_name.
18406 * If @key cannot be found then it is created.
18413 * g_key_file_set_double_list:
18414 * @key_file: a #GKeyFile
18415 * @group_name: a group name
18417 * @list: (array length=length): an array of double values
18418 * @length: number of double values in @list
18420 * Associates a list of double values with @key under
18421 * @group_name. If @key cannot be found then it is created.
18428 * g_key_file_set_int64:
18429 * @key_file: a #GKeyFile
18430 * @group_name: a group name
18432 * @value: an integer value
18434 * Associates a new integer value with @key under @group_name.
18435 * If @key cannot be found then it is created.
18442 * g_key_file_set_integer:
18443 * @key_file: a #GKeyFile
18444 * @group_name: a group name
18446 * @value: an integer value
18448 * Associates a new integer value with @key under @group_name.
18449 * If @key cannot be found then it is created.
18456 * g_key_file_set_integer_list:
18457 * @key_file: a #GKeyFile
18458 * @group_name: a group name
18460 * @list: (array length=length): an array of integer values
18461 * @length: number of integer values in @list
18463 * Associates a list of integer values with @key under @group_name.
18464 * If @key cannot be found then it is created.
18471 * g_key_file_set_list_separator:
18472 * @key_file: a #GKeyFile
18473 * @separator: the separator
18475 * Sets the character which is used to separate
18476 * values in lists. Typically ';' or ',' are used
18477 * as separators. The default list separator is ';'.
18484 * g_key_file_set_locale_string:
18485 * @key_file: a #GKeyFile
18486 * @group_name: a group name
18488 * @locale: a locale identifier
18489 * @string: a string
18491 * Associates a string value for @key and @locale under @group_name.
18492 * If the translation for @key cannot be found then it is created.
18499 * g_key_file_set_locale_string_list:
18500 * @key_file: a #GKeyFile
18501 * @group_name: a group name
18503 * @locale: a locale identifier
18504 * @list: (array zero-terminated=1 length=length): a %NULL-terminated array of locale string values
18505 * @length: the length of @list
18507 * Associates a list of string values for @key and @locale under
18508 * @group_name. If the translation for @key cannot be found then
18516 * g_key_file_set_string:
18517 * @key_file: a #GKeyFile
18518 * @group_name: a group name
18520 * @string: a string
18522 * Associates a new string value with @key under @group_name.
18523 * If @key cannot be found then it is created.
18524 * If @group_name cannot be found then it is created.
18525 * Unlike g_key_file_set_value(), this function handles characters
18526 * that need escaping, such as newlines.
18533 * g_key_file_set_string_list:
18534 * @key_file: a #GKeyFile
18535 * @group_name: a group name
18537 * @list: (array zero-terminated=1 length=length) (element-type utf8): an array of string values
18538 * @length: number of string values in @list
18540 * Associates a list of string values for @key under @group_name.
18541 * If @key cannot be found then it is created.
18542 * If @group_name cannot be found then it is created.
18549 * g_key_file_set_uint64:
18550 * @key_file: a #GKeyFile
18551 * @group_name: a group name
18553 * @value: an integer value
18555 * Associates a new integer value with @key under @group_name.
18556 * If @key cannot be found then it is created.
18563 * g_key_file_set_value:
18564 * @key_file: a #GKeyFile
18565 * @group_name: a group name
18569 * Associates a new value with @key under @group_name.
18571 * If @key cannot be found then it is created. If @group_name cannot
18572 * be found then it is created. To set an UTF-8 string which may contain
18573 * characters that need escaping (such as newlines or spaces), use
18574 * g_key_file_set_string().
18581 * g_key_file_to_data:
18582 * @key_file: a #GKeyFile
18583 * @length: (out) (allow-none): return location for the length of the
18584 * returned string, or %NULL
18585 * @error: return location for a #GError, or %NULL
18587 * This function outputs @key_file as a string.
18589 * Note that this function never reports an error,
18590 * so it is safe to pass %NULL as @error.
18592 * Returns: a newly allocated string holding
18593 * the contents of the #GKeyFile
18599 * g_key_file_unref:
18600 * @key_file: a #GKeyFile
18602 * Decreases the reference count of @key_file by 1. If the reference count
18603 * reaches zero, frees the key file and all its allocated memory.
18612 * Allocates space for one #GList element. It is called by
18613 * g_list_append(), g_list_prepend(), g_list_insert() and
18614 * g_list_insert_sorted() and so is rarely used on its own.
18616 * Returns: a pointer to the newly-allocated #GList element
18622 * @list: a pointer to a #GList
18623 * @data: the data for the new element
18625 * Adds a new element on to the end of the list.
18627 * Note that the return value is the new start of the list,
18628 * if @list was empty; make sure you store the new value.
18630 * g_list_append() has to traverse the entire list to find the end,
18631 * which is inefficient when adding multiple elements. A common idiom
18632 * to avoid the inefficiency is to use g_list_prepend() and reverse
18633 * the list with g_list_reverse() when all elements have been added.
18635 * |[<!-- language="C" -->
18636 * // Notice that these are initialized to the empty list.
18637 * GList *string_list = NULL, *number_list = NULL;
18639 * // This is a list of strings.
18640 * string_list = g_list_append (string_list, "first");
18641 * string_list = g_list_append (string_list, "second");
18643 * // This is a list of integers.
18644 * number_list = g_list_append (number_list, GINT_TO_POINTER (27));
18645 * number_list = g_list_append (number_list, GINT_TO_POINTER (14));
18648 * Returns: either @list or the new start of the #GList if @list was %NULL
18654 * @list1: a #GList, this must point to the top of the list
18655 * @list2: the #GList to add to the end of the first #GList,
18656 * this must point to the top of the list
18658 * Adds the second #GList onto the end of the first #GList.
18659 * Note that the elements of the second #GList are not copied.
18660 * They are used directly.
18662 * This function is for example used to move an element in the list.
18663 * The following example moves an element to the top of the list:
18664 * |[<!-- language="C" -->
18665 * list = g_list_remove_link (list, llink);
18666 * list = g_list_concat (llink, list);
18669 * Returns: the start of the new #GList, which equals @list1 if not %NULL
18675 * @list: a #GList, this must point to the top of the list
18679 * Note that this is a "shallow" copy. If the list elements
18680 * consist of pointers to data, the pointers are copied but
18681 * the actual data is not. See g_list_copy_deep() if you need
18682 * to copy the data as well.
18684 * Returns: the start of the new list that holds the same data as @list
18689 * g_list_copy_deep:
18690 * @list: a #GList, this must point to the top of the list
18691 * @func: a copy function used to copy every element in the list
18692 * @user_data: user data passed to the copy function @func, or %NULL
18694 * Makes a full (deep) copy of a #GList.
18696 * In contrast with g_list_copy(), this function uses @func to make
18697 * a copy of each list element, in addition to copying the list
18698 * container itself.
18700 * @func, as a #GCopyFunc, takes two arguments, the data to be copied
18701 * and a @user_data pointer. It's safe to pass %NULL as user_data,
18702 * if the copy function takes only one argument.
18704 * For instance, if @list holds a list of GObjects, you can do:
18705 * |[<!-- language="C" -->
18706 * another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL);
18709 * And, to entirely free the new list, you could do:
18710 * |[<!-- language="C" -->
18711 * g_list_free_full (another_list, g_object_unref);
18714 * Returns: the start of the new list that holds a full copy of @list,
18715 * use g_list_free_full() to free it
18721 * g_list_delete_link:
18722 * @list: a #GList, this must point to the top of the list
18723 * @link_: node to delete from @list
18725 * Removes the node link_ from the list and frees it.
18726 * Compare this to g_list_remove_link() which removes the node
18727 * without freeing it.
18729 * Returns: the (possibly changed) start of the #GList
18735 * @list: a #GList, this must point to the top of the list
18736 * @data: the element data to find
18738 * Finds the element in a #GList which contains the given data.
18740 * Returns: the found #GList element, or %NULL if it is not found
18745 * g_list_find_custom:
18746 * @list: a #GList, this must point to the top of the list
18747 * @data: user data passed to the function
18748 * @func: the function to call for each element.
18749 * It should return 0 when the desired element is found
18751 * Finds an element in a #GList, using a supplied function to
18752 * find the desired element. It iterates over the list, calling
18753 * the given function which should return 0 when the desired
18754 * element is found. The function takes two #gconstpointer arguments,
18755 * the #GList element's data as the first argument and the
18758 * Returns: the found #GList element, or %NULL if it is not found
18764 * @list: any #GList element
18766 * Gets the first element in a #GList.
18768 * Returns: the first element in the #GList,
18769 * or %NULL if the #GList has no elements
18775 * @list: a #GList, this must point to the top of the list
18776 * @func: the function to call with each element's data
18777 * @user_data: user data to pass to the function
18779 * Calls a function for each element of a #GList.
18787 * Frees all of the memory used by a #GList.
18788 * The freed elements are returned to the slice allocator.
18790 * If list elements contain dynamically-allocated memory, you should
18791 * either use g_list_free_full() or free them manually first.
18798 * Another name for g_list_free_1().
18804 * @list: a #GList element
18806 * Frees one #GList element, but does not update links from the next and
18807 * previous elements in the list, so you should not call this function on an
18808 * element that is currently part of a list.
18810 * It is usually used after g_list_remove_link().
18815 * g_list_free_full:
18816 * @list: a pointer to a #GList
18817 * @free_func: the function to be called to free each element's data
18819 * Convenience method, which frees all the memory used by a #GList,
18820 * and calls @free_func on every element's data.
18828 * @list: a #GList, this must point to the top of the list
18829 * @data: the data to find
18831 * Gets the position of the element containing
18832 * the given data (starting from 0).
18834 * Returns: the index of the element containing the data,
18835 * or -1 if the data is not found
18841 * @list: a pointer to a #GList, this must point to the top of the list
18842 * @data: the data for the new element
18843 * @position: the position to insert the element. If this is
18844 * negative, or is larger than the number of elements in the
18845 * list, the new element is added on to the end of the list.
18847 * Inserts a new element into the list at the given position.
18849 * Returns: the (possibly changed) start of the #GList
18854 * g_list_insert_before:
18855 * @list: a pointer to a #GList, this must point to the top of the list
18856 * @sibling: the list element before which the new element
18857 * is inserted or %NULL to insert at the end of the list
18858 * @data: the data for the new element
18860 * Inserts a new element into the list before the given position.
18862 * Returns: the (possibly changed) start of the #GList
18867 * g_list_insert_sorted:
18868 * @list: a pointer to a #GList, this must point to the top of the
18869 * already sorted list
18870 * @data: the data for the new element
18871 * @func: the function to compare elements in the list. It should
18872 * return a number > 0 if the first parameter comes after the
18873 * second parameter in the sort order.
18875 * Inserts a new element into the list, using the given comparison
18876 * function to determine its position.
18878 * If you are adding many new elements to a list, and the number of
18879 * new elements is much larger than the length of the list, use
18880 * g_list_prepend() to add the new items and sort the list afterwards
18881 * with g_list_sort().
18883 * Returns: the (possibly changed) start of the #GList
18888 * g_list_insert_sorted_with_data:
18889 * @list: a pointer to a #GList, this must point to the top of the
18890 * already sorted list
18891 * @data: the data for the new element
18892 * @func: the function to compare elements in the list. It should
18893 * return a number > 0 if the first parameter comes after the
18894 * second parameter in the sort order.
18895 * @user_data: user data to pass to comparison function
18897 * Inserts a new element into the list, using the given comparison
18898 * function to determine its position.
18900 * If you are adding many new elements to a list, and the number of
18901 * new elements is much larger than the length of the list, use
18902 * g_list_prepend() to add the new items and sort the list afterwards
18903 * with g_list_sort().
18905 * Returns: the (possibly changed) start of the #GList
18912 * @list: any #GList element
18914 * Gets the last element in a #GList.
18916 * Returns: the last element in the #GList,
18917 * or %NULL if the #GList has no elements
18923 * @list: a #GList, this must point to the top of the list
18925 * Gets the number of elements in a #GList.
18927 * This function iterates over the whole list to count its elements.
18928 * Use a #GQueue instead of a GList if you regularly need the number
18929 * of items. To check whether the list is non-empty, it is faster to check
18930 * @list against %NULL.
18932 * Returns: the number of elements in the #GList
18938 * @list: an element in a #GList
18940 * A convenience macro to get the next element in a #GList.
18941 * Note that it is considered perfectly acceptable to access
18942 * @list->next directly.
18944 * Returns: the next element, or %NULL if there are no more elements
18950 * @list: a #GList, this must point to the top of the list
18951 * @n: the position of the element, counting from 0
18953 * Gets the element at the given position in a #GList.
18955 * This iterates over the list until it reaches the @n-th position. If you
18956 * intend to iterate over every element, it is better to use a for-loop as
18957 * described in the #GList introduction.
18959 * Returns: the element, or %NULL if the position is off
18960 * the end of the #GList
18966 * @list: a #GList, this must point to the top of the list
18967 * @n: the position of the element
18969 * Gets the data of the element at the given position.
18971 * This iterates over the list until it reaches the @n-th position. If you
18972 * intend to iterate over every element, it is better to use a for-loop as
18973 * described in the #GList introduction.
18975 * Returns: the element's data, or %NULL if the position
18976 * is off the end of the #GList
18983 * @n: the position of the element, counting from 0
18985 * Gets the element @n places before @list.
18987 * Returns: the element, or %NULL if the position is
18988 * off the end of the #GList
18994 * @list: a #GList, this must point to the top of the list
18995 * @llink: an element in the #GList
18997 * Gets the position of the given element
18998 * in the #GList (starting from 0).
19000 * Returns: the position of the element in the #GList,
19001 * or -1 if the element is not found
19007 * @list: a pointer to a #GList, this must point to the top of the list
19008 * @data: the data for the new element
19010 * Prepends a new element on to the start of the list.
19012 * Note that the return value is the new start of the list,
19013 * which will have changed, so make sure you store the new value.
19015 * |[<!-- language="C" -->
19016 * // Notice that it is initialized to the empty list.
19017 * GList *list = NULL;
19019 * list = g_list_prepend (list, "last");
19020 * list = g_list_prepend (list, "first");
19023 * Do not use this function to prepend a new element to a different
19024 * element than the start of the list. Use g_list_insert_before() instead.
19026 * Returns: a pointer to the newly prepended element, which is the new
19027 * start of the #GList
19033 * @list: an element in a #GList
19035 * A convenience macro to get the previous element in a #GList.
19036 * Note that it is considered perfectly acceptable to access
19037 * @list->previous directly.
19039 * Returns: the previous element, or %NULL if there are no previous
19046 * @list: a #GList, this must point to the top of the list
19047 * @data: the data of the element to remove
19049 * Removes an element from a #GList.
19050 * If two elements contain the same data, only the first is removed.
19051 * If none of the elements contain the data, the #GList is unchanged.
19053 * Returns: the (possibly changed) start of the #GList
19058 * g_list_remove_all:
19059 * @list: a #GList, this must point to the top of the list
19060 * @data: data to remove
19062 * Removes all list nodes with data equal to @data.
19063 * Returns the new head of the list. Contrast with
19064 * g_list_remove() which removes only the first node
19065 * matching the given data.
19067 * Returns: the (possibly changed) start of the #GList
19072 * g_list_remove_link:
19073 * @list: a #GList, this must point to the top of the list
19074 * @llink: an element in the #GList
19076 * Removes an element from a #GList, without freeing the element.
19077 * The removed element's prev and next links are set to %NULL, so
19078 * that it becomes a self-contained list with one element.
19080 * This function is for example used to move an element in the list
19081 * (see the example for g_list_concat()) or to remove an element in
19082 * the list before freeing its data:
19083 * |[<!-- language="C" -->
19084 * list = g_list_remove_link (list, llink);
19085 * free_some_data_that_may_access_the_list_again (llink->data);
19086 * g_list_free (llink);
19089 * Returns: the (possibly changed) start of the #GList
19095 * @list: a #GList, this must point to the top of the list
19097 * Reverses a #GList.
19098 * It simply switches the next and prev pointers of each element.
19100 * Returns: the start of the reversed #GList
19106 * @list: a #GList, this must point to the top of the list
19107 * @compare_func: the comparison function used to sort the #GList.
19108 * This function is passed the data from 2 elements of the #GList
19109 * and should return 0 if they are equal, a negative value if the
19110 * first element comes before the second, or a positive value if
19111 * the first element comes after the second.
19113 * Sorts a #GList using the given comparison function. The algorithm
19114 * used is a stable sort.
19116 * Returns: the (possibly changed) start of the #GList
19121 * g_list_sort_with_data:
19122 * @list: a #GList, this must point to the top of the list
19123 * @compare_func: comparison function
19124 * @user_data: user data to pass to comparison function
19126 * Like g_list_sort(), but the comparison function accepts
19127 * a user data argument.
19129 * Returns: the (possibly changed) start of the #GList
19136 * Gets the names of all variables set in the environment.
19138 * Programs that want to be portable to Windows should typically use
19139 * this function and g_getenv() instead of using the environ array
19140 * from the C library directly. On Windows, the strings in the environ
19141 * array are in system codepage encoding, while in most of the typical
19142 * use cases for environment variables in GLib-using programs you want
19143 * the UTF-8 encoding that this function and g_getenv() provide.
19145 * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated
19146 * list of strings which must be freed with g_strfreev().
19152 * g_locale_from_utf8:
19153 * @utf8string: a UTF-8 encoded string
19154 * @len: the length of the string, or -1 if the string is
19155 * nul-terminated (Note that some encodings may allow nul
19156 * bytes to occur inside strings. In that case, using -1
19157 * for the @len parameter is unsafe)
19158 * @bytes_read: (out) (optional): location to store the number of bytes in the
19159 * input string that were successfully converted, or %NULL.
19160 * Even if the conversion was successful, this may be
19161 * less than @len if there were partial characters
19162 * at the end of the input. If the error
19163 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
19164 * stored will the byte offset after the last valid
19166 * @bytes_written: (out) (optional): the number of bytes stored in the output
19167 * buffer (not including the terminating nul).
19168 * @error: location to store the error occurring, or %NULL to ignore
19169 * errors. Any of the errors in #GConvertError may occur.
19171 * Converts a string from UTF-8 to the encoding used for strings by
19172 * the C runtime (usually the same as that used by the operating
19173 * system) in the [current locale][setlocale]. On Windows this means
19174 * the system codepage.
19176 * Returns: A newly-allocated buffer containing the converted string,
19177 * or %NULL on an error, and error will be set.
19182 * g_locale_to_utf8:
19183 * @opsysstring: a string in the encoding of the current locale. On Windows
19184 * this means the system codepage.
19185 * @len: the length of the string, or -1 if the string is
19186 * nul-terminated (Note that some encodings may allow nul
19187 * bytes to occur inside strings. In that case, using -1
19188 * for the @len parameter is unsafe)
19189 * @bytes_read: (out) (optional): location to store the number of bytes in the
19190 * input string that were successfully converted, or %NULL.
19191 * Even if the conversion was successful, this may be
19192 * less than @len if there were partial characters
19193 * at the end of the input. If the error
19194 * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
19195 * stored will the byte offset after the last valid
19197 * @bytes_written: (out) (optional): the number of bytes stored in the output
19198 * buffer (not including the terminating nul).
19199 * @error: location to store the error occurring, or %NULL to ignore
19200 * errors. Any of the errors in #GConvertError may occur.
19202 * Converts a string which is in the encoding used for strings by
19203 * the C runtime (usually the same as that used by the operating
19204 * system) in the [current locale][setlocale] into a UTF-8 string.
19206 * Returns: A newly-allocated buffer containing the converted string,
19207 * or %NULL on an error, and error will be set.
19213 * @log_domain: (nullable): the log domain, usually #G_LOG_DOMAIN, or %NULL
19215 * @log_level: the log level, either from #GLogLevelFlags
19216 * or a user-defined level
19217 * @format: the message format. See the printf() documentation
19218 * @...: the parameters to insert into the format string
19220 * Logs an error or debugging message.
19222 * If the log level has been set as fatal, the abort()
19223 * function is called to terminate the program.
19225 * If g_log_default_handler() is used as the log handler function, a new-line
19226 * character will automatically be appended to @..., and need not be entered
19232 * g_log_default_handler:
19233 * @log_domain: (nullable): the log domain of the message, or %NULL for the
19234 * default "" application domain
19235 * @log_level: the level of the message
19236 * @message: (nullable): the message
19237 * @unused_data: (nullable): data passed from g_log() which is unused
19239 * The default log handler set up by GLib; g_log_set_default_handler()
19240 * allows to install an alternate default log handler.
19241 * This is used if no log handler has been set for the particular log
19242 * domain and log level combination. It outputs the message to stderr
19243 * or stdout and if the log level is fatal it calls abort(). It automatically
19244 * prints a new-line character after the message, so one does not need to be
19245 * manually included in @message.
19247 * The behavior of this log handler can be influenced by a number of
19248 * environment variables:
19250 * - `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which
19251 * messages should be prefixed by the program name and PID of the
19254 * - `G_MESSAGES_DEBUG`: A space-separated list of log domains for
19255 * which debug and informational messages are printed. By default
19256 * these messages are not printed.
19258 * stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL,
19259 * %G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for
19265 * g_log_remove_handler:
19266 * @log_domain: the log domain
19267 * @handler_id: the id of the handler, which was returned
19268 * in g_log_set_handler()
19270 * Removes the log handler.
19275 * g_log_set_always_fatal:
19276 * @fatal_mask: the mask containing bits set for each level
19277 * of error which is to be fatal
19279 * Sets the message levels which are always fatal, in any log domain.
19280 * When a message with any of these levels is logged the program terminates.
19281 * You can only set the levels defined by GLib to be fatal.
19282 * %G_LOG_LEVEL_ERROR is always fatal.
19284 * You can also make some message levels fatal at runtime by setting
19285 * the `G_DEBUG` environment variable (see
19286 * [Running GLib Applications](glib-running.html)).
19288 * Libraries should not call this function, as it affects all messages logged
19289 * by a process, including those from other libraries.
19291 * Structured log messages (using g_log_structured() and
19292 * g_log_structured_array()) are fatal only if the default log writer is used;
19293 * otherwise it is up to the writer function to determine which log messages
19296 * Returns: the old fatal mask
19301 * g_log_set_default_handler:
19302 * @log_func: the log handler function
19303 * @user_data: data passed to the log handler
19305 * Installs a default log handler which is used if no
19306 * log handler has been set for the particular log domain
19307 * and log level combination. By default, GLib uses
19308 * g_log_default_handler() as default log handler.
19310 * Returns: the previous default log handler
19316 * g_log_set_fatal_mask:
19317 * @log_domain: the log domain
19318 * @fatal_mask: the new fatal mask
19320 * Sets the log levels which are fatal in the given domain.
19321 * %G_LOG_LEVEL_ERROR is always fatal.
19323 * This has no effect on structured log messages (using g_log_structured() or
19324 * g_log_structured_array()). To change the fatal behaviour for specific log
19325 * messages, programs must install a custom log writer function using
19326 * g_log_set_writer_func().
19328 * Returns: the old fatal mask for the log domain
19333 * g_log_set_handler:
19334 * @log_domain: (allow-none): the log domain, or %NULL for the default ""
19335 * application domain
19336 * @log_levels: the log levels to apply the log handler for.
19337 * To handle fatal and recursive messages as well, combine
19338 * the log levels with the #G_LOG_FLAG_FATAL and
19339 * #G_LOG_FLAG_RECURSION bit flags.
19340 * @log_func: the log handler function
19341 * @user_data: data passed to the log handler
19343 * Sets the log handler for a domain and a set of log levels.
19344 * To handle fatal and recursive messages the @log_levels parameter
19345 * must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION
19348 * Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if
19349 * you want to set a handler for this log level you must combine it with
19350 * #G_LOG_FLAG_FATAL.
19352 * Here is an example for adding a log handler for all warning messages
19353 * in the default domain:
19354 * |[<!-- language="C" -->
19355 * g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
19356 * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
19359 * This example adds a log handler for all critical messages from GTK+:
19360 * |[<!-- language="C" -->
19361 * g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
19362 * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
19365 * This example adds a log handler for all messages from GLib:
19366 * |[<!-- language="C" -->
19367 * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
19368 * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
19371 * Returns: the id of the new handler
19376 * g_log_set_handler_full: (rename-to g_log_set_handler)
19377 * @log_domain: (allow-none): the log domain, or %NULL for the default ""
19378 * application domain
19379 * @log_levels: the log levels to apply the log handler for.
19380 * To handle fatal and recursive messages as well, combine
19381 * the log levels with the #G_LOG_FLAG_FATAL and
19382 * #G_LOG_FLAG_RECURSION bit flags.
19383 * @log_func: the log handler function
19384 * @user_data: data passed to the log handler
19385 * @destroy: destroy notify for @user_data, or %NULL
19387 * Like g_log_sets_handler(), but takes a destroy notify for the @user_data.
19389 * Returns: the id of the new handler
19395 * g_log_set_writer_func:
19396 * @func: log writer function, which must not be %NULL
19397 * @user_data: (closure func): user data to pass to @func
19398 * @user_data_free: (destroy func): function to free @user_data once it’s
19399 * finished with, if non-%NULL
19401 * Set a writer function which will be called to format and write out each log
19402 * message. Each program should set a writer function, or the default writer
19403 * (g_log_writer_default()) will be used.
19405 * Libraries **must not** call this function — only programs are allowed to
19406 * install a writer function, as there must be a single, central point where
19407 * log messages are formatted and outputted.
19409 * There can only be one writer function. It is an error to set more than one.
19416 * g_log_structured:
19417 * @log_domain: log domain, usually %G_LOG_DOMAIN
19418 * @log_level: log level, either from #GLogLevelFlags, or a user-defined
19420 * @...: key-value pairs of structured data to add to the log entry, followed
19421 * by the key "MESSAGE", followed by a printf()-style message format,
19422 * followed by parameters to insert in the format string
19424 * Log a message with structured data. The message will be passed through to
19425 * the log writer set by the application using g_log_set_writer_func(). If the
19426 * message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will
19427 * be aborted at the end of this function.
19429 * The structured data is provided as key–value pairs, where keys are UTF-8
19430 * strings, and values are arbitrary pointers — typically pointing to UTF-8
19431 * strings, but that is not a requirement. To pass binary (non-nul-terminated)
19432 * structured data, use g_log_structured_array(). The keys for structured data
19433 * should follow the [systemd journal
19434 * fields](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html)
19435 * specification. It is suggested that custom keys are namespaced according to
19436 * the code which sets them. For example, custom keys from GLib all have a
19439 * The @log_domain will be converted into a `GLIB_DOMAIN` field. @log_level will
19440 * be converted into a
19441 * [`PRIORITY`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#PRIORITY=)
19442 * field. The format string will have its placeholders substituted for the provided
19443 * values and be converted into a
19444 * [`MESSAGE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE=)
19447 * Other fields you may commonly want to pass into this function:
19449 * * [`MESSAGE_ID`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=)
19450 * * [`CODE_FILE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=)
19451 * * [`CODE_LINE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_LINE=)
19452 * * [`CODE_FUNC`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FUNC=)
19453 * * [`ERRNO`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=)
19455 * Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by
19456 * the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(),
19457 * g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including
19461 * |[<!-- language="C" -->
19462 * g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,
19463 * "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e",
19464 * "MY_APPLICATION_CUSTOM_FIELD", "some debug string",
19465 * "MESSAGE", "This is a debug message about pointer %p and integer %u.",
19466 * some_pointer, some_integer);
19469 * Note that each `MESSAGE_ID` must be [uniquely and randomly
19470 * generated](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=).
19471 * If adding a `MESSAGE_ID`, consider shipping a [message
19472 * catalog](https://www.freedesktop.org/wiki/Software/systemd/catalog/) with
19475 * To pass a user data pointer to the log writer function which is specific to
19476 * this logging call, you must use g_log_structured_array() and pass the pointer
19477 * as a field with #GLogField.length set to zero, otherwise it will be
19478 * interpreted as a string.
19481 * |[<!-- language="C" -->
19482 * const GLogField fields[] = {
19483 * { "MESSAGE", "This is a debug message.", -1 },
19484 * { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 },
19485 * { "MY_APPLICATION_CUSTOM_FIELD", "some debug string", -1 },
19486 * { "MY_APPLICATION_STATE", state_object, 0 },
19488 * g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields));
19491 * Note also that, even if no structured fields are specified, the key-value
19492 * part of the argument list must be %NULL-terminated.
19494 * The default writer function for `stdout` and `stderr` will automatically
19495 * append a new-line character after the message, so you should not add one
19496 * manually to the format string.
19503 * g_log_structured_array:
19504 * @log_level: log level, either from #GLogLevelFlags, or a user-defined
19506 * @fields: (array length=n_fields): key–value pairs of structured data to add
19507 * to the log message
19508 * @n_fields: number of elements in the @fields array
19510 * Log a message with structured data. The message will be passed through to the
19511 * log writer set by the application using g_log_set_writer_func(). If the
19512 * message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will
19513 * be aborted at the end of this function.
19515 * See g_log_structured() for more documentation.
19517 * This assumes that @log_level is already present in @fields (typically as the
19518 * `PRIORITY` field).
19525 * g_log_writer_default:
19526 * @log_level: log level, either from #GLogLevelFlags, or a user-defined
19528 * @fields: (array length=n_fields): key–value pairs of structured data forming
19530 * @n_fields: number of elements in the @fields array
19531 * @user_data: user data passed to g_log_set_writer_func()
19533 * Format a structured log message and output it to the default log destination
19534 * for the platform. On Linux, this is typically the systemd journal, falling
19535 * back to `stdout` or `stderr` if running from the terminal or if output is
19536 * being redirected to a file.
19538 * Support for other platform-specific logging mechanisms may be added in
19539 * future. Distributors of GLib may modify this function to impose their own
19540 * (documented) platform-specific log writing policies.
19542 * This is suitable for use as a #GLogWriterFunc, and is the default writer used
19543 * if no other is set using g_log_set_writer_func().
19545 * Returns: %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise
19551 * g_log_writer_format_fields:
19552 * @log_level: log level, either from #GLogLevelFlags, or a user-defined
19554 * @fields: (array length=n_fields): key–value pairs of structured data forming
19556 * @n_fields: number of elements in the @fields array
19557 * @use_color: %TRUE to use ANSI color escape sequences when formatting the
19558 * message, %FALSE to not
19560 * Format a structured log message as a string suitable for outputting to the
19561 * terminal (or elsewhere). This will include the values of all fields it knows
19562 * how to interpret, which includes `MESSAGE` and `GLIB_DOMAIN` (see the
19563 * documentation for g_log_structured()). It does not include values from
19566 * The returned string does **not** have a trailing new-line character. It is
19567 * encoded in the character set of the current locale, which is not necessarily
19570 * Returns: (transfer full): string containing the formatted log message, in
19571 * the character set of the current locale
19577 * g_log_writer_is_journald:
19578 * @output_fd: output file descriptor to check
19580 * Check whether the given @output_fd file descriptor is a connection to the
19581 * systemd journal, or something else (like a log file or `stdout` or
19584 * Returns: %TRUE if @output_fd points to the journal, %FALSE otherwise
19590 * g_log_writer_journald:
19591 * @log_level: log level, either from #GLogLevelFlags, or a user-defined
19593 * @fields: (array length=n_fields): key–value pairs of structured data forming
19595 * @n_fields: number of elements in the @fields array
19596 * @user_data: user data passed to g_log_set_writer_func()
19598 * Format a structured log message and send it to the systemd journal as a set
19599 * of key–value pairs. All fields are sent to the journal, but if a field has
19600 * length zero (indicating program-specific data) then only its key will be
19603 * This is suitable for use as a #GLogWriterFunc.
19605 * If GLib has been compiled without systemd support, this function is still
19606 * defined, but will always return %G_LOG_WRITER_UNHANDLED.
19608 * Returns: %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise
19614 * g_log_writer_standard_streams:
19615 * @log_level: log level, either from #GLogLevelFlags, or a user-defined
19617 * @fields: (array length=n_fields): key–value pairs of structured data forming
19619 * @n_fields: number of elements in the @fields array
19620 * @user_data: user data passed to g_log_set_writer_func()
19622 * Format a structured log message and print it to either `stdout` or `stderr`,
19623 * depending on its log level. %G_LOG_LEVEL_INFO and %G_LOG_LEVEL_DEBUG messages
19624 * are sent to `stdout`; all other log levels are sent to `stderr`. Only fields
19625 * which are understood by this function are included in the formatted string
19626 * which is printed.
19628 * If the output stream supports ANSI color escape sequences, they will be used
19631 * A trailing new-line character is added to the log message when it is printed.
19633 * This is suitable for use as a #GLogWriterFunc.
19635 * Returns: %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise
19641 * g_log_writer_supports_color:
19642 * @output_fd: output file descriptor to check
19644 * Check whether the given @output_fd file descriptor supports ANSI color
19645 * escape sequences. If so, they can safely be used when formatting log
19648 * Returns: %TRUE if ANSI color escapes are supported, %FALSE otherwise
19655 * @log_domain: (nullable): the log domain, or %NULL for the default ""
19656 * application domain
19657 * @log_level: the log level
19658 * @format: the message format. See the printf() documentation
19659 * @args: the parameters to insert into the format string
19661 * Logs an error or debugging message.
19663 * If the log level has been set as fatal, the abort()
19664 * function is called to terminate the program.
19666 * If g_log_default_handler() is used as the log handler function, a new-line
19667 * character will automatically be appended to @..., and need not be entered
19674 * @filename: (type filename): a pathname in the GLib file name encoding
19675 * (UTF-8 on Windows)
19676 * @buf: a pointer to a stat struct, which will be filled with the file
19679 * A wrapper for the POSIX lstat() function. The lstat() function is
19680 * like stat() except that in the case of symbolic links, it returns
19681 * information about the symbolic link itself and not the file that it
19682 * refers to. If the system does not support symbolic links g_lstat()
19683 * is identical to g_stat().
19685 * See your C library manual for more details about lstat().
19687 * Returns: 0 if the information was successfully retrieved,
19688 * -1 if an error occurred
19694 * g_main_context_acquire:
19695 * @context: a #GMainContext
19697 * Tries to become the owner of the specified context.
19698 * If some other thread is the owner of the context,
19699 * returns %FALSE immediately. Ownership is properly
19700 * recursive: the owner can require ownership again
19701 * and will release ownership when g_main_context_release()
19702 * is called as many times as g_main_context_acquire().
19704 * You must be the owner of a context before you
19705 * can call g_main_context_prepare(), g_main_context_query(),
19706 * g_main_context_check(), g_main_context_dispatch().
19708 * Returns: %TRUE if the operation succeeded, and
19709 * this thread is now the owner of @context.
19714 * g_main_context_add_poll:
19715 * @context: (allow-none): a #GMainContext (or %NULL for the default context)
19716 * @fd: a #GPollFD structure holding information about a file
19717 * descriptor to watch.
19718 * @priority: the priority for this file descriptor which should be
19719 * the same as the priority used for g_source_attach() to ensure that the
19720 * file descriptor is polled whenever the results may be needed.
19722 * Adds a file descriptor to the set of file descriptors polled for
19723 * this context. This will very seldom be used directly. Instead
19724 * a typical event source will use g_source_add_unix_fd() instead.
19729 * g_main_context_check:
19730 * @context: a #GMainContext
19731 * @max_priority: the maximum numerical priority of sources to check
19732 * @fds: (array length=n_fds): array of #GPollFD's that was passed to
19733 * the last call to g_main_context_query()
19734 * @n_fds: return value of g_main_context_query()
19736 * Passes the results of polling back to the main loop.
19738 * You must have successfully acquired the context with
19739 * g_main_context_acquire() before you may call this function.
19741 * Returns: %TRUE if some sources are ready to be dispatched.
19746 * g_main_context_default:
19748 * Returns the global default main context. This is the main context
19749 * used for main loop functions when a main loop is not explicitly
19750 * specified, and corresponds to the "main" main loop. See also
19751 * g_main_context_get_thread_default().
19753 * Returns: (transfer none): the global default main context.
19758 * g_main_context_dispatch:
19759 * @context: a #GMainContext
19761 * Dispatches all pending sources.
19763 * You must have successfully acquired the context with
19764 * g_main_context_acquire() before you may call this function.
19769 * g_main_context_find_source_by_funcs_user_data:
19770 * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used).
19771 * @funcs: the @source_funcs passed to g_source_new().
19772 * @user_data: the user data from the callback.
19774 * Finds a source with the given source functions and user data. If
19775 * multiple sources exist with the same source function and user data,
19776 * the first one found will be returned.
19778 * Returns: (transfer none): the source, if one was found, otherwise %NULL
19783 * g_main_context_find_source_by_id:
19784 * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used)
19785 * @source_id: the source ID, as returned by g_source_get_id().
19787 * Finds a #GSource given a pair of context and ID.
19789 * It is a programmer error to attempt to lookup a non-existent source.
19791 * More specifically: source IDs can be reissued after a source has been
19792 * destroyed and therefore it is never valid to use this function with a
19793 * source ID which may have already been removed. An example is when
19794 * scheduling an idle to run in another thread with g_idle_add(): the
19795 * idle may already have run and been removed by the time this function
19796 * is called on its (now invalid) source ID. This source ID may have
19797 * been reissued, leading to the operation being performed against the
19800 * Returns: (transfer none): the #GSource
19805 * g_main_context_find_source_by_user_data:
19806 * @context: a #GMainContext
19807 * @user_data: the user_data for the callback.
19809 * Finds a source with the given user data for the callback. If
19810 * multiple sources exist with the same user data, the first
19811 * one found will be returned.
19813 * Returns: (transfer none): the source, if one was found, otherwise %NULL
19818 * g_main_context_get_poll_func:
19819 * @context: a #GMainContext
19821 * Gets the poll function set by g_main_context_set_poll_func().
19823 * Returns: the poll function
19828 * g_main_context_get_thread_default:
19830 * Gets the thread-default #GMainContext for this thread. Asynchronous
19831 * operations that want to be able to be run in contexts other than
19832 * the default one should call this method or
19833 * g_main_context_ref_thread_default() to get a #GMainContext to add
19834 * their #GSources to. (Note that even in single-threaded
19835 * programs applications may sometimes want to temporarily push a
19836 * non-default context, so it is not safe to assume that this will
19837 * always return %NULL if you are running in the default thread.)
19839 * If you need to hold a reference on the context, use
19840 * g_main_context_ref_thread_default() instead.
19842 * Returns: (transfer none): the thread-default #GMainContext, or
19843 * %NULL if the thread-default context is the global default context.
19849 * g_main_context_invoke:
19850 * @context: (allow-none): a #GMainContext, or %NULL
19851 * @function: function to call
19852 * @data: data to pass to @function
19854 * Invokes a function in such a way that @context is owned during the
19855 * invocation of @function.
19857 * If @context is %NULL then the global default main context — as
19858 * returned by g_main_context_default() — is used.
19860 * If @context is owned by the current thread, @function is called
19861 * directly. Otherwise, if @context is the thread-default main context
19862 * of the current thread and g_main_context_acquire() succeeds, then
19863 * @function is called and g_main_context_release() is called
19866 * In any other case, an idle source is created to call @function and
19867 * that source is attached to @context (presumably to be run in another
19868 * thread). The idle source is attached with #G_PRIORITY_DEFAULT
19869 * priority. If you want a different priority, use
19870 * g_main_context_invoke_full().
19872 * Note that, as with normal idle functions, @function should probably
19873 * return %FALSE. If it returns %TRUE, it will be continuously run in a
19874 * loop (and may prevent this call from returning).
19881 * g_main_context_invoke_full:
19882 * @context: (allow-none): a #GMainContext, or %NULL
19883 * @priority: the priority at which to run @function
19884 * @function: function to call
19885 * @data: data to pass to @function
19886 * @notify: (allow-none): a function to call when @data is no longer in use, or %NULL.
19888 * Invokes a function in such a way that @context is owned during the
19889 * invocation of @function.
19891 * This function is the same as g_main_context_invoke() except that it
19892 * lets you specify the priority incase @function ends up being
19893 * scheduled as an idle and also lets you give a #GDestroyNotify for @data.
19895 * @notify should not assume that it is called from any particular
19896 * thread or with any particular context acquired.
19903 * g_main_context_is_owner:
19904 * @context: a #GMainContext
19906 * Determines whether this thread holds the (recursive)
19907 * ownership of this #GMainContext. This is useful to
19908 * know before waiting on another thread that may be
19909 * blocking to get ownership of @context.
19911 * Returns: %TRUE if current thread is owner of @context.
19917 * g_main_context_iteration:
19918 * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used)
19919 * @may_block: whether the call may block.
19921 * Runs a single iteration for the given main loop. This involves
19922 * checking to see if any event sources are ready to be processed,
19923 * then if no events sources are ready and @may_block is %TRUE, waiting
19924 * for a source to become ready, then dispatching the highest priority
19925 * events sources that are ready. Otherwise, if @may_block is %FALSE
19926 * sources are not waited to become ready, only those highest priority
19927 * events sources will be dispatched (if any), that are ready at this
19928 * given moment without further waiting.
19930 * Note that even when @may_block is %TRUE, it is still possible for
19931 * g_main_context_iteration() to return %FALSE, since the wait may
19932 * be interrupted for other reasons than an event source becoming ready.
19934 * Returns: %TRUE if events were dispatched.
19939 * g_main_context_new:
19941 * Creates a new #GMainContext structure.
19943 * Returns: the new #GMainContext
19948 * g_main_context_pending:
19949 * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used)
19951 * Checks if any sources have pending events for the given context.
19953 * Returns: %TRUE if events are pending.
19958 * g_main_context_pop_thread_default:
19959 * @context: (allow-none): a #GMainContext object, or %NULL
19961 * Pops @context off the thread-default context stack (verifying that
19962 * it was on the top of the stack).
19969 * g_main_context_prepare:
19970 * @context: a #GMainContext
19971 * @priority: location to store priority of highest priority
19972 * source already ready.
19974 * Prepares to poll sources within a main loop. The resulting information
19975 * for polling is determined by calling g_main_context_query ().
19977 * You must have successfully acquired the context with
19978 * g_main_context_acquire() before you may call this function.
19980 * Returns: %TRUE if some source is ready to be dispatched
19981 * prior to polling.
19986 * g_main_context_push_thread_default:
19987 * @context: (allow-none): a #GMainContext, or %NULL for the global default context
19989 * Acquires @context and sets it as the thread-default context for the
19990 * current thread. This will cause certain asynchronous operations
19991 * (such as most [gio][gio]-based I/O) which are
19992 * started in this thread to run under @context and deliver their
19993 * results to its main loop, rather than running under the global
19994 * default context in the main thread. Note that calling this function
19995 * changes the context returned by g_main_context_get_thread_default(),
19996 * not the one returned by g_main_context_default(), so it does not affect
19997 * the context used by functions like g_idle_add().
19999 * Normally you would call this function shortly after creating a new
20000 * thread, passing it a #GMainContext which will be run by a
20001 * #GMainLoop in that thread, to set a new default context for all
20002 * async operations in that thread. In this case you may not need to
20003 * ever call g_main_context_pop_thread_default(), assuming you want the
20004 * new #GMainContext to be the default for the whole lifecycle of the
20007 * If you don't have control over how the new thread was created (e.g.
20008 * in the new thread isn't newly created, or if the thread life
20009 * cycle is managed by a #GThreadPool), it is always suggested to wrap
20010 * the logic that needs to use the new #GMainContext inside a
20011 * g_main_context_push_thread_default() / g_main_context_pop_thread_default()
20012 * pair, otherwise threads that are re-used will end up never explicitly
20013 * releasing the #GMainContext reference they hold.
20015 * In some cases you may want to schedule a single operation in a
20016 * non-default context, or temporarily use a non-default context in
20017 * the main thread. In that case, you can wrap the call to the
20018 * asynchronous operation inside a
20019 * g_main_context_push_thread_default() /
20020 * g_main_context_pop_thread_default() pair, but it is up to you to
20021 * ensure that no other asynchronous operations accidentally get
20022 * started while the non-default context is active.
20024 * Beware that libraries that predate this function may not correctly
20025 * handle being used from a thread with a thread-default context. Eg,
20026 * see g_file_supports_thread_contexts().
20033 * g_main_context_query:
20034 * @context: a #GMainContext
20035 * @max_priority: maximum priority source to check
20036 * @timeout_: (out): location to store timeout to be used in polling
20037 * @fds: (out caller-allocates) (array length=n_fds): location to
20038 * store #GPollFD records that need to be polled.
20039 * @n_fds: (in): length of @fds.
20041 * Determines information necessary to poll this main loop.
20043 * You must have successfully acquired the context with
20044 * g_main_context_acquire() before you may call this function.
20046 * Returns: the number of records actually stored in @fds,
20047 * or, if more than @n_fds records need to be stored, the number
20048 * of records that need to be stored.
20053 * g_main_context_ref:
20054 * @context: a #GMainContext
20056 * Increases the reference count on a #GMainContext object by one.
20058 * Returns: the @context that was passed in (since 2.6)
20063 * g_main_context_ref_thread_default:
20065 * Gets the thread-default #GMainContext for this thread, as with
20066 * g_main_context_get_thread_default(), but also adds a reference to
20067 * it with g_main_context_ref(). In addition, unlike
20068 * g_main_context_get_thread_default(), if the thread-default context
20069 * is the global default context, this will return that #GMainContext
20070 * (with a ref added to it) rather than returning %NULL.
20072 * Returns: (transfer full): the thread-default #GMainContext. Unref
20073 * with g_main_context_unref() when you are done with it.
20079 * g_main_context_release:
20080 * @context: a #GMainContext
20082 * Releases ownership of a context previously acquired by this thread
20083 * with g_main_context_acquire(). If the context was acquired multiple
20084 * times, the ownership will be released only when g_main_context_release()
20085 * is called as many times as it was acquired.
20090 * g_main_context_remove_poll:
20091 * @context: a #GMainContext
20092 * @fd: a #GPollFD descriptor previously added with g_main_context_add_poll()
20094 * Removes file descriptor from the set of file descriptors to be
20095 * polled for a particular context.
20100 * g_main_context_set_poll_func:
20101 * @context: a #GMainContext
20102 * @func: the function to call to poll all file descriptors
20104 * Sets the function to use to handle polling of file descriptors. It
20105 * will be used instead of the poll() system call
20106 * (or GLib's replacement function, which is used where
20107 * poll() isn't available).
20109 * This function could possibly be used to integrate the GLib event
20110 * loop with an external event loop.
20115 * g_main_context_unref:
20116 * @context: a #GMainContext
20118 * Decreases the reference count on a #GMainContext object by one. If
20119 * the result is zero, free the context and free all associated memory.
20124 * g_main_context_wait:
20125 * @context: a #GMainContext
20126 * @cond: a condition variable
20127 * @mutex: a mutex, currently held
20129 * Tries to become the owner of the specified context,
20130 * as with g_main_context_acquire(). But if another thread
20131 * is the owner, atomically drop @mutex and wait on @cond until
20132 * that owner releases ownership or until @cond is signaled, then
20133 * try again (once) to become the owner.
20135 * Returns: %TRUE if the operation succeeded, and
20136 * this thread is now the owner of @context.
20141 * g_main_context_wakeup:
20142 * @context: a #GMainContext
20144 * If @context is currently blocking in g_main_context_iteration()
20145 * waiting for a source to become ready, cause it to stop blocking
20146 * and return. Otherwise, cause the next invocation of
20147 * g_main_context_iteration() to return without blocking.
20149 * This API is useful for low-level control over #GMainContext; for
20150 * example, integrating it with main loop implementations such as
20153 * Another related use for this function is when implementing a main
20154 * loop with a termination condition, computed from multiple threads:
20156 * |[<!-- language="C" -->
20157 * #define NUM_TASKS 10
20158 * static volatile gint tasks_remaining = NUM_TASKS;
20161 * while (g_atomic_int_get (&tasks_remaining) != 0)
20162 * g_main_context_iteration (NULL, TRUE);
20165 * Then in a thread:
20166 * |[<!-- language="C" -->
20169 * if (g_atomic_int_dec_and_test (&tasks_remaining))
20170 * g_main_context_wakeup (NULL);
20176 * g_main_current_source:
20178 * Returns the currently firing source for this thread.
20180 * Returns: (transfer none): The currently firing source or %NULL.
20188 * Returns the depth of the stack of calls to
20189 * g_main_context_dispatch() on any #GMainContext in the current thread.
20190 * That is, when called from the toplevel, it gives 0. When
20191 * called from within a callback from g_main_context_iteration()
20192 * (or g_main_loop_run(), etc.) it returns 1. When called from within
20193 * a callback to a recursive call to g_main_context_iteration(),
20194 * it returns 2. And so forth.
20196 * This function is useful in a situation like the following:
20197 * Imagine an extremely simple "garbage collected" system.
20199 * |[<!-- language="C" -->
20200 * static GList *free_list;
20203 * allocate_memory (gsize size)
20205 * gpointer result = g_malloc (size);
20206 * free_list = g_list_prepend (free_list, result);
20211 * free_allocated_memory (void)
20214 * for (l = free_list; l; l = l->next);
20215 * g_free (l->data);
20216 * g_list_free (free_list);
20217 * free_list = NULL;
20224 * g_main_context_iteration (NULL, TRUE);
20225 * free_allocated_memory();
20229 * This works from an application, however, if you want to do the same
20230 * thing from a library, it gets more difficult, since you no longer
20231 * control the main loop. You might think you can simply use an idle
20232 * function to make the call to free_allocated_memory(), but that
20233 * doesn't work, since the idle function could be called from a
20234 * recursive callback. This can be fixed by using g_main_depth()
20236 * |[<!-- language="C" -->
20238 * allocate_memory (gsize size)
20240 * FreeListBlock *block = g_new (FreeListBlock, 1);
20241 * block->mem = g_malloc (size);
20242 * block->depth = g_main_depth ();
20243 * free_list = g_list_prepend (free_list, block);
20244 * return block->mem;
20248 * free_allocated_memory (void)
20252 * int depth = g_main_depth ();
20253 * for (l = free_list; l; );
20255 * GList *next = l->next;
20256 * FreeListBlock *block = l->data;
20257 * if (block->depth > depth)
20259 * g_free (block->mem);
20261 * free_list = g_list_delete_link (free_list, l);
20269 * There is a temptation to use g_main_depth() to solve
20270 * problems with reentrancy. For instance, while waiting for data
20271 * to be received from the network in response to a menu item,
20272 * the menu item might be selected again. It might seem that
20273 * one could make the menu item's callback return immediately
20274 * and do nothing if g_main_depth() returns a value greater than 1.
20275 * However, this should be avoided since the user then sees selecting
20276 * the menu item do nothing. Furthermore, you'll find yourself adding
20277 * these checks all over your code, since there are doubtless many,
20278 * many things that the user could do. Instead, you can use the
20279 * following techniques:
20281 * 1. Use gtk_widget_set_sensitive() or modal dialogs to prevent
20282 * the user from interacting with elements while the main
20283 * loop is recursing.
20285 * 2. Avoid main loop recursion in situations where you can't handle
20286 * arbitrary callbacks. Instead, structure your code so that you
20287 * simply return to the main loop and then get called again when
20288 * there is more work to do.
20290 * Returns: The main loop recursion level in the current thread
20295 * g_main_loop_get_context:
20296 * @loop: a #GMainLoop.
20298 * Returns the #GMainContext of @loop.
20300 * Returns: (transfer none): the #GMainContext of @loop
20305 * g_main_loop_is_running:
20306 * @loop: a #GMainLoop.
20308 * Checks to see if the main loop is currently being run via g_main_loop_run().
20310 * Returns: %TRUE if the mainloop is currently being run.
20316 * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used).
20317 * @is_running: set to %TRUE to indicate that the loop is running. This
20318 * is not very important since calling g_main_loop_run() will set this to
20321 * Creates a new #GMainLoop structure.
20323 * Returns: a new #GMainLoop.
20328 * g_main_loop_quit:
20329 * @loop: a #GMainLoop
20331 * Stops a #GMainLoop from running. Any calls to g_main_loop_run()
20332 * for the loop will return.
20334 * Note that sources that have already been dispatched when
20335 * g_main_loop_quit() is called will still be executed.
20341 * @loop: a #GMainLoop
20343 * Increases the reference count on a #GMainLoop object by one.
20351 * @loop: a #GMainLoop
20353 * Runs a main loop until g_main_loop_quit() is called on the loop.
20354 * If this is called for the thread of the loop's #GMainContext,
20355 * it will process events from the loop, otherwise it will
20361 * g_main_loop_unref:
20362 * @loop: a #GMainLoop
20364 * Decreases the reference count on a #GMainLoop object by one. If
20365 * the result is zero, free the loop and free all associated memory.
20371 * @n_bytes: the number of bytes to allocate
20373 * Allocates @n_bytes bytes of memory.
20374 * If @n_bytes is 0 it returns %NULL.
20376 * Returns: a pointer to the allocated memory
20382 * @n_bytes: the number of bytes to allocate
20384 * Allocates @n_bytes bytes of memory, initialized to 0's.
20385 * If @n_bytes is 0 it returns %NULL.
20387 * Returns: a pointer to the allocated memory
20393 * @n_blocks: the number of blocks to allocate
20394 * @n_block_bytes: the size of each block in bytes
20396 * This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
20397 * but care is taken to detect possible overflow during multiplication.
20400 * Returns: a pointer to the allocated memory
20406 * @n_blocks: the number of blocks to allocate
20407 * @n_block_bytes: the size of each block in bytes
20409 * This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
20410 * but care is taken to detect possible overflow during multiplication.
20413 * Returns: a pointer to the allocated memory
20418 * g_mapped_file_free:
20419 * @file: a #GMappedFile
20421 * This call existed before #GMappedFile had refcounting and is currently
20422 * exactly the same as g_mapped_file_unref().
20425 * Deprecated: 2.22: Use g_mapped_file_unref() instead.
20430 * g_mapped_file_get_bytes:
20431 * @file: a #GMappedFile
20433 * Creates a new #GBytes which references the data mapped from @file.
20434 * The mapped contents of the file must not be modified after creating this
20435 * bytes object, because a #GBytes should be immutable.
20437 * Returns: (transfer full): A newly allocated #GBytes referencing data
20444 * g_mapped_file_get_contents:
20445 * @file: a #GMappedFile
20447 * Returns the contents of a #GMappedFile.
20449 * Note that the contents may not be zero-terminated,
20450 * even if the #GMappedFile is backed by a text file.
20452 * If the file is empty then %NULL is returned.
20454 * Returns: the contents of @file, or %NULL.
20460 * g_mapped_file_get_length:
20461 * @file: a #GMappedFile
20463 * Returns the length of the contents of a #GMappedFile.
20465 * Returns: the length of the contents of @file.
20471 * g_mapped_file_new:
20472 * @filename: (type filename): The path of the file to load, in the GLib
20473 * filename encoding
20474 * @writable: whether the mapping should be writable
20475 * @error: return location for a #GError, or %NULL
20477 * Maps a file into memory. On UNIX, this is using the mmap() function.
20479 * If @writable is %TRUE, the mapped buffer may be modified, otherwise
20480 * it is an error to modify the mapped buffer. Modifications to the buffer
20481 * are not visible to other processes mapping the same file, and are not
20482 * written back to the file.
20484 * Note that modifications of the underlying file might affect the contents
20485 * of the #GMappedFile. Therefore, mapping should only be used if the file
20486 * will not be modified, or if all modifications of the file are done
20487 * atomically (e.g. using g_file_set_contents()).
20489 * If @filename is the name of an empty, regular file, the function
20490 * will successfully return an empty #GMappedFile. In other cases of
20491 * size 0 (e.g. device files such as /dev/null), @error will be set
20492 * to the #GFileError value #G_FILE_ERROR_INVAL.
20494 * Returns: a newly allocated #GMappedFile which must be unref'd
20495 * with g_mapped_file_unref(), or %NULL if the mapping failed.
20501 * g_mapped_file_new_from_fd:
20502 * @fd: The file descriptor of the file to load
20503 * @writable: whether the mapping should be writable
20504 * @error: return location for a #GError, or %NULL
20506 * Maps a file into memory. On UNIX, this is using the mmap() function.
20508 * If @writable is %TRUE, the mapped buffer may be modified, otherwise
20509 * it is an error to modify the mapped buffer. Modifications to the buffer
20510 * are not visible to other processes mapping the same file, and are not
20511 * written back to the file.
20513 * Note that modifications of the underlying file might affect the contents
20514 * of the #GMappedFile. Therefore, mapping should only be used if the file
20515 * will not be modified, or if all modifications of the file are done
20516 * atomically (e.g. using g_file_set_contents()).
20518 * Returns: a newly allocated #GMappedFile which must be unref'd
20519 * with g_mapped_file_unref(), or %NULL if the mapping failed.
20525 * g_mapped_file_ref:
20526 * @file: a #GMappedFile
20528 * Increments the reference count of @file by one. It is safe to call
20529 * this function from any thread.
20531 * Returns: the passed in #GMappedFile.
20537 * g_mapped_file_unref:
20538 * @file: a #GMappedFile
20540 * Decrements the reference count of @file by one. If the reference count
20541 * drops to 0, unmaps the buffer of @file and frees it.
20543 * It is safe to call this function from any thread.
20550 * g_markup_collect_attributes:
20551 * @element_name: the current tag name
20552 * @attribute_names: the attribute names
20553 * @attribute_values: the attribute values
20554 * @error: a pointer to a #GError or %NULL
20555 * @first_type: the #GMarkupCollectType of the first attribute
20556 * @first_attr: the name of the first attribute
20557 * @...: a pointer to the storage location of the first attribute
20558 * (or %NULL), followed by more types names and pointers, ending
20559 * with %G_MARKUP_COLLECT_INVALID
20561 * Collects the attributes of the element from the data passed to the
20562 * #GMarkupParser start_element function, dealing with common error
20563 * conditions and supporting boolean values.
20565 * This utility function is not required to write a parser but can save
20568 * The @element_name, @attribute_names, @attribute_values and @error
20569 * parameters passed to the start_element callback should be passed
20570 * unmodified to this function.
20572 * Following these arguments is a list of "supported" attributes to collect.
20573 * It is an error to specify multiple attributes with the same name. If any
20574 * attribute not in the list appears in the @attribute_names array then an
20575 * unknown attribute error will result.
20577 * The #GMarkupCollectType field allows specifying the type of collection
20578 * to perform and if a given attribute must appear or is optional.
20580 * The attribute name is simply the name of the attribute to collect.
20582 * The pointer should be of the appropriate type (see the descriptions
20583 * under #GMarkupCollectType) and may be %NULL in case a particular
20584 * attribute is to be allowed but ignored.
20586 * This function deals with issuing errors for missing attributes
20587 * (of type %G_MARKUP_ERROR_MISSING_ATTRIBUTE), unknown attributes
20588 * (of type %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE) and duplicate
20589 * attributes (of type %G_MARKUP_ERROR_INVALID_CONTENT) as well
20590 * as parse errors for boolean-valued attributes (again of type
20591 * %G_MARKUP_ERROR_INVALID_CONTENT). In all of these cases %FALSE
20592 * will be returned and @error will be set as appropriate.
20594 * Returns: %TRUE if successful
20600 * g_markup_escape_text:
20601 * @text: some valid UTF-8 text
20602 * @length: length of @text in bytes, or -1 if the text is nul-terminated
20604 * Escapes text so that the markup parser will parse it verbatim.
20605 * Less than, greater than, ampersand, etc. are replaced with the
20606 * corresponding entities. This function would typically be used
20607 * when writing out a file to be parsed with the markup parser.
20609 * Note that this function doesn't protect whitespace and line endings
20610 * from being processed according to the XML rules for normalization
20611 * of line endings and attribute values.
20613 * Note also that this function will produce character references in
20614 * the range of  ...  for all control sequences
20615 * except for tabstop, newline and carriage return. The character
20616 * references in this range are not valid XML 1.0, but they are
20617 * valid XML 1.1 and will be accepted by the GMarkup parser.
20619 * Returns: a newly allocated string with the escaped text
20624 * g_markup_parse_context_end_parse:
20625 * @context: a #GMarkupParseContext
20626 * @error: return location for a #GError
20628 * Signals to the #GMarkupParseContext that all data has been
20629 * fed into the parse context with g_markup_parse_context_parse().
20631 * This function reports an error if the document isn't complete,
20632 * for example if elements are still open.
20634 * Returns: %TRUE on success, %FALSE if an error was set
20639 * g_markup_parse_context_free:
20640 * @context: a #GMarkupParseContext
20642 * Frees a #GMarkupParseContext.
20644 * This function can't be called from inside one of the
20645 * #GMarkupParser functions or while a subparser is pushed.
20650 * g_markup_parse_context_get_element:
20651 * @context: a #GMarkupParseContext
20653 * Retrieves the name of the currently open element.
20655 * If called from the start_element or end_element handlers this will
20656 * give the element_name as passed to those functions. For the parent
20657 * elements, see g_markup_parse_context_get_element_stack().
20659 * Returns: the name of the currently open element, or %NULL
20665 * g_markup_parse_context_get_element_stack:
20666 * @context: a #GMarkupParseContext
20668 * Retrieves the element stack from the internal state of the parser.
20670 * The returned #GSList is a list of strings where the first item is
20671 * the currently open tag (as would be returned by
20672 * g_markup_parse_context_get_element()) and the next item is its
20673 * immediate parent.
20675 * This function is intended to be used in the start_element and
20676 * end_element handlers where g_markup_parse_context_get_element()
20677 * would merely return the name of the element that is being
20680 * Returns: the element stack, which must not be modified
20686 * g_markup_parse_context_get_position:
20687 * @context: a #GMarkupParseContext
20688 * @line_number: (allow-none): return location for a line number, or %NULL
20689 * @char_number: (allow-none): return location for a char-on-line number, or %NULL
20691 * Retrieves the current line number and the number of the character on
20692 * that line. Intended for use in error messages; there are no strict
20693 * semantics for what constitutes the "current" line number other than
20694 * "the best number we could come up with for error messages."
20699 * g_markup_parse_context_get_user_data:
20700 * @context: a #GMarkupParseContext
20702 * Returns the user_data associated with @context.
20704 * This will either be the user_data that was provided to
20705 * g_markup_parse_context_new() or to the most recent call
20706 * of g_markup_parse_context_push().
20708 * Returns: the provided user_data. The returned data belongs to
20709 * the markup context and will be freed when
20710 * g_markup_parse_context_free() is called.
20716 * g_markup_parse_context_new:
20717 * @parser: a #GMarkupParser
20718 * @flags: one or more #GMarkupParseFlags
20719 * @user_data: user data to pass to #GMarkupParser functions
20720 * @user_data_dnotify: user data destroy notifier called when
20721 * the parse context is freed
20723 * Creates a new parse context. A parse context is used to parse
20724 * marked-up documents. You can feed any number of documents into
20725 * a context, as long as no errors occur; once an error occurs,
20726 * the parse context can't continue to parse text (you have to
20727 * free it and create a new parse context).
20729 * Returns: a new #GMarkupParseContext
20734 * g_markup_parse_context_parse:
20735 * @context: a #GMarkupParseContext
20736 * @text: chunk of text to parse
20737 * @text_len: length of @text in bytes
20738 * @error: return location for a #GError
20740 * Feed some data to the #GMarkupParseContext.
20742 * The data need not be valid UTF-8; an error will be signaled if
20743 * it's invalid. The data need not be an entire document; you can
20744 * feed a document into the parser incrementally, via multiple calls
20745 * to this function. Typically, as you receive data from a network
20746 * connection or file, you feed each received chunk of data into this
20747 * function, aborting the process if an error occurs. Once an error
20748 * is reported, no further data may be fed to the #GMarkupParseContext;
20749 * all errors are fatal.
20751 * Returns: %FALSE if an error occurred, %TRUE on success
20756 * g_markup_parse_context_pop:
20757 * @context: a #GMarkupParseContext
20759 * Completes the process of a temporary sub-parser redirection.
20761 * This function exists to collect the user_data allocated by a
20762 * matching call to g_markup_parse_context_push(). It must be called
20763 * in the end_element handler corresponding to the start_element
20764 * handler during which g_markup_parse_context_push() was called.
20765 * You must not call this function from the error callback -- the
20766 * @user_data is provided directly to the callback in that case.
20768 * This function is not intended to be directly called by users
20769 * interested in invoking subparsers. Instead, it is intended to
20770 * be used by the subparsers themselves to implement a higher-level
20773 * Returns: the user data passed to g_markup_parse_context_push()
20779 * g_markup_parse_context_push:
20780 * @context: a #GMarkupParseContext
20781 * @parser: a #GMarkupParser
20782 * @user_data: user data to pass to #GMarkupParser functions
20784 * Temporarily redirects markup data to a sub-parser.
20786 * This function may only be called from the start_element handler of
20787 * a #GMarkupParser. It must be matched with a corresponding call to
20788 * g_markup_parse_context_pop() in the matching end_element handler
20789 * (except in the case that the parser aborts due to an error).
20791 * All tags, text and other data between the matching tags is
20792 * redirected to the subparser given by @parser. @user_data is used
20793 * as the user_data for that parser. @user_data is also passed to the
20794 * error callback in the event that an error occurs. This includes
20795 * errors that occur in subparsers of the subparser.
20797 * The end tag matching the start tag for which this call was made is
20798 * handled by the previous parser (which is given its own user_data)
20799 * which is why g_markup_parse_context_pop() is provided to allow "one
20800 * last access" to the @user_data provided to this function. In the
20801 * case of error, the @user_data provided here is passed directly to
20802 * the error callback of the subparser and g_markup_parse_context_pop()
20803 * should not be called. In either case, if @user_data was allocated
20804 * then it ought to be freed from both of these locations.
20806 * This function is not intended to be directly called by users
20807 * interested in invoking subparsers. Instead, it is intended to be
20808 * used by the subparsers themselves to implement a higher-level
20811 * As an example, see the following implementation of a simple
20812 * parser that counts the number of tags encountered.
20814 * |[<!-- language="C" -->
20821 * counter_start_element (GMarkupParseContext *context,
20822 * const gchar *element_name,
20823 * const gchar **attribute_names,
20824 * const gchar **attribute_values,
20825 * gpointer user_data,
20828 * CounterData *data = user_data;
20830 * data->tag_count++;
20834 * counter_error (GMarkupParseContext *context,
20836 * gpointer user_data)
20838 * CounterData *data = user_data;
20840 * g_slice_free (CounterData, data);
20843 * static GMarkupParser counter_subparser =
20845 * counter_start_element,
20853 * In order to allow this parser to be easily used as a subparser, the
20854 * following interface is provided:
20856 * |[<!-- language="C" -->
20858 * start_counting (GMarkupParseContext *context)
20860 * CounterData *data = g_slice_new (CounterData);
20862 * data->tag_count = 0;
20863 * g_markup_parse_context_push (context, &counter_subparser, data);
20867 * end_counting (GMarkupParseContext *context)
20869 * CounterData *data = g_markup_parse_context_pop (context);
20872 * result = data->tag_count;
20873 * g_slice_free (CounterData, data);
20879 * The subparser would then be used as follows:
20881 * |[<!-- language="C" -->
20882 * static void start_element (context, element_name, ...)
20884 * if (strcmp (element_name, "count-these") == 0)
20885 * start_counting (context);
20887 * // else, handle other tags...
20890 * static void end_element (context, element_name, ...)
20892 * if (strcmp (element_name, "count-these") == 0)
20893 * g_print ("Counted %d tags\n", end_counting (context));
20895 * // else, handle other tags...
20904 * g_markup_parse_context_ref:
20905 * @context: a #GMarkupParseContext
20907 * Increases the reference count of @context.
20909 * Returns: the same @context
20915 * g_markup_parse_context_unref:
20916 * @context: a #GMarkupParseContext
20918 * Decreases the reference count of @context. When its reference count
20919 * drops to 0, it is freed.
20926 * g_markup_printf_escaped:
20927 * @format: printf() style format string
20928 * @...: the arguments to insert in the format string
20930 * Formats arguments according to @format, escaping
20931 * all string and character arguments in the fashion
20932 * of g_markup_escape_text(). This is useful when you
20933 * want to insert literal strings into XML-style markup
20934 * output, without having to worry that the strings
20935 * might themselves contain markup.
20937 * |[<!-- language="C" -->
20938 * const char *store = "Fortnum & Mason";
20939 * const char *item = "Tea";
20942 * output = g_markup_printf_escaped ("<purchase>"
20943 * "<store>%s</store>"
20944 * "<item>%s</item>"
20949 * Returns: newly allocated result from formatting
20950 * operation. Free with g_free().
20956 * g_markup_vprintf_escaped:
20957 * @format: printf() style format string
20958 * @args: variable argument list, similar to vprintf()
20960 * Formats the data in @args according to @format, escaping
20961 * all string and character arguments in the fashion
20962 * of g_markup_escape_text(). See g_markup_printf_escaped().
20964 * Returns: newly allocated result from formatting
20965 * operation. Free with g_free().
20971 * g_match_info_expand_references:
20972 * @match_info: (allow-none): a #GMatchInfo or %NULL
20973 * @string_to_expand: the string to expand
20974 * @error: location to store the error occurring, or %NULL to ignore errors
20976 * Returns a new string containing the text in @string_to_expand with
20977 * references and escape sequences expanded. References refer to the last
20978 * match done with @string against @regex and have the same syntax used by
20979 * g_regex_replace().
20981 * The @string_to_expand must be UTF-8 encoded even if #G_REGEX_RAW was
20982 * passed to g_regex_new().
20984 * The backreferences are extracted from the string passed to the match
20985 * function, so you cannot call this function after freeing the string.
20987 * @match_info may be %NULL in which case @string_to_expand must not
20988 * contain references. For instance "foo\n" does not refer to an actual
20989 * pattern and '\n' merely will be replaced with \n character,
20990 * while to expand "\0" (whole match) one needs the result of a match.
20991 * Use g_regex_check_replacement() to find out whether @string_to_expand
20992 * contains references.
20994 * Returns: (allow-none): the expanded string, or %NULL if an error occurred
21000 * g_match_info_fetch:
21001 * @match_info: #GMatchInfo structure
21002 * @match_num: number of the sub expression
21004 * Retrieves the text matching the @match_num'th capturing
21005 * parentheses. 0 is the full text of the match, 1 is the first paren
21006 * set, 2 the second, and so on.
21008 * If @match_num is a valid sub pattern but it didn't match anything
21009 * (e.g. sub pattern 1, matching "b" against "(a)?b") then an empty
21010 * string is returned.
21012 * If the match was obtained using the DFA algorithm, that is using
21013 * g_regex_match_all() or g_regex_match_all_full(), the retrieved
21014 * string is not that of a set of parentheses but that of a matched
21015 * substring. Substrings are matched in reverse order of length, so
21016 * 0 is the longest match.
21018 * The string is fetched from the string passed to the match function,
21019 * so you cannot call this function after freeing the string.
21021 * Returns: (allow-none): The matched substring, or %NULL if an error
21022 * occurred. You have to free the string yourself
21028 * g_match_info_fetch_all:
21029 * @match_info: a #GMatchInfo structure
21031 * Bundles up pointers to each of the matching substrings from a match
21032 * and stores them in an array of gchar pointers. The first element in
21033 * the returned array is the match number 0, i.e. the entire matched
21036 * If a sub pattern didn't match anything (e.g. sub pattern 1, matching
21037 * "b" against "(a)?b") then an empty string is inserted.
21039 * If the last match was obtained using the DFA algorithm, that is using
21040 * g_regex_match_all() or g_regex_match_all_full(), the retrieved
21041 * strings are not that matched by sets of parentheses but that of the
21042 * matched substring. Substrings are matched in reverse order of length,
21043 * so the first one is the longest match.
21045 * The strings are fetched from the string passed to the match function,
21046 * so you cannot call this function after freeing the string.
21048 * Returns: (transfer full): a %NULL-terminated array of gchar *
21049 * pointers. It must be freed using g_strfreev(). If the previous
21050 * match failed %NULL is returned
21056 * g_match_info_fetch_named:
21057 * @match_info: #GMatchInfo structure
21058 * @name: name of the subexpression
21060 * Retrieves the text matching the capturing parentheses named @name.
21062 * If @name is a valid sub pattern name but it didn't match anything
21063 * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
21064 * then an empty string is returned.
21066 * The string is fetched from the string passed to the match function,
21067 * so you cannot call this function after freeing the string.
21069 * Returns: (allow-none): The matched substring, or %NULL if an error
21070 * occurred. You have to free the string yourself
21076 * g_match_info_fetch_named_pos:
21077 * @match_info: #GMatchInfo structure
21078 * @name: name of the subexpression
21079 * @start_pos: (out) (allow-none): pointer to location where to store
21080 * the start position, or %NULL
21081 * @end_pos: (out) (allow-none): pointer to location where to store
21082 * the end position, or %NULL
21084 * Retrieves the position in bytes of the capturing parentheses named @name.
21086 * If @name is a valid sub pattern name but it didn't match anything
21087 * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
21088 * then @start_pos and @end_pos are set to -1 and %TRUE is returned.
21090 * Returns: %TRUE if the position was fetched, %FALSE otherwise.
21091 * If the position cannot be fetched, @start_pos and @end_pos
21092 * are left unchanged.
21098 * g_match_info_fetch_pos:
21099 * @match_info: #GMatchInfo structure
21100 * @match_num: number of the sub expression
21101 * @start_pos: (out) (allow-none): pointer to location where to store
21102 * the start position, or %NULL
21103 * @end_pos: (out) (allow-none): pointer to location where to store
21104 * the end position, or %NULL
21106 * Retrieves the position in bytes of the @match_num'th capturing
21107 * parentheses. 0 is the full text of the match, 1 is the first
21108 * paren set, 2 the second, and so on.
21110 * If @match_num is a valid sub pattern but it didn't match anything
21111 * (e.g. sub pattern 1, matching "b" against "(a)?b") then @start_pos
21112 * and @end_pos are set to -1 and %TRUE is returned.
21114 * If the match was obtained using the DFA algorithm, that is using
21115 * g_regex_match_all() or g_regex_match_all_full(), the retrieved
21116 * position is not that of a set of parentheses but that of a matched
21117 * substring. Substrings are matched in reverse order of length, so
21118 * 0 is the longest match.
21120 * Returns: %TRUE if the position was fetched, %FALSE otherwise. If
21121 * the position cannot be fetched, @start_pos and @end_pos are left
21128 * g_match_info_free:
21129 * @match_info: (allow-none): a #GMatchInfo, or %NULL
21131 * If @match_info is not %NULL, calls g_match_info_unref(); otherwise does
21139 * g_match_info_get_match_count:
21140 * @match_info: a #GMatchInfo structure
21142 * Retrieves the number of matched substrings (including substring 0,
21143 * that is the whole matched text), so 1 is returned if the pattern
21144 * has no substrings in it and 0 is returned if the match failed.
21146 * If the last match was obtained using the DFA algorithm, that is
21147 * using g_regex_match_all() or g_regex_match_all_full(), the retrieved
21148 * count is not that of the number of capturing parentheses but that of
21149 * the number of matched substrings.
21151 * Returns: Number of matched substrings, or -1 if an error occurred
21157 * g_match_info_get_regex:
21158 * @match_info: a #GMatchInfo
21160 * Returns #GRegex object used in @match_info. It belongs to Glib
21161 * and must not be freed. Use g_regex_ref() if you need to keep it
21162 * after you free @match_info object.
21164 * Returns: #GRegex object used in @match_info
21170 * g_match_info_get_string:
21171 * @match_info: a #GMatchInfo
21173 * Returns the string searched with @match_info. This is the
21174 * string passed to g_regex_match() or g_regex_replace() so
21175 * you may not free it before calling this function.
21177 * Returns: the string searched with @match_info
21183 * g_match_info_is_partial_match:
21184 * @match_info: a #GMatchInfo structure
21186 * Usually if the string passed to g_regex_match*() matches as far as
21187 * it goes, but is too short to match the entire pattern, %FALSE is
21188 * returned. There are circumstances where it might be helpful to
21189 * distinguish this case from other cases in which there is no match.
21191 * Consider, for example, an application where a human is required to
21192 * type in data for a field with specific formatting requirements. An
21193 * example might be a date in the form ddmmmyy, defined by the pattern
21194 * "^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$".
21195 * If the application sees the user’s keystrokes one by one, and can
21196 * check that what has been typed so far is potentially valid, it is
21197 * able to raise an error as soon as a mistake is made.
21199 * GRegex supports the concept of partial matching by means of the
21200 * #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD flags.
21201 * When they are used, the return code for
21202 * g_regex_match() or g_regex_match_full() is, as usual, %TRUE
21203 * for a complete match, %FALSE otherwise. But, when these functions
21204 * return %FALSE, you can check if the match was partial calling
21205 * g_match_info_is_partial_match().
21207 * The difference between #G_REGEX_MATCH_PARTIAL_SOFT and
21208 * #G_REGEX_MATCH_PARTIAL_HARD is that when a partial match is encountered
21209 * with #G_REGEX_MATCH_PARTIAL_SOFT, matching continues to search for a
21210 * possible complete match, while with #G_REGEX_MATCH_PARTIAL_HARD matching
21211 * stops at the partial match.
21212 * When both #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD
21213 * are set, the latter takes precedence.
21215 * There were formerly some restrictions on the pattern for partial matching.
21216 * The restrictions no longer apply.
21218 * See pcrepartial(3) for more information on partial matching.
21220 * Returns: %TRUE if the match was partial, %FALSE otherwise
21226 * g_match_info_matches:
21227 * @match_info: a #GMatchInfo structure
21229 * Returns whether the previous match operation succeeded.
21231 * Returns: %TRUE if the previous match operation succeeded,
21238 * g_match_info_next:
21239 * @match_info: a #GMatchInfo structure
21240 * @error: location to store the error occurring, or %NULL to ignore errors
21242 * Scans for the next match using the same parameters of the previous
21243 * call to g_regex_match_full() or g_regex_match() that returned
21246 * The match is done on the string passed to the match function, so you
21247 * cannot free it before calling this function.
21249 * Returns: %TRUE is the string matched, %FALSE otherwise
21255 * g_match_info_ref:
21256 * @match_info: a #GMatchInfo
21258 * Increases reference count of @match_info by 1.
21260 * Returns: @match_info
21266 * g_match_info_unref:
21267 * @match_info: a #GMatchInfo
21269 * Decreases reference count of @match_info by 1. When reference count drops
21270 * to zero, it frees all the memory associated with the match_info structure.
21277 * g_mem_gc_friendly:
21279 * This variable is %TRUE if the `G_DEBUG` environment variable
21280 * includes the key `gc-friendly`.
21285 * g_mem_is_system_malloc:
21287 * Checks whether the allocator used by g_malloc() is the system's
21288 * malloc implementation. If it returns %TRUE memory allocated with
21289 * malloc() can be used interchangeable with memory allocated using g_malloc().
21290 * This function is useful for avoiding an extra copy of allocated memory returned
21291 * by a non-GLib-based API.
21293 * Returns: if %TRUE, malloc() and g_malloc() can be mixed.
21294 * Deprecated: 2.46: GLib always uses the system malloc, so this function always
21302 * GLib used to support some tools for memory profiling, but this
21303 * no longer works. There are many other useful tools for memory
21304 * profiling these days which can be used instead.
21306 * Deprecated: 2.46: Use other memory profiling tools instead
21311 * g_mem_set_vtable:
21312 * @vtable: table of memory allocation routines.
21314 * This function used to let you override the memory allocation function.
21315 * However, its use was incompatible with the use of global constructors
21316 * in GLib and GIO, because those use the GLib allocators before main is
21317 * reached. Therefore this function is now deprecated and is just a stub.
21319 * Deprecated: 2.46: Use other memory profiling tools instead
21325 * @mem: the memory to copy.
21326 * @byte_size: the number of bytes to copy.
21328 * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
21329 * from @mem. If @mem is %NULL it returns %NULL.
21331 * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
21338 * @dest: the destination address to copy the bytes to.
21339 * @src: the source address to copy the bytes from.
21340 * @len: the number of bytes to copy.
21342 * Copies a block of memory @len bytes long, from @src to @dest.
21343 * The source and destination areas may overlap.
21345 * Deprecated: 2.40: Just use memmove().
21351 * @...: format string, followed by parameters to insert
21352 * into the format string (as with printf())
21354 * A convenience function/macro to log a normal message.
21356 * If g_log_default_handler() is used as the log handler function, a new-line
21357 * character will automatically be appended to @..., and need not be entered
21364 * @filename: (type filename): a pathname in the GLib file name encoding
21365 * (UTF-8 on Windows)
21366 * @mode: permissions to use for the newly created directory
21368 * A wrapper for the POSIX mkdir() function. The mkdir() function
21369 * attempts to create a directory with the given name and permissions.
21370 * The mode argument is ignored on Windows.
21372 * See your C library manual for more details about mkdir().
21374 * Returns: 0 if the directory was successfully created, -1 if an error
21381 * g_mkdir_with_parents:
21382 * @pathname: (type filename): a pathname in the GLib file name encoding
21383 * @mode: permissions to use for newly created directories
21385 * Create a directory if it doesn't already exist. Create intermediate
21386 * parent directories as needed, too.
21388 * Returns: 0 if the directory already exists, or was successfully
21389 * created. Returns -1 if an error occurred, with errno set.
21396 * @tmpl: (type filename): template directory name
21398 * Creates a temporary directory. See the mkdtemp() documentation
21399 * on most UNIX-like systems.
21401 * The parameter is a string that should follow the rules for
21402 * mkdtemp() templates, i.e. contain the string "XXXXXX".
21403 * g_mkdtemp() is slightly more flexible than mkdtemp() in that the
21404 * sequence does not have to occur at the very end of the template
21405 * and you can pass a @mode and additional @flags. The X string will
21406 * be modified to form the name of a directory that didn't exist.
21407 * The string should be in the GLib file name encoding. Most importantly,
21408 * on Windows it should be in UTF-8.
21410 * Returns: (nullable) (type filename): A pointer to @tmpl, which has been
21411 * modified to hold the directory name. In case of errors, %NULL is
21412 * returned and %errno will be set.
21419 * @tmpl: (type filename): template directory name
21420 * @mode: permissions to create the temporary directory with
21422 * Creates a temporary directory. See the mkdtemp() documentation
21423 * on most UNIX-like systems.
21425 * The parameter is a string that should follow the rules for
21426 * mkdtemp() templates, i.e. contain the string "XXXXXX".
21427 * g_mkdtemp() is slightly more flexible than mkdtemp() in that the
21428 * sequence does not have to occur at the very end of the template
21429 * and you can pass a @mode. The X string will be modified to form
21430 * the name of a directory that didn't exist. The string should be
21431 * in the GLib file name encoding. Most importantly, on Windows it
21432 * should be in UTF-8.
21434 * Returns: (nullable) (type filename): A pointer to @tmpl, which has been
21435 * modified to hold the directory name. In case of errors, %NULL is
21436 * returned, and %errno will be set.
21443 * @tmpl: (type filename): template filename
21445 * Opens a temporary file. See the mkstemp() documentation
21446 * on most UNIX-like systems.
21448 * The parameter is a string that should follow the rules for
21449 * mkstemp() templates, i.e. contain the string "XXXXXX".
21450 * g_mkstemp() is slightly more flexible than mkstemp() in that the
21451 * sequence does not have to occur at the very end of the template.
21452 * The X string will be modified to form the name of a file that
21453 * didn't exist. The string should be in the GLib file name encoding.
21454 * Most importantly, on Windows it should be in UTF-8.
21456 * Returns: A file handle (as from open()) to the file
21457 * opened for reading and writing. The file is opened in binary
21458 * mode on platforms where there is a difference. The file handle
21459 * should be closed with close(). In case of errors, -1 is
21460 * returned and %errno will be set.
21466 * @tmpl: (type filename): template filename
21467 * @flags: flags to pass to an open() call in addition to O_EXCL
21468 * and O_CREAT, which are passed automatically
21469 * @mode: permissions to create the temporary file with
21471 * Opens a temporary file. See the mkstemp() documentation
21472 * on most UNIX-like systems.
21474 * The parameter is a string that should follow the rules for
21475 * mkstemp() templates, i.e. contain the string "XXXXXX".
21476 * g_mkstemp_full() is slightly more flexible than mkstemp()
21477 * in that the sequence does not have to occur at the very end of the
21478 * template and you can pass a @mode and additional @flags. The X
21479 * string will be modified to form the name of a file that didn't exist.
21480 * The string should be in the GLib file name encoding. Most importantly,
21481 * on Windows it should be in UTF-8.
21483 * Returns: A file handle (as from open()) to the file
21484 * opened for reading and writing. The file handle should be
21485 * closed with close(). In case of errors, -1 is returned
21486 * and %errno will be set.
21493 * @mutex: an initialized #GMutex
21495 * Frees the resources allocated to a mutex with g_mutex_init().
21497 * This function should not be used with a #GMutex that has been
21498 * statically allocated.
21500 * Calling g_mutex_clear() on a locked mutex leads to undefined
21509 * @mutex: an uninitialized #GMutex
21511 * Initializes a #GMutex so that it can be used.
21513 * This function is useful to initialize a mutex that has been
21514 * allocated on the stack, or as part of a larger structure.
21515 * It is not necessary to initialize a mutex that has been
21516 * statically allocated.
21518 * |[<!-- language="C" -->
21526 * b = g_new (Blob, 1);
21527 * g_mutex_init (&b->m);
21530 * To undo the effect of g_mutex_init() when a mutex is no longer
21531 * needed, use g_mutex_clear().
21533 * Calling g_mutex_init() on an already initialized #GMutex leads
21534 * to undefined behaviour.
21542 * @mutex: a #GMutex
21544 * Locks @mutex. If @mutex is already locked by another thread, the
21545 * current thread will block until @mutex is unlocked by the other
21548 * #GMutex is neither guaranteed to be recursive nor to be
21549 * non-recursive. As such, calling g_mutex_lock() on a #GMutex that has
21550 * already been locked by the same thread results in undefined behaviour
21551 * (including but not limited to deadlocks).
21557 * @mutex: a #GMutex
21559 * Tries to lock @mutex. If @mutex is already locked by another thread,
21560 * it immediately returns %FALSE. Otherwise it locks @mutex and returns
21563 * #GMutex is neither guaranteed to be recursive nor to be
21564 * non-recursive. As such, calling g_mutex_lock() on a #GMutex that has
21565 * already been locked by the same thread results in undefined behaviour
21566 * (including but not limited to deadlocks or arbitrary return values).
21568 * Returns: %TRUE if @mutex could be locked
21574 * @mutex: a #GMutex
21576 * Unlocks @mutex. If another thread is blocked in a g_mutex_lock()
21577 * call for @mutex, it will become unblocked and can lock @mutex itself.
21579 * Calling g_mutex_unlock() on a mutex that is not locked by the
21580 * current thread leads to undefined behaviour.
21585 * g_node_child_index:
21587 * @data: the data to find
21589 * Gets the position of the first child of a #GNode
21590 * which contains the given data.
21592 * Returns: the index of the child of @node which contains
21593 * @data, or -1 if the data is not found
21598 * g_node_child_position:
21600 * @child: a child of @node
21602 * Gets the position of a #GNode with respect to its siblings.
21603 * @child must be a child of @node. The first child is numbered 0,
21604 * the second 1, and so on.
21606 * Returns: the position of @child with respect to its siblings
21611 * g_node_children_foreach:
21613 * @flags: which types of children are to be visited, one of
21614 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
21615 * @func: the function to call for each visited node
21616 * @data: user data to pass to the function
21618 * Calls a function for each of the children of a #GNode.
21619 * Note that it doesn't descend beneath the child nodes.
21627 * Recursively copies a #GNode (but does not deep-copy the data inside the
21628 * nodes, see g_node_copy_deep() if you need that).
21630 * Returns: a new #GNode containing the same data pointers
21635 * g_node_copy_deep:
21637 * @copy_func: the function which is called to copy the data inside each node,
21638 * or %NULL to use the original data.
21639 * @data: data to pass to @copy_func
21641 * Recursively copies a #GNode and its data.
21643 * Returns: a new #GNode containing copies of the data in @node.
21652 * Gets the depth of a #GNode.
21654 * If @node is %NULL the depth is 0. The root node has a depth of 1.
21655 * For the children of the root node the depth is 2. And so on.
21657 * Returns: the depth of the #GNode
21663 * @root: the root of the tree/subtree to destroy
21665 * Removes @root and its children from the tree, freeing any memory
21672 * @root: the root #GNode of the tree to search
21673 * @order: the order in which nodes are visited - %G_IN_ORDER,
21674 * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER
21675 * @flags: which types of children are to be searched, one of
21676 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
21677 * @data: the data to find
21679 * Finds a #GNode in a tree.
21681 * Returns: the found #GNode, or %NULL if the data is not found
21686 * g_node_find_child:
21688 * @flags: which types of children are to be searched, one of
21689 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
21690 * @data: the data to find
21692 * Finds the first child of a #GNode with the given data.
21694 * Returns: the found child #GNode, or %NULL if the data is not found
21699 * g_node_first_sibling:
21702 * Gets the first sibling of a #GNode.
21703 * This could possibly be the node itself.
21705 * Returns: the first sibling of @node
21713 * Gets the root of a tree.
21715 * Returns: the root of the tree
21721 * @parent: the #GNode to place @node under
21722 * @position: the position to place @node at, with respect to its siblings
21723 * If position is -1, @node is inserted as the last child of @parent
21724 * @node: the #GNode to insert
21726 * Inserts a #GNode beneath the parent at the given position.
21728 * Returns: the inserted #GNode
21733 * g_node_insert_after:
21734 * @parent: the #GNode to place @node under
21735 * @sibling: the sibling #GNode to place @node after.
21736 * If sibling is %NULL, the node is inserted as the first child of @parent.
21737 * @node: the #GNode to insert
21739 * Inserts a #GNode beneath the parent after the given sibling.
21741 * Returns: the inserted #GNode
21746 * g_node_insert_before:
21747 * @parent: the #GNode to place @node under
21748 * @sibling: the sibling #GNode to place @node before.
21749 * If sibling is %NULL, the node is inserted as the last child of @parent.
21750 * @node: the #GNode to insert
21752 * Inserts a #GNode beneath the parent before the given sibling.
21754 * Returns: the inserted #GNode
21759 * g_node_is_ancestor:
21761 * @descendant: a #GNode
21763 * Returns %TRUE if @node is an ancestor of @descendant.
21764 * This is true if node is the parent of @descendant,
21765 * or if node is the grandparent of @descendant etc.
21767 * Returns: %TRUE if @node is an ancestor of @descendant
21772 * g_node_last_child:
21773 * @node: a #GNode (must not be %NULL)
21775 * Gets the last child of a #GNode.
21777 * Returns: the last child of @node, or %NULL if @node has no children
21782 * g_node_last_sibling:
21785 * Gets the last sibling of a #GNode.
21786 * This could possibly be the node itself.
21788 * Returns: the last sibling of @node
21793 * g_node_max_height:
21796 * Gets the maximum height of all branches beneath a #GNode.
21797 * This is the maximum distance from the #GNode to all leaf nodes.
21799 * If @root is %NULL, 0 is returned. If @root has no children,
21800 * 1 is returned. If @root has children, 2 is returned. And so on.
21802 * Returns: the maximum height of the tree beneath @root
21807 * g_node_n_children:
21810 * Gets the number of children of a #GNode.
21812 * Returns: the number of children of @node
21819 * @flags: which types of children are to be counted, one of
21820 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
21822 * Gets the number of nodes in a tree.
21824 * Returns: the number of nodes in the tree
21830 * @data: the data of the new node
21832 * Creates a new #GNode containing the given data.
21833 * Used to create the first node in a tree.
21835 * Returns: a new #GNode
21840 * g_node_nth_child:
21842 * @n: the index of the desired child
21844 * Gets a child of a #GNode, using the given index.
21845 * The first child is at index 0. If the index is
21846 * too big, %NULL is returned.
21848 * Returns: the child of @node at index @n
21854 * @parent: the #GNode to place the new #GNode under
21855 * @node: the #GNode to insert
21857 * Inserts a #GNode as the first child of the given parent.
21859 * Returns: the inserted #GNode
21864 * g_node_reverse_children:
21867 * Reverses the order of the children of a #GNode.
21868 * (It doesn't change the order of the grandchildren.)
21874 * @root: the root #GNode of the tree to traverse
21875 * @order: the order in which nodes are visited - %G_IN_ORDER,
21876 * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER.
21877 * @flags: which types of children are to be visited, one of
21878 * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
21879 * @max_depth: the maximum depth of the traversal. Nodes below this
21880 * depth will not be visited. If max_depth is -1 all nodes in
21881 * the tree are visited. If depth is 1, only the root is visited.
21882 * If depth is 2, the root and its children are visited. And so on.
21883 * @func: the function to call for each visited #GNode
21884 * @data: user data to pass to the function
21886 * Traverses a tree starting at the given root #GNode.
21887 * It calls the given function for each node visited.
21888 * The traversal can be halted at any point by returning %TRUE from @func.
21894 * @node: the #GNode to unlink, which becomes the root of a new tree
21896 * Unlinks a #GNode from a tree, resulting in two separate trees.
21902 * @val: a 32-bit integer value in network byte order
21904 * Converts a 32-bit integer value from network to host byte order.
21906 * Returns: @val converted to host byte order.
21912 * @val: a 16-bit integer value in network byte order
21914 * Converts a 16-bit integer value from network to host byte order.
21916 * Returns: @val converted to host byte order
21921 * g_nullify_pointer:
21922 * @nullify_location: (not nullable): the memory address of the pointer.
21924 * Set the pointer at the specified location to %NULL.
21929 * g_on_error_query:
21930 * @prg_name: the program name, needed by gdb for the "[S]tack trace"
21931 * option. If @prg_name is %NULL, g_get_prgname() is called to get
21932 * the program name (which will work correctly if gdk_init() or
21933 * gtk_init() has been called)
21935 * Prompts the user with
21936 * `[E]xit, [H]alt, show [S]tack trace or [P]roceed`.
21937 * This function is intended to be used for debugging use only.
21938 * The following example shows how it can be used together with
21939 * the g_log() functions.
21941 * |[<!-- language="C" -->
21942 * #include <glib.h>
21945 * log_handler (const gchar *log_domain,
21946 * GLogLevelFlags log_level,
21947 * const gchar *message,
21948 * gpointer user_data)
21950 * g_log_default_handler (log_domain, log_level, message, user_data);
21952 * g_on_error_query (MY_PROGRAM_NAME);
21956 * main (int argc, char *argv[])
21958 * g_log_set_handler (MY_LOG_DOMAIN,
21959 * G_LOG_LEVEL_WARNING |
21960 * G_LOG_LEVEL_ERROR |
21961 * G_LOG_LEVEL_CRITICAL,
21967 * If "[E]xit" is selected, the application terminates with a call
21970 * If "[S]tack" trace is selected, g_on_error_stack_trace() is called.
21971 * This invokes gdb, which attaches to the current process and shows
21972 * a stack trace. The prompt is then shown again.
21974 * If "[P]roceed" is selected, the function returns.
21976 * This function may cause different actions on non-UNIX platforms.
21981 * g_on_error_stack_trace:
21982 * @prg_name: the program name, needed by gdb for the "[S]tack trace"
21985 * Invokes gdb, which attaches to the current process and shows a
21986 * stack trace. Called by g_on_error_query() when the "[S]tack trace"
21987 * option is selected. You can get the current process's program name
21988 * with g_get_prgname(), assuming that you have called gtk_init() or
21991 * This function may cause different actions on non-UNIX platforms.
21997 * @once: a #GOnce structure
21998 * @func: the #GThreadFunc function associated to @once. This function
21999 * is called only once, regardless of the number of times it and
22000 * its associated #GOnce struct are passed to g_once().
22001 * @arg: data to be passed to @func
22003 * The first call to this routine by a process with a given #GOnce
22004 * struct calls @func with the given argument. Thereafter, subsequent
22005 * calls to g_once() with the same #GOnce struct do not call @func
22006 * again, but return the stored result of the first call. On return
22007 * from g_once(), the status of @once will be %G_ONCE_STATUS_READY.
22009 * For example, a mutex or a thread-specific data key must be created
22010 * exactly once. In a threaded environment, calling g_once() ensures
22011 * that the initialization is serialized across multiple threads.
22013 * Calling g_once() recursively on the same #GOnce struct in
22014 * @func will lead to a deadlock.
22016 * |[<!-- language="C" -->
22018 * get_debug_flags (void)
22020 * static GOnce my_once = G_ONCE_INIT;
22022 * g_once (&my_once, parse_debug_flags, NULL);
22024 * return my_once.retval;
22033 * g_once_init_enter:
22034 * @location: (not nullable): location of a static initializable variable
22037 * Function to be called when starting a critical initialization
22038 * section. The argument @location must point to a static
22039 * 0-initialized variable that will be set to a value other than 0 at
22040 * the end of the initialization section. In combination with
22041 * g_once_init_leave() and the unique address @value_location, it can
22042 * be ensured that an initialization section will be executed only once
22043 * during a program's life time, and that concurrent threads are
22044 * blocked until initialization completed. To be used in constructs
22047 * |[<!-- language="C" -->
22048 * static gsize initialization_value = 0;
22050 * if (g_once_init_enter (&initialization_value))
22052 * gsize setup_value = 42; // initialization code here
22054 * g_once_init_leave (&initialization_value, setup_value);
22057 * // use initialization_value here
22060 * Returns: %TRUE if the initialization section should be entered,
22061 * %FALSE and blocks otherwise
22067 * g_once_init_leave:
22068 * @location: (not nullable): location of a static initializable variable
22070 * @result: new non-0 value for *@value_location
22072 * Counterpart to g_once_init_enter(). Expects a location of a static
22073 * 0-initialized initialization variable, and an initialization value
22074 * other than 0. Sets the variable to the initialization value, and
22075 * releases concurrent threads blocking in g_once_init_enter() on this
22076 * initialization variable.
22084 * @filename: (type filename): a pathname in the GLib file name encoding
22085 * (UTF-8 on Windows)
22086 * @flags: as in open()
22087 * @mode: as in open()
22089 * A wrapper for the POSIX open() function. The open() function is
22090 * used to convert a pathname into a file descriptor.
22092 * On POSIX systems file descriptors are implemented by the operating
22093 * system. On Windows, it's the C library that implements open() and
22094 * file descriptors. The actual Win32 API for opening files is quite
22095 * different, see MSDN documentation for CreateFile(). The Win32 API
22096 * uses file handles, which are more randomish integers, not small
22097 * integers like file descriptors.
22099 * Because file descriptors are specific to the C library on Windows,
22100 * the file descriptor returned by this function makes sense only to
22101 * functions in the same C library. Thus if the GLib-using code uses a
22102 * different C library than GLib does, the file descriptor returned by
22103 * this function cannot be passed to C library functions like write()
22106 * See your C library manual for more details about open().
22108 * Returns: a new file descriptor, or -1 if an error occurred.
22109 * The return value can be used exactly like the return value
22116 * g_option_context_add_group:
22117 * @context: a #GOptionContext
22118 * @group: (transfer full): the group to add
22120 * Adds a #GOptionGroup to the @context, so that parsing with @context
22121 * will recognize the options in the group. Note that this will take
22122 * ownership of the @group and thus the @group should not be freed.
22129 * g_option_context_add_main_entries:
22130 * @context: a #GOptionContext
22131 * @entries: a %NULL-terminated array of #GOptionEntrys
22132 * @translation_domain: (allow-none): a translation domain to use for translating
22133 * the `--help` output for the options in @entries
22134 * with gettext(), or %NULL
22136 * A convenience function which creates a main group if it doesn't
22137 * exist, adds the @entries to it and sets the translation domain.
22144 * g_option_context_free:
22145 * @context: a #GOptionContext
22147 * Frees context and all the groups which have been
22150 * Please note that parsed arguments need to be freed separately (see
22158 * g_option_context_get_description:
22159 * @context: a #GOptionContext
22161 * Returns the description. See g_option_context_set_description().
22163 * Returns: the description
22169 * g_option_context_get_help:
22170 * @context: a #GOptionContext
22171 * @main_help: if %TRUE, only include the main group
22172 * @group: (allow-none): the #GOptionGroup to create help for, or %NULL
22174 * Returns a formatted, translated help text for the given context.
22175 * To obtain the text produced by `--help`, call
22176 * `g_option_context_get_help (context, TRUE, NULL)`.
22177 * To obtain the text produced by `--help-all`, call
22178 * `g_option_context_get_help (context, FALSE, NULL)`.
22179 * To obtain the help text for an option group, call
22180 * `g_option_context_get_help (context, FALSE, group)`.
22182 * Returns: A newly allocated string containing the help text
22188 * g_option_context_get_help_enabled:
22189 * @context: a #GOptionContext
22191 * Returns whether automatic `--help` generation
22192 * is turned on for @context. See g_option_context_set_help_enabled().
22194 * Returns: %TRUE if automatic help generation is turned on.
22200 * g_option_context_get_ignore_unknown_options:
22201 * @context: a #GOptionContext
22203 * Returns whether unknown options are ignored or not. See
22204 * g_option_context_set_ignore_unknown_options().
22206 * Returns: %TRUE if unknown options are ignored.
22212 * g_option_context_get_main_group:
22213 * @context: a #GOptionContext
22215 * Returns a pointer to the main group of @context.
22217 * Returns: (transfer none): the main group of @context, or %NULL if
22218 * @context doesn't have a main group. Note that group belongs to
22219 * @context and should not be modified or freed.
22225 * g_option_context_get_strict_posix:
22226 * @context: a #GoptionContext
22228 * Returns whether strict POSIX code is enabled.
22230 * See g_option_context_set_strict_posix() for more information.
22232 * Returns: %TRUE if strict POSIX is enabled, %FALSE otherwise.
22238 * g_option_context_get_summary:
22239 * @context: a #GOptionContext
22241 * Returns the summary. See g_option_context_set_summary().
22243 * Returns: the summary
22249 * g_option_context_new:
22250 * @parameter_string: (allow-none): a string which is displayed in
22251 * the first line of `--help` output, after the usage summary
22252 * `programname [OPTION...]`
22254 * Creates a new option context.
22256 * The @parameter_string can serve multiple purposes. It can be used
22257 * to add descriptions for "rest" arguments, which are not parsed by
22258 * the #GOptionContext, typically something like "FILES" or
22259 * "FILE1 FILE2...". If you are using #G_OPTION_REMAINING for
22260 * collecting "rest" arguments, GLib handles this automatically by
22261 * using the @arg_description of the corresponding #GOptionEntry in
22262 * the usage summary.
22264 * Another usage is to give a short summary of the program
22265 * functionality, like " - frob the strings", which will be displayed
22266 * in the same line as the usage. For a longer description of the
22267 * program functionality that should be displayed as a paragraph
22268 * below the usage line, use g_option_context_set_summary().
22270 * Note that the @parameter_string is translated using the
22271 * function set with g_option_context_set_translate_func(), so
22272 * it should normally be passed untranslated.
22274 * Returns: a newly created #GOptionContext, which must be
22275 * freed with g_option_context_free() after use.
22281 * g_option_context_parse:
22282 * @context: a #GOptionContext
22283 * @argc: (inout) (allow-none): a pointer to the number of command line arguments
22284 * @argv: (inout) (array length=argc) (allow-none): a pointer to the array of command line arguments
22285 * @error: a return location for errors
22287 * Parses the command line arguments, recognizing options
22288 * which have been added to @context. A side-effect of
22289 * calling this function is that g_set_prgname() will be
22292 * If the parsing is successful, any parsed arguments are
22293 * removed from the array and @argc and @argv are updated
22294 * accordingly. A '--' option is stripped from @argv
22295 * unless there are unparsed options before and after it,
22296 * or some of the options after it start with '-'. In case
22297 * of an error, @argc and @argv are left unmodified.
22299 * If automatic `--help` support is enabled
22300 * (see g_option_context_set_help_enabled()), and the
22301 * @argv array contains one of the recognized help options,
22302 * this function will produce help output to stdout and
22305 * Note that function depends on the [current locale][setlocale] for
22306 * automatic character set conversion of string and filename
22309 * Returns: %TRUE if the parsing was successful,
22310 * %FALSE if an error occurred
22316 * g_option_context_parse_strv:
22317 * @context: a #GOptionContext
22318 * @arguments: (inout) (array null-terminated=1): a pointer to the
22319 * command line arguments (which must be in UTF-8 on Windows)
22320 * @error: a return location for errors
22322 * Parses the command line arguments.
22324 * This function is similar to g_option_context_parse() except that it
22325 * respects the normal memory rules when dealing with a strv instead of
22326 * assuming that the passed-in array is the argv of the main function.
22328 * In particular, strings that are removed from the arguments list will
22329 * be freed using g_free().
22331 * On Windows, the strings are expected to be in UTF-8. This is in
22332 * contrast to g_option_context_parse() which expects them to be in the
22333 * system codepage, which is how they are passed as @argv to main().
22334 * See g_win32_get_command_line() for a solution.
22336 * This function is useful if you are trying to use #GOptionContext with
22339 * Returns: %TRUE if the parsing was successful,
22340 * %FALSE if an error occurred
22346 * g_option_context_set_description:
22347 * @context: a #GOptionContext
22348 * @description: (allow-none): a string to be shown in `--help` output
22349 * after the list of options, or %NULL
22351 * Adds a string to be displayed in `--help` output after the list
22352 * of options. This text often includes a bug reporting address.
22354 * Note that the summary is translated (see
22355 * g_option_context_set_translate_func()).
22362 * g_option_context_set_help_enabled:
22363 * @context: a #GOptionContext
22364 * @help_enabled: %TRUE to enable `--help`, %FALSE to disable it
22366 * Enables or disables automatic generation of `--help` output.
22367 * By default, g_option_context_parse() recognizes `--help`, `-h`,
22368 * `-?`, `--help-all` and `--help-groupname` and creates suitable
22369 * output to stdout.
22376 * g_option_context_set_ignore_unknown_options:
22377 * @context: a #GOptionContext
22378 * @ignore_unknown: %TRUE to ignore unknown options, %FALSE to produce
22379 * an error when unknown options are met
22381 * Sets whether to ignore unknown options or not. If an argument is
22382 * ignored, it is left in the @argv array after parsing. By default,
22383 * g_option_context_parse() treats unknown options as error.
22385 * This setting does not affect non-option arguments (i.e. arguments
22386 * which don't start with a dash). But note that GOption cannot reliably
22387 * determine whether a non-option belongs to a preceding unknown option.
22394 * g_option_context_set_main_group:
22395 * @context: a #GOptionContext
22396 * @group: (transfer full): the group to set as main group
22398 * Sets a #GOptionGroup as main group of the @context.
22399 * This has the same effect as calling g_option_context_add_group(),
22400 * the only difference is that the options in the main group are
22401 * treated differently when generating `--help` output.
22408 * g_option_context_set_strict_posix:
22409 * @context: a #GoptionContext
22410 * @strict_posix: the new value
22412 * Sets strict POSIX mode.
22414 * By default, this mode is disabled.
22416 * In strict POSIX mode, the first non-argument parameter encountered
22417 * (eg: filename) terminates argument processing. Remaining arguments
22418 * are treated as non-options and are not attempted to be parsed.
22420 * If strict POSIX mode is disabled then parsing is done in the GNU way
22421 * where option arguments can be freely mixed with non-options.
22423 * As an example, consider "ls foo -l". With GNU style parsing, this
22424 * will list "foo" in long mode. In strict POSIX style, this will list
22425 * the files named "foo" and "-l".
22427 * It may be useful to force strict POSIX mode when creating "verb
22428 * style" command line tools. For example, the "gsettings" command line
22429 * tool supports the global option "--schemadir" as well as many
22430 * subcommands ("get", "set", etc.) which each have their own set of
22431 * arguments. Using strict POSIX mode will allow parsing the global
22432 * options up to the verb name while leaving the remaining options to be
22433 * parsed by the relevant subcommand (which can be determined by
22434 * examining the verb name, which should be present in argv[1] after
22442 * g_option_context_set_summary:
22443 * @context: a #GOptionContext
22444 * @summary: (allow-none): a string to be shown in `--help` output
22445 * before the list of options, or %NULL
22447 * Adds a string to be displayed in `--help` output before the list
22448 * of options. This is typically a summary of the program functionality.
22450 * Note that the summary is translated (see
22451 * g_option_context_set_translate_func() and
22452 * g_option_context_set_translation_domain()).
22459 * g_option_context_set_translate_func:
22460 * @context: a #GOptionContext
22461 * @func: (allow-none): the #GTranslateFunc, or %NULL
22462 * @data: (allow-none): user data to pass to @func, or %NULL
22463 * @destroy_notify: (allow-none): a function which gets called to free @data, or %NULL
22465 * Sets the function which is used to translate the contexts
22466 * user-visible strings, for `--help` output. If @func is %NULL,
22467 * strings are not translated.
22469 * Note that option groups have their own translation functions,
22470 * this function only affects the @parameter_string (see g_option_context_new()),
22471 * the summary (see g_option_context_set_summary()) and the description
22472 * (see g_option_context_set_description()).
22474 * If you are using gettext(), you only need to set the translation
22475 * domain, see g_option_context_set_translation_domain().
22482 * g_option_context_set_translation_domain:
22483 * @context: a #GOptionContext
22484 * @domain: the domain to use
22486 * A convenience function to use gettext() for translating
22487 * user-visible strings.
22494 * g_option_group_add_entries:
22495 * @group: a #GOptionGroup
22496 * @entries: a %NULL-terminated array of #GOptionEntrys
22498 * Adds the options specified in @entries to @group.
22505 * g_option_group_free:
22506 * @group: a #GOptionGroup
22508 * Frees a #GOptionGroup. Note that you must not free groups
22509 * which have been added to a #GOptionContext.
22512 * Deprecated: 2.44: Use g_option_group_unref() instead.
22517 * g_option_group_new:
22518 * @name: the name for the option group, this is used to provide
22519 * help for the options in this group with `--help-`@name
22520 * @description: a description for this group to be shown in
22521 * `--help`. This string is translated using the translation
22522 * domain or translation function of the group
22523 * @help_description: a description for the `--help-`@name option.
22524 * This string is translated using the translation domain or translation function
22526 * @user_data: (allow-none): user data that will be passed to the pre- and post-parse hooks,
22527 * the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL
22528 * @destroy: (allow-none): a function that will be called to free @user_data, or %NULL
22530 * Creates a new #GOptionGroup.
22532 * Returns: a newly created option group. It should be added
22533 * to a #GOptionContext or freed with g_option_group_unref().
22539 * g_option_group_ref:
22540 * @group: a #GOptionGroup
22542 * Increments the reference count of @group by one.
22544 * Returns: a #GoptionGroup
22550 * g_option_group_set_error_hook:
22551 * @group: a #GOptionGroup
22552 * @error_func: a function to call when an error occurs
22554 * Associates a function with @group which will be called
22555 * from g_option_context_parse() when an error occurs.
22557 * Note that the user data to be passed to @error_func can be
22558 * specified when constructing the group with g_option_group_new().
22565 * g_option_group_set_parse_hooks:
22566 * @group: a #GOptionGroup
22567 * @pre_parse_func: (allow-none): a function to call before parsing, or %NULL
22568 * @post_parse_func: (allow-none): a function to call after parsing, or %NULL
22570 * Associates two functions with @group which will be called
22571 * from g_option_context_parse() before the first option is parsed
22572 * and after the last option has been parsed, respectively.
22574 * Note that the user data to be passed to @pre_parse_func and
22575 * @post_parse_func can be specified when constructing the group
22576 * with g_option_group_new().
22583 * g_option_group_set_translate_func:
22584 * @group: a #GOptionGroup
22585 * @func: (allow-none): the #GTranslateFunc, or %NULL
22586 * @data: (allow-none): user data to pass to @func, or %NULL
22587 * @destroy_notify: (allow-none): a function which gets called to free @data, or %NULL
22589 * Sets the function which is used to translate user-visible strings,
22590 * for `--help` output. Different groups can use different
22591 * #GTranslateFuncs. If @func is %NULL, strings are not translated.
22593 * If you are using gettext(), you only need to set the translation
22594 * domain, see g_option_group_set_translation_domain().
22601 * g_option_group_set_translation_domain:
22602 * @group: a #GOptionGroup
22603 * @domain: the domain to use
22605 * A convenience function to use gettext() for translating
22606 * user-visible strings.
22613 * g_option_group_unref:
22614 * @group: a #GOptionGroup
22616 * Decrements the reference count of @group by one.
22617 * If the reference count drops to 0, the @group will be freed.
22618 * and all memory allocated by the @group is released.
22625 * g_parse_debug_string:
22626 * @string: (allow-none): a list of debug options separated by colons, spaces, or
22627 * commas, or %NULL.
22628 * @keys: (array length=nkeys): pointer to an array of #GDebugKey which associate
22629 * strings with bit flags.
22630 * @nkeys: the number of #GDebugKeys in the array.
22632 * Parses a string containing debugging options
22633 * into a %guint containing bit flags. This is used
22634 * within GDK and GTK+ to parse the debug options passed on the
22635 * command line or through environment variables.
22637 * If @string is equal to "all", all flags are set. Any flags
22638 * specified along with "all" in @string are inverted; thus,
22639 * "all,foo,bar" or "foo,bar,all" sets all flags except those
22640 * corresponding to "foo" and "bar".
22642 * If @string is equal to "help", all the available keys in @keys
22643 * are printed out to standard error.
22645 * Returns: the combined set of bit flags.
22650 * g_path_get_basename:
22651 * @file_name: (type filename): the name of the file
22653 * Gets the last component of the filename.
22655 * If @file_name ends with a directory separator it gets the component
22656 * before the last slash. If @file_name consists only of directory
22657 * separators (and on Windows, possibly a drive letter), a single
22658 * separator is returned. If @file_name is empty, it gets ".".
22660 * Returns: (type filename): a newly allocated string containing the last
22661 * component of the filename
22666 * g_path_get_dirname:
22667 * @file_name: (type filename): the name of the file
22669 * Gets the directory components of a file name.
22671 * If the file name has no directory components "." is returned.
22672 * The returned string should be freed when no longer needed.
22674 * Returns: (type filename): the directory components of the file
22679 * g_path_is_absolute:
22680 * @file_name: (type filename): a file name
22682 * Returns %TRUE if the given @file_name is an absolute file name.
22683 * Note that this is a somewhat vague concept on Windows.
22685 * On POSIX systems, an absolute file name is well-defined. It always
22686 * starts from the single root directory. For example "/usr/local".
22688 * On Windows, the concepts of current drive and drive-specific
22689 * current directory introduce vagueness. This function interprets as
22690 * an absolute file name one that either begins with a directory
22691 * separator such as "\Users\tml" or begins with the root on a drive,
22692 * for example "C:\Windows". The first case also includes UNC paths
22693 * such as "\\myserver\docs\foo". In all cases, either slashes or
22694 * backslashes are accepted.
22696 * Note that a file name relative to the current drive root does not
22697 * truly specify a file uniquely over time and across processes, as
22698 * the current drive is a per-process value and can be changed.
22700 * File names relative the current directory on some specific drive,
22701 * such as "D:foo/bar", are not interpreted as absolute by this
22702 * function, but they obviously are not relative to the normal current
22703 * directory as returned by getcwd() or g_get_current_dir()
22704 * either. Such paths should be avoided, or need to be handled using
22705 * Windows-specific code.
22707 * Returns: %TRUE if @file_name is absolute
22712 * g_path_skip_root:
22713 * @file_name: (type filename): a file name
22715 * Returns a pointer into @file_name after the root component,
22716 * i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name
22717 * is not an absolute path it returns %NULL.
22719 * Returns: (type filename) (nullable): a pointer into @file_name after the
22726 * @pspec: a #GPatternSpec
22727 * @string_length: the length of @string (in bytes, i.e. strlen(),
22728 * not g_utf8_strlen())
22729 * @string: the UTF-8 encoded string to match
22730 * @string_reversed: (allow-none): the reverse of @string or %NULL
22732 * Matches a string against a compiled pattern. Passing the correct
22733 * length of the string given is mandatory. The reversed string can be
22734 * omitted by passing %NULL, this is more efficient if the reversed
22735 * version of the string to be matched is not at hand, as
22736 * g_pattern_match() will only construct it if the compiled pattern
22737 * requires reverse matches.
22739 * Note that, if the user code will (possibly) match a string against a
22740 * multitude of patterns containing wildcards, chances are high that
22741 * some patterns will require a reversed string. In this case, it's
22742 * more efficient to provide the reversed string to avoid multiple
22743 * constructions thereof in the various calls to g_pattern_match().
22745 * Note also that the reverse of a UTF-8 encoded string can in general
22746 * not be obtained by g_strreverse(). This works only if the string
22747 * does not contain any multibyte characters. GLib offers the
22748 * g_utf8_strreverse() function to reverse UTF-8 encoded strings.
22750 * Returns: %TRUE if @string matches @pspec
22755 * g_pattern_match_simple:
22756 * @pattern: the UTF-8 encoded pattern
22757 * @string: the UTF-8 encoded string to match
22759 * Matches a string against a pattern given as a string. If this
22760 * function is to be called in a loop, it's more efficient to compile
22761 * the pattern once with g_pattern_spec_new() and call
22762 * g_pattern_match_string() repeatedly.
22764 * Returns: %TRUE if @string matches @pspec
22769 * g_pattern_match_string:
22770 * @pspec: a #GPatternSpec
22771 * @string: the UTF-8 encoded string to match
22773 * Matches a string against a compiled pattern. If the string is to be
22774 * matched against more than one pattern, consider using
22775 * g_pattern_match() instead while supplying the reversed string.
22777 * Returns: %TRUE if @string matches @pspec
22782 * g_pattern_spec_equal:
22783 * @pspec1: a #GPatternSpec
22784 * @pspec2: another #GPatternSpec
22786 * Compares two compiled pattern specs and returns whether they will
22787 * match the same set of strings.
22789 * Returns: Whether the compiled patterns are equal
22794 * g_pattern_spec_free:
22795 * @pspec: a #GPatternSpec
22797 * Frees the memory allocated for the #GPatternSpec.
22802 * g_pattern_spec_new:
22803 * @pattern: a zero-terminated UTF-8 encoded string
22805 * Compiles a pattern to a #GPatternSpec.
22807 * Returns: a newly-allocated #GPatternSpec
22812 * g_pointer_bit_lock:
22813 * @address: (not nullable): a pointer to a #gpointer-sized value
22814 * @lock_bit: a bit value between 0 and 31
22816 * This is equivalent to g_bit_lock, but working on pointers (or other
22817 * pointer-sized values).
22819 * For portability reasons, you may only lock on the bottom 32 bits of
22827 * g_pointer_bit_trylock:
22828 * @address: (not nullable): a pointer to a #gpointer-sized value
22829 * @lock_bit: a bit value between 0 and 31
22831 * This is equivalent to g_bit_trylock, but working on pointers (or
22832 * other pointer-sized values).
22834 * For portability reasons, you may only lock on the bottom 32 bits of
22837 * Returns: %TRUE if the lock was acquired
22843 * g_pointer_bit_unlock:
22844 * @address: (not nullable): a pointer to a #gpointer-sized value
22845 * @lock_bit: a bit value between 0 and 31
22847 * This is equivalent to g_bit_unlock, but working on pointers (or other
22848 * pointer-sized values).
22850 * For portability reasons, you may only lock on the bottom 32 bits of
22859 * @fds: file descriptors to poll
22860 * @nfds: the number of file descriptors in @fds
22861 * @timeout: amount of time to wait, in milliseconds, or -1 to wait forever
22863 * Polls @fds, as with the poll() system call, but portably. (On
22864 * systems that don't have poll(), it is emulated using select().)
22865 * This is used internally by #GMainContext, but it can be called
22866 * directly if you need to block until a file descriptor is ready, but
22867 * don't want to run the full main loop.
22869 * Each element of @fds is a #GPollFD describing a single file
22870 * descriptor to poll. The %fd field indicates the file descriptor,
22871 * and the %events field indicates the events to poll for. On return,
22872 * the %revents fields will be filled with the events that actually
22875 * On POSIX systems, the file descriptors in @fds can be any sort of
22876 * file descriptor, but the situation is much more complicated on
22877 * Windows. If you need to use g_poll() in code that has to run on
22878 * Windows, the easiest solution is to construct all of your
22879 * #GPollFDs with g_io_channel_win32_make_pollfd().
22881 * Returns: the number of entries in @fds whose %revents fields
22882 * were filled in, or 0 if the operation timed out, or -1 on error or
22883 * if the call was interrupted.
22890 * @err: (inout) (optional) (nullable): a return location for a #GError
22891 * @format: printf()-style format string
22892 * @...: arguments to @format
22894 * Formats a string according to @format and prefix it to an existing
22895 * error message. If @err is %NULL (ie: no error variable) then do
22898 * If *@err is %NULL (ie: an error variable is present but there is no
22899 * error condition) then also do nothing. Whether or not it makes sense
22900 * to take advantage of this feature is up to you.
22908 * @format: the message format. See the printf() documentation
22909 * @...: the parameters to insert into the format string
22911 * Outputs a formatted message via the print handler.
22912 * The default print handler simply outputs the message to stdout, without
22913 * appending a trailing new-line character. Typically, @format should end with
22914 * its own new-line character.
22916 * g_print() should not be used from within libraries for debugging
22917 * messages, since it may be redirected by applications to special
22918 * purpose message windows or even files. Instead, libraries should
22919 * use g_log(), or the convenience functions g_message(), g_warning()
22926 * @format: the message format. See the printf() documentation
22927 * @...: the parameters to insert into the format string
22929 * Outputs a formatted message via the error message handler.
22930 * The default handler simply outputs the message to stderr, without appending
22931 * a trailing new-line character. Typically, @format should end with its own
22932 * new-line character.
22934 * g_printerr() should not be used from within libraries.
22935 * Instead g_log() should be used, or the convenience functions
22936 * g_message(), g_warning() and g_error().
22942 * @format: a standard printf() format string, but notice
22943 * [string precision pitfalls][string-precision]
22944 * @...: the arguments to insert in the output.
22946 * An implementation of the standard printf() function which supports
22947 * positional parameters, as specified in the Single Unix Specification.
22949 * As with the standard printf(), this does not automatically append a trailing
22950 * new-line character to the message, so typically @format should end with its
22951 * own new-line character.
22953 * Returns: the number of bytes printed.
22959 * g_printf_string_upper_bound:
22960 * @format: the format string. See the printf() documentation
22961 * @args: the parameters to be inserted into the format string
22963 * Calculates the maximum space needed to store the output
22964 * of the sprintf() function.
22966 * Returns: the maximum space needed to store the formatted string
22972 * @key: a #GPrivate
22974 * Returns the current value of the thread local variable @key.
22976 * If the value has not yet been set in this thread, %NULL is returned.
22977 * Values are never copied between threads (when a new thread is
22978 * created, for example).
22980 * Returns: the thread-local value
22985 * g_private_replace:
22986 * @key: a #GPrivate
22987 * @value: the new value
22989 * Sets the thread local variable @key to have the value @value in the
22992 * This function differs from g_private_set() in the following way: if
22993 * the previous value was non-%NULL then the #GDestroyNotify handler for
22994 * @key is run on it.
23002 * @key: a #GPrivate
23003 * @value: the new value
23005 * Sets the thread local variable @key to have the value @value in the
23008 * This function differs from g_private_replace() in the following way:
23009 * the #GDestroyNotify for @key is not called on the old value.
23014 * g_propagate_error:
23015 * @dest: (out callee-allocates) (optional) (nullable): error return location
23016 * @src: (transfer full): error to move into the return location
23018 * If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
23019 * The error variable @dest points to must be %NULL.
23021 * @src must be non-%NULL.
23023 * Note that @src is no longer valid after this call. If you want
23024 * to keep using the same GError*, you need to set it to %NULL
23025 * after calling this function on it.
23030 * g_propagate_prefixed_error:
23031 * @dest: error return location
23032 * @src: error to move into the return location
23033 * @format: printf()-style format string
23034 * @...: arguments to @format
23036 * If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
23037 * *@dest must be %NULL. After the move, add a prefix as with
23038 * g_prefix_error().
23046 * @array: a #GPtrArray
23047 * @data: the pointer to add
23049 * Adds a pointer to the end of the pointer array. The array will grow
23050 * in size automatically if necessary.
23055 * g_ptr_array_foreach:
23056 * @array: a #GPtrArray
23057 * @func: the function to call for each array element
23058 * @user_data: user data to pass to the function
23060 * Calls a function for each element of a #GPtrArray.
23067 * g_ptr_array_free:
23068 * @array: a #GPtrArray
23069 * @free_seg: if %TRUE the actual pointer array is freed as well
23071 * Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE
23072 * it frees the memory block holding the elements as well. Pass %FALSE
23073 * if you want to free the #GPtrArray wrapper but preserve the
23074 * underlying array for use elsewhere. If the reference count of @array
23075 * is greater than one, the #GPtrArray wrapper is preserved but the
23076 * size of @array will be set to zero.
23078 * If array contents point to dynamically-allocated memory, they should
23079 * be freed separately if @free_seg is %TRUE and no #GDestroyNotify
23080 * function has been set for @array.
23082 * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL.
23083 * The pointer array should be freed using g_free().
23088 * g_ptr_array_index:
23089 * @array: a #GPtrArray
23090 * @index_: the index of the pointer to return
23092 * Returns the pointer at the given index of the pointer array.
23094 * This does not perform bounds checking on the given @index_,
23095 * so you are responsible for checking it against the array length.
23097 * Returns: the pointer at the given index
23102 * g_ptr_array_insert:
23103 * @array: a #GPtrArray
23104 * @index_: the index to place the new element at, or -1 to append
23105 * @data: the pointer to add.
23107 * Inserts an element into the pointer array at the given index. The
23108 * array will grow in size automatically if necessary.
23117 * Creates a new #GPtrArray with a reference count of 1.
23119 * Returns: the new #GPtrArray
23124 * g_ptr_array_new_full:
23125 * @reserved_size: number of pointers preallocated
23126 * @element_free_func: (allow-none): A function to free elements with
23127 * destroy @array or %NULL
23129 * Creates a new #GPtrArray with @reserved_size pointers preallocated
23130 * and a reference count of 1. This avoids frequent reallocation, if
23131 * you are going to add many pointers to the array. Note however that
23132 * the size of the array is still 0. It also set @element_free_func
23133 * for freeing each element when the array is destroyed either via
23134 * g_ptr_array_unref(), when g_ptr_array_free() is called with
23135 * @free_segment set to %TRUE or when removing elements.
23137 * Returns: A new #GPtrArray
23143 * g_ptr_array_new_with_free_func:
23144 * @element_free_func: (allow-none): A function to free elements with
23145 * destroy @array or %NULL
23147 * Creates a new #GPtrArray with a reference count of 1 and use
23148 * @element_free_func for freeing each element when the array is destroyed
23149 * either via g_ptr_array_unref(), when g_ptr_array_free() is called with
23150 * @free_segment set to %TRUE or when removing elements.
23152 * Returns: A new #GPtrArray
23159 * @array: a #GPtrArray
23161 * Atomically increments the reference count of @array by one.
23162 * This function is thread-safe and may be called from any thread.
23164 * Returns: The passed in #GPtrArray
23170 * g_ptr_array_remove:
23171 * @array: a #GPtrArray
23172 * @data: the pointer to remove
23174 * Removes the first occurrence of the given pointer from the pointer
23175 * array. The following elements are moved down one place. If @array
23176 * has a non-%NULL #GDestroyNotify function it is called for the
23179 * It returns %TRUE if the pointer was removed, or %FALSE if the
23180 * pointer was not found.
23182 * Returns: %TRUE if the pointer is removed, %FALSE if the pointer
23183 * is not found in the array
23188 * g_ptr_array_remove_fast:
23189 * @array: a #GPtrArray
23190 * @data: the pointer to remove
23192 * Removes the first occurrence of the given pointer from the pointer
23193 * array. The last element in the array is used to fill in the space,
23194 * so this function does not preserve the order of the array. But it
23195 * is faster than g_ptr_array_remove(). If @array has a non-%NULL
23196 * #GDestroyNotify function it is called for the removed element.
23198 * It returns %TRUE if the pointer was removed, or %FALSE if the
23199 * pointer was not found.
23201 * Returns: %TRUE if the pointer was found in the array
23206 * g_ptr_array_remove_index:
23207 * @array: a #GPtrArray
23208 * @index_: the index of the pointer to remove
23210 * Removes the pointer at the given index from the pointer array.
23211 * The following elements are moved down one place. If @array has
23212 * a non-%NULL #GDestroyNotify function it is called for the removed
23215 * Returns: the pointer which was removed
23220 * g_ptr_array_remove_index_fast:
23221 * @array: a #GPtrArray
23222 * @index_: the index of the pointer to remove
23224 * Removes the pointer at the given index from the pointer array.
23225 * The last element in the array is used to fill in the space, so
23226 * this function does not preserve the order of the array. But it
23227 * is faster than g_ptr_array_remove_index(). If @array has a non-%NULL
23228 * #GDestroyNotify function it is called for the removed element.
23230 * Returns: the pointer which was removed
23235 * g_ptr_array_remove_range:
23236 * @array: a @GPtrArray
23237 * @index_: the index of the first pointer to remove
23238 * @length: the number of pointers to remove
23240 * Removes the given number of pointers starting at the given index
23241 * from a #GPtrArray. The following elements are moved to close the
23242 * gap. If @array has a non-%NULL #GDestroyNotify function it is
23243 * called for the removed elements.
23245 * Returns: the @array
23251 * g_ptr_array_set_free_func:
23252 * @array: A #GPtrArray
23253 * @element_free_func: (allow-none): A function to free elements with
23254 * destroy @array or %NULL
23256 * Sets a function for freeing each element when @array is destroyed
23257 * either via g_ptr_array_unref(), when g_ptr_array_free() is called
23258 * with @free_segment set to %TRUE or when removing elements.
23265 * g_ptr_array_set_size:
23266 * @array: a #GPtrArray
23267 * @length: the new length of the pointer array
23269 * Sets the size of the array. When making the array larger,
23270 * newly-added elements will be set to %NULL. When making it smaller,
23271 * if @array has a non-%NULL #GDestroyNotify function then it will be
23272 * called for the removed elements.
23277 * g_ptr_array_sized_new:
23278 * @reserved_size: number of pointers preallocated
23280 * Creates a new #GPtrArray with @reserved_size pointers preallocated
23281 * and a reference count of 1. This avoids frequent reallocation, if
23282 * you are going to add many pointers to the array. Note however that
23283 * the size of the array is still 0.
23285 * Returns: the new #GPtrArray
23290 * g_ptr_array_sort:
23291 * @array: a #GPtrArray
23292 * @compare_func: comparison function
23294 * Sorts the array, using @compare_func which should be a qsort()-style
23295 * comparison function (returns less than zero for first arg is less
23296 * than second arg, zero for equal, greater than zero if irst arg is
23297 * greater than second arg).
23299 * Note that the comparison function for g_ptr_array_sort() doesn't
23300 * take the pointers from the array as arguments, it takes pointers to
23301 * the pointers in the array.
23303 * This is guaranteed to be a stable sort since version 2.32.
23308 * g_ptr_array_sort_with_data:
23309 * @array: a #GPtrArray
23310 * @compare_func: comparison function
23311 * @user_data: data to pass to @compare_func
23313 * Like g_ptr_array_sort(), but the comparison function has an extra
23314 * user data argument.
23316 * Note that the comparison function for g_ptr_array_sort_with_data()
23317 * doesn't take the pointers from the array as arguments, it takes
23318 * pointers to the pointers in the array.
23320 * This is guaranteed to be a stable sort since version 2.32.
23325 * g_ptr_array_unref:
23326 * @array: A #GPtrArray
23328 * Atomically decrements the reference count of @array by one. If the
23329 * reference count drops to 0, the effect is the same as calling
23330 * g_ptr_array_free() with @free_segment set to %TRUE. This function
23331 * is MT-safe and may be called from any thread.
23338 * g_qsort_with_data:
23339 * @pbase: (not nullable): start of array to sort
23340 * @total_elems: elements in the array
23341 * @size: size of each element
23342 * @compare_func: function to compare elements
23343 * @user_data: data to pass to @compare_func
23345 * This is just like the standard C qsort() function, but
23346 * the comparison routine accepts a user data argument.
23348 * This is guaranteed to be a stable sort since version 2.32.
23353 * g_quark_from_static_string:
23354 * @string: (allow-none): a string
23356 * Gets the #GQuark identifying the given (static) string. If the
23357 * string does not currently have an associated #GQuark, a new #GQuark
23358 * is created, linked to the given string.
23360 * Note that this function is identical to g_quark_from_string() except
23361 * that if a new #GQuark is created the string itself is used rather
23362 * than a copy. This saves memory, but can only be used if the string
23363 * will continue to exist until the program terminates. It can be used
23364 * with statically allocated strings in the main program, but not with
23365 * statically allocated memory in dynamically loaded modules, if you
23366 * expect to ever unload the module again (e.g. do not use this
23367 * function in GTK+ theme engines).
23369 * Returns: the #GQuark identifying the string, or 0 if @string is %NULL
23374 * g_quark_from_string:
23375 * @string: (allow-none): a string
23377 * Gets the #GQuark identifying the given string. If the string does
23378 * not currently have an associated #GQuark, a new #GQuark is created,
23379 * using a copy of the string.
23381 * Returns: the #GQuark identifying the string, or 0 if @string is %NULL
23386 * g_quark_to_string:
23387 * @quark: a #GQuark.
23389 * Gets the string associated with the given #GQuark.
23391 * Returns: the string associated with the #GQuark
23396 * g_quark_try_string:
23397 * @string: (allow-none): a string
23399 * Gets the #GQuark associated with the given string, or 0 if string is
23400 * %NULL or it has no associated #GQuark.
23402 * If you want the GQuark to be created if it doesn't already exist,
23403 * use g_quark_from_string() or g_quark_from_static_string().
23405 * Returns: the #GQuark associated with the string, or 0 if @string is
23406 * %NULL or there is no #GQuark associated with it
23412 * @queue: a #GQueue
23414 * Removes all the elements in @queue. If queue elements contain
23415 * dynamically-allocated memory, they should be freed first.
23423 * @queue: a #GQueue
23425 * Copies a @queue. Note that is a shallow copy. If the elements in the
23426 * queue consist of pointers to data, the pointers are copied, but the
23427 * actual data is not.
23429 * Returns: a copy of @queue
23435 * g_queue_delete_link:
23436 * @queue: a #GQueue
23437 * @link_: a #GList link that must be part of @queue
23439 * Removes @link_ from @queue and frees it.
23441 * @link_ must be part of @queue.
23449 * @queue: a #GQueue
23450 * @data: data to find
23452 * Finds the first link in @queue which contains @data.
23454 * Returns: the first link in @queue which contains @data
23460 * g_queue_find_custom:
23461 * @queue: a #GQueue
23462 * @data: user data passed to @func
23463 * @func: a #GCompareFunc to call for each element. It should return 0
23464 * when the desired element is found
23466 * Finds an element in a #GQueue, using a supplied function to find the
23467 * desired element. It iterates over the queue, calling the given function
23468 * which should return 0 when the desired element is found. The function
23469 * takes two gconstpointer arguments, the #GQueue element's data as the
23470 * first argument and the given user data as the second argument.
23472 * Returns: the found link, or %NULL if it wasn't found
23479 * @queue: a #GQueue
23480 * @func: the function to call for each element's data
23481 * @user_data: user data to pass to @func
23483 * Calls @func for each element in the queue passing @user_data to the
23492 * @queue: a #GQueue
23494 * Frees the memory allocated for the #GQueue. Only call this function
23495 * if @queue was created with g_queue_new(). If queue elements contain
23496 * dynamically-allocated memory, they should be freed first.
23498 * If queue elements contain dynamically-allocated memory, you should
23499 * either use g_queue_free_full() or free them manually first.
23504 * g_queue_free_full:
23505 * @queue: a pointer to a #GQueue
23506 * @free_func: the function to be called to free each element's data
23508 * Convenience method, which frees all the memory used by a #GQueue,
23509 * and calls the specified destroy function on every element's data.
23516 * g_queue_get_length:
23517 * @queue: a #GQueue
23519 * Returns the number of items in @queue.
23521 * Returns: the number of items in @queue
23528 * @queue: a #GQueue
23529 * @data: the data to find
23531 * Returns the position of the first element in @queue which contains @data.
23533 * Returns: the position of the first element in @queue which
23534 * contains @data, or -1 if no element in @queue contains @data
23541 * @queue: an uninitialized #GQueue
23543 * A statically-allocated #GQueue must be initialized with this function
23544 * before it can be used. Alternatively you can initialize it with
23545 * #G_QUEUE_INIT. It is not necessary to initialize queues created with
23553 * g_queue_insert_after:
23554 * @queue: a #GQueue
23555 * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
23556 * push at the head of the queue.
23557 * @data: the data to insert
23559 * Inserts @data into @queue after @sibling.
23561 * @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the
23562 * data at the head of the queue.
23569 * g_queue_insert_before:
23570 * @queue: a #GQueue
23571 * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
23572 * push at the tail of the queue.
23573 * @data: the data to insert
23575 * Inserts @data into @queue before @sibling.
23577 * @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the
23578 * data at the tail of the queue.
23585 * g_queue_insert_sorted:
23586 * @queue: a #GQueue
23587 * @data: the data to insert
23588 * @func: the #GCompareDataFunc used to compare elements in the queue. It is
23589 * called with two elements of the @queue and @user_data. It should
23590 * return 0 if the elements are equal, a negative value if the first
23591 * element comes before the second, and a positive value if the second
23592 * element comes before the first.
23593 * @user_data: user data passed to @func
23595 * Inserts @data into @queue using @func to determine the new position.
23602 * g_queue_is_empty:
23603 * @queue: a #GQueue.
23605 * Returns %TRUE if the queue is empty.
23607 * Returns: %TRUE if the queue is empty
23612 * g_queue_link_index:
23613 * @queue: a #GQueue
23614 * @link_: a #GList link
23616 * Returns the position of @link_ in @queue.
23618 * Returns: the position of @link_, or -1 if the link is
23619 * not part of @queue
23627 * Creates a new #GQueue.
23629 * Returns: a newly allocated #GQueue
23634 * g_queue_peek_head:
23635 * @queue: a #GQueue
23637 * Returns the first element of the queue.
23639 * Returns: the data of the first element in the queue, or %NULL
23640 * if the queue is empty
23645 * g_queue_peek_head_link:
23646 * @queue: a #GQueue
23648 * Returns the first link in @queue.
23650 * Returns: the first link in @queue, or %NULL if @queue is empty
23656 * g_queue_peek_nth:
23657 * @queue: a #GQueue
23658 * @n: the position of the element
23660 * Returns the @n'th element of @queue.
23662 * Returns: the data for the @n'th element of @queue,
23663 * or %NULL if @n is off the end of @queue
23669 * g_queue_peek_nth_link:
23670 * @queue: a #GQueue
23671 * @n: the position of the link
23673 * Returns the link at the given position
23675 * Returns: the link at the @n'th position, or %NULL
23676 * if @n is off the end of the list
23682 * g_queue_peek_tail:
23683 * @queue: a #GQueue
23685 * Returns the last element of the queue.
23687 * Returns: the data of the last element in the queue, or %NULL
23688 * if the queue is empty
23693 * g_queue_peek_tail_link:
23694 * @queue: a #GQueue
23696 * Returns the last link in @queue.
23698 * Returns: the last link in @queue, or %NULL if @queue is empty
23704 * g_queue_pop_head:
23705 * @queue: a #GQueue
23707 * Removes the first element of the queue and returns its data.
23709 * Returns: the data of the first element in the queue, or %NULL
23710 * if the queue is empty
23715 * g_queue_pop_head_link:
23716 * @queue: a #GQueue
23718 * Removes and returns the first element of the queue.
23720 * Returns: the #GList element at the head of the queue, or %NULL
23721 * if the queue is empty
23727 * @queue: a #GQueue
23728 * @n: the position of the element
23730 * Removes the @n'th element of @queue and returns its data.
23732 * Returns: the element's data, or %NULL if @n is off the end of @queue
23738 * g_queue_pop_nth_link:
23739 * @queue: a #GQueue
23740 * @n: the link's position
23742 * Removes and returns the link at the given position.
23744 * Returns: the @n'th link, or %NULL if @n is off the end of @queue
23750 * g_queue_pop_tail:
23751 * @queue: a #GQueue
23753 * Removes the last element of the queue and returns its data.
23755 * Returns: the data of the last element in the queue, or %NULL
23756 * if the queue is empty
23761 * g_queue_pop_tail_link:
23762 * @queue: a #GQueue
23764 * Removes and returns the last element of the queue.
23766 * Returns: the #GList element at the tail of the queue, or %NULL
23767 * if the queue is empty
23772 * g_queue_push_head:
23773 * @queue: a #GQueue.
23774 * @data: the data for the new element.
23776 * Adds a new element at the head of the queue.
23781 * g_queue_push_head_link:
23782 * @queue: a #GQueue
23783 * @link_: a single #GList element, not a list with more than one element
23785 * Adds a new element at the head of the queue.
23790 * g_queue_push_nth:
23791 * @queue: a #GQueue
23792 * @data: the data for the new element
23793 * @n: the position to insert the new element. If @n is negative or
23794 * larger than the number of elements in the @queue, the element is
23795 * added to the end of the queue.
23797 * Inserts a new element into @queue at the given position.
23804 * g_queue_push_nth_link:
23805 * @queue: a #GQueue
23806 * @n: the position to insert the link. If this is negative or larger than
23807 * the number of elements in @queue, the link is added to the end of
23809 * @link_: the link to add to @queue
23811 * Inserts @link into @queue at the given position.
23818 * g_queue_push_tail:
23819 * @queue: a #GQueue
23820 * @data: the data for the new element
23822 * Adds a new element at the tail of the queue.
23827 * g_queue_push_tail_link:
23828 * @queue: a #GQueue
23829 * @link_: a single #GList element, not a list with more than one element
23831 * Adds a new element at the tail of the queue.
23837 * @queue: a #GQueue
23838 * @data: the data to remove
23840 * Removes the first element in @queue that contains @data.
23842 * Returns: %TRUE if @data was found and removed from @queue
23848 * g_queue_remove_all:
23849 * @queue: a #GQueue
23850 * @data: the data to remove
23852 * Remove all elements whose data equals @data from @queue.
23854 * Returns: the number of elements removed from @queue
23861 * @queue: a #GQueue
23863 * Reverses the order of the items in @queue.
23871 * @queue: a #GQueue
23872 * @compare_func: the #GCompareDataFunc used to sort @queue. This function
23873 * is passed two elements of the queue and should return 0 if they are
23874 * equal, a negative value if the first comes before the second, and
23875 * a positive value if the second comes before the first.
23876 * @user_data: user data passed to @compare_func
23878 * Sorts @queue using @compare_func.
23886 * @queue: a #GQueue
23887 * @link_: a #GList link that must be part of @queue
23889 * Unlinks @link_ so that it will no longer be part of @queue.
23890 * The link is not freed.
23892 * @link_ must be part of @queue.
23902 * Returns a random #gboolean from @rand_.
23903 * This corresponds to a unbiased coin toss.
23905 * Returns: a random #gboolean
23913 * Copies a #GRand into a new one with the same exact state as before.
23914 * This way you can take a snapshot of the random number generator for
23917 * Returns: the new #GRand
23926 * Returns the next random #gdouble from @rand_ equally distributed over
23927 * the range [0..1).
23929 * Returns: a random number
23934 * g_rand_double_range:
23936 * @begin: lower closed bound of the interval
23937 * @end: upper open bound of the interval
23939 * Returns the next random #gdouble from @rand_ equally distributed over
23940 * the range [@begin..@end).
23942 * Returns: a random number
23950 * Frees the memory allocated for the #GRand.
23958 * Returns the next random #guint32 from @rand_ equally distributed over
23959 * the range [0..2^32-1].
23961 * Returns: a random number
23966 * g_rand_int_range:
23968 * @begin: lower closed bound of the interval
23969 * @end: upper open bound of the interval
23971 * Returns the next random #gint32 from @rand_ equally distributed over
23972 * the range [@begin..@end-1].
23974 * Returns: a random number
23981 * Creates a new random number generator initialized with a seed taken
23982 * either from `/dev/urandom` (if existing) or from the current time
23985 * On Windows, the seed is taken from rand_s().
23987 * Returns: the new #GRand
23992 * g_rand_new_with_seed:
23993 * @seed: a value to initialize the random number generator
23995 * Creates a new random number generator initialized with @seed.
23997 * Returns: the new #GRand
24002 * g_rand_new_with_seed_array:
24003 * @seed: an array of seeds to initialize the random number generator
24004 * @seed_length: an array of seeds to initialize the random number
24007 * Creates a new random number generator initialized with @seed.
24009 * Returns: the new #GRand
24017 * @seed: a value to reinitialize the random number generator
24019 * Sets the seed for the random number generator #GRand to @seed.
24024 * g_rand_set_seed_array:
24026 * @seed: array to initialize with
24027 * @seed_length: length of array
24029 * Initializes the random number generator by an array of longs.
24030 * Array can be of arbitrary size, though only the first 624 values
24031 * are taken. This function is useful if you have many low entropy
24032 * seeds, or if you require more then 32 bits of actual entropy for
24033 * your application.
24040 * g_random_boolean:
24042 * Returns a random #gboolean.
24043 * This corresponds to a unbiased coin toss.
24045 * Returns: a random #gboolean
24052 * Returns a random #gdouble equally distributed over the range [0..1).
24054 * Returns: a random number
24059 * g_random_double_range:
24060 * @begin: lower closed bound of the interval
24061 * @end: upper open bound of the interval
24063 * Returns a random #gdouble equally distributed over the range
24066 * Returns: a random number
24073 * Return a random #guint32 equally distributed over the range
24076 * Returns: a random number
24081 * g_random_int_range:
24082 * @begin: lower closed bound of the interval
24083 * @end: upper open bound of the interval
24085 * Returns a random #gint32 equally distributed over the range
24086 * [@begin..@end-1].
24088 * Returns: a random number
24093 * g_random_set_seed:
24094 * @seed: a value to reinitialize the global random number generator
24096 * Sets the seed for the global random number generator, which is used
24097 * by the g_random_* functions, to @seed.
24103 * @mem: (allow-none): the memory to reallocate
24104 * @n_bytes: new size of the memory in bytes
24106 * Reallocates the memory pointed to by @mem, so that it now has space for
24107 * @n_bytes bytes of memory. It returns the new address of the memory, which may
24108 * have been moved. @mem may be %NULL, in which case it's considered to
24109 * have zero-length. @n_bytes may be 0, in which case %NULL will be returned
24110 * and @mem will be freed unless it is %NULL.
24112 * Returns: the new address of the allocated memory
24118 * @mem: (allow-none): the memory to reallocate
24119 * @n_blocks: the number of blocks to allocate
24120 * @n_block_bytes: the size of each block in bytes
24122 * This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
24123 * but care is taken to detect possible overflow during multiplication.
24126 * Returns: the new address of the allocated memory
24131 * g_rec_mutex_clear:
24132 * @rec_mutex: an initialized #GRecMutex
24134 * Frees the resources allocated to a recursive mutex with
24135 * g_rec_mutex_init().
24137 * This function should not be used with a #GRecMutex that has been
24138 * statically allocated.
24140 * Calling g_rec_mutex_clear() on a locked recursive mutex leads
24141 * to undefined behaviour.
24148 * g_rec_mutex_init:
24149 * @rec_mutex: an uninitialized #GRecMutex
24151 * Initializes a #GRecMutex so that it can be used.
24153 * This function is useful to initialize a recursive mutex
24154 * that has been allocated on the stack, or as part of a larger
24157 * It is not necessary to initialise a recursive mutex that has been
24158 * statically allocated.
24160 * |[<!-- language="C" -->
24168 * b = g_new (Blob, 1);
24169 * g_rec_mutex_init (&b->m);
24172 * Calling g_rec_mutex_init() on an already initialized #GRecMutex
24173 * leads to undefined behaviour.
24175 * To undo the effect of g_rec_mutex_init() when a recursive mutex
24176 * is no longer needed, use g_rec_mutex_clear().
24183 * g_rec_mutex_lock:
24184 * @rec_mutex: a #GRecMutex
24186 * Locks @rec_mutex. If @rec_mutex is already locked by another
24187 * thread, the current thread will block until @rec_mutex is
24188 * unlocked by the other thread. If @rec_mutex is already locked
24189 * by the current thread, the 'lock count' of @rec_mutex is increased.
24190 * The mutex will only become available again when it is unlocked
24191 * as many times as it has been locked.
24198 * g_rec_mutex_trylock:
24199 * @rec_mutex: a #GRecMutex
24201 * Tries to lock @rec_mutex. If @rec_mutex is already locked
24202 * by another thread, it immediately returns %FALSE. Otherwise
24203 * it locks @rec_mutex and returns %TRUE.
24205 * Returns: %TRUE if @rec_mutex could be locked
24211 * g_rec_mutex_unlock:
24212 * @rec_mutex: a #GRecMutex
24214 * Unlocks @rec_mutex. If another thread is blocked in a
24215 * g_rec_mutex_lock() call for @rec_mutex, it will become unblocked
24216 * and can lock @rec_mutex itself.
24218 * Calling g_rec_mutex_unlock() on a recursive mutex that is not
24219 * locked by the current thread leads to undefined behaviour.
24226 * g_regex_check_replacement:
24227 * @replacement: the replacement string
24228 * @has_references: (out) (allow-none): location to store information about
24229 * references in @replacement or %NULL
24230 * @error: location to store error
24232 * Checks whether @replacement is a valid replacement string
24233 * (see g_regex_replace()), i.e. that all escape sequences in
24236 * If @has_references is not %NULL then @replacement is checked
24237 * for pattern references. For instance, replacement text 'foo\n'
24238 * does not contain references and may be evaluated without information
24239 * about actual match, but '\0\1' (whole match followed by first
24240 * subpattern) requires valid #GMatchInfo object.
24242 * Returns: whether @replacement is a valid replacement string
24248 * g_regex_escape_nul:
24249 * @string: the string to escape
24250 * @length: the length of @string
24252 * Escapes the nul characters in @string to "\x00". It can be used
24253 * to compile a regex with embedded nul characters.
24255 * For completeness, @length can be -1 for a nul-terminated string.
24256 * In this case the output string will be of course equal to @string.
24258 * Returns: a newly-allocated escaped string
24264 * g_regex_escape_string:
24265 * @string: (array length=length): the string to escape
24266 * @length: the length of @string, or -1 if @string is nul-terminated
24268 * Escapes the special characters used for regular expressions
24269 * in @string, for instance "a.b*c" becomes "a\.b\*c". This
24270 * function is useful to dynamically generate regular expressions.
24272 * @string can contain nul characters that are replaced with "\0",
24273 * in this case remember to specify the correct length of @string
24276 * Returns: a newly-allocated escaped string
24282 * g_regex_get_capture_count:
24283 * @regex: a #GRegex
24285 * Returns the number of capturing subpatterns in the pattern.
24287 * Returns: the number of capturing subpatterns
24293 * g_regex_get_compile_flags:
24294 * @regex: a #GRegex
24296 * Returns the compile options that @regex was created with.
24298 * Returns: flags from #GRegexCompileFlags
24304 * g_regex_get_has_cr_or_lf:
24305 * @regex: a #GRegex structure
24307 * Checks whether the pattern contains explicit CR or LF references.
24309 * Returns: %TRUE if the pattern contains explicit CR or LF references
24315 * g_regex_get_match_flags:
24316 * @regex: a #GRegex
24318 * Returns the match options that @regex was created with.
24320 * Returns: flags from #GRegexMatchFlags
24326 * g_regex_get_max_backref:
24327 * @regex: a #GRegex
24329 * Returns the number of the highest back reference
24330 * in the pattern, or 0 if the pattern does not contain
24333 * Returns: the number of the highest back reference
24339 * g_regex_get_max_lookbehind:
24340 * @regex: a #GRegex structure
24342 * Gets the number of characters in the longest lookbehind assertion in the
24343 * pattern. This information is useful when doing multi-segment matching using
24344 * the partial matching facilities.
24346 * Returns: the number of characters in the longest lookbehind assertion.
24352 * g_regex_get_pattern:
24353 * @regex: a #GRegex structure
24355 * Gets the pattern string associated with @regex, i.e. a copy of
24356 * the string passed to g_regex_new().
24358 * Returns: the pattern of @regex
24364 * g_regex_get_string_number:
24365 * @regex: #GRegex structure
24366 * @name: name of the subexpression
24368 * Retrieves the number of the subexpression named @name.
24370 * Returns: The number of the subexpression or -1 if @name
24378 * @regex: a #GRegex structure from g_regex_new()
24379 * @string: the string to scan for matches
24380 * @match_options: match options
24381 * @match_info: (out) (allow-none): pointer to location where to store
24382 * the #GMatchInfo, or %NULL if you do not need it
24384 * Scans for a match in string for the pattern in @regex.
24385 * The @match_options are combined with the match options specified
24386 * when the @regex structure was created, letting you have more
24387 * flexibility in reusing #GRegex structures.
24389 * A #GMatchInfo structure, used to get information on the match,
24390 * is stored in @match_info if not %NULL. Note that if @match_info
24391 * is not %NULL then it is created even if the function returns %FALSE,
24392 * i.e. you must free it regardless if regular expression actually matched.
24394 * To retrieve all the non-overlapping matches of the pattern in
24395 * string you can use g_match_info_next().
24397 * |[<!-- language="C" -->
24399 * print_uppercase_words (const gchar *string)
24401 * // Print all uppercase-only words.
24403 * GMatchInfo *match_info;
24405 * regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
24406 * g_regex_match (regex, string, 0, &match_info);
24407 * while (g_match_info_matches (match_info))
24409 * gchar *word = g_match_info_fetch (match_info, 0);
24410 * g_print ("Found: %s\n", word);
24412 * g_match_info_next (match_info, NULL);
24414 * g_match_info_free (match_info);
24415 * g_regex_unref (regex);
24419 * @string is not copied and is used in #GMatchInfo internally. If
24420 * you use any #GMatchInfo method (except g_match_info_free()) after
24421 * freeing or modifying @string then the behaviour is undefined.
24423 * Returns: %TRUE is the string matched, %FALSE otherwise
24429 * g_regex_match_all:
24430 * @regex: a #GRegex structure from g_regex_new()
24431 * @string: the string to scan for matches
24432 * @match_options: match options
24433 * @match_info: (out) (allow-none): pointer to location where to store
24434 * the #GMatchInfo, or %NULL if you do not need it
24436 * Using the standard algorithm for regular expression matching only
24437 * the longest match in the string is retrieved. This function uses
24438 * a different algorithm so it can retrieve all the possible matches.
24439 * For more documentation see g_regex_match_all_full().
24441 * A #GMatchInfo structure, used to get information on the match, is
24442 * stored in @match_info if not %NULL. Note that if @match_info is
24443 * not %NULL then it is created even if the function returns %FALSE,
24444 * i.e. you must free it regardless if regular expression actually
24447 * @string is not copied and is used in #GMatchInfo internally. If
24448 * you use any #GMatchInfo method (except g_match_info_free()) after
24449 * freeing or modifying @string then the behaviour is undefined.
24451 * Returns: %TRUE is the string matched, %FALSE otherwise
24457 * g_regex_match_all_full:
24458 * @regex: a #GRegex structure from g_regex_new()
24459 * @string: (array length=string_len): the string to scan for matches
24460 * @string_len: the length of @string, or -1 if @string is nul-terminated
24461 * @start_position: starting index of the string to match, in bytes
24462 * @match_options: match options
24463 * @match_info: (out) (allow-none): pointer to location where to store
24464 * the #GMatchInfo, or %NULL if you do not need it
24465 * @error: location to store the error occurring, or %NULL to ignore errors
24467 * Using the standard algorithm for regular expression matching only
24468 * the longest match in the string is retrieved, it is not possible
24469 * to obtain all the available matches. For instance matching
24470 * "<a> <b> <c>" against the pattern "<.*>"
24471 * you get "<a> <b> <c>".
24473 * This function uses a different algorithm (called DFA, i.e. deterministic
24474 * finite automaton), so it can retrieve all the possible matches, all
24475 * starting at the same point in the string. For instance matching
24476 * "<a> <b> <c>" against the pattern "<.*>;"
24477 * you would obtain three matches: "<a> <b> <c>",
24478 * "<a> <b>" and "<a>".
24480 * The number of matched strings is retrieved using
24481 * g_match_info_get_match_count(). To obtain the matched strings and
24482 * their position you can use, respectively, g_match_info_fetch() and
24483 * g_match_info_fetch_pos(). Note that the strings are returned in
24484 * reverse order of length; that is, the longest matching string is
24487 * Note that the DFA algorithm is slower than the standard one and it
24488 * is not able to capture substrings, so backreferences do not work.
24490 * Setting @start_position differs from just passing over a shortened
24491 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
24492 * that begins with any kind of lookbehind assertion, such as "\b".
24494 * A #GMatchInfo structure, used to get information on the match, is
24495 * stored in @match_info if not %NULL. Note that if @match_info is
24496 * not %NULL then it is created even if the function returns %FALSE,
24497 * i.e. you must free it regardless if regular expression actually
24500 * @string is not copied and is used in #GMatchInfo internally. If
24501 * you use any #GMatchInfo method (except g_match_info_free()) after
24502 * freeing or modifying @string then the behaviour is undefined.
24504 * Returns: %TRUE is the string matched, %FALSE otherwise
24510 * g_regex_match_full:
24511 * @regex: a #GRegex structure from g_regex_new()
24512 * @string: (array length=string_len): the string to scan for matches
24513 * @string_len: the length of @string, or -1 if @string is nul-terminated
24514 * @start_position: starting index of the string to match, in bytes
24515 * @match_options: match options
24516 * @match_info: (out) (allow-none): pointer to location where to store
24517 * the #GMatchInfo, or %NULL if you do not need it
24518 * @error: location to store the error occurring, or %NULL to ignore errors
24520 * Scans for a match in string for the pattern in @regex.
24521 * The @match_options are combined with the match options specified
24522 * when the @regex structure was created, letting you have more
24523 * flexibility in reusing #GRegex structures.
24525 * Setting @start_position differs from just passing over a shortened
24526 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
24527 * that begins with any kind of lookbehind assertion, such as "\b".
24529 * A #GMatchInfo structure, used to get information on the match, is
24530 * stored in @match_info if not %NULL. Note that if @match_info is
24531 * not %NULL then it is created even if the function returns %FALSE,
24532 * i.e. you must free it regardless if regular expression actually
24535 * @string is not copied and is used in #GMatchInfo internally. If
24536 * you use any #GMatchInfo method (except g_match_info_free()) after
24537 * freeing or modifying @string then the behaviour is undefined.
24539 * To retrieve all the non-overlapping matches of the pattern in
24540 * string you can use g_match_info_next().
24542 * |[<!-- language="C" -->
24544 * print_uppercase_words (const gchar *string)
24546 * // Print all uppercase-only words.
24548 * GMatchInfo *match_info;
24549 * GError *error = NULL;
24551 * regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
24552 * g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error);
24553 * while (g_match_info_matches (match_info))
24555 * gchar *word = g_match_info_fetch (match_info, 0);
24556 * g_print ("Found: %s\n", word);
24558 * g_match_info_next (match_info, &error);
24560 * g_match_info_free (match_info);
24561 * g_regex_unref (regex);
24562 * if (error != NULL)
24564 * g_printerr ("Error while matching: %s\n", error->message);
24565 * g_error_free (error);
24570 * Returns: %TRUE is the string matched, %FALSE otherwise
24576 * g_regex_match_simple:
24577 * @pattern: the regular expression
24578 * @string: the string to scan for matches
24579 * @compile_options: compile options for the regular expression, or 0
24580 * @match_options: match options, or 0
24582 * Scans for a match in @string for @pattern.
24584 * This function is equivalent to g_regex_match() but it does not
24585 * require to compile the pattern with g_regex_new(), avoiding some
24586 * lines of code when you need just to do a match without extracting
24587 * substrings, capture counts, and so on.
24589 * If this function is to be called on the same @pattern more than
24590 * once, it's more efficient to compile the pattern once with
24591 * g_regex_new() and then use g_regex_match().
24593 * Returns: %TRUE if the string matched, %FALSE otherwise
24600 * @pattern: the regular expression
24601 * @compile_options: compile options for the regular expression, or 0
24602 * @match_options: match options for the regular expression, or 0
24603 * @error: return location for a #GError
24605 * Compiles the regular expression to an internal form, and does
24606 * the initial setup of the #GRegex structure.
24608 * Returns: (nullable): a #GRegex structure or %NULL if an error occured. Call
24609 * g_regex_unref() when you are done with it
24616 * @regex: a #GRegex
24618 * Increases reference count of @regex by 1.
24627 * @regex: a #GRegex structure
24628 * @string: (array length=string_len): the string to perform matches against
24629 * @string_len: the length of @string, or -1 if @string is nul-terminated
24630 * @start_position: starting index of the string to match, in bytes
24631 * @replacement: text to replace each match with
24632 * @match_options: options for the match
24633 * @error: location to store the error occurring, or %NULL to ignore errors
24635 * Replaces all occurrences of the pattern in @regex with the
24636 * replacement text. Backreferences of the form '\number' or
24637 * '\g<number>' in the replacement text are interpolated by the
24638 * number-th captured subexpression of the match, '\g<name>' refers
24639 * to the captured subexpression with the given name. '\0' refers
24640 * to the complete match, but '\0' followed by a number is the octal
24641 * representation of a character. To include a literal '\' in the
24642 * replacement, write '\\'.
24644 * There are also escapes that changes the case of the following text:
24646 * - \l: Convert to lower case the next character
24647 * - \u: Convert to upper case the next character
24648 * - \L: Convert to lower case till \E
24649 * - \U: Convert to upper case till \E
24650 * - \E: End case modification
24652 * If you do not need to use backreferences use g_regex_replace_literal().
24654 * The @replacement string must be UTF-8 encoded even if #G_REGEX_RAW was
24655 * passed to g_regex_new(). If you want to use not UTF-8 encoded stings
24656 * you can use g_regex_replace_literal().
24658 * Setting @start_position differs from just passing over a shortened
24659 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that
24660 * begins with any kind of lookbehind assertion, such as "\b".
24662 * Returns: a newly allocated string containing the replacements
24668 * g_regex_replace_eval:
24669 * @regex: a #GRegex structure from g_regex_new()
24670 * @string: (array length=string_len): string to perform matches against
24671 * @string_len: the length of @string, or -1 if @string is nul-terminated
24672 * @start_position: starting index of the string to match, in bytes
24673 * @match_options: options for the match
24674 * @eval: a function to call for each match
24675 * @user_data: user data to pass to the function
24676 * @error: location to store the error occurring, or %NULL to ignore errors
24678 * Replaces occurrences of the pattern in regex with the output of
24679 * @eval for that occurrence.
24681 * Setting @start_position differs from just passing over a shortened
24682 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
24683 * that begins with any kind of lookbehind assertion, such as "\b".
24685 * The following example uses g_regex_replace_eval() to replace multiple
24687 * |[<!-- language="C" -->
24689 * eval_cb (const GMatchInfo *info,
24696 * match = g_match_info_fetch (info, 0);
24697 * r = g_hash_table_lookup ((GHashTable *)data, match);
24698 * g_string_append (res, r);
24710 * h = g_hash_table_new (g_str_hash, g_str_equal);
24712 * g_hash_table_insert (h, "1", "ONE");
24713 * g_hash_table_insert (h, "2", "TWO");
24714 * g_hash_table_insert (h, "3", "THREE");
24715 * g_hash_table_insert (h, "4", "FOUR");
24717 * reg = g_regex_new ("1|2|3|4", 0, 0, NULL);
24718 * res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL);
24719 * g_hash_table_destroy (h);
24724 * Returns: a newly allocated string containing the replacements
24730 * g_regex_replace_literal:
24731 * @regex: a #GRegex structure
24732 * @string: (array length=string_len): the string to perform matches against
24733 * @string_len: the length of @string, or -1 if @string is nul-terminated
24734 * @start_position: starting index of the string to match, in bytes
24735 * @replacement: text to replace each match with
24736 * @match_options: options for the match
24737 * @error: location to store the error occurring, or %NULL to ignore errors
24739 * Replaces all occurrences of the pattern in @regex with the
24740 * replacement text. @replacement is replaced literally, to
24741 * include backreferences use g_regex_replace().
24743 * Setting @start_position differs from just passing over a
24744 * shortened string and setting #G_REGEX_MATCH_NOTBOL in the
24745 * case of a pattern that begins with any kind of lookbehind
24746 * assertion, such as "\b".
24748 * Returns: a newly allocated string containing the replacements
24755 * @regex: a #GRegex structure
24756 * @string: the string to split with the pattern
24757 * @match_options: match time option flags
24759 * Breaks the string on the pattern, and returns an array of the tokens.
24760 * If the pattern contains capturing parentheses, then the text for each
24761 * of the substrings will also be returned. If the pattern does not match
24762 * anywhere in the string, then the whole string is returned as the first
24765 * As a special case, the result of splitting the empty string "" is an
24766 * empty vector, not a vector containing a single string. The reason for
24767 * this special case is that being able to represent a empty vector is
24768 * typically more useful than consistent handling of empty elements. If
24769 * you do need to represent empty elements, you'll need to check for the
24770 * empty string before calling this function.
24772 * A pattern that can match empty strings splits @string into separate
24773 * characters wherever it matches the empty string between characters.
24774 * For example splitting "ab c" using as a separator "\s*", you will get
24775 * "a", "b" and "c".
24777 * Returns: (transfer full): a %NULL-terminated gchar ** array. Free
24778 * it using g_strfreev()
24784 * g_regex_split_full:
24785 * @regex: a #GRegex structure
24786 * @string: (array length=string_len): the string to split with the pattern
24787 * @string_len: the length of @string, or -1 if @string is nul-terminated
24788 * @start_position: starting index of the string to match, in bytes
24789 * @match_options: match time option flags
24790 * @max_tokens: the maximum number of tokens to split @string into.
24791 * If this is less than 1, the string is split completely
24792 * @error: return location for a #GError
24794 * Breaks the string on the pattern, and returns an array of the tokens.
24795 * If the pattern contains capturing parentheses, then the text for each
24796 * of the substrings will also be returned. If the pattern does not match
24797 * anywhere in the string, then the whole string is returned as the first
24800 * As a special case, the result of splitting the empty string "" is an
24801 * empty vector, not a vector containing a single string. The reason for
24802 * this special case is that being able to represent a empty vector is
24803 * typically more useful than consistent handling of empty elements. If
24804 * you do need to represent empty elements, you'll need to check for the
24805 * empty string before calling this function.
24807 * A pattern that can match empty strings splits @string into separate
24808 * characters wherever it matches the empty string between characters.
24809 * For example splitting "ab c" using as a separator "\s*", you will get
24810 * "a", "b" and "c".
24812 * Setting @start_position differs from just passing over a shortened
24813 * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
24814 * that begins with any kind of lookbehind assertion, such as "\b".
24816 * Returns: (transfer full): a %NULL-terminated gchar ** array. Free
24817 * it using g_strfreev()
24823 * g_regex_split_simple:
24824 * @pattern: the regular expression
24825 * @string: the string to scan for matches
24826 * @compile_options: compile options for the regular expression, or 0
24827 * @match_options: match options, or 0
24829 * Breaks the string on the pattern, and returns an array of
24830 * the tokens. If the pattern contains capturing parentheses,
24831 * then the text for each of the substrings will also be returned.
24832 * If the pattern does not match anywhere in the string, then the
24833 * whole string is returned as the first token.
24835 * This function is equivalent to g_regex_split() but it does
24836 * not require to compile the pattern with g_regex_new(), avoiding
24837 * some lines of code when you need just to do a split without
24838 * extracting substrings, capture counts, and so on.
24840 * If this function is to be called on the same @pattern more than
24841 * once, it's more efficient to compile the pattern once with
24842 * g_regex_new() and then use g_regex_split().
24844 * As a special case, the result of splitting the empty string ""
24845 * is an empty vector, not a vector containing a single string.
24846 * The reason for this special case is that being able to represent
24847 * a empty vector is typically more useful than consistent handling
24848 * of empty elements. If you do need to represent empty elements,
24849 * you'll need to check for the empty string before calling this
24852 * A pattern that can match empty strings splits @string into
24853 * separate characters wherever it matches the empty string between
24854 * characters. For example splitting "ab c" using as a separator
24855 * "\s*", you will get "a", "b" and "c".
24857 * Returns: (transfer full): a %NULL-terminated array of strings. Free
24858 * it using g_strfreev()
24865 * @regex: a #GRegex
24867 * Decreases reference count of @regex by 1. When reference count drops
24868 * to zero, it frees all the memory associated with the regex structure.
24875 * g_reload_user_special_dirs_cache:
24877 * Resets the cache used for g_get_user_special_dir(), so
24878 * that the latest on-disk version is used. Call this only
24879 * if you just changed the data on disk yourself.
24881 * Due to threadsafety issues this may cause leaking of strings
24882 * that were previously returned from g_get_user_special_dir()
24883 * that can't be freed. We ensure to only leak the data for
24884 * the directories that actually changed value though.
24892 * @filename: (type filename): a pathname in the GLib file name encoding
24893 * (UTF-8 on Windows)
24895 * A wrapper for the POSIX remove() function. The remove() function
24896 * deletes a name from the filesystem.
24898 * See your C library manual for more details about how remove() works
24899 * on your system. On Unix, remove() removes also directories, as it
24900 * calls unlink() for files and rmdir() for directories. On Windows,
24901 * although remove() in the C library only works for files, this
24902 * function tries first remove() and then if that fails rmdir(), and
24903 * thus works for both files and directories. Note however, that on
24904 * Windows, it is in general not possible to remove a file that is
24905 * open to some process, or mapped into memory.
24907 * If this function fails on Windows you can't infer too much from the
24908 * errno value. rmdir() is tried regardless of what caused remove() to
24909 * fail. Any errno value set by remove() will be overwritten by that
24912 * Returns: 0 if the file was successfully removed, -1 if an error
24920 * @oldfilename: (type filename): a pathname in the GLib file name encoding
24921 * (UTF-8 on Windows)
24922 * @newfilename: (type filename): a pathname in the GLib file name encoding
24924 * A wrapper for the POSIX rename() function. The rename() function
24925 * renames a file, moving it between directories if required.
24927 * See your C library manual for more details about how rename() works
24928 * on your system. It is not possible in general on Windows to rename
24929 * a file that is open to some process.
24931 * Returns: 0 if the renaming succeeded, -1 if an error occurred
24937 * g_return_if_fail_warning: (skip)
24938 * @log_domain: (nullable):
24939 * @pretty_function:
24940 * @expression: (nullable):
24946 * @filename: (type filename): a pathname in the GLib file name encoding
24947 * (UTF-8 on Windows)
24949 * A wrapper for the POSIX rmdir() function. The rmdir() function
24950 * deletes a directory from the filesystem.
24952 * See your C library manual for more details about how rmdir() works
24955 * Returns: 0 if the directory was successfully removed, -1 if an error
24963 * @rw_lock: an initialized #GRWLock
24965 * Frees the resources allocated to a lock with g_rw_lock_init().
24967 * This function should not be used with a #GRWLock that has been
24968 * statically allocated.
24970 * Calling g_rw_lock_clear() when any thread holds the lock
24971 * leads to undefined behaviour.
24979 * @rw_lock: an uninitialized #GRWLock
24981 * Initializes a #GRWLock so that it can be used.
24983 * This function is useful to initialize a lock that has been
24984 * allocated on the stack, or as part of a larger structure. It is not
24985 * necessary to initialise a reader-writer lock that has been statically
24988 * |[<!-- language="C" -->
24996 * b = g_new (Blob, 1);
24997 * g_rw_lock_init (&b->l);
25000 * To undo the effect of g_rw_lock_init() when a lock is no longer
25001 * needed, use g_rw_lock_clear().
25003 * Calling g_rw_lock_init() on an already initialized #GRWLock leads
25004 * to undefined behaviour.
25011 * g_rw_lock_reader_lock:
25012 * @rw_lock: a #GRWLock
25014 * Obtain a read lock on @rw_lock. If another thread currently holds
25015 * the write lock on @rw_lock or blocks waiting for it, the current
25016 * thread will block. Read locks can be taken recursively.
25018 * It is implementation-defined how many threads are allowed to
25019 * hold read locks on the same lock simultaneously.
25026 * g_rw_lock_reader_trylock:
25027 * @rw_lock: a #GRWLock
25029 * Tries to obtain a read lock on @rw_lock and returns %TRUE if
25030 * the read lock was successfully obtained. Otherwise it
25033 * Returns: %TRUE if @rw_lock could be locked
25039 * g_rw_lock_reader_unlock:
25040 * @rw_lock: a #GRWLock
25042 * Release a read lock on @rw_lock.
25044 * Calling g_rw_lock_reader_unlock() on a lock that is not held
25045 * by the current thread leads to undefined behaviour.
25052 * g_rw_lock_writer_lock:
25053 * @rw_lock: a #GRWLock
25055 * Obtain a write lock on @rw_lock. If any thread already holds
25056 * a read or write lock on @rw_lock, the current thread will block
25057 * until all other threads have dropped their locks on @rw_lock.
25064 * g_rw_lock_writer_trylock:
25065 * @rw_lock: a #GRWLock
25067 * Tries to obtain a write lock on @rw_lock. If any other thread holds
25068 * a read or write lock on @rw_lock, it immediately returns %FALSE.
25069 * Otherwise it locks @rw_lock and returns %TRUE.
25071 * Returns: %TRUE if @rw_lock could be locked
25077 * g_rw_lock_writer_unlock:
25078 * @rw_lock: a #GRWLock
25080 * Release a write lock on @rw_lock.
25082 * Calling g_rw_lock_writer_unlock() on a lock that is not held
25083 * by the current thread leads to undefined behaviour.
25090 * g_scanner_add_symbol:
25091 * @scanner: a #GScanner
25092 * @symbol: the symbol to add
25093 * @value: the value of the symbol
25095 * Adds a symbol to the default scope.
25097 * Deprecated: 2.2: Use g_scanner_scope_add_symbol() instead.
25102 * g_scanner_cur_line:
25103 * @scanner: a #GScanner
25105 * Returns the current line in the input stream (counting
25106 * from 1). This is the line of the last token parsed via
25107 * g_scanner_get_next_token().
25109 * Returns: the current line
25114 * g_scanner_cur_position:
25115 * @scanner: a #GScanner
25117 * Returns the current position in the current line (counting
25118 * from 0). This is the position of the last token parsed via
25119 * g_scanner_get_next_token().
25121 * Returns: the current position on the line
25126 * g_scanner_cur_token:
25127 * @scanner: a #GScanner
25129 * Gets the current token type. This is simply the @token
25130 * field in the #GScanner structure.
25132 * Returns: the current token type
25137 * g_scanner_cur_value:
25138 * @scanner: a #GScanner
25140 * Gets the current token value. This is simply the @value
25141 * field in the #GScanner structure.
25143 * Returns: the current token value
25148 * g_scanner_destroy:
25149 * @scanner: a #GScanner
25151 * Frees all memory used by the #GScanner.
25157 * @scanner: a #GScanner
25159 * Returns %TRUE if the scanner has reached the end of
25160 * the file or text buffer.
25162 * Returns: %TRUE if the scanner has reached the end of
25163 * the file or text buffer
25169 * @scanner: a #GScanner
25170 * @format: the message format. See the printf() documentation
25171 * @...: the parameters to insert into the format string
25173 * Outputs an error message, via the #GScanner message handler.
25178 * g_scanner_foreach_symbol:
25179 * @scanner: a #GScanner
25180 * @func: the function to call with each symbol
25181 * @data: data to pass to the function
25183 * Calls a function for each symbol in the default scope.
25185 * Deprecated: 2.2: Use g_scanner_scope_foreach_symbol() instead.
25190 * g_scanner_freeze_symbol_table:
25191 * @scanner: a #GScanner
25193 * There is no reason to use this macro, since it does nothing.
25195 * Deprecated: 2.2: This macro does nothing.
25200 * g_scanner_get_next_token:
25201 * @scanner: a #GScanner
25203 * Parses the next token just like g_scanner_peek_next_token()
25204 * and also removes it from the input stream. The token data is
25205 * placed in the @token, @value, @line, and @position fields of
25206 * the #GScanner structure.
25208 * Returns: the type of the token
25213 * g_scanner_input_file:
25214 * @scanner: a #GScanner
25215 * @input_fd: a file descriptor
25217 * Prepares to scan a file.
25222 * g_scanner_input_text:
25223 * @scanner: a #GScanner
25224 * @text: the text buffer to scan
25225 * @text_len: the length of the text buffer
25227 * Prepares to scan a text buffer.
25232 * g_scanner_lookup_symbol:
25233 * @scanner: a #GScanner
25234 * @symbol: the symbol to look up
25236 * Looks up a symbol in the current scope and return its value.
25237 * If the symbol is not bound in the current scope, %NULL is
25240 * Returns: the value of @symbol in the current scope, or %NULL
25241 * if @symbol is not bound in the current scope
25247 * @config_templ: the initial scanner settings
25249 * Creates a new #GScanner.
25251 * The @config_templ structure specifies the initial settings
25252 * of the scanner, which are copied into the #GScanner
25253 * @config field. If you pass %NULL then the default settings
25256 * Returns: the new #GScanner
25261 * g_scanner_peek_next_token:
25262 * @scanner: a #GScanner
25264 * Parses the next token, without removing it from the input stream.
25265 * The token data is placed in the @next_token, @next_value, @next_line,
25266 * and @next_position fields of the #GScanner structure.
25268 * Note that, while the token is not removed from the input stream
25269 * (i.e. the next call to g_scanner_get_next_token() will return the
25270 * same token), it will not be reevaluated. This can lead to surprising
25271 * results when changing scope or the scanner configuration after peeking
25272 * the next token. Getting the next token after switching the scope or
25273 * configuration will return whatever was peeked before, regardless of
25274 * any symbols that may have been added or removed in the new scope.
25276 * Returns: the type of the token
25281 * g_scanner_remove_symbol:
25282 * @scanner: a #GScanner
25283 * @symbol: the symbol to remove
25285 * Removes a symbol from the default scope.
25287 * Deprecated: 2.2: Use g_scanner_scope_remove_symbol() instead.
25292 * g_scanner_scope_add_symbol:
25293 * @scanner: a #GScanner
25294 * @scope_id: the scope id
25295 * @symbol: the symbol to add
25296 * @value: the value of the symbol
25298 * Adds a symbol to the given scope.
25303 * g_scanner_scope_foreach_symbol:
25304 * @scanner: a #GScanner
25305 * @scope_id: the scope id
25306 * @func: the function to call for each symbol/value pair
25307 * @user_data: user data to pass to the function
25309 * Calls the given function for each of the symbol/value pairs
25310 * in the given scope of the #GScanner. The function is passed
25311 * the symbol and value of each pair, and the given @user_data
25317 * g_scanner_scope_lookup_symbol:
25318 * @scanner: a #GScanner
25319 * @scope_id: the scope id
25320 * @symbol: the symbol to look up
25322 * Looks up a symbol in a scope and return its value. If the
25323 * symbol is not bound in the scope, %NULL is returned.
25325 * Returns: the value of @symbol in the given scope, or %NULL
25326 * if @symbol is not bound in the given scope.
25331 * g_scanner_scope_remove_symbol:
25332 * @scanner: a #GScanner
25333 * @scope_id: the scope id
25334 * @symbol: the symbol to remove
25336 * Removes a symbol from a scope.
25341 * g_scanner_set_scope:
25342 * @scanner: a #GScanner
25343 * @scope_id: the new scope id
25345 * Sets the current scope.
25347 * Returns: the old scope id
25352 * g_scanner_sync_file_offset:
25353 * @scanner: a #GScanner
25355 * Rewinds the filedescriptor to the current buffer position
25356 * and blows the file read ahead buffer. This is useful for
25357 * third party uses of the scanners filedescriptor, which hooks
25358 * onto the current scanning position.
25363 * g_scanner_thaw_symbol_table:
25364 * @scanner: a #GScanner
25366 * There is no reason to use this macro, since it does nothing.
25368 * Deprecated: 2.2: This macro does nothing.
25373 * g_scanner_unexp_token:
25374 * @scanner: a #GScanner
25375 * @expected_token: the expected token
25376 * @identifier_spec: a string describing how the scanner's user
25377 * refers to identifiers (%NULL defaults to "identifier").
25378 * This is used if @expected_token is %G_TOKEN_IDENTIFIER or
25379 * %G_TOKEN_IDENTIFIER_NULL.
25380 * @symbol_spec: a string describing how the scanner's user refers
25381 * to symbols (%NULL defaults to "symbol"). This is used if
25382 * @expected_token is %G_TOKEN_SYMBOL or any token value greater
25383 * than %G_TOKEN_LAST.
25384 * @symbol_name: the name of the symbol, if the scanner's current
25385 * token is a symbol.
25386 * @message: a message string to output at the end of the
25387 * warning/error, or %NULL.
25388 * @is_error: if %TRUE it is output as an error. If %FALSE it is
25389 * output as a warning.
25391 * Outputs a message through the scanner's msg_handler,
25392 * resulting from an unexpected token in the input stream.
25393 * Note that you should not call g_scanner_peek_next_token()
25394 * followed by g_scanner_unexp_token() without an intermediate
25395 * call to g_scanner_get_next_token(), as g_scanner_unexp_token()
25396 * evaluates the scanner's current token (not the peeked token)
25397 * to construct part of the message.
25403 * @scanner: a #GScanner
25404 * @format: the message format. See the printf() documentation
25405 * @...: the parameters to insert into the format string
25407 * Outputs a warning message, via the #GScanner message handler.
25412 * g_sequence_append:
25413 * @seq: a #GSequence
25414 * @data: the data for the new item
25416 * Adds a new item to the end of @seq.
25418 * Returns: an iterator pointing to the new item
25424 * g_sequence_foreach:
25425 * @seq: a #GSequence
25426 * @func: the function to call for each item in @seq
25427 * @user_data: user data passed to @func
25429 * Calls @func for each item in the sequence passing @user_data
25437 * g_sequence_foreach_range:
25438 * @begin: a #GSequenceIter
25439 * @end: a #GSequenceIter
25441 * @user_data: user data passed to @func
25443 * Calls @func for each item in the range (@begin, @end) passing
25444 * @user_data to the function.
25452 * @seq: a #GSequence
25454 * Frees the memory allocated for @seq. If @seq has a data destroy
25455 * function associated with it, that function is called on all items
25464 * @iter: a #GSequenceIter
25466 * Returns the data that @iter points to.
25468 * Returns: the data that @iter points to
25474 * g_sequence_get_begin_iter:
25475 * @seq: a #GSequence
25477 * Returns the begin iterator for @seq.
25479 * Returns: the begin iterator for @seq.
25485 * g_sequence_get_end_iter:
25486 * @seq: a #GSequence
25488 * Returns the end iterator for @seg
25490 * Returns: the end iterator for @seq
25496 * g_sequence_get_iter_at_pos:
25497 * @seq: a #GSequence
25498 * @pos: a position in @seq, or -1 for the end
25500 * Returns the iterator at position @pos. If @pos is negative or larger
25501 * than the number of items in @seq, the end iterator is returned.
25503 * Returns: The #GSequenceIter at position @pos
25509 * g_sequence_get_length:
25510 * @seq: a #GSequence
25512 * Returns the length of @seq. Note that this method is O(h) where `h' is the
25513 * height of the tree. It is thus more efficient to use g_sequence_is_empty()
25514 * when comparing the length to zero.
25516 * Returns: the length of @seq
25522 * g_sequence_insert_before:
25523 * @iter: a #GSequenceIter
25524 * @data: the data for the new item
25526 * Inserts a new item just before the item pointed to by @iter.
25528 * Returns: an iterator pointing to the new item
25534 * g_sequence_insert_sorted:
25535 * @seq: a #GSequence
25536 * @data: the data to insert
25537 * @cmp_func: the function used to compare items in the sequence
25538 * @cmp_data: user data passed to @cmp_func.
25540 * Inserts @data into @sequence using @func to determine the new
25541 * position. The sequence must already be sorted according to @cmp_func;
25542 * otherwise the new position of @data is undefined.
25544 * @cmp_func is called with two items of the @seq and @user_data.
25545 * It should return 0 if the items are equal, a negative value
25546 * if the first item comes before the second, and a positive value
25547 * if the second item comes before the first.
25549 * Returns: a #GSequenceIter pointing to the new item.
25555 * g_sequence_insert_sorted_iter:
25556 * @seq: a #GSequence
25557 * @data: data for the new item
25558 * @iter_cmp: the function used to compare iterators in the sequence
25559 * @cmp_data: user data passed to @cmp_func
25561 * Like g_sequence_insert_sorted(), but uses
25562 * a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
25563 * the compare function.
25565 * @iter_cmp is called with two iterators pointing into @seq.
25566 * It should return 0 if the iterators are equal, a negative
25567 * value if the first iterator comes before the second, and a
25568 * positive value if the second iterator comes before the first.
25570 * It is called with two iterators pointing into @seq. It should
25571 * return 0 if the iterators are equal, a negative value if the
25572 * first iterator comes before the second, and a positive value
25573 * if the second iterator comes before the first.
25575 * Returns: a #GSequenceIter pointing to the new item
25581 * g_sequence_is_empty:
25582 * @seq: a #GSequence
25584 * Returns %TRUE if the sequence contains zero items.
25586 * This function is functionally identical to checking the result of
25587 * g_sequence_get_length() being equal to zero. However this function is
25588 * implemented in O(1) running time.
25590 * Returns: %TRUE if the sequence is empty, otherwise %FALSE.
25596 * g_sequence_iter_compare:
25597 * @a: a #GSequenceIter
25598 * @b: a #GSequenceIter
25600 * Returns a negative number if @a comes before @b, 0 if they are equal,
25601 * and a positive number if @a comes after @b.
25603 * The @a and @b iterators must point into the same sequence.
25605 * Returns: a negative number if @a comes before @b, 0 if they are
25606 * equal, and a positive number if @a comes after @b
25612 * g_sequence_iter_get_position:
25613 * @iter: a #GSequenceIter
25615 * Returns the position of @iter
25617 * Returns: the position of @iter
25623 * g_sequence_iter_get_sequence:
25624 * @iter: a #GSequenceIter
25626 * Returns the #GSequence that @iter points into.
25628 * Returns: the #GSequence that @iter points into
25634 * g_sequence_iter_is_begin:
25635 * @iter: a #GSequenceIter
25637 * Returns whether @iter is the begin iterator
25639 * Returns: whether @iter is the begin iterator
25645 * g_sequence_iter_is_end:
25646 * @iter: a #GSequenceIter
25648 * Returns whether @iter is the end iterator
25650 * Returns: Whether @iter is the end iterator
25656 * g_sequence_iter_move:
25657 * @iter: a #GSequenceIter
25658 * @delta: A positive or negative number indicating how many positions away
25659 * from @iter the returned #GSequenceIter will be
25661 * Returns the #GSequenceIter which is @delta positions away from @iter.
25662 * If @iter is closer than -@delta positions to the beginning of the sequence,
25663 * the begin iterator is returned. If @iter is closer than @delta positions
25664 * to the end of the sequence, the end iterator is returned.
25666 * Returns: a #GSequenceIter which is @delta positions away from @iter
25672 * g_sequence_iter_next:
25673 * @iter: a #GSequenceIter
25675 * Returns an iterator pointing to the next position after @iter.
25676 * If @iter is the end iterator, the end iterator is returned.
25678 * Returns: a #GSequenceIter pointing to the next position after @iter
25684 * g_sequence_iter_prev:
25685 * @iter: a #GSequenceIter
25687 * Returns an iterator pointing to the previous position before @iter.
25688 * If @iter is the begin iterator, the begin iterator is returned.
25690 * Returns: a #GSequenceIter pointing to the previous position
25697 * g_sequence_lookup:
25698 * @seq: a #GSequence
25699 * @data: data to lookup
25700 * @cmp_func: the function used to compare items in the sequence
25701 * @cmp_data: user data passed to @cmp_func
25703 * Returns an iterator pointing to the position of the first item found
25704 * equal to @data according to @cmp_func and @cmp_data. If more than one
25705 * item is equal, it is not guaranteed that it is the first which is
25706 * returned. In that case, you can use g_sequence_iter_next() and
25707 * g_sequence_iter_prev() to get others.
25709 * @cmp_func is called with two items of the @seq and @user_data.
25710 * It should return 0 if the items are equal, a negative value if
25711 * the first item comes before the second, and a positive value if
25712 * the second item comes before the first.
25714 * This function will fail if the data contained in the sequence is
25715 * unsorted. Use g_sequence_insert_sorted() or
25716 * g_sequence_insert_sorted_iter() to add data to your sequence or, if
25717 * you want to add a large amount of data, call g_sequence_sort() after
25718 * doing unsorted insertions.
25720 * Returns: an #GSequenceIter pointing to the position of the
25721 * first item found equal to @data according to @cmp_func and
25722 * @cmp_data, or %NULL if no such item exists
25728 * g_sequence_lookup_iter:
25729 * @seq: a #GSequence
25730 * @data: data to lookup
25731 * @iter_cmp: the function used to compare iterators in the sequence
25732 * @cmp_data: user data passed to @iter_cmp
25734 * Like g_sequence_lookup(), but uses a #GSequenceIterCompareFunc
25735 * instead of a #GCompareDataFunc as the compare function.
25737 * @iter_cmp is called with two iterators pointing into @seq.
25738 * It should return 0 if the iterators are equal, a negative value
25739 * if the first iterator comes before the second, and a positive
25740 * value if the second iterator comes before the first.
25742 * This function will fail if the data contained in the sequence is
25743 * unsorted. Use g_sequence_insert_sorted() or
25744 * g_sequence_insert_sorted_iter() to add data to your sequence or, if
25745 * you want to add a large amount of data, call g_sequence_sort() after
25746 * doing unsorted insertions.
25748 * Returns: an #GSequenceIter pointing to the position of
25749 * the first item found equal to @data according to @cmp_func
25750 * and @cmp_data, or %NULL if no such item exists
25757 * @src: a #GSequenceIter pointing to the item to move
25758 * @dest: a #GSequenceIter pointing to the position to which
25759 * the item is moved
25761 * Moves the item pointed to by @src to the position indicated by @dest.
25762 * After calling this function @dest will point to the position immediately
25763 * after @src. It is allowed for @src and @dest to point into different
25771 * g_sequence_move_range:
25772 * @dest: a #GSequenceIter
25773 * @begin: a #GSequenceIter
25774 * @end: a #GSequenceIter
25776 * Inserts the (@begin, @end) range at the destination pointed to by ptr.
25777 * The @begin and @end iters must point into the same sequence. It is
25778 * allowed for @dest to point to a different sequence than the one pointed
25779 * into by @begin and @end.
25781 * If @dest is NULL, the range indicated by @begin and @end is
25782 * removed from the sequence. If @dest iter points to a place within
25783 * the (@begin, @end) range, the range does not move.
25791 * @data_destroy: (allow-none): a #GDestroyNotify function, or %NULL
25793 * Creates a new GSequence. The @data_destroy function, if non-%NULL will
25794 * be called on all items when the sequence is destroyed and on items that
25795 * are removed from the sequence.
25797 * Returns: a new #GSequence
25803 * g_sequence_prepend:
25804 * @seq: a #GSequence
25805 * @data: the data for the new item
25807 * Adds a new item to the front of @seq
25809 * Returns: an iterator pointing to the new item
25815 * g_sequence_range_get_midpoint:
25816 * @begin: a #GSequenceIter
25817 * @end: a #GSequenceIter
25819 * Finds an iterator somewhere in the range (@begin, @end). This
25820 * iterator will be close to the middle of the range, but is not
25821 * guaranteed to be exactly in the middle.
25823 * The @begin and @end iterators must both point to the same sequence
25824 * and @begin must come before or be equal to @end in the sequence.
25826 * Returns: a #GSequenceIter pointing somewhere in the
25827 * (@begin, @end) range
25833 * g_sequence_remove:
25834 * @iter: a #GSequenceIter
25836 * Removes the item pointed to by @iter. It is an error to pass the
25837 * end iterator to this function.
25839 * If the sequence has a data destroy function associated with it, this
25840 * function is called on the data for the removed item.
25847 * g_sequence_remove_range:
25848 * @begin: a #GSequenceIter
25849 * @end: a #GSequenceIter
25851 * Removes all items in the (@begin, @end) range.
25853 * If the sequence has a data destroy function associated with it, this
25854 * function is called on the data for the removed items.
25861 * g_sequence_search:
25862 * @seq: a #GSequence
25863 * @data: data for the new item
25864 * @cmp_func: the function used to compare items in the sequence
25865 * @cmp_data: user data passed to @cmp_func
25867 * Returns an iterator pointing to the position where @data would
25868 * be inserted according to @cmp_func and @cmp_data.
25870 * @cmp_func is called with two items of the @seq and @user_data.
25871 * It should return 0 if the items are equal, a negative value if
25872 * the first item comes before the second, and a positive value if
25873 * the second item comes before the first.
25875 * If you are simply searching for an existing element of the sequence,
25876 * consider using g_sequence_lookup().
25878 * This function will fail if the data contained in the sequence is
25879 * unsorted. Use g_sequence_insert_sorted() or
25880 * g_sequence_insert_sorted_iter() to add data to your sequence or, if
25881 * you want to add a large amount of data, call g_sequence_sort() after
25882 * doing unsorted insertions.
25884 * Returns: an #GSequenceIter pointing to the position where @data
25885 * would have been inserted according to @cmp_func and @cmp_data
25891 * g_sequence_search_iter:
25892 * @seq: a #GSequence
25893 * @data: data for the new item
25894 * @iter_cmp: the function used to compare iterators in the sequence
25895 * @cmp_data: user data passed to @iter_cmp
25897 * Like g_sequence_search(), but uses a #GSequenceIterCompareFunc
25898 * instead of a #GCompareDataFunc as the compare function.
25900 * @iter_cmp is called with two iterators pointing into @seq.
25901 * It should return 0 if the iterators are equal, a negative value
25902 * if the first iterator comes before the second, and a positive
25903 * value if the second iterator comes before the first.
25905 * If you are simply searching for an existing element of the sequence,
25906 * consider using g_sequence_lookup_iter().
25908 * This function will fail if the data contained in the sequence is
25909 * unsorted. Use g_sequence_insert_sorted() or
25910 * g_sequence_insert_sorted_iter() to add data to your sequence or, if
25911 * you want to add a large amount of data, call g_sequence_sort() after
25912 * doing unsorted insertions.
25914 * Returns: a #GSequenceIter pointing to the position in @seq
25915 * where @data would have been inserted according to @iter_cmp
25923 * @iter: a #GSequenceIter
25924 * @data: new data for the item
25926 * Changes the data for the item pointed to by @iter to be @data. If
25927 * the sequence has a data destroy function associated with it, that
25928 * function is called on the existing data that @iter pointed to.
25936 * @seq: a #GSequence
25937 * @cmp_func: the function used to sort the sequence
25938 * @cmp_data: user data passed to @cmp_func
25940 * Sorts @seq using @cmp_func.
25942 * @cmp_func is passed two items of @seq and should
25943 * return 0 if they are equal, a negative value if the
25944 * first comes before the second, and a positive value
25945 * if the second comes before the first.
25952 * g_sequence_sort_changed:
25953 * @iter: A #GSequenceIter
25954 * @cmp_func: the function used to compare items in the sequence
25955 * @cmp_data: user data passed to @cmp_func.
25957 * Moves the data pointed to a new position as indicated by @cmp_func. This
25958 * function should be called for items in a sequence already sorted according
25959 * to @cmp_func whenever some aspect of an item changes so that @cmp_func
25960 * may return different values for that item.
25962 * @cmp_func is called with two items of the @seq and @user_data.
25963 * It should return 0 if the items are equal, a negative value if
25964 * the first item comes before the second, and a positive value if
25965 * the second item comes before the first.
25972 * g_sequence_sort_changed_iter:
25973 * @iter: a #GSequenceIter
25974 * @iter_cmp: the function used to compare iterators in the sequence
25975 * @cmp_data: user data passed to @cmp_func
25977 * Like g_sequence_sort_changed(), but uses
25978 * a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
25979 * the compare function.
25981 * @iter_cmp is called with two iterators pointing into @seq. It should
25982 * return 0 if the iterators are equal, a negative value if the first
25983 * iterator comes before the second, and a positive value if the second
25984 * iterator comes before the first.
25991 * g_sequence_sort_iter:
25992 * @seq: a #GSequence
25993 * @cmp_func: the function used to compare iterators in the sequence
25994 * @cmp_data: user data passed to @cmp_func
25996 * Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead
25997 * of a GCompareDataFunc as the compare function
25999 * @cmp_func is called with two iterators pointing into @seq. It should
26000 * return 0 if the iterators are equal, a negative value if the first
26001 * iterator comes before the second, and a positive value if the second
26002 * iterator comes before the first.
26010 * @a: a #GSequenceIter
26011 * @b: a #GSequenceIter
26013 * Swaps the items pointed to by @a and @b. It is allowed for @a and @b
26014 * to point into difference sequences.
26021 * g_set_application_name:
26022 * @application_name: localized name of the application
26024 * Sets a human-readable name for the application. This name should be
26025 * localized if possible, and is intended for display to the user.
26026 * Contrast with g_set_prgname(), which sets a non-localized name.
26027 * g_set_prgname() will be called automatically by gtk_init(),
26028 * but g_set_application_name() will not.
26030 * Note that for thread safety reasons, this function can only
26033 * The application name will be used in contexts such as error messages,
26034 * or when displaying an application's name in the task list.
26042 * @err: (out callee-allocates) (optional): a return location for a #GError
26043 * @domain: error domain
26044 * @code: error code
26045 * @format: printf()-style format
26046 * @...: args for @format
26048 * Does nothing if @err is %NULL; if @err is non-%NULL, then *@err
26049 * must be %NULL. A new #GError is created and assigned to *@err.
26054 * g_set_error_literal:
26055 * @err: (out callee-allocates) (optional): a return location for a #GError
26056 * @domain: error domain
26057 * @code: error code
26058 * @message: error message
26060 * Does nothing if @err is %NULL; if @err is non-%NULL, then *@err
26061 * must be %NULL. A new #GError is created and assigned to *@err.
26062 * Unlike g_set_error(), @message is not a printf()-style format string.
26063 * Use this function if @message contains text you don't have control over,
26064 * that could include printf() escape sequences.
26072 * @prgname: the name of the program.
26074 * Sets the name of the program. This name should not be localized,
26075 * in contrast to g_set_application_name().
26077 * Note that for thread-safety reasons this function can only be called once.
26082 * g_set_print_handler:
26083 * @func: the new print handler
26085 * Sets the print handler.
26087 * Any messages passed to g_print() will be output via
26088 * the new handler. The default handler simply outputs
26089 * the message to stdout. By providing your own handler
26090 * you can redirect the output, to a GTK+ widget or a
26091 * log file for example.
26093 * Returns: the old print handler
26098 * g_set_printerr_handler:
26099 * @func: the new error message handler
26101 * Sets the handler for printing error messages.
26103 * Any messages passed to g_printerr() will be output via
26104 * the new handler. The default handler simply outputs the
26105 * message to stderr. By providing your own handler you can
26106 * redirect the output, to a GTK+ widget or a log file for
26109 * Returns: the old error message handler
26115 * @variable: the environment variable to set, must not contain '='.
26116 * @value: the value for to set the variable to.
26117 * @overwrite: whether to change the variable if it already exists.
26119 * Sets an environment variable. On UNIX, both the variable's name and
26120 * value can be arbitrary byte strings, except that the variable's name
26121 * cannot contain '='. On Windows, they should be in UTF-8.
26123 * Note that on some systems, when variables are overwritten, the memory
26124 * used for the previous variables and its value isn't reclaimed.
26126 * You should be mindful of the fact that environment variable handling
26127 * in UNIX is not thread-safe, and your program may crash if one thread
26128 * calls g_setenv() while another thread is calling getenv(). (And note
26129 * that many functions, such as gettext(), call getenv() internally.)
26130 * This function is only safe to use at the very start of your program,
26131 * before creating any other threads (or creating objects that create
26132 * worker threads of their own).
26134 * If you need to set up the environment for a child process, you can
26135 * use g_get_environ() to get an environment array, modify that with
26136 * g_environ_setenv() and g_environ_unsetenv(), and then pass that
26137 * array directly to execvpe(), g_spawn_async(), or the like.
26139 * Returns: %FALSE if the environment variable couldn't be set.
26145 * g_shell_parse_argv:
26146 * @command_line: command line to parse
26147 * @argcp: (out) (optional): return location for number of args
26148 * @argvp: (out) (optional) (array length=argcp zero-terminated=1): return
26149 * location for array of args
26150 * @error: (optional): return location for error
26152 * Parses a command line into an argument vector, in much the same way
26153 * the shell would, but without many of the expansions the shell would
26154 * perform (variable expansion, globs, operators, filename expansion,
26155 * etc. are not supported). The results are defined to be the same as
26156 * those you would get from a UNIX98 /bin/sh, as long as the input
26157 * contains none of the unsupported shell expansions. If the input
26158 * does contain such expansions, they are passed through
26159 * literally. Possible errors are those from the #G_SHELL_ERROR
26160 * domain. Free the returned vector with g_strfreev().
26162 * Returns: %TRUE on success, %FALSE if error set
26168 * @unquoted_string: a literal string
26170 * Quotes a string so that the shell (/bin/sh) will interpret the
26171 * quoted string to mean @unquoted_string. If you pass a filename to
26172 * the shell, for example, you should first quote it with this
26173 * function. The return value must be freed with g_free(). The
26174 * quoting style used is undefined (single or double quotes may be
26177 * Returns: quoted string
26183 * @quoted_string: shell-quoted string
26184 * @error: error return location or NULL
26186 * Unquotes a string as the shell (/bin/sh) would. Only handles
26187 * quotes; if a string contains file globs, arithmetic operators,
26188 * variables, backticks, redirections, or other special-to-the-shell
26189 * features, the result will be different from the result a real shell
26190 * would produce (the variables, backticks, etc. will be passed
26191 * through literally instead of being expanded). This function is
26192 * guaranteed to succeed if applied to the result of
26193 * g_shell_quote(). If it fails, it returns %NULL and sets the
26194 * error. The @quoted_string need not actually contain quoted or
26195 * escaped text; g_shell_unquote() simply goes through the string and
26196 * unquotes/unescapes anything that the shell would. Both single and
26197 * double quotes are handled, as are escapes including escaped
26198 * newlines. The return value must be freed with g_free(). Possible
26199 * errors are in the #G_SHELL_ERROR domain.
26201 * Shell quoting rules are a bit strange. Single quotes preserve the
26202 * literal string exactly. escape sequences are not allowed; not even
26203 * \' - if you want a ' in the quoted text, you have to do something
26204 * like 'foo'\''bar'. Double quotes allow $, `, ", \, and newline to
26205 * be escaped with backslash. Otherwise double quotes preserve things
26208 * Returns: an unquoted string
26213 * g_size_checked_add:
26214 * @dest: a pointer to the #gsize destination
26215 * @a: the #gsize left operand
26216 * @b: the #gsize right operand
26218 * Performs a checked addition of @a and @b, storing the result in
26221 * If the operation is successful, %TRUE is returned. If the operation
26222 * overflows then the state of @dest is undefined and %FALSE is
26225 * Returns: %TRUE if there was no overflow
26231 * g_size_checked_mul:
26232 * @dest: a pointer to the #gsize destination
26233 * @a: the #gsize left operand
26234 * @b: the #gsize right operand
26236 * Performs a checked multiplication of @a and @b, storing the result in
26239 * If the operation is successful, %TRUE is returned. If the operation
26240 * overflows then the state of @dest is undefined and %FALSE is
26243 * Returns: %TRUE if there was no overflow
26250 * @block_size: the number of bytes to allocate
26252 * Allocates a block of memory from the slice allocator.
26253 * The block adress handed out can be expected to be aligned
26254 * to at least 1 * sizeof (void*),
26255 * though in general slices are 2 * sizeof (void*) bytes aligned,
26256 * if a malloc() fallback implementation is used instead,
26257 * the alignment may be reduced in a libc dependent fashion.
26258 * Note that the underlying slice allocation mechanism can
26259 * be changed with the [`G_SLICE=always-malloc`][G_SLICE]
26260 * environment variable.
26262 * Returns: a pointer to the allocated memory block, which will be %NULL if and
26263 * only if @mem_size is 0
26270 * @block_size: the number of bytes to allocate
26272 * Allocates a block of memory via g_slice_alloc() and initializes
26273 * the returned memory to 0. Note that the underlying slice allocation
26274 * mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE]
26275 * environment variable.
26277 * Returns: a pointer to the allocated block, which will be %NULL if and only
26278 * if @mem_size is 0
26285 * @block_size: the number of bytes to allocate
26286 * @mem_block: the memory to copy
26288 * Allocates a block of memory from the slice allocator
26289 * and copies @block_size bytes into it from @mem_block.
26291 * @mem_block must be non-%NULL if @block_size is non-zero.
26293 * Returns: a pointer to the allocated memory block, which will be %NULL if and
26294 * only if @mem_size is 0
26301 * @type: the type to duplicate, typically a structure name
26302 * @mem: (not nullable): the memory to copy into the allocated block
26304 * A convenience macro to duplicate a block of memory using
26305 * the slice allocator.
26307 * It calls g_slice_copy() with `sizeof (@type)`
26308 * and casts the returned pointer to a pointer of the given type,
26309 * avoiding a type cast in the source code.
26310 * Note that the underlying slice allocation mechanism can
26311 * be changed with the [`G_SLICE=always-malloc`][G_SLICE]
26312 * environment variable.
26314 * This can never return %NULL.
26316 * Returns: (not nullable): a pointer to the allocated block, cast to a pointer
26324 * @type: the type of the block to free, typically a structure name
26325 * @mem: a pointer to the block to free
26327 * A convenience macro to free a block of memory that has
26328 * been allocated from the slice allocator.
26330 * It calls g_slice_free1() using `sizeof (type)`
26331 * as the block size.
26332 * Note that the exact release behaviour can be changed with the
26333 * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
26334 * [`G_SLICE`][G_SLICE] for related debugging options.
26336 * If @mem is %NULL, this macro does nothing.
26344 * @block_size: the size of the block
26345 * @mem_block: a pointer to the block to free
26347 * Frees a block of memory.
26349 * The memory must have been allocated via g_slice_alloc() or
26350 * g_slice_alloc0() and the @block_size has to match the size
26351 * specified upon allocation. Note that the exact release behaviour
26352 * can be changed with the [`G_DEBUG=gc-friendly`][G_DEBUG] environment
26353 * variable, also see [`G_SLICE`][G_SLICE] for related debugging options.
26355 * If @mem_block is %NULL, this function does nothing.
26362 * g_slice_free_chain:
26363 * @type: the type of the @mem_chain blocks
26364 * @mem_chain: a pointer to the first block of the chain
26365 * @next: the field name of the next pointer in @type
26367 * Frees a linked list of memory blocks of structure type @type.
26368 * The memory blocks must be equal-sized, allocated via
26369 * g_slice_alloc() or g_slice_alloc0() and linked together by
26370 * a @next pointer (similar to #GSList). The name of the
26371 * @next field in @type is passed as third argument.
26372 * Note that the exact release behaviour can be changed with the
26373 * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
26374 * [`G_SLICE`][G_SLICE] for related debugging options.
26376 * If @mem_chain is %NULL, this function does nothing.
26383 * g_slice_free_chain_with_offset:
26384 * @block_size: the size of the blocks
26385 * @mem_chain: a pointer to the first block of the chain
26386 * @next_offset: the offset of the @next field in the blocks
26388 * Frees a linked list of memory blocks of structure type @type.
26390 * The memory blocks must be equal-sized, allocated via
26391 * g_slice_alloc() or g_slice_alloc0() and linked together by a
26392 * @next pointer (similar to #GSList). The offset of the @next
26393 * field in each block is passed as third argument.
26394 * Note that the exact release behaviour can be changed with the
26395 * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
26396 * [`G_SLICE`][G_SLICE] for related debugging options.
26398 * If @mem_chain is %NULL, this function does nothing.
26406 * @type: the type to allocate, typically a structure name
26408 * A convenience macro to allocate a block of memory from the
26411 * It calls g_slice_alloc() with `sizeof (@type)` and casts the
26412 * returned pointer to a pointer of the given type, avoiding a type
26413 * cast in the source code. Note that the underlying slice allocation
26414 * mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE]
26415 * environment variable.
26417 * This can never return %NULL as the minimum allocation size from
26418 * `sizeof (@type)` is 1 byte.
26420 * Returns: (not nullable): a pointer to the allocated block, cast to a pointer
26428 * @type: the type to allocate, typically a structure name
26430 * A convenience macro to allocate a block of memory from the
26431 * slice allocator and set the memory to 0.
26433 * It calls g_slice_alloc0() with `sizeof (@type)`
26434 * and casts the returned pointer to a pointer of the given type,
26435 * avoiding a type cast in the source code.
26436 * Note that the underlying slice allocation mechanism can
26437 * be changed with the [`G_SLICE=always-malloc`][G_SLICE]
26438 * environment variable.
26440 * This can never return %NULL as the minimum allocation size from
26441 * `sizeof (@type)` is 1 byte.
26443 * Returns: (not nullable): a pointer to the allocated block, cast to a pointer
26452 * Allocates space for one #GSList element. It is called by the
26453 * g_slist_append(), g_slist_prepend(), g_slist_insert() and
26454 * g_slist_insert_sorted() functions and so is rarely used on its own.
26456 * Returns: a pointer to the newly-allocated #GSList element.
26463 * @data: the data for the new element
26465 * Adds a new element on to the end of the list.
26467 * The return value is the new start of the list, which may
26468 * have changed, so make sure you store the new value.
26470 * Note that g_slist_append() has to traverse the entire list
26471 * to find the end, which is inefficient when adding multiple
26472 * elements. A common idiom to avoid the inefficiency is to prepend
26473 * the elements and reverse the list when all elements have been added.
26475 * |[<!-- language="C" -->
26476 * // Notice that these are initialized to the empty list.
26477 * GSList *list = NULL, *number_list = NULL;
26479 * // This is a list of strings.
26480 * list = g_slist_append (list, "first");
26481 * list = g_slist_append (list, "second");
26483 * // This is a list of integers.
26484 * number_list = g_slist_append (number_list, GINT_TO_POINTER (27));
26485 * number_list = g_slist_append (number_list, GINT_TO_POINTER (14));
26488 * Returns: the new start of the #GSList
26494 * @list1: a #GSList
26495 * @list2: the #GSList to add to the end of the first #GSList
26497 * Adds the second #GSList onto the end of the first #GSList.
26498 * Note that the elements of the second #GSList are not copied.
26499 * They are used directly.
26501 * Returns: the start of the new #GSList
26509 * Copies a #GSList.
26511 * Note that this is a "shallow" copy. If the list elements
26512 * consist of pointers to data, the pointers are copied but
26513 * the actual data isn't. See g_slist_copy_deep() if you need
26514 * to copy the data as well.
26516 * Returns: a copy of @list
26521 * g_slist_copy_deep:
26523 * @func: a copy function used to copy every element in the list
26524 * @user_data: user data passed to the copy function @func, or #NULL
26526 * Makes a full (deep) copy of a #GSList.
26528 * In contrast with g_slist_copy(), this function uses @func to make a copy of
26529 * each list element, in addition to copying the list container itself.
26531 * @func, as a #GCopyFunc, takes two arguments, the data to be copied and a user
26532 * pointer. It's safe to pass #NULL as user_data, if the copy function takes only
26535 * For instance, if @list holds a list of GObjects, you can do:
26536 * |[<!-- language="C" -->
26537 * another_list = g_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL);
26540 * And, to entirely free the new list, you could do:
26541 * |[<!-- language="C" -->
26542 * g_slist_free_full (another_list, g_object_unref);
26545 * Returns: a full copy of @list, use #g_slist_free_full to free it
26551 * g_slist_delete_link:
26553 * @link_: node to delete
26555 * Removes the node link_ from the list and frees it.
26556 * Compare this to g_slist_remove_link() which removes the node
26557 * without freeing it.
26559 * Removing arbitrary nodes from a singly-linked list requires time
26560 * that is proportional to the length of the list (ie. O(n)). If you
26561 * find yourself using g_slist_delete_link() frequently, you should
26562 * consider a different data structure, such as the doubly-linked
26565 * Returns: the new head of @list
26572 * @data: the element data to find
26574 * Finds the element in a #GSList which
26575 * contains the given data.
26577 * Returns: the found #GSList element,
26578 * or %NULL if it is not found
26583 * g_slist_find_custom:
26585 * @data: user data passed to the function
26586 * @func: the function to call for each element.
26587 * It should return 0 when the desired element is found
26589 * Finds an element in a #GSList, using a supplied function to
26590 * find the desired element. It iterates over the list, calling
26591 * the given function which should return 0 when the desired
26592 * element is found. The function takes two #gconstpointer arguments,
26593 * the #GSList element's data as the first argument and the
26596 * Returns: the found #GSList element, or %NULL if it is not found
26603 * @func: the function to call with each element's data
26604 * @user_data: user data to pass to the function
26606 * Calls a function for each element of a #GSList.
26614 * Frees all of the memory used by a #GSList.
26615 * The freed elements are returned to the slice allocator.
26617 * If list elements contain dynamically-allocated memory,
26618 * you should either use g_slist_free_full() or free them manually
26626 * A macro which does the same as g_slist_free_1().
26634 * @list: a #GSList element
26636 * Frees one #GSList element.
26637 * It is usually used after g_slist_remove_link().
26642 * g_slist_free_full:
26643 * @list: a pointer to a #GSList
26644 * @free_func: the function to be called to free each element's data
26646 * Convenience method, which frees all the memory used by a #GSList, and
26647 * calls the specified destroy function on every element's data.
26656 * @data: the data to find
26658 * Gets the position of the element containing
26659 * the given data (starting from 0).
26661 * Returns: the index of the element containing the data,
26662 * or -1 if the data is not found
26669 * @data: the data for the new element
26670 * @position: the position to insert the element.
26671 * If this is negative, or is larger than the number
26672 * of elements in the list, the new element is added on
26673 * to the end of the list.
26675 * Inserts a new element into the list at the given position.
26677 * Returns: the new start of the #GSList
26682 * g_slist_insert_before:
26683 * @slist: a #GSList
26684 * @sibling: node to insert @data before
26685 * @data: data to put in the newly-inserted node
26687 * Inserts a node before @sibling containing @data.
26689 * Returns: the new head of the list.
26694 * g_slist_insert_sorted:
26696 * @data: the data for the new element
26697 * @func: the function to compare elements in the list.
26698 * It should return a number > 0 if the first parameter
26699 * comes after the second parameter in the sort order.
26701 * Inserts a new element into the list, using the given
26702 * comparison function to determine its position.
26704 * Returns: the new start of the #GSList
26709 * g_slist_insert_sorted_with_data:
26711 * @data: the data for the new element
26712 * @func: the function to compare elements in the list.
26713 * It should return a number > 0 if the first parameter
26714 * comes after the second parameter in the sort order.
26715 * @user_data: data to pass to comparison function
26717 * Inserts a new element into the list, using the given
26718 * comparison function to determine its position.
26720 * Returns: the new start of the #GSList
26729 * Gets the last element in a #GSList.
26731 * This function iterates over the whole list.
26733 * Returns: the last element in the #GSList,
26734 * or %NULL if the #GSList has no elements
26742 * Gets the number of elements in a #GSList.
26744 * This function iterates over the whole list to
26745 * count its elements. To check whether the list is non-empty, it is faster to
26746 * check @list against %NULL.
26748 * Returns: the number of elements in the #GSList
26754 * @slist: an element in a #GSList.
26756 * A convenience macro to get the next element in a #GSList.
26758 * Returns: the next element, or %NULL if there are no more elements.
26765 * @n: the position of the element, counting from 0
26767 * Gets the element at the given position in a #GSList.
26769 * Returns: the element, or %NULL if the position is off
26770 * the end of the #GSList
26775 * g_slist_nth_data:
26777 * @n: the position of the element
26779 * Gets the data of the element at the given position.
26781 * Returns: the element's data, or %NULL if the position
26782 * is off the end of the #GSList
26787 * g_slist_position:
26789 * @llink: an element in the #GSList
26791 * Gets the position of the given element
26792 * in the #GSList (starting from 0).
26794 * Returns: the position of the element in the #GSList,
26795 * or -1 if the element is not found
26802 * @data: the data for the new element
26804 * Adds a new element on to the start of the list.
26806 * The return value is the new start of the list, which
26807 * may have changed, so make sure you store the new value.
26809 * |[<!-- language="C" -->
26810 * // Notice that it is initialized to the empty list.
26811 * GSList *list = NULL;
26812 * list = g_slist_prepend (list, "last");
26813 * list = g_slist_prepend (list, "first");
26816 * Returns: the new start of the #GSList
26823 * @data: the data of the element to remove
26825 * Removes an element from a #GSList.
26826 * If two elements contain the same data, only the first is removed.
26827 * If none of the elements contain the data, the #GSList is unchanged.
26829 * Returns: the new start of the #GSList
26834 * g_slist_remove_all:
26836 * @data: data to remove
26838 * Removes all list nodes with data equal to @data.
26839 * Returns the new head of the list. Contrast with
26840 * g_slist_remove() which removes only the first node
26841 * matching the given data.
26843 * Returns: new head of @list
26848 * g_slist_remove_link:
26850 * @link_: an element in the #GSList
26852 * Removes an element from a #GSList, without
26853 * freeing the element. The removed element's next
26854 * link is set to %NULL, so that it becomes a
26855 * self-contained list with one element.
26857 * Removing arbitrary nodes from a singly-linked list
26858 * requires time that is proportional to the length of the list
26859 * (ie. O(n)). If you find yourself using g_slist_remove_link()
26860 * frequently, you should consider a different data structure,
26861 * such as the doubly-linked #GList.
26863 * Returns: the new start of the #GSList, without the element
26871 * Reverses a #GSList.
26873 * Returns: the start of the reversed #GSList
26880 * @compare_func: the comparison function used to sort the #GSList.
26881 * This function is passed the data from 2 elements of the #GSList
26882 * and should return 0 if they are equal, a negative value if the
26883 * first element comes before the second, or a positive value if
26884 * the first element comes after the second.
26886 * Sorts a #GSList using the given comparison function.
26888 * Returns: the start of the sorted #GSList
26893 * g_slist_sort_with_data:
26895 * @compare_func: comparison function
26896 * @user_data: data to pass to comparison function
26898 * Like g_slist_sort(), but the sort function accepts a user data argument.
26900 * Returns: new head of the list
26906 * @string: the buffer to hold the output.
26907 * @n: the maximum number of bytes to produce (including the
26908 * terminating nul character).
26909 * @format: a standard printf() format string, but notice
26910 * [string precision pitfalls][string-precision]
26911 * @...: the arguments to insert in the output.
26913 * A safer form of the standard sprintf() function. The output is guaranteed
26914 * to not exceed @n characters (including the terminating nul character), so
26915 * it is easy to ensure that a buffer overflow cannot occur.
26917 * See also g_strdup_printf().
26919 * In versions of GLib prior to 1.2.3, this function may return -1 if the
26920 * output was truncated, and the truncated string may not be nul-terminated.
26921 * In versions prior to 1.3.12, this function returns the length of the output
26924 * The return value of g_snprintf() conforms to the snprintf()
26925 * function as standardized in ISO C99. Note that this is different from
26926 * traditional snprintf(), which returns the length of the output string.
26928 * The format string may contain positional parameters, as specified in
26929 * the Single Unix Specification.
26931 * Returns: the number of bytes which would be produced if the buffer
26932 * was large enough.
26937 * g_source_add_child_source:
26938 * @source: a #GSource
26939 * @child_source: a second #GSource that @source should "poll"
26941 * Adds @child_source to @source as a "polled" source; when @source is
26942 * added to a #GMainContext, @child_source will be automatically added
26943 * with the same priority, when @child_source is triggered, it will
26944 * cause @source to dispatch (in addition to calling its own
26945 * callback), and when @source is destroyed, it will destroy
26946 * @child_source as well. (@source will also still be dispatched if
26947 * its own prepare/check functions indicate that it is ready.)
26949 * If you don't need @child_source to do anything on its own when it
26950 * triggers, you can call g_source_set_dummy_callback() on it to set a
26951 * callback that does nothing (except return %TRUE if appropriate).
26953 * @source will hold a reference on @child_source while @child_source
26954 * is attached to it.
26956 * This API is only intended to be used by implementations of #GSource.
26957 * Do not call this API on a #GSource that you did not create.
26964 * g_source_add_poll:
26965 * @source: a #GSource
26966 * @fd: a #GPollFD structure holding information about a file
26967 * descriptor to watch.
26969 * Adds a file descriptor to the set of file descriptors polled for
26970 * this source. This is usually combined with g_source_new() to add an
26971 * event source. The event source's check function will typically test
26972 * the @revents field in the #GPollFD struct and return %TRUE if events need
26975 * This API is only intended to be used by implementations of #GSource.
26976 * Do not call this API on a #GSource that you did not create.
26978 * Using this API forces the linear scanning of event sources on each
26979 * main loop iteration. Newly-written event sources should try to use
26980 * g_source_add_unix_fd() instead of this API.
26985 * g_source_add_unix_fd:
26986 * @source: a #GSource
26987 * @fd: the fd to monitor
26988 * @events: an event mask
26990 * Monitors @fd for the IO events in @events.
26992 * The tag returned by this function can be used to remove or modify the
26993 * monitoring of the fd using g_source_remove_unix_fd() or
26994 * g_source_modify_unix_fd().
26996 * It is not necessary to remove the fd before destroying the source; it
26997 * will be cleaned up automatically.
26999 * This API is only intended to be used by implementations of #GSource.
27000 * Do not call this API on a #GSource that you did not create.
27002 * As the name suggests, this function is not available on Windows.
27004 * Returns: (not nullable): an opaque tag
27011 * @source: a #GSource
27012 * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used)
27014 * Adds a #GSource to a @context so that it will be executed within
27015 * that context. Remove it by calling g_source_destroy().
27017 * Returns: the ID (greater than 0) for the source within the
27023 * g_source_destroy:
27024 * @source: a #GSource
27026 * Removes a source from its #GMainContext, if any, and mark it as
27027 * destroyed. The source cannot be subsequently added to another
27028 * context. It is safe to call this on sources which have already been
27029 * removed from their context.
27034 * g_source_get_can_recurse:
27035 * @source: a #GSource
27037 * Checks whether a source is allowed to be called recursively.
27038 * see g_source_set_can_recurse().
27040 * Returns: whether recursion is allowed.
27045 * g_source_get_context:
27046 * @source: a #GSource
27048 * Gets the #GMainContext with which the source is associated.
27050 * You can call this on a source that has been destroyed, provided
27051 * that the #GMainContext it was attached to still exists (in which
27052 * case it will return that #GMainContext). In particular, you can
27053 * always call this function on the source returned from
27054 * g_main_current_source(). But calling this function on a source
27055 * whose #GMainContext has been destroyed is an error.
27057 * Returns: (transfer none) (allow-none): the #GMainContext with which the
27058 * source is associated, or %NULL if the context has not
27059 * yet been added to a source.
27064 * g_source_get_current_time:
27065 * @source: a #GSource
27066 * @timeval: #GTimeVal structure in which to store current time.
27068 * This function ignores @source and is otherwise the same as
27069 * g_get_current_time().
27071 * Deprecated: 2.28: use g_source_get_time() instead
27077 * @source: a #GSource
27079 * Returns the numeric ID for a particular source. The ID of a source
27080 * is a positive integer which is unique within a particular main loop
27081 * context. The reverse
27082 * mapping from ID to source is done by g_main_context_find_source_by_id().
27084 * Returns: the ID (greater than 0) for the source
27089 * g_source_get_name:
27090 * @source: a #GSource
27092 * Gets a name for the source, used in debugging and profiling. The
27093 * name may be #NULL if it has never been set with g_source_set_name().
27095 * Returns: the name of the source
27101 * g_source_get_priority:
27102 * @source: a #GSource
27104 * Gets the priority of a source.
27106 * Returns: the priority of the source
27111 * g_source_get_ready_time:
27112 * @source: a #GSource
27114 * Gets the "ready time" of @source, as set by
27115 * g_source_set_ready_time().
27117 * Any time before the current monotonic time (including 0) is an
27118 * indication that the source will fire immediately.
27120 * Returns: the monotonic ready time, -1 for "never"
27125 * g_source_get_time:
27126 * @source: a #GSource
27128 * Gets the time to be used when checking this source. The advantage of
27129 * calling this function over calling g_get_monotonic_time() directly is
27130 * that when checking multiple sources, GLib can cache a single value
27131 * instead of having to repeatedly get the system monotonic time.
27133 * The time here is the system monotonic time, if available, or some
27134 * other reasonable alternative otherwise. See g_get_monotonic_time().
27136 * Returns: the monotonic time in microseconds
27142 * g_source_is_destroyed:
27143 * @source: a #GSource
27145 * Returns whether @source has been destroyed.
27147 * This is important when you operate upon your objects
27148 * from within idle handlers, but may have freed the object
27149 * before the dispatch of your idle handler.
27151 * |[<!-- language="C" -->
27153 * idle_callback (gpointer data)
27155 * SomeWidget *self = data;
27157 * GDK_THREADS_ENTER ();
27158 * // do stuff with self
27159 * self->idle_id = 0;
27160 * GDK_THREADS_LEAVE ();
27162 * return G_SOURCE_REMOVE;
27166 * some_widget_do_stuff_later (SomeWidget *self)
27168 * self->idle_id = g_idle_add (idle_callback, self);
27172 * some_widget_finalize (GObject *object)
27174 * SomeWidget *self = SOME_WIDGET (object);
27176 * if (self->idle_id)
27177 * g_source_remove (self->idle_id);
27179 * G_OBJECT_CLASS (parent_class)->finalize (object);
27183 * This will fail in a multi-threaded application if the
27184 * widget is destroyed before the idle handler fires due
27185 * to the use after free in the callback. A solution, to
27186 * this particular problem, is to check to if the source
27187 * has already been destroy within the callback.
27189 * |[<!-- language="C" -->
27191 * idle_callback (gpointer data)
27193 * SomeWidget *self = data;
27195 * GDK_THREADS_ENTER ();
27196 * if (!g_source_is_destroyed (g_main_current_source ()))
27198 * // do stuff with self
27200 * GDK_THREADS_LEAVE ();
27206 * Returns: %TRUE if the source has been destroyed
27212 * g_source_modify_unix_fd:
27213 * @source: a #GSource
27214 * @tag: (not nullable): the tag from g_source_add_unix_fd()
27215 * @new_events: the new event mask to watch
27217 * Updates the event mask to watch for the fd identified by @tag.
27219 * @tag is the tag returned from g_source_add_unix_fd().
27221 * If you want to remove a fd, don't set its event mask to zero.
27222 * Instead, call g_source_remove_unix_fd().
27224 * This API is only intended to be used by implementations of #GSource.
27225 * Do not call this API on a #GSource that you did not create.
27227 * As the name suggests, this function is not available on Windows.
27235 * @source_funcs: structure containing functions that implement
27236 * the sources behavior.
27237 * @struct_size: size of the #GSource structure to create.
27239 * Creates a new #GSource structure. The size is specified to
27240 * allow creating structures derived from #GSource that contain
27241 * additional data. The size passed in must be at least
27242 * `sizeof (GSource)`.
27244 * The source will not initially be associated with any #GMainContext
27245 * and must be added to one with g_source_attach() before it will be
27248 * Returns: the newly-created #GSource.
27253 * g_source_query_unix_fd:
27254 * @source: a #GSource
27255 * @tag: (not nullable): the tag from g_source_add_unix_fd()
27257 * Queries the events reported for the fd corresponding to @tag on
27258 * @source during the last poll.
27260 * The return value of this function is only defined when the function
27261 * is called from the check or dispatch functions for @source.
27263 * This API is only intended to be used by implementations of #GSource.
27264 * Do not call this API on a #GSource that you did not create.
27266 * As the name suggests, this function is not available on Windows.
27268 * Returns: the conditions reported on the fd
27275 * @source: a #GSource
27277 * Increases the reference count on a source by one.
27285 * @tag: the ID of the source to remove.
27287 * Removes the source with the given id from the default main context.
27289 * The id of a #GSource is given by g_source_get_id(), or will be
27290 * returned by the functions g_source_attach(), g_idle_add(),
27291 * g_idle_add_full(), g_timeout_add(), g_timeout_add_full(),
27292 * g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and
27293 * g_io_add_watch_full().
27295 * See also g_source_destroy(). You must use g_source_destroy() for sources
27296 * added to a non-default main context.
27298 * It is a programmer error to attempt to remove a non-existent source.
27300 * More specifically: source IDs can be reissued after a source has been
27301 * destroyed and therefore it is never valid to use this function with a
27302 * source ID which may have already been removed. An example is when
27303 * scheduling an idle to run in another thread with g_idle_add(): the
27304 * idle may already have run and been removed by the time this function
27305 * is called on its (now invalid) source ID. This source ID may have
27306 * been reissued, leading to the operation being performed against the
27309 * Returns: For historical reasons, this function always returns %TRUE
27314 * g_source_remove_by_funcs_user_data:
27315 * @funcs: The @source_funcs passed to g_source_new()
27316 * @user_data: the user data for the callback
27318 * Removes a source from the default main loop context given the
27319 * source functions and user data. If multiple sources exist with the
27320 * same source functions and user data, only one will be destroyed.
27322 * Returns: %TRUE if a source was found and removed.
27327 * g_source_remove_by_user_data:
27328 * @user_data: the user_data for the callback.
27330 * Removes a source from the default main loop context given the user
27331 * data for the callback. If multiple sources exist with the same user
27332 * data, only one will be destroyed.
27334 * Returns: %TRUE if a source was found and removed.
27339 * g_source_remove_child_source:
27340 * @source: a #GSource
27341 * @child_source: a #GSource previously passed to
27342 * g_source_add_child_source().
27344 * Detaches @child_source from @source and destroys it.
27346 * This API is only intended to be used by implementations of #GSource.
27347 * Do not call this API on a #GSource that you did not create.
27354 * g_source_remove_poll:
27355 * @source: a #GSource
27356 * @fd: a #GPollFD structure previously passed to g_source_add_poll().
27358 * Removes a file descriptor from the set of file descriptors polled for
27361 * This API is only intended to be used by implementations of #GSource.
27362 * Do not call this API on a #GSource that you did not create.
27367 * g_source_remove_unix_fd:
27368 * @source: a #GSource
27369 * @tag: (not nullable): the tag from g_source_add_unix_fd()
27371 * Reverses the effect of a previous call to g_source_add_unix_fd().
27373 * You only need to call this if you want to remove an fd from being
27374 * watched while keeping the same source around. In the normal case you
27375 * will just want to destroy the source.
27377 * This API is only intended to be used by implementations of #GSource.
27378 * Do not call this API on a #GSource that you did not create.
27380 * As the name suggests, this function is not available on Windows.
27387 * g_source_set_callback:
27388 * @source: the source
27389 * @func: a callback function
27390 * @data: the data to pass to callback function
27391 * @notify: (allow-none): a function to call when @data is no longer in use, or %NULL.
27393 * Sets the callback function for a source. The callback for a source is
27394 * called from the source's dispatch function.
27396 * The exact type of @func depends on the type of source; ie. you
27397 * should not count on @func being called with @data as its first
27400 * See [memory management of sources][mainloop-memory-management] for details
27401 * on how to handle memory management of @data.
27403 * Typically, you won't use this function. Instead use functions specific
27404 * to the type of source you are using.
27409 * g_source_set_callback_indirect:
27410 * @source: the source
27411 * @callback_data: pointer to callback data "object"
27412 * @callback_funcs: functions for reference counting @callback_data
27413 * and getting the callback and data
27415 * Sets the callback function storing the data as a refcounted callback
27416 * "object". This is used internally. Note that calling
27417 * g_source_set_callback_indirect() assumes
27418 * an initial reference count on @callback_data, and thus
27419 * @callback_funcs->unref will eventually be called once more
27420 * than @callback_funcs->ref.
27425 * g_source_set_can_recurse:
27426 * @source: a #GSource
27427 * @can_recurse: whether recursion is allowed for this source
27429 * Sets whether a source can be called recursively. If @can_recurse is
27430 * %TRUE, then while the source is being dispatched then this source
27431 * will be processed normally. Otherwise, all processing of this
27432 * source is blocked until the dispatch function returns.
27437 * g_source_set_funcs:
27438 * @source: a #GSource
27439 * @funcs: the new #GSourceFuncs
27441 * Sets the source functions (can be used to override
27442 * default implementations) of an unattached source.
27449 * g_source_set_name:
27450 * @source: a #GSource
27451 * @name: debug name for the source
27453 * Sets a name for the source, used in debugging and profiling.
27454 * The name defaults to #NULL.
27456 * The source name should describe in a human-readable way
27457 * what the source does. For example, "X11 event queue"
27458 * or "GTK+ repaint idle handler" or whatever it is.
27460 * It is permitted to call this function multiple times, but is not
27461 * recommended due to the potential performance impact. For example,
27462 * one could change the name in the "check" function of a #GSourceFuncs
27463 * to include details like the event type in the source name.
27465 * Use caution if changing the name while another thread may be
27466 * accessing it with g_source_get_name(); that function does not copy
27467 * the value, and changing the value will free it while the other thread
27468 * may be attempting to use it.
27475 * g_source_set_name_by_id:
27476 * @tag: a #GSource ID
27477 * @name: debug name for the source
27479 * Sets the name of a source using its ID.
27481 * This is a convenience utility to set source names from the return
27482 * value of g_idle_add(), g_timeout_add(), etc.
27484 * It is a programmer error to attempt to set the name of a non-existent
27487 * More specifically: source IDs can be reissued after a source has been
27488 * destroyed and therefore it is never valid to use this function with a
27489 * source ID which may have already been removed. An example is when
27490 * scheduling an idle to run in another thread with g_idle_add(): the
27491 * idle may already have run and been removed by the time this function
27492 * is called on its (now invalid) source ID. This source ID may have
27493 * been reissued, leading to the operation being performed against the
27501 * g_source_set_priority:
27502 * @source: a #GSource
27503 * @priority: the new priority.
27505 * Sets the priority of a source. While the main loop is being run, a
27506 * source will be dispatched if it is ready to be dispatched and no
27507 * sources at a higher (numerically smaller) priority are ready to be
27510 * A child source always has the same priority as its parent. It is not
27511 * permitted to change the priority of a source once it has been added
27512 * as a child of another source.
27517 * g_source_set_ready_time:
27518 * @source: a #GSource
27519 * @ready_time: the monotonic time at which the source will be ready,
27520 * 0 for "immediately", -1 for "never"
27522 * Sets a #GSource to be dispatched when the given monotonic time is
27523 * reached (or passed). If the monotonic time is in the past (as it
27524 * always will be if @ready_time is 0) then the source will be
27525 * dispatched immediately.
27527 * If @ready_time is -1 then the source is never woken up on the basis
27528 * of the passage of time.
27530 * Dispatching the source does not reset the ready time. You should do
27531 * so yourself, from the source dispatch function.
27533 * Note that if you have a pair of sources where the ready time of one
27534 * suggests that it will be delivered first but the priority for the
27535 * other suggests that it would be delivered first, and the ready time
27536 * for both sources is reached during the same main context iteration
27537 * then the order of dispatch is undefined.
27539 * This API is only intended to be used by implementations of #GSource.
27540 * Do not call this API on a #GSource that you did not create.
27548 * @source: a #GSource
27550 * Decreases the reference count of a source by one. If the
27551 * resulting reference count is zero the source and associated
27552 * memory will be destroyed.
27557 * g_spaced_primes_closest:
27560 * Gets the smallest prime number from a built-in array of primes which
27561 * is larger than @num. This is used within GLib to calculate the optimum
27562 * size of a #GHashTable.
27564 * The built-in array of primes ranges from 11 to 13845163 such that
27565 * each prime is approximately 1.5-2 times the previous prime.
27567 * Returns: the smallest prime number from a built-in array of primes
27568 * which is larger than @num
27574 * @working_directory: (type filename) (allow-none): child's current working directory, or %NULL to inherit parent's
27575 * @argv: (array zero-terminated=1): child's argument vector
27576 * @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's
27577 * @flags: flags from #GSpawnFlags
27578 * @child_setup: (scope async) (allow-none): function to run in the child just before exec()
27579 * @user_data: (closure): user data for @child_setup
27580 * @child_pid: (out) (allow-none): return location for child process reference, or %NULL
27581 * @error: return location for error
27583 * See g_spawn_async_with_pipes() for a full description; this function
27584 * simply calls the g_spawn_async_with_pipes() without any pipes.
27586 * You should call g_spawn_close_pid() on the returned child process
27587 * reference when you don't need it any more.
27589 * If you are writing a GTK+ application, and the program you are
27590 * spawning is a graphical application, too, then you may want to
27591 * use gdk_spawn_on_screen() instead to ensure that the spawned program
27592 * opens its windows on the right screen.
27594 * Note that the returned @child_pid on Windows is a handle to the child
27595 * process and not its identifier. Process handles and process identifiers
27596 * are different concepts on Windows.
27598 * Returns: %TRUE on success, %FALSE if error is set
27603 * g_spawn_async_with_pipes:
27604 * @working_directory: (type filename) (allow-none): child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding
27605 * @argv: (array zero-terminated=1): child's argument vector, in the GLib file name encoding
27606 * @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's, in the GLib file name encoding
27607 * @flags: flags from #GSpawnFlags
27608 * @child_setup: (scope async) (allow-none): function to run in the child just before exec()
27609 * @user_data: (closure): user data for @child_setup
27610 * @child_pid: (out) (allow-none): return location for child process ID, or %NULL
27611 * @standard_input: (out) (allow-none): return location for file descriptor to write to child's stdin, or %NULL
27612 * @standard_output: (out) (allow-none): return location for file descriptor to read child's stdout, or %NULL
27613 * @standard_error: (out) (allow-none): return location for file descriptor to read child's stderr, or %NULL
27614 * @error: return location for error
27616 * Executes a child program asynchronously (your program will not
27617 * block waiting for the child to exit). The child program is
27618 * specified by the only argument that must be provided, @argv.
27619 * @argv should be a %NULL-terminated array of strings, to be passed
27620 * as the argument vector for the child. The first string in @argv
27621 * is of course the name of the program to execute. By default, the
27622 * name of the program must be a full path. If @flags contains the
27623 * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is
27624 * used to search for the executable. If @flags contains the
27625 * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from
27626 * @envp is used to search for the executable. If both the
27627 * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags
27628 * are set, the `PATH` variable from @envp takes precedence over
27629 * the environment variable.
27631 * If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not
27632 * used, then the program will be run from the current directory (or
27633 * @working_directory, if specified); this might be unexpected or even
27634 * dangerous in some cases when the current directory is world-writable.
27636 * On Windows, note that all the string or string vector arguments to
27637 * this function and the other g_spawn*() functions are in UTF-8, the
27638 * GLib file name encoding. Unicode characters that are not part of
27639 * the system codepage passed in these arguments will be correctly
27640 * available in the spawned program only if it uses wide character API
27641 * to retrieve its command line. For C programs built with Microsoft's
27642 * tools it is enough to make the program have a wmain() instead of
27643 * main(). wmain() has a wide character argument vector as parameter.
27645 * At least currently, mingw doesn't support wmain(), so if you use
27646 * mingw to develop the spawned program, it should call
27647 * g_win32_get_command_line() to get arguments in UTF-8.
27649 * On Windows the low-level child process creation API CreateProcess()
27650 * doesn't use argument vectors, but a command line. The C runtime
27651 * library's spawn*() family of functions (which g_spawn_async_with_pipes()
27652 * eventually calls) paste the argument vector elements together into
27653 * a command line, and the C runtime startup code does a corresponding
27654 * reconstruction of an argument vector from the command line, to be
27655 * passed to main(). Complications arise when you have argument vector
27656 * elements that contain spaces of double quotes. The spawn*() functions
27657 * don't do any quoting or escaping, but on the other hand the startup
27658 * code does do unquoting and unescaping in order to enable receiving
27659 * arguments with embedded spaces or double quotes. To work around this
27660 * asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on
27661 * argument vector elements that need it before calling the C runtime
27662 * spawn() function.
27664 * The returned @child_pid on Windows is a handle to the child
27665 * process, not its identifier. Process handles and process
27666 * identifiers are different concepts on Windows.
27668 * @envp is a %NULL-terminated array of strings, where each string
27669 * has the form `KEY=VALUE`. This will become the child's environment.
27670 * If @envp is %NULL, the child inherits its parent's environment.
27672 * @flags should be the bitwise OR of any flags you want to affect the
27673 * function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the
27674 * child will not automatically be reaped; you must use a child watch to
27675 * be notified about the death of the child process. Eventually you must
27676 * call g_spawn_close_pid() on the @child_pid, in order to free
27677 * resources which may be associated with the child process. (On Unix,
27678 * using a child watch is equivalent to calling waitpid() or handling
27679 * the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid()
27680 * is equivalent to calling CloseHandle() on the process handle returned
27681 * in @child_pid). See g_child_watch_add().
27683 * %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file
27684 * descriptors will be inherited by the child; otherwise all descriptors
27685 * except stdin/stdout/stderr will be closed before calling exec() in
27686 * the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an
27687 * absolute path, it will be looked for in the `PATH` environment
27688 * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an
27689 * absolute path, it will be looked for in the `PATH` variable from
27690 * @envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP
27691 * are used, the value from @envp takes precedence over the environment.
27692 * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output
27693 * will be discarded, instead of going to the same location as the parent's
27694 * standard output. If you use this flag, @standard_output must be %NULL.
27695 * %G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error
27696 * will be discarded, instead of going to the same location as the parent's
27697 * standard error. If you use this flag, @standard_error must be %NULL.
27698 * %G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's
27699 * standard input (by default, the child's standard input is attached to
27700 * /dev/null). If you use this flag, @standard_input must be %NULL.
27701 * %G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is
27702 * the file to execute, while the remaining elements are the actual
27703 * argument vector to pass to the file. Normally g_spawn_async_with_pipes()
27704 * uses @argv[0] as the file to execute, and passes all of @argv to the child.
27706 * @child_setup and @user_data are a function and user data. On POSIX
27707 * platforms, the function is called in the child after GLib has
27708 * performed all the setup it plans to perform (including creating
27709 * pipes, closing file descriptors, etc.) but before calling exec().
27710 * That is, @child_setup is called just before calling exec() in the
27711 * child. Obviously actions taken in this function will only affect
27712 * the child, not the parent.
27714 * On Windows, there is no separate fork() and exec() functionality.
27715 * Child processes are created and run with a single API call,
27716 * CreateProcess(). There is no sensible thing @child_setup
27717 * could be used for on Windows so it is ignored and not called.
27719 * If non-%NULL, @child_pid will on Unix be filled with the child's
27720 * process ID. You can use the process ID to send signals to the child,
27721 * or to use g_child_watch_add() (or waitpid()) if you specified the
27722 * %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be
27723 * filled with a handle to the child process only if you specified the
27724 * %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child
27725 * process using the Win32 API, for example wait for its termination
27726 * with the WaitFor*() functions, or examine its exit code with
27727 * GetExitCodeProcess(). You should close the handle with CloseHandle()
27728 * or g_spawn_close_pid() when you no longer need it.
27730 * If non-%NULL, the @standard_input, @standard_output, @standard_error
27731 * locations will be filled with file descriptors for writing to the child's
27732 * standard input or reading from its standard output or standard error.
27733 * The caller of g_spawn_async_with_pipes() must close these file descriptors
27734 * when they are no longer in use. If these parameters are %NULL, the
27735 * corresponding pipe won't be created.
27737 * If @standard_input is NULL, the child's standard input is attached to
27738 * /dev/null unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
27740 * If @standard_error is NULL, the child's standard error goes to the same
27741 * location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL
27744 * If @standard_output is NULL, the child's standard output goes to the same
27745 * location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL
27748 * @error can be %NULL to ignore errors, or non-%NULL to report errors.
27749 * If an error is set, the function returns %FALSE. Errors are reported
27750 * even if they occur in the child (for example if the executable in
27751 * @argv[0] is not found). Typically the `message` field of returned
27752 * errors should be displayed to users. Possible errors are those from
27753 * the #G_SPAWN_ERROR domain.
27755 * If an error occurs, @child_pid, @standard_input, @standard_output,
27756 * and @standard_error will not be filled with valid values.
27758 * If @child_pid is not %NULL and an error does not occur then the returned
27759 * process reference must be closed using g_spawn_close_pid().
27761 * If you are writing a GTK+ application, and the program you
27762 * are spawning is a graphical application, too, then you may
27763 * want to use gdk_spawn_on_screen_with_pipes() instead to ensure that
27764 * the spawned program opens its windows on the right screen.
27766 * Returns: %TRUE on success, %FALSE if an error was set
27771 * g_spawn_check_exit_status:
27772 * @exit_status: An exit code as returned from g_spawn_sync()
27773 * @error: a #GError
27775 * Set @error if @exit_status indicates the child exited abnormally
27776 * (e.g. with a nonzero exit code, or via a fatal signal).
27778 * The g_spawn_sync() and g_child_watch_add() family of APIs return an
27779 * exit status for subprocesses encoded in a platform-specific way.
27780 * On Unix, this is guaranteed to be in the same format waitpid() returns,
27781 * and on Windows it is guaranteed to be the result of GetExitCodeProcess().
27783 * Prior to the introduction of this function in GLib 2.34, interpreting
27784 * @exit_status required use of platform-specific APIs, which is problematic
27785 * for software using GLib as a cross-platform layer.
27787 * Additionally, many programs simply want to determine whether or not
27788 * the child exited successfully, and either propagate a #GError or
27789 * print a message to standard error. In that common case, this function
27790 * can be used. Note that the error message in @error will contain
27791 * human-readable information about the exit status.
27793 * The @domain and @code of @error have special semantics in the case
27794 * where the process has an "exit code", as opposed to being killed by
27795 * a signal. On Unix, this happens if WIFEXITED() would be true of
27796 * @exit_status. On Windows, it is always the case.
27798 * The special semantics are that the actual exit code will be the
27799 * code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR.
27800 * This allows you to differentiate between different exit codes.
27802 * If the process was terminated by some means other than an exit
27803 * status, the domain will be %G_SPAWN_ERROR, and the code will be
27804 * %G_SPAWN_ERROR_FAILED.
27806 * This function just offers convenience; you can of course also check
27807 * the available platform via a macro such as %G_OS_UNIX, and use
27808 * WIFEXITED() and WEXITSTATUS() on @exit_status directly. Do not attempt
27809 * to scan or parse the error message string; it may be translated and/or
27810 * change in future versions of GLib.
27812 * Returns: %TRUE if child exited successfully, %FALSE otherwise (and
27813 * @error will be set)
27819 * g_spawn_close_pid:
27820 * @pid: The process reference to close
27822 * On some platforms, notably Windows, the #GPid type represents a resource
27823 * which must be closed to prevent resource leaking. g_spawn_close_pid()
27824 * is provided for this purpose. It should be used on all platforms, even
27825 * though it doesn't do anything under UNIX.
27830 * g_spawn_command_line_async:
27831 * @command_line: a command line
27832 * @error: return location for errors
27834 * A simple version of g_spawn_async() that parses a command line with
27835 * g_shell_parse_argv() and passes it to g_spawn_async(). Runs a
27836 * command line in the background. Unlike g_spawn_async(), the
27837 * %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note
27838 * that %G_SPAWN_SEARCH_PATH can have security implications, so
27839 * consider using g_spawn_async() directly if appropriate. Possible
27840 * errors are those from g_shell_parse_argv() and g_spawn_async().
27842 * The same concerns on Windows apply as for g_spawn_command_line_sync().
27844 * Returns: %TRUE on success, %FALSE if error is set
27849 * g_spawn_command_line_sync:
27850 * @command_line: a command line
27851 * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child output
27852 * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child errors
27853 * @exit_status: (out) (allow-none): return location for child exit status, as returned by waitpid()
27854 * @error: return location for errors
27856 * A simple version of g_spawn_sync() with little-used parameters
27857 * removed, taking a command line instead of an argument vector. See
27858 * g_spawn_sync() for full details. @command_line will be parsed by
27859 * g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag
27860 * is enabled. Note that %G_SPAWN_SEARCH_PATH can have security
27861 * implications, so consider using g_spawn_sync() directly if
27862 * appropriate. Possible errors are those from g_spawn_sync() and those
27863 * from g_shell_parse_argv().
27865 * If @exit_status is non-%NULL, the platform-specific exit status of
27866 * the child is stored there; see the documentation of
27867 * g_spawn_check_exit_status() for how to use and interpret this.
27869 * On Windows, please note the implications of g_shell_parse_argv()
27870 * parsing @command_line. Parsing is done according to Unix shell rules, not
27871 * Windows command interpreter rules.
27872 * Space is a separator, and backslashes are
27873 * special. Thus you cannot simply pass a @command_line containing
27874 * canonical Windows paths, like "c:\\program files\\app\\app.exe", as
27875 * the backslashes will be eaten, and the space will act as a
27876 * separator. You need to enclose such paths with single quotes, like
27877 * "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'".
27879 * Returns: %TRUE on success, %FALSE if an error was set
27885 * @working_directory: (type filename) (allow-none): child's current working directory, or %NULL to inherit parent's
27886 * @argv: (array zero-terminated=1): child's argument vector
27887 * @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's
27888 * @flags: flags from #GSpawnFlags
27889 * @child_setup: (scope async) (allow-none): function to run in the child just before exec()
27890 * @user_data: (closure): user data for @child_setup
27891 * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child output, or %NULL
27892 * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (allow-none): return location for child error messages, or %NULL
27893 * @exit_status: (out) (allow-none): return location for child exit status, as returned by waitpid(), or %NULL
27894 * @error: return location for error, or %NULL
27896 * Executes a child synchronously (waits for the child to exit before returning).
27897 * All output from the child is stored in @standard_output and @standard_error,
27898 * if those parameters are non-%NULL. Note that you must set the
27899 * %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when
27900 * passing %NULL for @standard_output and @standard_error.
27902 * If @exit_status is non-%NULL, the platform-specific exit status of
27903 * the child is stored there; see the documentation of
27904 * g_spawn_check_exit_status() for how to use and interpret this.
27905 * Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in
27908 * If an error occurs, no data is returned in @standard_output,
27909 * @standard_error, or @exit_status.
27911 * This function calls g_spawn_async_with_pipes() internally; see that
27912 * function for full details on the other parameters and details on
27913 * how these functions work on Windows.
27915 * Returns: %TRUE on success, %FALSE if an error was set
27921 * @string: A pointer to a memory buffer to contain the resulting string. It
27922 * is up to the caller to ensure that the allocated buffer is large
27923 * enough to hold the formatted result
27924 * @format: a standard printf() format string, but notice
27925 * [string precision pitfalls][string-precision]
27926 * @...: the arguments to insert in the output.
27928 * An implementation of the standard sprintf() function which supports
27929 * positional parameters, as specified in the Single Unix Specification.
27931 * Note that it is usually better to use g_snprintf(), to avoid the
27932 * risk of buffer overflow.
27934 * See also g_strdup_printf().
27936 * Returns: the number of bytes printed.
27943 * @filename: (type filename): a pathname in the GLib file name encoding
27944 * (UTF-8 on Windows)
27945 * @buf: a pointer to a stat struct, which will be filled with the file
27948 * A wrapper for the POSIX stat() function. The stat() function
27949 * returns information about a file. On Windows the stat() function in
27950 * the C library checks only the FAT-style READONLY attribute and does
27951 * not look at the ACL at all. Thus on Windows the protection bits in
27952 * the @st_mode field are a fabrication of little use.
27954 * On Windows the Microsoft C libraries have several variants of the
27955 * stat struct and stat() function with names like _stat(), _stat32(),
27956 * _stat32i64() and _stat64i32(). The one used here is for 32-bit code
27957 * the one with 32-bit size and time fields, specifically called _stat32().
27959 * In Microsoft's compiler, by default struct stat means one with
27960 * 64-bit time fields while in MinGW struct stat is the legacy one
27961 * with 32-bit fields. To hopefully clear up this messs, the gstdio.h
27962 * header defines a type #GStatBuf which is the appropriate struct type
27963 * depending on the platform and/or compiler being used. On POSIX it
27964 * is just struct stat, but note that even on POSIX platforms, stat()
27965 * might be a macro.
27967 * See your C library manual for more details about stat().
27969 * Returns: 0 if the information was successfully retrieved,
27970 * -1 if an error occurred
27977 * @dest: destination buffer.
27978 * @src: source string.
27980 * Copies a nul-terminated string into the dest buffer, include the
27981 * trailing nul, and return a pointer to the trailing nul byte.
27982 * This is useful for concatenating multiple strings together
27983 * without having to repeatedly scan for the end.
27985 * Returns: a pointer to trailing nul byte.
27991 * @v1: (not nullable): a key
27992 * @v2: (not nullable): a key to compare with @v1
27994 * Compares two strings for byte-by-byte equality and returns %TRUE
27995 * if they are equal. It can be passed to g_hash_table_new() as the
27996 * @key_equal_func parameter, when using non-%NULL strings as keys in a
27999 * Note that this function is primarily meant as a hash table comparison
28000 * function. For a general-purpose, %NULL-safe string comparison function,
28003 * Returns: %TRUE if the two keys match
28008 * g_str_has_prefix:
28009 * @str: a nul-terminated string
28010 * @prefix: the nul-terminated prefix to look for
28012 * Looks whether the string @str begins with @prefix.
28014 * Returns: %TRUE if @str begins with @prefix, %FALSE otherwise.
28020 * g_str_has_suffix:
28021 * @str: a nul-terminated string
28022 * @suffix: the nul-terminated suffix to look for
28024 * Looks whether the string @str ends with @suffix.
28026 * Returns: %TRUE if @str end with @suffix, %FALSE otherwise.
28033 * @v: (not nullable): a string key
28035 * Converts a string to a hash value.
28037 * This function implements the widely used "djb" hash apparently
28038 * posted by Daniel Bernstein to comp.lang.c some time ago. The 32
28039 * bit unsigned hash value starts at 5381 and for each byte 'c' in
28040 * the string, is updated: `hash = hash * 33 + c`. This function
28041 * uses the signed value of each byte.
28043 * It can be passed to g_hash_table_new() as the @hash_func parameter,
28044 * when using non-%NULL strings as keys in a #GHashTable.
28046 * Note that this function may not be a perfect fit for all use cases.
28047 * For example, it produces some hash collisions with strings as short
28050 * Returns: a hash value corresponding to the key
28058 * Determines if a string is pure ASCII. A string is pure ASCII if it
28059 * contains no bytes with the high bit set.
28061 * Returns: %TRUE if @str is ASCII
28067 * g_str_match_string:
28068 * @search_term: the search term from the user
28069 * @potential_hit: the text that may be a hit
28070 * @accept_alternates: %TRUE to accept ASCII alternates
28072 * Checks if a search conducted for @search_term should match
28075 * This function calls g_str_tokenize_and_fold() on both
28076 * @search_term and @potential_hit. ASCII alternates are never taken
28077 * for @search_term but will be taken for @potential_hit according to
28078 * the value of @accept_alternates.
28080 * A hit occurs when each folded token in @search_term is a prefix of a
28081 * folded token from @potential_hit.
28083 * Depending on how you're performing the search, it will typically be
28084 * faster to call g_str_tokenize_and_fold() on each string in
28085 * your corpus and build an index on the returned folded tokens, then
28086 * call g_str_tokenize_and_fold() on the search term and
28087 * perform lookups into that index.
28089 * As some examples, searching for "fred" would match the potential hit
28090 * "Smith, Fred" and also "Frédéric". Searching for "Fréd" would match
28091 * "Frédéric" but not "Frederic" (due to the one-directional nature of
28092 * accent matching). Searching "fo" would match "Foo" and "Bar Foo
28093 * Baz", but not "SFO" (because no word as "fo" as a prefix).
28095 * Returns: %TRUE if @potential_hit is a hit
28102 * @str: a string, in UTF-8
28103 * @from_locale: (allow-none): the source locale, if known
28105 * Transliterate @str to plain ASCII.
28107 * For best results, @str should be in composed normalised form.
28109 * This function performs a reasonably good set of character
28110 * replacements. The particular set of replacements that is done may
28111 * change by version or even by runtime environment.
28113 * If the source language of @str is known, it can used to improve the
28114 * accuracy of the translation by passing it as @from_locale. It should
28115 * be a valid POSIX locale string (of the form
28116 * "language[_territory][.codeset][@modifier]").
28118 * If @from_locale is %NULL then the current locale is used.
28120 * If you want to do translation for no specific locale, and you want it
28121 * to be done independently of the currently locale, specify "C" for
28124 * Returns: a string in plain ASCII
28130 * g_str_tokenize_and_fold:
28131 * @string: a string
28132 * @translit_locale: (allow-none): the language code (like 'de' or
28133 * 'en_GB') from which @string originates
28134 * @ascii_alternates: (out) (transfer full) (array zero-terminated=1): a
28135 * return location for ASCII alternates
28137 * Tokenises @string and performs folding on each token.
28139 * A token is a non-empty sequence of alphanumeric characters in the
28140 * source string, separated by non-alphanumeric characters. An
28141 * "alphanumeric" character for this purpose is one that matches
28142 * g_unichar_isalnum() or g_unichar_ismark().
28144 * Each token is then (Unicode) normalised and case-folded. If
28145 * @ascii_alternates is non-%NULL and some of the returned tokens
28146 * contain non-ASCII characters, ASCII alternatives will be generated.
28148 * The number of ASCII alternatives that are generated and the method
28149 * for doing so is unspecified, but @translit_locale (if specified) may
28150 * improve the transliteration if the language of the source string is
28153 * Returns: (transfer full) (array zero-terminated=1): the folded tokens
28160 * @string: a nul-terminated array of bytes
28161 * @valid_chars: bytes permitted in @string
28162 * @substitutor: replacement character for disallowed bytes
28164 * For each character in @string, if the character is not in @valid_chars,
28165 * replaces the character with @substitutor. Modifies @string in place,
28166 * and return @string itself, not a copy. The return value is to allow
28168 * |[<!-- language="C" -->
28169 * g_ascii_strup (g_strcanon (str, "abc", '?'))
28179 * @s2: a string to compare with @s1
28181 * A case-insensitive string comparison, corresponding to the standard
28182 * strcasecmp() function on platforms which support it.
28184 * Returns: 0 if the strings match, a negative value if @s1 < @s2,
28185 * or a positive value if @s1 > @s2.
28186 * Deprecated: 2.2: See g_strncasecmp() for a discussion of why this
28187 * function is deprecated and how to replace it.
28193 * @string: a string to remove the trailing whitespace from
28195 * Removes trailing whitespace from a string.
28197 * This function doesn't allocate or reallocate any memory;
28198 * it modifies @string in place. Therefore, it cannot be used
28199 * on statically allocated strings.
28201 * The pointer to @string is returned to allow the nesting of functions.
28203 * Also see g_strchug() and g_strstrip().
28211 * @string: a string to remove the leading whitespace from
28213 * Removes leading whitespace from a string, by moving the rest
28214 * of the characters forward.
28216 * This function doesn't allocate or reallocate any memory;
28217 * it modifies @string in place. Therefore, it cannot be used on
28218 * statically allocated strings.
28220 * The pointer to @string is returned to allow the nesting of functions.
28222 * Also see g_strchomp() and g_strstrip().
28230 * @str1: (allow-none): a C string or %NULL
28231 * @str2: (allow-none): another C string or %NULL
28233 * Compares @str1 and @str2 like strcmp(). Handles %NULL
28234 * gracefully by sorting it before non-%NULL strings.
28235 * Comparing two %NULL pointers returns 0.
28237 * Returns: an integer less than, equal to, or greater than zero, if @str1 is <, == or > than @str2.
28244 * @source: a string to compress
28246 * Replaces all escaped characters with their one byte equivalent.
28248 * This function does the reverse conversion of g_strescape().
28250 * Returns: a newly-allocated copy of @source with all escaped
28251 * character compressed
28257 * @string1: the first string to add, which must not be %NULL
28258 * @...: a %NULL-terminated list of strings to append to the string
28260 * Concatenates all of the given strings into one long string. The
28261 * returned string should be freed with g_free() when no longer needed.
28263 * The variable argument list must end with %NULL. If you forget the %NULL,
28264 * g_strconcat() will start appending random memory junk to your string.
28266 * Note that this function is usually not the right function to use to
28267 * assemble a translated message from pieces, since proper translation
28268 * often requires the pieces to be reordered.
28270 * Returns: a newly-allocated string containing all the string arguments
28276 * @string: the string to convert
28277 * @delimiters: (allow-none): a string containing the current delimiters,
28278 * or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS
28279 * @new_delimiter: the new delimiter character
28281 * Converts any delimiter characters in @string to @new_delimiter.
28282 * Any characters in @string which are found in @delimiters are
28283 * changed to the @new_delimiter character. Modifies @string in place,
28284 * and returns @string itself, not a copy. The return value is to
28285 * allow nesting such as
28286 * |[<!-- language="C" -->
28287 * g_ascii_strup (g_strdelimit (str, "abc", '?'))
28296 * @string: the string to convert.
28298 * Converts a string to lower case.
28300 * Returns: the string
28301 * Deprecated: 2.2: This function is totally broken for the reasons discussed
28302 * in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown()
28309 * @str: (nullable): the string to duplicate
28311 * Duplicates a string. If @str is %NULL it returns %NULL.
28312 * The returned string should be freed with g_free()
28313 * when no longer needed.
28315 * Returns: a newly-allocated copy of @str
28321 * @format: a standard printf() format string, but notice
28322 * [string precision pitfalls][string-precision]
28323 * @...: the parameters to insert into the format string
28325 * Similar to the standard C sprintf() function but safer, since it
28326 * calculates the maximum space required and allocates memory to hold
28327 * the result. The returned string should be freed with g_free() when no
28330 * Returns: a newly-allocated string holding the result
28335 * g_strdup_vprintf:
28336 * @format: a standard printf() format string, but notice
28337 * [string precision pitfalls][string-precision]
28338 * @args: the list of parameters to insert into the format string
28340 * Similar to the standard C vsprintf() function but safer, since it
28341 * calculates the maximum space required and allocates memory to hold
28342 * the result. The returned string should be freed with g_free() when
28343 * no longer needed.
28345 * See also g_vasprintf(), which offers the same functionality, but
28346 * additionally returns the length of the allocated string.
28348 * Returns: a newly-allocated string holding the result
28354 * @str_array: (nullable): a %NULL-terminated array of strings
28356 * Copies %NULL-terminated array of strings. The copy is a deep copy;
28357 * the new array should be freed by first freeing each string, then
28358 * the array itself. g_strfreev() does this for you. If called
28359 * on a %NULL value, g_strdupv() simply returns %NULL.
28361 * Returns: (nullable): a new %NULL-terminated array of strings.
28367 * @errnum: the system error number. See the standard C %errno
28370 * Returns a string corresponding to the given error code, e.g. "no
28371 * such process". Unlike strerror(), this always returns a string in
28372 * UTF-8 encoding, and the pointer is guaranteed to remain valid for
28373 * the lifetime of the process.
28375 * Note that the string may be translated according to the current locale.
28377 * The value of %errno will not be changed by this function.
28379 * Returns: a UTF-8 string describing the error code. If the error code
28380 * is unknown, it returns a string like "unknown error (<code>)".
28386 * @source: a string to escape
28387 * @exceptions: (nullable): a string of characters not to escape in @source
28389 * Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
28390 * and '"' in the string @source by inserting a '\' before
28391 * them. Additionally all characters in the range 0x01-0x1F (everything
28392 * below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
28393 * replaced with a '\' followed by their octal representation.
28394 * Characters supplied in @exceptions are not escaped.
28396 * g_strcompress() does the reverse conversion.
28398 * Returns: a newly-allocated copy of @source with certain
28399 * characters escaped. See above.
28405 * @str_array: (nullable): a %NULL-terminated array of strings to free
28407 * Frees a %NULL-terminated array of strings, as well as each
28408 * string it contains.
28410 * If @str_array is %NULL, this function simply returns.
28416 * @string: a #GString
28417 * @val: the string to append onto the end of @string
28419 * Adds a string onto the end of a #GString, expanding
28422 * Returns: (transfer none): @string
28427 * g_string_append_c:
28428 * @string: a #GString
28429 * @c: the byte to append onto the end of @string
28431 * Adds a byte onto the end of a #GString, expanding
28434 * Returns: (transfer none): @string
28439 * g_string_append_len:
28440 * @string: a #GString
28441 * @val: bytes to append
28442 * @len: number of bytes of @val to use
28444 * Appends @len bytes of @val to @string. Because @len is
28445 * provided, @val may contain embedded nuls and need not
28446 * be nul-terminated.
28448 * Since this function does not stop at nul bytes, it is
28449 * the caller's responsibility to ensure that @val has at
28450 * least @len addressable bytes.
28452 * Returns: (transfer none): @string
28457 * g_string_append_printf:
28458 * @string: a #GString
28459 * @format: the string format. See the printf() documentation
28460 * @...: the parameters to insert into the format string
28462 * Appends a formatted string onto the end of a #GString.
28463 * This function is similar to g_string_printf() except
28464 * that the text is appended to the #GString.
28469 * g_string_append_unichar:
28470 * @string: a #GString
28471 * @wc: a Unicode character
28473 * Converts a Unicode character into UTF-8, and appends it
28476 * Returns: (transfer none): @string
28481 * g_string_append_uri_escaped:
28482 * @string: a #GString
28483 * @unescaped: a string
28484 * @reserved_chars_allowed: a string of reserved characters allowed
28485 * to be used, or %NULL
28486 * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters
28488 * Appends @unescaped to @string, escaped any characters that
28489 * are reserved in URIs using URI-style escape sequences.
28491 * Returns: (transfer none): @string
28497 * g_string_append_vprintf:
28498 * @string: a #GString
28499 * @format: the string format. See the printf() documentation
28500 * @args: the list of arguments to insert in the output
28502 * Appends a formatted string onto the end of a #GString.
28503 * This function is similar to g_string_append_printf()
28504 * except that the arguments to the format string are passed
28512 * g_string_ascii_down:
28513 * @string: a GString
28515 * Converts all uppercase ASCII letters to lowercase ASCII letters.
28517 * Returns: (transfer none): passed-in @string pointer, with all the
28518 * uppercase characters converted to lowercase in place,
28519 * with semantics that exactly match g_ascii_tolower().
28524 * g_string_ascii_up:
28525 * @string: a GString
28527 * Converts all lowercase ASCII letters to uppercase ASCII letters.
28529 * Returns: (transfer none): passed-in @string pointer, with all the
28530 * lowercase characters converted to uppercase in place,
28531 * with semantics that exactly match g_ascii_toupper().
28537 * @string: the destination #GString. Its current contents
28539 * @rval: the string to copy into @string
28541 * Copies the bytes from a string into a #GString,
28542 * destroying any previous contents. It is rather like
28543 * the standard strcpy() function, except that you do not
28544 * have to worry about having enough space to copy the string.
28546 * Returns: (transfer none): @string
28551 * g_string_chunk_clear:
28552 * @chunk: a #GStringChunk
28554 * Frees all strings contained within the #GStringChunk.
28555 * After calling g_string_chunk_clear() it is not safe to
28556 * access any of the strings which were contained within it.
28563 * g_string_chunk_free:
28564 * @chunk: a #GStringChunk
28566 * Frees all memory allocated by the #GStringChunk.
28567 * After calling g_string_chunk_free() it is not safe to
28568 * access any of the strings which were contained within it.
28573 * g_string_chunk_insert:
28574 * @chunk: a #GStringChunk
28575 * @string: the string to add
28577 * Adds a copy of @string to the #GStringChunk.
28578 * It returns a pointer to the new copy of the string
28579 * in the #GStringChunk. The characters in the string
28580 * can be changed, if necessary, though you should not
28581 * change anything after the end of the string.
28583 * Unlike g_string_chunk_insert_const(), this function
28584 * does not check for duplicates. Also strings added
28585 * with g_string_chunk_insert() will not be searched
28586 * by g_string_chunk_insert_const() when looking for
28589 * Returns: a pointer to the copy of @string within
28590 * the #GStringChunk
28595 * g_string_chunk_insert_const:
28596 * @chunk: a #GStringChunk
28597 * @string: the string to add
28599 * Adds a copy of @string to the #GStringChunk, unless the same
28600 * string has already been added to the #GStringChunk with
28601 * g_string_chunk_insert_const().
28603 * This function is useful if you need to copy a large number
28604 * of strings but do not want to waste space storing duplicates.
28605 * But you must remember that there may be several pointers to
28606 * the same string, and so any changes made to the strings
28607 * should be done very carefully.
28609 * Note that g_string_chunk_insert_const() will not return a
28610 * pointer to a string added with g_string_chunk_insert(), even
28611 * if they do match.
28613 * Returns: a pointer to the new or existing copy of @string
28614 * within the #GStringChunk
28619 * g_string_chunk_insert_len:
28620 * @chunk: a #GStringChunk
28621 * @string: bytes to insert
28622 * @len: number of bytes of @string to insert, or -1 to insert a
28623 * nul-terminated string
28625 * Adds a copy of the first @len bytes of @string to the #GStringChunk.
28626 * The copy is nul-terminated.
28628 * Since this function does not stop at nul bytes, it is the caller's
28629 * responsibility to ensure that @string has at least @len addressable
28632 * The characters in the returned string can be changed, if necessary,
28633 * though you should not change anything after the end of the string.
28635 * Returns: a pointer to the copy of @string within the #GStringChunk
28641 * g_string_chunk_new:
28642 * @size: the default size of the blocks of memory which are
28643 * allocated to store the strings. If a particular string
28644 * is larger than this default size, a larger block of
28645 * memory will be allocated for it.
28647 * Creates a new #GStringChunk.
28649 * Returns: a new #GStringChunk
28655 * @string: a #GString
28657 * Converts a #GString to lowercase.
28659 * Returns: (transfer none): the #GString
28660 * Deprecated: 2.2: This function uses the locale-specific
28661 * tolower() function, which is almost never the right thing.
28662 * Use g_string_ascii_down() or g_utf8_strdown() instead.
28669 * @v2: another #GString
28671 * Compares two strings for equality, returning %TRUE if they are equal.
28672 * For use with #GHashTable.
28674 * Returns: %TRUE if the strings are the same length and contain the
28681 * @string: a #GString
28682 * @pos: the position of the content to remove
28683 * @len: the number of bytes to remove, or -1 to remove all
28686 * Removes @len bytes from a #GString, starting at position @pos.
28687 * The rest of the #GString is shifted down to fill the gap.
28689 * Returns: (transfer none): @string
28695 * @string: (transfer full): a #GString
28696 * @free_segment: if %TRUE, the actual character data is freed as well
28698 * Frees the memory allocated for the #GString.
28699 * If @free_segment is %TRUE it also frees the character data. If
28700 * it's %FALSE, the caller gains ownership of the buffer and must
28701 * free it after use with g_free().
28703 * Returns: (nullable): the character data of @string
28704 * (i.e. %NULL if @free_segment is %TRUE)
28709 * g_string_free_to_bytes:
28710 * @string: (transfer full): a #GString
28712 * Transfers ownership of the contents of @string to a newly allocated
28713 * #GBytes. The #GString structure itself is deallocated, and it is
28714 * therefore invalid to use @string after invoking this function.
28716 * Note that while #GString ensures that its buffer always has a
28717 * trailing nul character (not reflected in its "len"), the returned
28718 * #GBytes does not include this extra nul; i.e. it has length exactly
28719 * equal to the "len" member.
28721 * Returns: (transfer full): A newly allocated #GBytes containing contents of @string; @string itself is freed
28728 * @str: a string to hash
28730 * Creates a hash code for @str; for use with #GHashTable.
28732 * Returns: hash code for @str
28738 * @string: a #GString
28739 * @pos: the position to insert the copy of the string
28740 * @val: the string to insert
28742 * Inserts a copy of a string into a #GString,
28743 * expanding it if necessary.
28745 * Returns: (transfer none): @string
28750 * g_string_insert_c:
28751 * @string: a #GString
28752 * @pos: the position to insert the byte
28753 * @c: the byte to insert
28755 * Inserts a byte into a #GString, expanding it if necessary.
28757 * Returns: (transfer none): @string
28762 * g_string_insert_len:
28763 * @string: a #GString
28764 * @pos: position in @string where insertion should
28765 * happen, or -1 for at the end
28766 * @val: bytes to insert
28767 * @len: number of bytes of @val to insert
28769 * Inserts @len bytes of @val into @string at @pos.
28770 * Because @len is provided, @val may contain embedded
28771 * nuls and need not be nul-terminated. If @pos is -1,
28772 * bytes are inserted at the end of the string.
28774 * Since this function does not stop at nul bytes, it is
28775 * the caller's responsibility to ensure that @val has at
28776 * least @len addressable bytes.
28778 * Returns: (transfer none): @string
28783 * g_string_insert_unichar:
28784 * @string: a #GString
28785 * @pos: the position at which to insert character, or -1
28786 * to append at the end of the string
28787 * @wc: a Unicode character
28789 * Converts a Unicode character into UTF-8, and insert it
28790 * into the string at the given position.
28792 * Returns: (transfer none): @string
28798 * @init: (nullable): the initial text to copy into the string, or %NULL to
28799 * start with an empty string
28801 * Creates a new #GString, initialized with the given string.
28803 * Returns: the new #GString
28808 * g_string_new_len:
28809 * @init: initial contents of the string
28810 * @len: length of @init to use
28812 * Creates a new #GString with @len bytes of the @init buffer.
28813 * Because a length is provided, @init need not be nul-terminated,
28814 * and can contain embedded nul bytes.
28816 * Since this function does not stop at nul bytes, it is the caller's
28817 * responsibility to ensure that @init has at least @len addressable
28820 * Returns: a new #GString
28825 * g_string_overwrite:
28826 * @string: a #GString
28827 * @pos: the position at which to start overwriting
28828 * @val: the string that will overwrite the @string starting at @pos
28830 * Overwrites part of a string, lengthening it if necessary.
28832 * Returns: (transfer none): @string
28838 * g_string_overwrite_len:
28839 * @string: a #GString
28840 * @pos: the position at which to start overwriting
28841 * @val: the string that will overwrite the @string starting at @pos
28842 * @len: the number of bytes to write from @val
28844 * Overwrites part of a string, lengthening it if necessary.
28845 * This function will work with embedded nuls.
28847 * Returns: (transfer none): @string
28853 * g_string_prepend:
28854 * @string: a #GString
28855 * @val: the string to prepend on the start of @string
28857 * Adds a string on to the start of a #GString,
28858 * expanding it if necessary.
28860 * Returns: (transfer none): @string
28865 * g_string_prepend_c:
28866 * @string: a #GString
28867 * @c: the byte to prepend on the start of the #GString
28869 * Adds a byte onto the start of a #GString,
28870 * expanding it if necessary.
28872 * Returns: (transfer none): @string
28877 * g_string_prepend_len:
28878 * @string: a #GString
28879 * @val: bytes to prepend
28880 * @len: number of bytes in @val to prepend
28882 * Prepends @len bytes of @val to @string.
28883 * Because @len is provided, @val may contain
28884 * embedded nuls and need not be nul-terminated.
28886 * Since this function does not stop at nul bytes,
28887 * it is the caller's responsibility to ensure that
28888 * @val has at least @len addressable bytes.
28890 * Returns: (transfer none): @string
28895 * g_string_prepend_unichar:
28896 * @string: a #GString
28897 * @wc: a Unicode character
28899 * Converts a Unicode character into UTF-8, and prepends it
28902 * Returns: (transfer none): @string
28908 * @string: a #GString
28909 * @format: the string format. See the printf() documentation
28910 * @...: the parameters to insert into the format string
28912 * Writes a formatted string into a #GString.
28913 * This is similar to the standard sprintf() function,
28914 * except that the #GString buffer automatically expands
28915 * to contain the results. The previous contents of the
28916 * #GString are destroyed.
28921 * g_string_set_size:
28922 * @string: a #GString
28923 * @len: the new length
28925 * Sets the length of a #GString. If the length is less than
28926 * the current length, the string will be truncated. If the
28927 * length is greater than the current length, the contents
28928 * of the newly added area are undefined. (However, as
28929 * always, string->str[string->len] will be a nul byte.)
28931 * Returns: (transfer none): @string
28936 * g_string_sized_new:
28937 * @dfl_size: the default size of the space allocated to
28940 * Creates a new #GString, with enough space for @dfl_size
28941 * bytes. This is useful if you are going to add a lot of
28942 * text to the string and don't want it to be reallocated
28945 * Returns: the new #GString
28950 * g_string_sprintf:
28951 * @string: a #GString
28952 * @format: the string format. See the sprintf() documentation
28953 * @...: the parameters to insert into the format string
28955 * Writes a formatted string into a #GString.
28956 * This is similar to the standard sprintf() function,
28957 * except that the #GString buffer automatically expands
28958 * to contain the results. The previous contents of the
28959 * #GString are destroyed.
28961 * Deprecated: This function has been renamed to g_string_printf().
28966 * g_string_sprintfa:
28967 * @string: a #GString
28968 * @format: the string format. See the sprintf() documentation
28969 * @...: the parameters to insert into the format string
28971 * Appends a formatted string onto the end of a #GString.
28972 * This function is similar to g_string_sprintf() except that
28973 * the text is appended to the #GString.
28975 * Deprecated: This function has been renamed to g_string_append_printf()
28980 * g_string_truncate:
28981 * @string: a #GString
28982 * @len: the new size of @string
28984 * Cuts off the end of the GString, leaving the first @len bytes.
28986 * Returns: (transfer none): @string
28992 * @string: a #GString
28994 * Converts a #GString to uppercase.
28996 * Returns: (transfer none): @string
28997 * Deprecated: 2.2: This function uses the locale-specific
28998 * toupper() function, which is almost never the right thing.
28999 * Use g_string_ascii_up() or g_utf8_strup() instead.
29004 * g_string_vprintf:
29005 * @string: a #GString
29006 * @format: the string format. See the printf() documentation
29007 * @args: the parameters to insert into the format string
29009 * Writes a formatted string into a #GString.
29010 * This function is similar to g_string_printf() except that
29011 * the arguments to the format string are passed as a va_list.
29020 * @msgval: another string
29022 * An auxiliary function for gettext() support (see Q_()).
29024 * Returns: @msgval, unless @msgval is identical to @msgid
29025 * and contains a '|' character, in which case a pointer to
29026 * the substring of msgid after the first '|' character is returned.
29033 * @separator: (allow-none): a string to insert between each of the
29034 * strings, or %NULL
29035 * @...: a %NULL-terminated list of strings to join
29037 * Joins a number of strings together to form one long string, with the
29038 * optional @separator inserted between each of them. The returned string
29039 * should be freed with g_free().
29041 * Returns: a newly-allocated string containing all of the strings joined
29042 * together, with @separator between them
29048 * @separator: (allow-none): a string to insert between each of the
29049 * strings, or %NULL
29050 * @str_array: a %NULL-terminated array of strings to join
29052 * Joins a number of strings together to form one long string, with the
29053 * optional @separator inserted between each of them. The returned string
29054 * should be freed with g_free().
29056 * If @str_array has no items, the return value will be an
29057 * empty string. If @str_array contains a single item, @separator will not
29058 * appear in the resulting string.
29060 * Returns: a newly-allocated string containing all of the strings joined
29061 * together, with @separator between them
29067 * @dest: destination buffer, already containing one nul-terminated string
29068 * @src: source buffer
29069 * @dest_size: length of @dest buffer in bytes (not length of existing string
29072 * Portability wrapper that calls strlcat() on systems which have it,
29073 * and emulates it otherwise. Appends nul-terminated @src string to @dest,
29074 * guaranteeing nul-termination for @dest. The total size of @dest won't
29075 * exceed @dest_size.
29077 * At most @dest_size - 1 characters will be copied. Unlike strncat(),
29078 * @dest_size is the full size of dest, not the space left over. This
29079 * function does not allocate memory. It always nul-terminates (unless
29080 * @dest_size == 0 or there were no nul characters in the @dest_size
29081 * characters of dest to start with).
29083 * Caveat: this is supposedly a more secure alternative to strcat() or
29084 * strncat(), but for real security g_strconcat() is harder to mess up.
29086 * Returns: size of attempted result, which is MIN (dest_size, strlen
29087 * (original dest)) + strlen (src), so if retval >= dest_size,
29088 * truncation occurred.
29094 * @dest: destination buffer
29095 * @src: source buffer
29096 * @dest_size: length of @dest in bytes
29098 * Portability wrapper that calls strlcpy() on systems which have it,
29099 * and emulates strlcpy() otherwise. Copies @src to @dest; @dest is
29100 * guaranteed to be nul-terminated; @src must be nul-terminated;
29101 * @dest_size is the buffer size, not the number of bytes to copy.
29103 * At most @dest_size - 1 characters will be copied. Always nul-terminates
29104 * (unless @dest_size is 0). This function does not allocate memory. Unlike
29105 * strncpy(), this function doesn't pad @dest (so it's often faster). It
29106 * returns the size of the attempted result, strlen (src), so if
29107 * @retval >= @dest_size, truncation occurred.
29109 * Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(),
29110 * but if you really want to avoid screwups, g_strdup() is an even better
29113 * Returns: length of @src
29120 * @s2: a string to compare with @s1
29121 * @n: the maximum number of characters to compare
29123 * A case-insensitive string comparison, corresponding to the standard
29124 * strncasecmp() function on platforms which support it. It is similar
29125 * to g_strcasecmp() except it only compares the first @n characters of
29128 * Returns: 0 if the strings match, a negative value if @s1 < @s2,
29129 * or a positive value if @s1 > @s2.
29130 * Deprecated: 2.2: The problem with g_strncasecmp() is that it does
29131 * the comparison by calling toupper()/tolower(). These functions
29132 * are locale-specific and operate on single bytes. However, it is
29133 * impossible to handle things correctly from an internationalization
29134 * standpoint by operating on bytes, since characters may be multibyte.
29135 * Thus g_strncasecmp() is broken if your string is guaranteed to be
29136 * ASCII, since it is locale-sensitive, and it's broken if your string
29137 * is localized, since it doesn't work on many encodings at all,
29138 * including UTF-8, EUC-JP, etc.
29140 * There are therefore two replacement techniques: g_ascii_strncasecmp(),
29141 * which only works on ASCII and is not locale-sensitive, and
29142 * g_utf8_casefold() followed by strcmp() on the resulting strings,
29143 * which is good for case-insensitive sorting of UTF-8.
29149 * @str: the string to duplicate
29150 * @n: the maximum number of bytes to copy from @str
29152 * Duplicates the first @n bytes of a string, returning a newly-allocated
29153 * buffer @n + 1 bytes long which will always be nul-terminated. If @str
29154 * is less than @n bytes long the buffer is padded with nuls. If @str is
29155 * %NULL it returns %NULL. The returned value should be freed when no longer
29158 * To copy a number of characters from a UTF-8 encoded string,
29159 * use g_utf8_strncpy() instead.
29161 * Returns: a newly-allocated buffer containing the first @n bytes
29162 * of @str, nul-terminated
29168 * @length: the length of the new string
29169 * @fill_char: the byte to fill the string with
29171 * Creates a new string @length bytes long filled with @fill_char.
29172 * The returned string should be freed when no longer needed.
29174 * Returns: a newly-allocated string filled the @fill_char
29180 * @string: the string to reverse
29182 * Reverses all of the bytes in a string. For example,
29183 * `g_strreverse ("abcdef")` will result in "fedcba".
29185 * Note that g_strreverse() doesn't work on UTF-8 strings
29186 * containing multibyte characters. For that purpose, use
29187 * g_utf8_strreverse().
29189 * Returns: the same pointer passed in as @string
29195 * @haystack: a nul-terminated string
29196 * @needle: the nul-terminated string to search for
29198 * Searches the string @haystack for the last occurrence
29199 * of the string @needle.
29201 * Returns: a pointer to the found occurrence, or
29202 * %NULL if not found.
29208 * @haystack: a nul-terminated string
29209 * @haystack_len: the maximum length of @haystack
29210 * @needle: the nul-terminated string to search for
29212 * Searches the string @haystack for the last occurrence
29213 * of the string @needle, limiting the length of the search
29214 * to @haystack_len.
29216 * Returns: a pointer to the found occurrence, or
29217 * %NULL if not found.
29223 * @signum: the signal number. See the `signal` documentation
29225 * Returns a string describing the given signal, e.g. "Segmentation fault".
29226 * You should use this function in preference to strsignal(), because it
29227 * returns a string in UTF-8 encoding, and since not all platforms support
29228 * the strsignal() function.
29230 * Returns: a UTF-8 string describing the signal. If the signal is unknown,
29231 * it returns "unknown signal (<signum>)".
29237 * @string: a string to split
29238 * @delimiter: a string which specifies the places at which to split
29239 * the string. The delimiter is not included in any of the resulting
29240 * strings, unless @max_tokens is reached.
29241 * @max_tokens: the maximum number of pieces to split @string into.
29242 * If this is less than 1, the string is split completely.
29244 * Splits a string into a maximum of @max_tokens pieces, using the given
29245 * @delimiter. If @max_tokens is reached, the remainder of @string is
29246 * appended to the last token.
29248 * As an example, the result of g_strsplit (":a:bc::d:", ":", -1) is a
29249 * %NULL-terminated vector containing the six strings "", "a", "bc", "", "d"
29252 * As a special case, the result of splitting the empty string "" is an empty
29253 * vector, not a vector containing a single string. The reason for this
29254 * special case is that being able to represent a empty vector is typically
29255 * more useful than consistent handling of empty elements. If you do need
29256 * to represent empty elements, you'll need to check for the empty string
29257 * before calling g_strsplit().
29259 * Returns: a newly-allocated %NULL-terminated array of strings. Use
29260 * g_strfreev() to free it.
29266 * @string: The string to be tokenized
29267 * @delimiters: A nul-terminated string containing bytes that are used
29268 * to split the string.
29269 * @max_tokens: The maximum number of tokens to split @string into.
29270 * If this is less than 1, the string is split completely
29272 * Splits @string into a number of tokens not containing any of the characters
29273 * in @delimiter. A token is the (possibly empty) longest string that does not
29274 * contain any of the characters in @delimiters. If @max_tokens is reached, the
29275 * remainder is appended to the last token.
29277 * For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a
29278 * %NULL-terminated vector containing the three strings "abc", "def",
29281 * The result of g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated
29282 * vector containing the four strings "", "def", "ghi", and "".
29284 * As a special case, the result of splitting the empty string "" is an empty
29285 * vector, not a vector containing a single string. The reason for this
29286 * special case is that being able to represent a empty vector is typically
29287 * more useful than consistent handling of empty elements. If you do need
29288 * to represent empty elements, you'll need to check for the empty string
29289 * before calling g_strsplit_set().
29291 * Note that this function works on bytes not characters, so it can't be used
29292 * to delimit UTF-8 strings for anything but ASCII characters.
29294 * Returns: a newly-allocated %NULL-terminated array of strings. Use
29295 * g_strfreev() to free it.
29302 * @haystack: a string
29303 * @haystack_len: the maximum length of @haystack. Note that -1 is
29304 * a valid length, if @haystack is nul-terminated, meaning it will
29305 * search through the whole string.
29306 * @needle: the string to search for
29308 * Searches the string @haystack for the first occurrence
29309 * of the string @needle, limiting the length of the search
29310 * to @haystack_len.
29312 * Returns: a pointer to the found occurrence, or
29313 * %NULL if not found.
29319 * @string: a string to remove the leading and trailing whitespace from
29321 * Removes leading and trailing whitespace from a string.
29322 * See g_strchomp() and g_strchug().
29330 * @nptr: the string to convert to a numeric value.
29331 * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the
29332 * character after the last character used in the conversion.
29334 * Converts a string to a #gdouble value.
29335 * It calls the standard strtod() function to handle the conversion, but
29336 * if the string is not completely converted it attempts the conversion
29337 * again with g_ascii_strtod(), and returns the best match.
29339 * This function should seldom be used. The normal situation when reading
29340 * numbers not for human consumption is to use g_ascii_strtod(). Only when
29341 * you know that you must expect both locale formatted and C formatted numbers
29342 * should you use this. Make sure that you don't pass strings such as comma
29343 * separated lists of values, since the commas may be interpreted as a decimal
29344 * point in some locales, causing unexpected results.
29346 * Returns: the #gdouble value.
29352 * @string: the string to convert
29354 * Converts a string to upper case.
29356 * Returns: the string
29357 * Deprecated: 2.2: This function is totally broken for the reasons
29358 * discussed in the g_strncasecmp() docs - use g_ascii_strup()
29359 * or g_utf8_strup() instead.
29365 * @strv: a %NULL-terminated array of strings
29368 * Checks if @strv contains @str. @strv must not be %NULL.
29370 * Returns: %TRUE if @str is an element of @strv, according to g_str_equal().
29377 * @str_array: a %NULL-terminated array of strings
29379 * Returns the length of the given %NULL-terminated
29380 * string array @str_array.
29382 * Returns: length of @str_array.
29389 * @testpath: The test path for a new test case.
29390 * @Fixture: The type of a fixture data structure.
29391 * @tdata: Data argument for the test functions.
29392 * @fsetup: The function to set up the fixture data.
29393 * @ftest: The actual test function.
29394 * @fteardown: The function to tear down the fixture data.
29396 * Hook up a new test case at @testpath, similar to g_test_add_func().
29397 * A fixture data structure with setup and teardown functions may be provided,
29398 * similar to g_test_create_case().
29400 * g_test_add() is implemented as a macro, so that the fsetup(), ftest() and
29401 * fteardown() callbacks can expect a @Fixture pointer as their first argument
29402 * in a type safe manner. They otherwise have type #GTestFixtureFunc.
29409 * g_test_add_data_func:
29410 * @testpath: /-separated test case path name for the test.
29411 * @test_data: Test data argument for the test function.
29412 * @test_func: (scope async): The test function to invoke for this test.
29414 * Create a new test case, similar to g_test_create_case(). However
29415 * the test is assumed to use no fixture, and test suites are automatically
29416 * created on the fly and added to the root fixture, based on the
29417 * slash-separated portions of @testpath. The @test_data argument
29418 * will be passed as first argument to @test_func.
29420 * If @testpath includes the component "subprocess" anywhere in it,
29421 * the test will be skipped by default, and only run if explicitly
29422 * required via the `-p` command-line option or g_test_trap_subprocess().
29429 * g_test_add_data_func_full:
29430 * @testpath: /-separated test case path name for the test.
29431 * @test_data: Test data argument for the test function.
29432 * @test_func: The test function to invoke for this test.
29433 * @data_free_func: #GDestroyNotify for @test_data.
29435 * Create a new test case, as with g_test_add_data_func(), but freeing
29436 * @test_data after the test run is complete.
29444 * @testpath: /-separated test case path name for the test.
29445 * @test_func: (scope async): The test function to invoke for this test.
29447 * Create a new test case, similar to g_test_create_case(). However
29448 * the test is assumed to use no fixture, and test suites are automatically
29449 * created on the fly and added to the root fixture, based on the
29450 * slash-separated portions of @testpath.
29452 * If @testpath includes the component "subprocess" anywhere in it,
29453 * the test will be skipped by default, and only run if explicitly
29454 * required via the `-p` command-line option or g_test_trap_subprocess().
29461 * g_test_assert_expected_messages:
29463 * Asserts that all messages previously indicated via
29464 * g_test_expect_message() have been seen and suppressed.
29466 * If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly
29467 * expected via g_test_expect_message() then they will be ignored.
29475 * @bug_uri_snippet: Bug specific bug tracker URI portion.
29477 * This function adds a message to test reports that
29478 * associates a bug URI with a test case.
29479 * Bug URIs are constructed from a base URI set with g_test_bug_base()
29480 * and @bug_uri_snippet.
29488 * @uri_pattern: the base pattern for bug URIs
29490 * Specify the base URI for bug reports.
29492 * The base URI is used to construct bug report messages for
29493 * g_test_message() when g_test_bug() is called.
29494 * Calling this function outside of a test case sets the
29495 * default base URI for all test cases. Calling it from within
29496 * a test case changes the base URI for the scope of the test
29498 * Bug URIs are constructed by appending a bug specific URI
29499 * portion to @uri_pattern, or by replacing the special string
29500 * '\%s' within @uri_pattern if that is present.
29507 * g_test_build_filename:
29508 * @file_type: the type of file (built vs. distributed)
29509 * @first_path: the first segment of the pathname
29510 * @...: %NULL-terminated additional path segments
29512 * Creates the pathname to a data file that is required for a test.
29514 * This function is conceptually similar to g_build_filename() except
29515 * that the first argument has been replaced with a #GTestFileType
29518 * The data file should either have been distributed with the module
29519 * containing the test (%G_TEST_DIST) or built as part of the build
29520 * system of that module (%G_TEST_BUILT).
29522 * In order for this function to work in srcdir != builddir situations,
29523 * the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to
29524 * have been defined. As of 2.38, this is done by the glib.mk
29525 * included in GLib. Please ensure that your copy is up to date before
29526 * using this function.
29528 * In case neither variable is set, this function will fall back to
29529 * using the dirname portion of argv[0], possibly removing ".libs".
29530 * This allows for casual running of tests directly from the commandline
29531 * in the srcdir == builddir case and should also support running of
29532 * installed tests, assuming the data files have been installed in the
29533 * same relative path as the test binary.
29535 * Returns: the path of the file, to be freed using g_free()
29541 * g_test_create_case:
29542 * @test_name: the name for the test case
29543 * @data_size: the size of the fixture data structure
29544 * @test_data: test data argument for the test functions
29545 * @data_setup: (scope async): the function to set up the fixture data
29546 * @data_test: (scope async): the actual test function
29547 * @data_teardown: (scope async): the function to teardown the fixture data
29549 * Create a new #GTestCase, named @test_name, this API is fairly
29550 * low level, calling g_test_add() or g_test_add_func() is preferable.
29551 * When this test is executed, a fixture structure of size @data_size
29552 * will be automatically allocated and filled with zeros. Then @data_setup is
29553 * called to initialize the fixture. After fixture setup, the actual test
29554 * function @data_test is called. Once the test run completes, the
29555 * fixture structure is torn down by calling @data_teardown and
29556 * after that the memory is automatically released by the test framework.
29558 * Splitting up a test run into fixture setup, test function and
29559 * fixture teardown is most useful if the same fixture is used for
29560 * multiple tests. In this cases, g_test_create_case() will be
29561 * called with the same fixture, but varying @test_name and
29562 * @data_test arguments.
29564 * Returns: a newly allocated #GTestCase.
29570 * g_test_create_suite:
29571 * @suite_name: a name for the suite
29573 * Create a new test suite with the name @suite_name.
29575 * Returns: A newly allocated #GTestSuite instance.
29581 * g_test_expect_message:
29582 * @log_domain: (allow-none): the log domain of the message
29583 * @log_level: the log level of the message
29584 * @pattern: a glob-style [pattern][glib-Glob-style-pattern-matching]
29586 * Indicates that a message with the given @log_domain and @log_level,
29587 * with text matching @pattern, is expected to be logged. When this
29588 * message is logged, it will not be printed, and the test case will
29591 * Use g_test_assert_expected_messages() to assert that all
29592 * previously-expected messages have been seen and suppressed.
29594 * You can call this multiple times in a row, if multiple messages are
29595 * expected as a result of a single call. (The messages must appear in
29596 * the same order as the calls to g_test_expect_message().)
29600 * |[<!-- language="C" -->
29601 * // g_main_context_push_thread_default() should fail if the
29602 * // context is already owned by another thread.
29603 * g_test_expect_message (G_LOG_DOMAIN,
29604 * G_LOG_LEVEL_CRITICAL,
29605 * "assertion*acquired_context*failed");
29606 * g_main_context_push_thread_default (bad_context);
29607 * g_test_assert_expected_messages ();
29610 * Note that you cannot use this to test g_error() messages, since
29611 * g_error() intentionally never returns even if the program doesn't
29612 * abort; use g_test_trap_subprocess() in this case.
29614 * If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly
29615 * expected via g_test_expect_message() then they will be ignored.
29624 * Indicates that a test failed. This function can be called
29625 * multiple times from the same test. You can use this function
29626 * if your test failed in a recoverable way.
29628 * Do not use this function if the failure of a test could cause
29629 * other tests to malfunction.
29631 * Calling this function will not stop the test from running, you
29632 * need to return from the test function yourself. So you can
29633 * produce additional diagnostic messages or even continue running
29636 * If not called from inside a test, this function does nothing.
29645 * Returns whether a test has already failed. This will
29646 * be the case when g_test_fail(), g_test_incomplete()
29647 * or g_test_skip() have been called, but also if an
29648 * assertion has failed.
29650 * This can be useful to return early from a test if
29651 * continuing after a failed assertion might be harmful.
29653 * The return value of this function is only meaningful
29654 * if it is called from inside a test function.
29656 * Returns: %TRUE if the test has failed
29663 * @file_type: the type of file (built vs. distributed)
29665 * Gets the pathname of the directory containing test files of the type
29666 * specified by @file_type.
29668 * This is approximately the same as calling g_test_build_filename("."),
29669 * but you don't need to free the return value.
29671 * Returns: (type filename): the path of the directory, owned by GLib
29677 * g_test_get_filename:
29678 * @file_type: the type of file (built vs. distributed)
29679 * @first_path: the first segment of the pathname
29680 * @...: %NULL-terminated additional path segments
29682 * Gets the pathname to a data file that is required for a test.
29684 * This is the same as g_test_build_filename() with two differences.
29685 * The first difference is that must only use this function from within
29686 * a testcase function. The second difference is that you need not free
29687 * the return value -- it will be automatically freed when the testcase
29688 * finishes running.
29690 * It is safe to use this function from a thread inside of a testcase
29691 * but you must ensure that all such uses occur before the main testcase
29692 * function returns (ie: it is best to ensure that all threads have been
29695 * Returns: the path, automatically freed at the end of the testcase
29703 * Get the toplevel test suite for the test path API.
29705 * Returns: the toplevel #GTestSuite
29711 * g_test_incomplete:
29712 * @msg: (allow-none): explanation
29714 * Indicates that a test failed because of some incomplete
29715 * functionality. This function can be called multiple times
29716 * from the same test.
29718 * Calling this function will not stop the test from running, you
29719 * need to return from the test function yourself. So you can
29720 * produce additional diagnostic messages or even continue running
29723 * If not called from inside a test, this function does nothing.
29731 * @argc: Address of the @argc parameter of the main() function.
29732 * Changed if any arguments were handled.
29733 * @argv: Address of the @argv parameter of main().
29734 * Any parameters understood by g_test_init() stripped before return.
29735 * @...: %NULL-terminated list of special options. Currently the only
29736 * defined option is `"no_g_set_prgname"`, which
29737 * will cause g_test_init() to not call g_set_prgname().
29739 * Initialize the GLib testing framework, e.g. by seeding the
29740 * test random number generator, the name for g_get_prgname()
29741 * and parsing test related command line args.
29743 * So far, the following arguments are understood:
29745 * - `-l`: List test cases available in a test executable.
29746 * - `--seed=SEED`: Provide a random seed to reproduce test
29747 * runs using random numbers.
29748 * - `--verbose`: Run tests verbosely.
29749 * - `-q`, `--quiet`: Run tests quietly.
29750 * - `-p PATH`: Execute all tests matching the given path.
29751 * This can also be used to force a test to run that would otherwise
29752 * be skipped (ie, a test whose name contains "/subprocess").
29753 * - `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes:
29755 * `perf`: Performance tests, may take long and report results.
29757 * `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage.
29759 * `quick`: Quick tests, should run really quickly and give good coverage.
29761 * `undefined`: Tests for undefined behaviour, may provoke programming errors
29762 * under g_test_trap_subprocess() or g_test_expect_messages() to check
29763 * that appropriate assertions or warnings are given
29765 * `no-undefined`: Avoid tests for undefined behaviour
29767 * - `--debug-log`: Debug test logging output.
29774 * g_test_initialized:
29776 * Returns %TRUE if g_test_init() has been called.
29778 * Returns: %TRUE if g_test_init() has been called.
29784 * g_test_log_buffer_free:
29786 * Internal function for gtester to free test log messages, no ABI guarantees provided.
29791 * g_test_log_buffer_new:
29793 * Internal function for gtester to decode test log messages, no ABI guarantees provided.
29798 * g_test_log_buffer_pop:
29800 * Internal function for gtester to retrieve test log messages, no ABI guarantees provided.
29805 * g_test_log_buffer_push:
29807 * Internal function for gtester to decode test log messages, no ABI guarantees provided.
29812 * g_test_log_msg_free:
29814 * Internal function for gtester to free test log messages, no ABI guarantees provided.
29819 * g_test_log_set_fatal_handler:
29820 * @log_func: the log handler function.
29821 * @user_data: data passed to the log handler.
29823 * Installs a non-error fatal log handler which can be
29824 * used to decide whether log messages which are counted
29825 * as fatal abort the program.
29827 * The use case here is that you are running a test case
29828 * that depends on particular libraries or circumstances
29829 * and cannot prevent certain known critical or warning
29830 * messages. So you install a handler that compares the
29831 * domain and message to precisely not abort in such a case.
29833 * Note that the handler is reset at the beginning of
29834 * any test case, so you have to set it inside each test
29835 * function which needs the special behavior.
29837 * This handler has no effect on g_error messages.
29839 * This handler also has no effect on structured log messages (using
29840 * g_log_structured() or g_log_structured_array()). To change the fatal
29841 * behaviour for specific log messages, programs must install a custom log
29842 * writer function using g_log_set_writer_func().
29849 * g_test_maximized_result:
29850 * @maximized_quantity: the reported value
29851 * @format: the format string of the report message
29852 * @...: arguments to pass to the printf() function
29854 * Report the result of a performance or measurement test.
29855 * The test should generally strive to maximize the reported
29856 * quantities (larger values are better than smaller ones),
29857 * this and @maximized_quantity can determine sorting
29858 * order for test result reports.
29866 * @format: the format string
29867 * @...: printf-like arguments to @format
29869 * Add a message to the test report.
29876 * g_test_minimized_result:
29877 * @minimized_quantity: the reported value
29878 * @format: the format string of the report message
29879 * @...: arguments to pass to the printf() function
29881 * Report the result of a performance or measurement test.
29882 * The test should generally strive to minimize the reported
29883 * quantities (smaller values are better than larger ones),
29884 * this and @minimized_quantity can determine sorting
29885 * order for test result reports.
29894 * Returns %TRUE if tests are run in performance mode.
29896 * Returns: %TRUE if in performance mode
29901 * g_test_queue_destroy:
29902 * @destroy_func: Destroy callback for teardown phase.
29903 * @destroy_data: Destroy callback data.
29905 * This function enqueus a callback @destroy_func to be executed
29906 * during the next test case teardown phase. This is most useful
29907 * to auto destruct allocted test resources at the end of a test run.
29908 * Resources are released in reverse queue order, that means enqueueing
29909 * callback A before callback B will cause B() to be called before
29910 * A() during teardown.
29917 * g_test_queue_free:
29918 * @gfree_pointer: the pointer to be stored.
29920 * Enqueue a pointer to be released with g_free() during the next
29921 * teardown phase. This is equivalent to calling g_test_queue_destroy()
29922 * with a destroy callback of g_free().
29929 * g_test_queue_unref:
29930 * @gobject: the object to unref
29932 * Enqueue an object to be released with g_object_unref() during
29933 * the next teardown phase. This is equivalent to calling
29934 * g_test_queue_destroy() with a destroy callback of g_object_unref().
29943 * Returns %TRUE if tests are run in quick mode.
29944 * Exactly one of g_test_quick() and g_test_slow() is active in any run;
29945 * there is no "medium speed".
29947 * Returns: %TRUE if in quick mode
29954 * Returns %TRUE if tests are run in quiet mode.
29955 * The default is neither g_test_verbose() nor g_test_quiet().
29957 * Returns: %TRUE if in quiet mode
29964 * Get a reproducible random bit (0 or 1), see g_test_rand_int()
29965 * for details on test case random numbers.
29972 * g_test_rand_double:
29974 * Get a reproducible random floating point number,
29975 * see g_test_rand_int() for details on test case random numbers.
29977 * Returns: a random number from the seeded random number generator.
29983 * g_test_rand_double_range:
29984 * @range_start: the minimum value returned by this function
29985 * @range_end: the minimum value not returned by this function
29987 * Get a reproducible random floating pointer number out of a specified range,
29988 * see g_test_rand_int() for details on test case random numbers.
29990 * Returns: a number with @range_start <= number < @range_end.
29998 * Get a reproducible random integer number.
30000 * The random numbers generated by the g_test_rand_*() family of functions
30001 * change with every new test program start, unless the --seed option is
30002 * given when starting test programs.
30004 * For individual test cases however, the random number generator is
30005 * reseeded, to avoid dependencies between tests and to make --seed
30006 * effective for all test cases.
30008 * Returns: a random number from the seeded random number generator.
30014 * g_test_rand_int_range:
30015 * @begin: the minimum value returned by this function
30016 * @end: the smallest value not to be returned by this function
30018 * Get a reproducible random integer number out of a specified range,
30019 * see g_test_rand_int() for details on test case random numbers.
30021 * Returns: a number with @begin <= number < @end.
30029 * Runs all tests under the toplevel suite which can be retrieved
30030 * with g_test_get_root(). Similar to g_test_run_suite(), the test
30031 * cases to be run are filtered according to test path arguments
30032 * (`-p testpath`) as parsed by g_test_init(). g_test_run_suite()
30033 * or g_test_run() may only be called once in a program.
30035 * In general, the tests and sub-suites within each suite are run in
30036 * the order in which they are defined. However, note that prior to
30037 * GLib 2.36, there was a bug in the `g_test_add_*`
30038 * functions which caused them to create multiple suites with the same
30039 * name, meaning that if you created tests "/foo/simple",
30040 * "/bar/simple", and "/foo/using-bar" in that order, they would get
30041 * run in that order (since g_test_run() would run the first "/foo"
30042 * suite, then the "/bar" suite, then the second "/foo" suite). As of
30043 * 2.36, this bug is fixed, and adding the tests in that order would
30044 * result in a running order of "/foo/simple", "/foo/using-bar",
30045 * "/bar/simple". If this new ordering is sub-optimal (because it puts
30046 * more-complicated tests before simpler ones, making it harder to
30047 * figure out exactly what has failed), you can fix it by changing the
30048 * test paths to group tests by suite in a way that will result in the
30049 * desired running order. Eg, "/simple/foo", "/simple/bar",
30050 * "/complex/foo-using-bar".
30052 * However, you should never make the actual result of a test depend
30053 * on the order that tests are run in. If you need to ensure that some
30054 * particular code runs before or after a given test case, use
30055 * g_test_add(), which lets you specify setup and teardown functions.
30057 * If all tests are skipped, this function will return 0 if
30058 * producing TAP output, or 77 (treated as "skip test" by Automake) otherwise.
30060 * Returns: 0 on success, 1 on failure (assuming it returns at all),
30061 * 0 or 77 if all tests were skipped with g_test_skip()
30067 * g_test_run_suite:
30068 * @suite: a #GTestSuite
30070 * Execute the tests within @suite and all nested #GTestSuites.
30071 * The test suites to be executed are filtered according to
30072 * test path arguments (`-p testpath`) as parsed by g_test_init().
30073 * See the g_test_run() documentation for more information on the
30074 * order that tests are run in.
30076 * g_test_run_suite() or g_test_run() may only be called once
30079 * Returns: 0 on success
30085 * g_test_set_nonfatal_assertions:
30087 * Changes the behaviour of g_assert_cmpstr(), g_assert_cmpint(),
30088 * g_assert_cmpuint(), g_assert_cmphex(), g_assert_cmpfloat(),
30089 * g_assert_true(), g_assert_false(), g_assert_null(), g_assert_no_error(),
30090 * g_assert_error(), g_test_assert_expected_messages() and the various
30091 * g_test_trap_assert_*() macros to not abort to program, but instead
30092 * call g_test_fail() and continue. (This also changes the behavior of
30093 * g_test_fail() so that it will not cause the test program to abort
30094 * after completing the failed test.)
30096 * Note that the g_assert_not_reached() and g_assert() are not
30097 * affected by this.
30099 * This function can only be called after g_test_init().
30107 * @msg: (allow-none): explanation
30109 * Indicates that a test was skipped.
30111 * Calling this function will not stop the test from running, you
30112 * need to return from the test function yourself. So you can
30113 * produce additional diagnostic messages or even continue running
30116 * If not called from inside a test, this function does nothing.
30125 * Returns %TRUE if tests are run in slow mode.
30126 * Exactly one of g_test_quick() and g_test_slow() is active in any run;
30127 * there is no "medium speed".
30129 * Returns: the opposite of g_test_quick()
30134 * g_test_subprocess:
30136 * Returns %TRUE (after g_test_init() has been called) if the test
30137 * program is running under g_test_trap_subprocess().
30139 * Returns: %TRUE if the test program is running under
30140 * g_test_trap_subprocess().
30146 * g_test_suite_add:
30147 * @suite: a #GTestSuite
30148 * @test_case: a #GTestCase
30150 * Adds @test_case to @suite.
30157 * g_test_suite_add_suite:
30158 * @suite: a #GTestSuite
30159 * @nestedsuite: another #GTestSuite
30161 * Adds @nestedsuite to @suite.
30170 * Returns %TRUE if tests are run in thorough mode, equivalent to
30173 * Returns: the same thing as g_test_slow()
30178 * g_test_timer_elapsed:
30180 * Get the time since the last start of the timer with g_test_timer_start().
30182 * Returns: the time since the last start of the timer, as a double
30188 * g_test_timer_last:
30190 * Report the last result of g_test_timer_elapsed().
30192 * Returns: the last result of g_test_timer_elapsed(), as a double
30198 * g_test_timer_start:
30200 * Start a timing test. Call g_test_timer_elapsed() when the task is supposed
30201 * to be done. Call this function again to restart the timer.
30208 * g_test_trap_assert_failed:
30210 * Assert that the last test subprocess failed.
30211 * See g_test_trap_subprocess().
30213 * This is sometimes used to test situations that are formally considered to
30214 * be undefined behaviour, like inputs that fail a g_return_if_fail()
30215 * check. In these situations you should skip the entire test, including the
30216 * call to g_test_trap_subprocess(), unless g_test_undefined() returns %TRUE
30217 * to indicate that undefined behaviour may be tested.
30224 * g_test_trap_assert_passed:
30226 * Assert that the last test subprocess passed.
30227 * See g_test_trap_subprocess().
30234 * g_test_trap_assert_stderr:
30235 * @serrpattern: a glob-style [pattern][glib-Glob-style-pattern-matching]
30237 * Assert that the stderr output of the last test subprocess
30238 * matches @serrpattern. See g_test_trap_subprocess().
30240 * This is sometimes used to test situations that are formally
30241 * considered to be undefined behaviour, like code that hits a
30242 * g_assert() or g_error(). In these situations you should skip the
30243 * entire test, including the call to g_test_trap_subprocess(), unless
30244 * g_test_undefined() returns %TRUE to indicate that undefined
30245 * behaviour may be tested.
30252 * g_test_trap_assert_stderr_unmatched:
30253 * @serrpattern: a glob-style [pattern][glib-Glob-style-pattern-matching]
30255 * Assert that the stderr output of the last test subprocess
30256 * does not match @serrpattern. See g_test_trap_subprocess().
30263 * g_test_trap_assert_stdout:
30264 * @soutpattern: a glob-style [pattern][glib-Glob-style-pattern-matching]
30266 * Assert that the stdout output of the last test subprocess matches
30267 * @soutpattern. See g_test_trap_subprocess().
30274 * g_test_trap_assert_stdout_unmatched:
30275 * @soutpattern: a glob-style [pattern][glib-Glob-style-pattern-matching]
30277 * Assert that the stdout output of the last test subprocess
30278 * does not match @soutpattern. See g_test_trap_subprocess().
30285 * g_test_trap_fork:
30286 * @usec_timeout: Timeout for the forked test in micro seconds.
30287 * @test_trap_flags: Flags to modify forking behaviour.
30289 * Fork the current test program to execute a test case that might
30290 * not return or that might abort.
30292 * If @usec_timeout is non-0, the forked test case is aborted and
30293 * considered failing if its run time exceeds it.
30295 * The forking behavior can be configured with the #GTestTrapFlags flags.
30297 * In the following example, the test code forks, the forked child
30298 * process produces some sample output and exits successfully.
30299 * The forking parent process then asserts successful child program
30300 * termination and validates child program outputs.
30302 * |[<!-- language="C" -->
30304 * test_fork_patterns (void)
30306 * if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR))
30308 * g_print ("some stdout text: somagic17\n");
30309 * g_printerr ("some stderr text: semagic43\n");
30310 * exit (0); // successful test run
30312 * g_test_trap_assert_passed ();
30313 * g_test_trap_assert_stdout ("*somagic17*");
30314 * g_test_trap_assert_stderr ("*semagic43*");
30318 * Returns: %TRUE for the forked child and %FALSE for the executing parent process.
30320 * Deprecated: This function is implemented only on Unix platforms,
30321 * and is not always reliable due to problems inherent in
30322 * fork-without-exec. Use g_test_trap_subprocess() instead.
30327 * g_test_trap_has_passed:
30329 * Check the result of the last g_test_trap_subprocess() call.
30331 * Returns: %TRUE if the last test subprocess terminated successfully.
30337 * g_test_trap_reached_timeout:
30339 * Check the result of the last g_test_trap_subprocess() call.
30341 * Returns: %TRUE if the last test subprocess got killed due to a timeout.
30347 * g_test_trap_subprocess:
30348 * @test_path: (allow-none): Test to run in a subprocess
30349 * @usec_timeout: Timeout for the subprocess test in micro seconds.
30350 * @test_flags: Flags to modify subprocess behaviour.
30352 * Respawns the test program to run only @test_path in a subprocess.
30353 * This can be used for a test case that might not return, or that
30356 * If @test_path is %NULL then the same test is re-run in a subprocess.
30357 * You can use g_test_subprocess() to determine whether the test is in
30358 * a subprocess or not.
30360 * @test_path can also be the name of the parent test, followed by
30361 * "`/subprocess/`" and then a name for the specific subtest (or just
30362 * ending with "`/subprocess`" if the test only has one child test);
30363 * tests with names of this form will automatically be skipped in the
30366 * If @usec_timeout is non-0, the test subprocess is aborted and
30367 * considered failing if its run time exceeds it.
30369 * The subprocess behavior can be configured with the
30370 * #GTestSubprocessFlags flags.
30372 * You can use methods such as g_test_trap_assert_passed(),
30373 * g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to
30374 * check the results of the subprocess. (But note that
30375 * g_test_trap_assert_stdout() and g_test_trap_assert_stderr()
30376 * cannot be used if @test_flags specifies that the child should
30377 * inherit the parent stdout/stderr.)
30379 * If your `main ()` needs to behave differently in
30380 * the subprocess, you can call g_test_subprocess() (after calling
30381 * g_test_init()) to see whether you are in a subprocess.
30383 * The following example tests that calling
30384 * `my_object_new(1000000)` will abort with an error
30387 * |[<!-- language="C" -->
30389 * test_create_large_object (void)
30391 * if (g_test_subprocess ())
30393 * my_object_new (1000000);
30397 * // Reruns this same test in a subprocess
30398 * g_test_trap_subprocess (NULL, 0, 0);
30399 * g_test_trap_assert_failed ();
30400 * g_test_trap_assert_stderr ("*ERROR*too large*");
30404 * main (int argc, char **argv)
30406 * g_test_init (&argc, &argv, NULL);
30408 * g_test_add_func ("/myobject/create_large_object",
30409 * test_create_large_object);
30410 * return g_test_run ();
30419 * g_test_undefined:
30421 * Returns %TRUE if tests may provoke assertions and other formally-undefined
30422 * behaviour, to verify that appropriate warnings are given. It might, in some
30423 * cases, be useful to turn this off if running tests under valgrind.
30425 * Returns: %TRUE if tests may provoke programming errors
30432 * Returns %TRUE if tests are run in verbose mode.
30433 * The default is neither g_test_verbose() nor g_test_quiet().
30435 * Returns: %TRUE if in verbose mode
30441 * @retval: the return value of this thread
30443 * Terminates the current thread.
30445 * If another thread is waiting for us using g_thread_join() then the
30446 * waiting thread will be woken up and get @retval as the return value
30447 * of g_thread_join().
30449 * Calling g_thread_exit() with a parameter @retval is equivalent to
30450 * returning @retval from the function @func, as given to g_thread_new().
30452 * You must only call g_thread_exit() from a thread that you created
30453 * yourself with g_thread_new() or related APIs. You must not call
30454 * this function from a thread created with another threading library
30455 * or or from within a #GThreadPool.
30461 * @thread: a #GThread
30463 * Waits until @thread finishes, i.e. the function @func, as
30464 * given to g_thread_new(), returns or g_thread_exit() is called.
30465 * If @thread has already terminated, then g_thread_join()
30466 * returns immediately.
30468 * Any thread can wait for any other thread by calling g_thread_join(),
30469 * not just its 'creator'. Calling g_thread_join() from multiple threads
30470 * for the same @thread leads to undefined behaviour.
30472 * The value returned by @func or given to g_thread_exit() is
30473 * returned by this function.
30475 * g_thread_join() consumes the reference to the passed-in @thread.
30476 * This will usually cause the #GThread struct and associated resources
30477 * to be freed. Use g_thread_ref() to obtain an extra reference if you
30478 * want to keep the GThread alive beyond the g_thread_join() call.
30480 * Returns: the return value of the thread
30486 * @name: (allow-none): an (optional) name for the new thread
30487 * @func: a function to execute in the new thread
30488 * @data: an argument to supply to the new thread
30490 * This function creates a new thread. The new thread starts by invoking
30491 * @func with the argument data. The thread will run until @func returns
30492 * or until g_thread_exit() is called from the new thread. The return value
30493 * of @func becomes the return value of the thread, which can be obtained
30494 * with g_thread_join().
30496 * The @name can be useful for discriminating threads in a debugger.
30497 * It is not used for other purposes and does not have to be unique.
30498 * Some systems restrict the length of @name to 16 bytes.
30500 * If the thread can not be created the program aborts. See
30501 * g_thread_try_new() if you want to attempt to deal with failures.
30503 * If you are using threads to offload (potentially many) short-lived tasks,
30504 * #GThreadPool may be more appropriate than manually spawning and tracking
30505 * multiple #GThreads.
30507 * To free the struct returned by this function, use g_thread_unref().
30508 * Note that g_thread_join() implicitly unrefs the #GThread as well.
30510 * Returns: the new #GThread
30516 * g_thread_pool_free:
30517 * @pool: a #GThreadPool
30518 * @immediate: should @pool shut down immediately?
30519 * @wait_: should the function wait for all tasks to be finished?
30521 * Frees all resources allocated for @pool.
30523 * If @immediate is %TRUE, no new task is processed for @pool.
30524 * Otherwise @pool is not freed before the last task is processed.
30525 * Note however, that no thread of this pool is interrupted while
30526 * processing a task. Instead at least all still running threads
30527 * can finish their tasks before the @pool is freed.
30529 * If @wait_ is %TRUE, the functions does not return before all
30530 * tasks to be processed (dependent on @immediate, whether all
30531 * or only the currently running) are ready.
30532 * Otherwise the function returns immediately.
30534 * After calling this function @pool must not be used anymore.
30539 * g_thread_pool_get_max_idle_time:
30541 * This function will return the maximum @interval that a
30542 * thread will wait in the thread pool for new tasks before
30545 * If this function returns 0, threads waiting in the thread
30546 * pool for new work are not stopped.
30548 * Returns: the maximum @interval (milliseconds) to wait
30549 * for new tasks in the thread pool before stopping the
30556 * g_thread_pool_get_max_threads:
30557 * @pool: a #GThreadPool
30559 * Returns the maximal number of threads for @pool.
30561 * Returns: the maximal number of threads
30566 * g_thread_pool_get_max_unused_threads:
30568 * Returns the maximal allowed number of unused threads.
30570 * Returns: the maximal number of unused threads
30575 * g_thread_pool_get_num_threads:
30576 * @pool: a #GThreadPool
30578 * Returns the number of threads currently running in @pool.
30580 * Returns: the number of threads currently running
30585 * g_thread_pool_get_num_unused_threads:
30587 * Returns the number of currently unused threads.
30589 * Returns: the number of currently unused threads
30594 * g_thread_pool_move_to_front:
30595 * @pool: a #GThreadPool
30596 * @data: an unprocessed item in the pool
30598 * Moves the item to the front of the queue of unprocessed
30599 * items, so that it will be processed next.
30601 * Returns: %TRUE if the item was found and moved
30607 * g_thread_pool_new:
30608 * @func: a function to execute in the threads of the new thread pool
30609 * @user_data: user data that is handed over to @func every time it
30611 * @max_threads: the maximal number of threads to execute concurrently
30612 * in the new thread pool, -1 means no limit
30613 * @exclusive: should this thread pool be exclusive?
30614 * @error: return location for error, or %NULL
30616 * This function creates a new thread pool.
30618 * Whenever you call g_thread_pool_push(), either a new thread is
30619 * created or an unused one is reused. At most @max_threads threads
30620 * are running concurrently for this thread pool. @max_threads = -1
30621 * allows unlimited threads to be created for this thread pool. The
30622 * newly created or reused thread now executes the function @func
30623 * with the two arguments. The first one is the parameter to
30624 * g_thread_pool_push() and the second one is @user_data.
30626 * The parameter @exclusive determines whether the thread pool owns
30627 * all threads exclusive or shares them with other thread pools.
30628 * If @exclusive is %TRUE, @max_threads threads are started
30629 * immediately and they will run exclusively for this thread pool
30630 * until it is destroyed by g_thread_pool_free(). If @exclusive is
30631 * %FALSE, threads are created when needed and shared between all
30632 * non-exclusive thread pools. This implies that @max_threads may
30633 * not be -1 for exclusive thread pools. Besides, exclusive thread
30634 * pools are not affected by g_thread_pool_set_max_idle_time()
30635 * since their threads are never considered idle and returned to the
30638 * @error can be %NULL to ignore errors, or non-%NULL to report
30639 * errors. An error can only occur when @exclusive is set to %TRUE
30640 * and not all @max_threads threads could be created.
30641 * See #GThreadError for possible errors that may occur.
30642 * Note, even in case of error a valid #GThreadPool is returned.
30644 * Returns: the new #GThreadPool
30649 * g_thread_pool_push:
30650 * @pool: a #GThreadPool
30651 * @data: a new task for @pool
30652 * @error: return location for error, or %NULL
30654 * Inserts @data into the list of tasks to be executed by @pool.
30656 * When the number of currently running threads is lower than the
30657 * maximal allowed number of threads, a new thread is started (or
30658 * reused) with the properties given to g_thread_pool_new().
30659 * Otherwise, @data stays in the queue until a thread in this pool
30660 * finishes its previous task and processes @data.
30662 * @error can be %NULL to ignore errors, or non-%NULL to report
30663 * errors. An error can only occur when a new thread couldn't be
30664 * created. In that case @data is simply appended to the queue of
30667 * Before version 2.32, this function did not return a success status.
30669 * Returns: %TRUE on success, %FALSE if an error occurred
30674 * g_thread_pool_set_max_idle_time:
30675 * @interval: the maximum @interval (in milliseconds)
30676 * a thread can be idle
30678 * This function will set the maximum @interval that a thread
30679 * waiting in the pool for new tasks can be idle for before
30680 * being stopped. This function is similar to calling
30681 * g_thread_pool_stop_unused_threads() on a regular timeout,
30682 * except this is done on a per thread basis.
30684 * By setting @interval to 0, idle threads will not be stopped.
30686 * The default value is 15000 (15 seconds).
30693 * g_thread_pool_set_max_threads:
30694 * @pool: a #GThreadPool
30695 * @max_threads: a new maximal number of threads for @pool,
30696 * or -1 for unlimited
30697 * @error: return location for error, or %NULL
30699 * Sets the maximal allowed number of threads for @pool.
30700 * A value of -1 means that the maximal number of threads
30701 * is unlimited. If @pool is an exclusive thread pool, setting
30702 * the maximal number of threads to -1 is not allowed.
30704 * Setting @max_threads to 0 means stopping all work for @pool.
30705 * It is effectively frozen until @max_threads is set to a non-zero
30708 * A thread is never terminated while calling @func, as supplied by
30709 * g_thread_pool_new(). Instead the maximal number of threads only
30710 * has effect for the allocation of new threads in g_thread_pool_push().
30711 * A new thread is allocated, whenever the number of currently
30712 * running threads in @pool is smaller than the maximal number.
30714 * @error can be %NULL to ignore errors, or non-%NULL to report
30715 * errors. An error can only occur when a new thread couldn't be
30718 * Before version 2.32, this function did not return a success status.
30720 * Returns: %TRUE on success, %FALSE if an error occurred
30725 * g_thread_pool_set_max_unused_threads:
30726 * @max_threads: maximal number of unused threads
30728 * Sets the maximal number of unused threads to @max_threads.
30729 * If @max_threads is -1, no limit is imposed on the number
30730 * of unused threads.
30732 * The default value is 2.
30737 * g_thread_pool_set_sort_function:
30738 * @pool: a #GThreadPool
30739 * @func: the #GCompareDataFunc used to sort the list of tasks.
30740 * This function is passed two tasks. It should return
30741 * 0 if the order in which they are handled does not matter,
30742 * a negative value if the first task should be processed before
30743 * the second or a positive value if the second task should be
30745 * @user_data: user data passed to @func
30747 * Sets the function used to sort the list of tasks. This allows the
30748 * tasks to be processed by a priority determined by @func, and not
30749 * just in the order in which they were added to the pool.
30751 * Note, if the maximum number of threads is more than 1, the order
30752 * that threads are executed cannot be guaranteed 100%. Threads are
30753 * scheduled by the operating system and are executed at random. It
30754 * cannot be assumed that threads are executed in the order they are
30762 * g_thread_pool_stop_unused_threads:
30764 * Stops all currently unused threads. This does not change the
30765 * maximal number of unused threads. This function can be used to
30766 * regularly stop all unused threads e.g. from g_timeout_add().
30771 * g_thread_pool_unprocessed:
30772 * @pool: a #GThreadPool
30774 * Returns the number of tasks still unprocessed in @pool.
30776 * Returns: the number of unprocessed tasks
30782 * @thread: a #GThread
30784 * Increase the reference count on @thread.
30786 * Returns: a new reference to @thread
30794 * This function returns the #GThread corresponding to the
30795 * current thread. Note that this function does not increase
30796 * the reference count of the returned struct.
30798 * This function will return a #GThread even for threads that
30799 * were not created by GLib (i.e. those created by other threading
30800 * APIs). This may be useful for thread identification purposes
30801 * (i.e. comparisons) but you must not use GLib functions (such
30802 * as g_thread_join()) on these threads.
30804 * Returns: the #GThread representing the current thread
30809 * g_thread_supported:
30811 * This macro returns %TRUE if the thread system is initialized,
30812 * and %FALSE if it is not.
30814 * For language bindings, g_thread_get_initialized() provides
30815 * the same functionality as a function.
30817 * Returns: %TRUE, if the thread system is initialized
30822 * g_thread_try_new:
30823 * @name: (allow-none): an (optional) name for the new thread
30824 * @func: a function to execute in the new thread
30825 * @data: an argument to supply to the new thread
30826 * @error: return location for error, or %NULL
30828 * This function is the same as g_thread_new() except that
30829 * it allows for the possibility of failure.
30831 * If a thread can not be created (due to resource limits),
30832 * @error is set and %NULL is returned.
30834 * Returns: the new #GThread, or %NULL if an error occurred
30841 * @thread: a #GThread
30843 * Decrease the reference count on @thread, possibly freeing all
30844 * resources associated with it.
30846 * Note that each thread holds a reference to its #GThread while
30847 * it is running, so it is safe to drop your own reference to it
30848 * if you don't need it anymore.
30857 * Causes the calling thread to voluntarily relinquish the CPU, so
30858 * that other threads can run.
30860 * This function is often used as a method to make busy wait less evil.
30866 * @time_: a #GTimeVal
30867 * @microseconds: number of microseconds to add to @time
30869 * Adds the given number of microseconds to @time_. @microseconds can
30870 * also be negative to decrease the value of @time_.
30875 * g_time_val_from_iso8601:
30876 * @iso_date: an ISO 8601 encoded date string
30877 * @time_: (out): a #GTimeVal
30879 * Converts a string containing an ISO 8601 encoded date and time
30880 * to a #GTimeVal and puts it into @time_.
30882 * @iso_date must include year, month, day, hours, minutes, and
30883 * seconds. It can optionally include fractions of a second and a time
30884 * zone indicator. (In the absence of any time zone indication, the
30885 * timestamp is assumed to be in local time.)
30887 * Returns: %TRUE if the conversion was successful.
30893 * g_time_val_to_iso8601:
30894 * @time_: a #GTimeVal
30896 * Converts @time_ into an RFC 3339 encoded string, relative to the
30897 * Coordinated Universal Time (UTC). This is one of the many formats
30898 * allowed by ISO 8601.
30900 * ISO 8601 allows a large number of date/time formats, with or without
30901 * punctuation and optional elements. The format returned by this function
30902 * is a complete date and time, with optional punctuation included, the
30903 * UTC time zone represented as "Z", and the @tv_usec part included if
30904 * and only if it is nonzero, i.e. either
30905 * "YYYY-MM-DDTHH:MM:SSZ" or "YYYY-MM-DDTHH:MM:SS.fffffZ".
30907 * This corresponds to the Internet date/time format defined by
30908 * [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt),
30909 * and to either of the two most-precise formats defined by
30911 * [Date and Time Formats](http://www.w3.org/TR/NOTE-datetime-19980827).
30912 * Both of these documents are profiles of ISO 8601.
30914 * Use g_date_time_format() or g_strdup_printf() if a different
30915 * variation of ISO 8601 format is required.
30917 * Returns: a newly allocated string containing an ISO 8601 date
30923 * g_time_zone_adjust_time:
30924 * @tz: a #GTimeZone
30925 * @type: the #GTimeType of @time_
30926 * @time_: a pointer to a number of seconds since January 1, 1970
30928 * Finds an interval within @tz that corresponds to the given @time_,
30929 * possibly adjusting @time_ if required to fit into an interval.
30930 * The meaning of @time_ depends on @type.
30932 * This function is similar to g_time_zone_find_interval(), with the
30933 * difference that it always succeeds (by making the adjustments
30934 * described below).
30936 * In any of the cases where g_time_zone_find_interval() succeeds then
30937 * this function returns the same value, without modifying @time_.
30939 * This function may, however, modify @time_ in order to deal with
30940 * non-existent times. If the non-existent local @time_ of 02:30 were
30941 * requested on March 14th 2010 in Toronto then this function would
30942 * adjust @time_ to be 03:00 and return the interval containing the
30945 * Returns: the interval containing @time_, never -1
30951 * g_time_zone_find_interval:
30952 * @tz: a #GTimeZone
30953 * @type: the #GTimeType of @time_
30954 * @time_: a number of seconds since January 1, 1970
30956 * Finds an the interval within @tz that corresponds to the given @time_.
30957 * The meaning of @time_ depends on @type.
30959 * If @type is %G_TIME_TYPE_UNIVERSAL then this function will always
30960 * succeed (since universal time is monotonic and continuous).
30962 * Otherwise @time_ is treated as local time. The distinction between
30963 * %G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in
30964 * the case that the given @time_ is ambiguous. In Toronto, for example,
30965 * 01:30 on November 7th 2010 occurred twice (once inside of daylight
30966 * savings time and the next, an hour later, outside of daylight savings
30967 * time). In this case, the different value of @type would result in a
30968 * different interval being returned.
30970 * It is still possible for this function to fail. In Toronto, for
30971 * example, 02:00 on March 14th 2010 does not exist (due to the leap
30972 * forward to begin daylight savings time). -1 is returned in that
30975 * Returns: the interval containing @time_, or -1 in case of failure
30981 * g_time_zone_get_abbreviation:
30982 * @tz: a #GTimeZone
30983 * @interval: an interval within the timezone
30985 * Determines the time zone abbreviation to be used during a particular
30986 * @interval of time in the time zone @tz.
30988 * For example, in Toronto this is currently "EST" during the winter
30989 * months and "EDT" during the summer months when daylight savings time
30992 * Returns: the time zone abbreviation, which belongs to @tz
30998 * g_time_zone_get_offset:
30999 * @tz: a #GTimeZone
31000 * @interval: an interval within the timezone
31002 * Determines the offset to UTC in effect during a particular @interval
31003 * of time in the time zone @tz.
31005 * The offset is the number of seconds that you add to UTC time to
31006 * arrive at local time for @tz (ie: negative numbers for time zones
31007 * west of GMT, positive numbers for east).
31009 * Returns: the number of seconds that should be added to UTC to get the
31010 * local time in @tz
31016 * g_time_zone_is_dst:
31017 * @tz: a #GTimeZone
31018 * @interval: an interval within the timezone
31020 * Determines if daylight savings time is in effect during a particular
31021 * @interval of time in the time zone @tz.
31023 * Returns: %TRUE if daylight savings time is in effect
31030 * @identifier: (allow-none): a timezone identifier
31032 * Creates a #GTimeZone corresponding to @identifier.
31034 * @identifier can either be an RFC3339/ISO 8601 time offset or
31035 * something that would pass as a valid value for the `TZ` environment
31036 * variable (including %NULL).
31038 * In Windows, @identifier can also be the unlocalized name of a time
31039 * zone for standard time, for example "Pacific Standard Time".
31041 * Valid RFC3339 time offsets are `"Z"` (for UTC) or
31042 * `"±hh:mm"`. ISO 8601 additionally specifies
31043 * `"±hhmm"` and `"±hh"`. Offsets are
31044 * time values to be added to Coordinated Universal Time (UTC) to get
31047 * In UNIX, the `TZ` environment variable typically corresponds
31048 * to the name of a file in the zoneinfo database, or string in
31049 * "std offset [dst [offset],start[/time],end[/time]]" (POSIX) format.
31050 * There are no spaces in the specification. The name of standard
31051 * and daylight savings time zone must be three or more alphabetic
31052 * characters. Offsets are time values to be added to local time to
31053 * get Coordinated Universal Time (UTC) and should be
31054 * `"[±]hh[[:]mm[:ss]]"`. Dates are either
31055 * `"Jn"` (Julian day with n between 1 and 365, leap
31056 * years not counted), `"n"` (zero-based Julian day
31057 * with n between 0 and 365) or `"Mm.w.d"` (day d
31058 * (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day
31059 * 0 is a Sunday). Times are in local wall clock time, the default is
31062 * In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also
31063 * accepts POSIX format. The Windows format uses US rules for all time
31064 * zones; daylight savings time is 60 minutes behind the standard time
31065 * with date and time of change taken from Pacific Standard Time.
31066 * Offsets are time values to be added to the local time to get
31067 * Coordinated Universal Time (UTC).
31069 * g_time_zone_new_local() calls this function with the value of the
31070 * `TZ` environment variable. This function itself is independent of
31071 * the value of `TZ`, but if @identifier is %NULL then `/etc/localtime`
31072 * will be consulted to discover the correct time zone on UNIX and the
31073 * registry will be consulted or GetTimeZoneInformation() will be used
31074 * to get the local time zone on Windows.
31076 * If intervals are not available, only time zone rules from `TZ`
31077 * environment variable or other means, then they will be computed
31078 * from year 1900 to 2037. If the maximum year for the rules is
31079 * available and it is greater than 2037, then it will followed
31083 * [RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6)
31084 * for a precise definition of valid RFC3339 time offsets
31085 * (the `time-offset` expansion) and ISO 8601 for the
31086 * full list of valid time offsets. See
31087 * [The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html)
31088 * for an explanation of the possible
31089 * values of the `TZ` environment variable. See
31090 * [Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx)
31091 * for the list of time zones on Windows.
31093 * You should release the return value by calling g_time_zone_unref()
31094 * when you are done with it.
31096 * Returns: the requested timezone
31102 * g_time_zone_new_local:
31104 * Creates a #GTimeZone corresponding to local time. The local time
31105 * zone may change between invocations to this function; for example,
31106 * if the system administrator changes it.
31108 * This is equivalent to calling g_time_zone_new() with the value of
31109 * the `TZ` environment variable (including the possibility of %NULL).
31111 * You should release the return value by calling g_time_zone_unref()
31112 * when you are done with it.
31114 * Returns: the local timezone
31120 * g_time_zone_new_utc:
31122 * Creates a #GTimeZone corresponding to UTC.
31124 * This is equivalent to calling g_time_zone_new() with a value like
31125 * "Z", "UTC", "+00", etc.
31127 * You should release the return value by calling g_time_zone_unref()
31128 * when you are done with it.
31130 * Returns: the universal timezone
31137 * @tz: a #GTimeZone
31139 * Increases the reference count on @tz.
31141 * Returns: a new reference to @tz.
31147 * g_time_zone_unref:
31148 * @tz: a #GTimeZone
31150 * Decreases the reference count on @tz.
31158 * @interval: the time between calls to the function, in milliseconds
31159 * (1/1000ths of a second)
31160 * @function: function to call
31161 * @data: data to pass to @function
31163 * Sets a function to be called at regular intervals, with the default
31164 * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly
31165 * until it returns %FALSE, at which point the timeout is automatically
31166 * destroyed and the function will not be called again. The first call
31167 * to the function will be at the end of the first @interval.
31169 * Note that timeout functions may be delayed, due to the processing of other
31170 * event sources. Thus they should not be relied on for precise timing.
31171 * After each call to the timeout function, the time of the next
31172 * timeout is recalculated based on the current time and the given interval
31173 * (it does not try to 'catch up' time lost in delays).
31175 * See [memory management of sources][mainloop-memory-management] for details
31176 * on how to handle the return value and memory management of @data.
31178 * If you want to have a timer in the "seconds" range and do not care
31179 * about the exact time of the first call of the timer, use the
31180 * g_timeout_add_seconds() function; this function allows for more
31181 * optimizations and more efficient system power usage.
31183 * This internally creates a main loop source using g_timeout_source_new()
31184 * and attaches it to the global #GMainContext using g_source_attach(), so
31185 * the callback will be invoked in whichever thread is running that main
31186 * context. You can do these steps manually if you need greater control or to
31187 * use a custom main context.
31189 * The interval given is in terms of monotonic time, not wall clock
31190 * time. See g_get_monotonic_time().
31192 * Returns: the ID (greater than 0) of the event source.
31197 * g_timeout_add_full: (rename-to g_timeout_add)
31198 * @priority: the priority of the timeout source. Typically this will be in
31199 * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
31200 * @interval: the time between calls to the function, in milliseconds
31201 * (1/1000ths of a second)
31202 * @function: function to call
31203 * @data: data to pass to @function
31204 * @notify: (allow-none): function to call when the timeout is removed, or %NULL
31206 * Sets a function to be called at regular intervals, with the given
31207 * priority. The function is called repeatedly until it returns
31208 * %FALSE, at which point the timeout is automatically destroyed and
31209 * the function will not be called again. The @notify function is
31210 * called when the timeout is destroyed. The first call to the
31211 * function will be at the end of the first @interval.
31213 * Note that timeout functions may be delayed, due to the processing of other
31214 * event sources. Thus they should not be relied on for precise timing.
31215 * After each call to the timeout function, the time of the next
31216 * timeout is recalculated based on the current time and the given interval
31217 * (it does not try to 'catch up' time lost in delays).
31219 * See [memory management of sources][mainloop-memory-management] for details
31220 * on how to handle the return value and memory management of @data.
31222 * This internally creates a main loop source using g_timeout_source_new()
31223 * and attaches it to the global #GMainContext using g_source_attach(), so
31224 * the callback will be invoked in whichever thread is running that main
31225 * context. You can do these steps manually if you need greater control or to
31226 * use a custom main context.
31228 * The interval given in terms of monotonic time, not wall clock time.
31229 * See g_get_monotonic_time().
31231 * Returns: the ID (greater than 0) of the event source.
31236 * g_timeout_add_seconds:
31237 * @interval: the time between calls to the function, in seconds
31238 * @function: function to call
31239 * @data: data to pass to @function
31241 * Sets a function to be called at regular intervals with the default
31242 * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until
31243 * it returns %FALSE, at which point the timeout is automatically destroyed
31244 * and the function will not be called again.
31246 * This internally creates a main loop source using
31247 * g_timeout_source_new_seconds() and attaches it to the main loop context
31248 * using g_source_attach(). You can do these steps manually if you need
31249 * greater control. Also see g_timeout_add_seconds_full().
31251 * Note that the first call of the timer may not be precise for timeouts
31252 * of one second. If you need finer precision and have such a timeout,
31253 * you may want to use g_timeout_add() instead.
31255 * See [memory management of sources][mainloop-memory-management] for details
31256 * on how to handle the return value and memory management of @data.
31258 * The interval given is in terms of monotonic time, not wall clock
31259 * time. See g_get_monotonic_time().
31261 * Returns: the ID (greater than 0) of the event source.
31267 * g_timeout_add_seconds_full: (rename-to g_timeout_add_seconds)
31268 * @priority: the priority of the timeout source. Typically this will be in
31269 * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
31270 * @interval: the time between calls to the function, in seconds
31271 * @function: function to call
31272 * @data: data to pass to @function
31273 * @notify: (allow-none): function to call when the timeout is removed, or %NULL
31275 * Sets a function to be called at regular intervals, with @priority.
31276 * The function is called repeatedly until it returns %FALSE, at which
31277 * point the timeout is automatically destroyed and the function will
31278 * not be called again.
31280 * Unlike g_timeout_add(), this function operates at whole second granularity.
31281 * The initial starting point of the timer is determined by the implementation
31282 * and the implementation is expected to group multiple timers together so that
31283 * they fire all at the same time.
31284 * To allow this grouping, the @interval to the first timer is rounded
31285 * and can deviate up to one second from the specified interval.
31286 * Subsequent timer iterations will generally run at the specified interval.
31288 * Note that timeout functions may be delayed, due to the processing of other
31289 * event sources. Thus they should not be relied on for precise timing.
31290 * After each call to the timeout function, the time of the next
31291 * timeout is recalculated based on the current time and the given @interval
31293 * See [memory management of sources][mainloop-memory-management] for details
31294 * on how to handle the return value and memory management of @data.
31296 * If you want timing more precise than whole seconds, use g_timeout_add()
31299 * The grouping of timers to fire at the same time results in a more power
31300 * and CPU efficient behavior so if your timer is in multiples of seconds
31301 * and you don't require the first timer exactly one second from now, the
31302 * use of g_timeout_add_seconds() is preferred over g_timeout_add().
31304 * This internally creates a main loop source using
31305 * g_timeout_source_new_seconds() and attaches it to the main loop context
31306 * using g_source_attach(). You can do these steps manually if you need
31309 * The interval given is in terms of monotonic time, not wall clock
31310 * time. See g_get_monotonic_time().
31312 * Returns: the ID (greater than 0) of the event source.
31318 * g_timeout_source_new:
31319 * @interval: the timeout interval in milliseconds.
31321 * Creates a new timeout source.
31323 * The source will not initially be associated with any #GMainContext
31324 * and must be added to one with g_source_attach() before it will be
31327 * The interval given is in terms of monotonic time, not wall clock
31328 * time. See g_get_monotonic_time().
31330 * Returns: the newly-created timeout source
31335 * g_timeout_source_new_seconds:
31336 * @interval: the timeout interval in seconds
31338 * Creates a new timeout source.
31340 * The source will not initially be associated with any #GMainContext
31341 * and must be added to one with g_source_attach() before it will be
31344 * The scheduling granularity/accuracy of this timeout source will be
31347 * The interval given in terms of monotonic time, not wall clock time.
31348 * See g_get_monotonic_time().
31350 * Returns: the newly-created timeout source
31356 * g_timer_continue:
31357 * @timer: a #GTimer.
31359 * Resumes a timer that has previously been stopped with
31360 * g_timer_stop(). g_timer_stop() must be called before using this
31369 * @timer: a #GTimer to destroy.
31371 * Destroys a timer, freeing associated resources.
31377 * @timer: a #GTimer.
31378 * @microseconds: return location for the fractional part of seconds
31379 * elapsed, in microseconds (that is, the total number
31380 * of microseconds elapsed, modulo 1000000), or %NULL
31382 * If @timer has been started but not stopped, obtains the time since
31383 * the timer was started. If @timer has been stopped, obtains the
31384 * elapsed time between the time it was started and the time it was
31385 * stopped. The return value is the number of seconds elapsed,
31386 * including any fractional part. The @microseconds out parameter is
31387 * essentially useless.
31389 * Returns: seconds elapsed as a floating point value, including any
31397 * Creates a new timer, and starts timing (i.e. g_timer_start() is
31398 * implicitly called for you).
31400 * Returns: a new #GTimer.
31406 * @timer: a #GTimer.
31408 * This function is useless; it's fine to call g_timer_start() on an
31409 * already-started timer to reset the start time, so g_timer_reset()
31410 * serves no purpose.
31416 * @timer: a #GTimer.
31418 * Marks a start time, so that future calls to g_timer_elapsed() will
31419 * report the time since g_timer_start() was called. g_timer_new()
31420 * automatically marks the start time, so no need to call
31421 * g_timer_start() immediately after creating the timer.
31427 * @timer: a #GTimer.
31429 * Marks an end time, so calls to g_timer_elapsed() will return the
31430 * difference between this end time and the start time.
31435 * g_trash_stack_height:
31436 * @stack_p: a #GTrashStack
31438 * Returns the height of a #GTrashStack.
31440 * Note that execution of this function is of O(N) complexity
31441 * where N denotes the number of items on the stack.
31443 * Returns: the height of the stack
31444 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
31449 * g_trash_stack_peek:
31450 * @stack_p: a #GTrashStack
31452 * Returns the element at the top of a #GTrashStack
31453 * which may be %NULL.
31455 * Returns: the element at the top of the stack
31456 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
31461 * g_trash_stack_pop:
31462 * @stack_p: a #GTrashStack
31464 * Pops a piece of memory off a #GTrashStack.
31466 * Returns: the element at the top of the stack
31467 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
31472 * g_trash_stack_push:
31473 * @stack_p: a #GTrashStack
31474 * @data_p: (not nullable): the piece of memory to push on the stack
31476 * Pushes a piece of memory onto a #GTrashStack.
31478 * Deprecated: 2.48: #GTrashStack is deprecated without replacement
31486 * Removes all keys and values from the #GTree and decreases its
31487 * reference count by one. If keys and/or values are dynamically
31488 * allocated, you should either free them first or create the #GTree
31489 * using g_tree_new_full(). In the latter case the destroy functions
31490 * you supplied will be called on all keys and values before destroying
31498 * @func: the function to call for each node visited.
31499 * If this function returns %TRUE, the traversal is stopped.
31500 * @user_data: user data to pass to the function
31502 * Calls the given function for each of the key/value pairs in the #GTree.
31503 * The function is passed the key and value of each pair, and the given
31504 * @data parameter. The tree is traversed in sorted order.
31506 * The tree may not be modified while iterating over it (you can't
31507 * add/remove items). To remove all items matching a predicate, you need
31508 * to add each item to a list in your #GTraverseFunc as you walk over
31509 * the tree, then walk the list and remove each item.
31517 * Gets the height of a #GTree.
31519 * If the #GTree contains no nodes, the height is 0.
31520 * If the #GTree contains only one root node the height is 1.
31521 * If the root node has children the height is 2, etc.
31523 * Returns: the height of @tree
31530 * @key: the key to insert
31531 * @value: the value corresponding to the key
31533 * Inserts a key/value pair into a #GTree.
31535 * If the given key already exists in the #GTree its corresponding value
31536 * is set to the new value. If you supplied a @value_destroy_func when
31537 * creating the #GTree, the old value is freed using that function. If
31538 * you supplied a @key_destroy_func when creating the #GTree, the passed
31539 * key is freed using that function.
31541 * The tree is automatically 'balanced' as new key/value pairs are added,
31542 * so that the distance from the root to every leaf is as small as possible.
31549 * @key: the key to look up
31551 * Gets the value corresponding to the given key. Since a #GTree is
31552 * automatically balanced as key/value pairs are added, key lookup
31553 * is O(log n) (where n is the number of key/value pairs in the tree).
31555 * Returns: the value corresponding to the key, or %NULL
31556 * if the key was not found
31561 * g_tree_lookup_extended:
31563 * @lookup_key: the key to look up
31564 * @orig_key: (optional) (nullable): returns the original key
31565 * @value: (optional) (nullable): returns the value associated with the key
31567 * Looks up a key in the #GTree, returning the original key and the
31568 * associated value. This is useful if you need to free the memory
31569 * allocated for the original key, for example before calling
31572 * Returns: %TRUE if the key was found in the #GTree
31578 * @key_compare_func: the function used to order the nodes in the #GTree.
31579 * It should return values similar to the standard strcmp() function -
31580 * 0 if the two arguments are equal, a negative value if the first argument
31581 * comes before the second, or a positive value if the first argument comes
31582 * after the second.
31584 * Creates a new #GTree.
31586 * Returns: a newly allocated #GTree
31592 * @key_compare_func: qsort()-style comparison function
31593 * @key_compare_data: data to pass to comparison function
31594 * @key_destroy_func: a function to free the memory allocated for the key
31595 * used when removing the entry from the #GTree or %NULL if you don't
31596 * want to supply such a function
31597 * @value_destroy_func: a function to free the memory allocated for the
31598 * value used when removing the entry from the #GTree or %NULL if you
31599 * don't want to supply such a function
31601 * Creates a new #GTree like g_tree_new() and allows to specify functions
31602 * to free the memory allocated for the key and value that get called when
31603 * removing the entry from the #GTree.
31605 * Returns: a newly allocated #GTree
31610 * g_tree_new_with_data:
31611 * @key_compare_func: qsort()-style comparison function
31612 * @key_compare_data: data to pass to comparison function
31614 * Creates a new #GTree with a comparison function that accepts user data.
31615 * See g_tree_new() for more details.
31617 * Returns: a newly allocated #GTree
31625 * Gets the number of nodes in a #GTree.
31627 * Returns: the number of nodes in @tree
31635 * Increments the reference count of @tree by one.
31637 * It is safe to call this function from any thread.
31639 * Returns: the passed in #GTree
31647 * @key: the key to remove
31649 * Removes a key/value pair from a #GTree.
31651 * If the #GTree was created using g_tree_new_full(), the key and value
31652 * are freed using the supplied destroy functions, otherwise you have to
31653 * make sure that any dynamically allocated values are freed yourself.
31654 * If the key does not exist in the #GTree, the function does nothing.
31656 * Returns: %TRUE if the key was found (prior to 2.8, this function
31657 * returned nothing)
31664 * @key: the key to insert
31665 * @value: the value corresponding to the key
31667 * Inserts a new key and value into a #GTree similar to g_tree_insert().
31668 * The difference is that if the key already exists in the #GTree, it gets
31669 * replaced by the new key. If you supplied a @value_destroy_func when
31670 * creating the #GTree, the old value is freed using that function. If you
31671 * supplied a @key_destroy_func when creating the #GTree, the old key is
31672 * freed using that function.
31674 * The tree is automatically 'balanced' as new key/value pairs are added,
31675 * so that the distance from the root to every leaf is as small as possible.
31682 * @search_func: a function used to search the #GTree
31683 * @user_data: the data passed as the second argument to @search_func
31685 * Searches a #GTree using @search_func.
31687 * The @search_func is called with a pointer to the key of a key/value
31688 * pair in the tree, and the passed in @user_data. If @search_func returns
31689 * 0 for a key/value pair, then the corresponding value is returned as
31690 * the result of g_tree_search(). If @search_func returns -1, searching
31691 * will proceed among the key/value pairs that have a smaller key; if
31692 * @search_func returns 1, searching will proceed among the key/value
31693 * pairs that have a larger key.
31695 * Returns: the value corresponding to the found key, or %NULL
31696 * if the key was not found
31703 * @key: the key to remove
31705 * Removes a key and its associated value from a #GTree without calling
31706 * the key and value destroy functions.
31708 * If the key does not exist in the #GTree, the function does nothing.
31710 * Returns: %TRUE if the key was found (prior to 2.8, this function
31711 * returned nothing)
31718 * @traverse_func: the function to call for each node visited. If this
31719 * function returns %TRUE, the traversal is stopped.
31720 * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER,
31721 * %G_PRE_ORDER and %G_POST_ORDER
31722 * @user_data: user data to pass to the function
31724 * Calls the given function for each node in the #GTree.
31726 * Deprecated: 2.2: The order of a balanced tree is somewhat arbitrary.
31727 * If you just want to visit all nodes in sorted order, use
31728 * g_tree_foreach() instead. If you really need to visit nodes in
31729 * a different order, consider using an [n-ary tree][glib-N-ary-Trees].
31737 * Decrements the reference count of @tree by one.
31738 * If the reference count drops to 0, all keys and values will
31739 * be destroyed (if destroy functions were specified) and all
31740 * memory allocated by @tree will be released.
31742 * It is safe to call this function from any thread.
31750 * @n_bytes: number of bytes to allocate.
31752 * Attempts to allocate @n_bytes, and returns %NULL on failure.
31753 * Contrast with g_malloc(), which aborts the program on failure.
31755 * Returns: the allocated memory, or %NULL.
31761 * @n_bytes: number of bytes to allocate
31763 * Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on
31764 * failure. Contrast with g_malloc0(), which aborts the program on failure.
31767 * Returns: the allocated memory, or %NULL
31773 * @n_blocks: the number of blocks to allocate
31774 * @n_block_bytes: the size of each block in bytes
31776 * This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
31777 * but care is taken to detect possible overflow during multiplication.
31780 * Returns: the allocated memory, or %NULL
31786 * @n_blocks: the number of blocks to allocate
31787 * @n_block_bytes: the size of each block in bytes
31789 * This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
31790 * but care is taken to detect possible overflow during multiplication.
31793 * Returns: the allocated memory, or %NULL.
31799 * @mem: (allow-none): previously-allocated memory, or %NULL.
31800 * @n_bytes: number of bytes to allocate.
31802 * Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
31803 * on failure. Contrast with g_realloc(), which aborts the program
31806 * If @mem is %NULL, behaves the same as g_try_malloc().
31808 * Returns: the allocated memory, or %NULL.
31814 * @mem: (allow-none): previously-allocated memory, or %NULL.
31815 * @n_blocks: the number of blocks to allocate
31816 * @n_block_bytes: the size of each block in bytes
31818 * This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
31819 * but care is taken to detect possible overflow during multiplication.
31822 * Returns: the allocated memory, or %NULL.
31828 * @str: a UCS-4 encoded string
31829 * @len: the maximum length (number of characters) of @str to use.
31830 * If @len < 0, then the string is nul-terminated.
31831 * @items_read: (out caller-allocates) (optional): location to store number of
31832 * bytes read, or %NULL. If an error occurs then the index of the invalid
31833 * input is stored here.
31834 * @items_written: (out caller-allocates) (optional): location to store number
31835 * of #gunichar2 written, or %NULL. The value stored here does not include
31837 * @error: location to store the error occurring, or %NULL to ignore
31838 * errors. Any of the errors in #GConvertError other than
31839 * %G_CONVERT_ERROR_NO_CONVERSION may occur.
31841 * Convert a string from UCS-4 to UTF-16. A 0 character will be
31842 * added to the result after the converted text.
31844 * Returns: a pointer to a newly allocated UTF-16 string.
31845 * This value must be freed with g_free(). If an error occurs,
31846 * %NULL will be returned and @error set.
31852 * @str: a UCS-4 encoded string
31853 * @len: the maximum length (number of characters) of @str to use.
31854 * If @len < 0, then the string is nul-terminated.
31855 * @items_read: (out caller-allocates) (optional): location to store number of
31856 * characters read, or %NULL.
31857 * @items_written: (out caller-allocates) (optional): location to store number
31858 * of bytes written or %NULL. The value here stored does not include the
31860 * @error: location to store the error occurring, or %NULL to ignore
31861 * errors. Any of the errors in #GConvertError other than
31862 * %G_CONVERT_ERROR_NO_CONVERSION may occur.
31864 * Convert a string from a 32-bit fixed width representation as UCS-4.
31865 * to UTF-8. The result will be terminated with a 0 byte.
31867 * Returns: a pointer to a newly allocated UTF-8 string.
31868 * This value must be freed with g_free(). If an error occurs,
31869 * %NULL will be returned and @error set. In that case, @items_read
31870 * will be set to the position of the first invalid input character.
31875 * g_uint64_checked_add:
31876 * @dest: a pointer to the #guint64 destination
31877 * @a: the #guint64 left operand
31878 * @b: the #guint64 right operand
31880 * Performs a checked addition of @a and @b, storing the result in
31883 * If the operation is successful, %TRUE is returned. If the operation
31884 * overflows then the state of @dest is undefined and %FALSE is
31887 * Returns: %TRUE if there was no overflow
31893 * g_uint64_checked_mul:
31894 * @dest: a pointer to the #guint64 destination
31895 * @a: the #guint64 left operand
31896 * @b: the #guint64 right operand
31898 * Performs a checked multiplication of @a and @b, storing the result in
31901 * If the operation is successful, %TRUE is returned. If the operation
31902 * overflows then the state of @dest is undefined and %FALSE is
31905 * Returns: %TRUE if there was no overflow
31911 * g_uint_checked_add:
31912 * @dest: a pointer to the #guint destination
31913 * @a: the #guint left operand
31914 * @b: the #guint right operand
31916 * Performs a checked addition of @a and @b, storing the result in
31919 * If the operation is successful, %TRUE is returned. If the operation
31920 * overflows then the state of @dest is undefined and %FALSE is
31923 * Returns: %TRUE if there was no overflow
31929 * g_uint_checked_mul:
31930 * @dest: a pointer to the #guint destination
31931 * @a: the #guint left operand
31932 * @b: the #guint right operand
31934 * Performs a checked multiplication of @a and @b, storing the result in
31937 * If the operation is successful, %TRUE is returned. If the operation
31938 * overflows then the state of @dest is undefined and %FALSE is
31941 * Returns: %TRUE if there was no overflow
31947 * g_unichar_break_type:
31948 * @c: a Unicode character
31950 * Determines the break type of @c. @c should be a Unicode character
31951 * (to derive a character from UTF-8 encoded text, use
31952 * g_utf8_get_char()). The break type is used to find word and line
31953 * breaks ("text boundaries"), Pango implements the Unicode boundary
31954 * resolution algorithms and normally you would use a function such
31955 * as pango_break() instead of caring about break types yourself.
31957 * Returns: the break type of @c
31962 * g_unichar_combining_class:
31963 * @uc: a Unicode character
31965 * Determines the canonical combining class of a Unicode character.
31967 * Returns: the combining class of the character
31973 * g_unichar_compose:
31974 * @a: a Unicode character
31975 * @b: a Unicode character
31976 * @ch: return location for the composed character
31978 * Performs a single composition step of the
31979 * Unicode canonical composition algorithm.
31981 * This function includes algorithmic Hangul Jamo composition,
31982 * but it is not exactly the inverse of g_unichar_decompose().
31983 * No composition can have either of @a or @b equal to zero.
31984 * To be precise, this function composes if and only if
31985 * there exists a Primary Composite P which is canonically
31986 * equivalent to the sequence <@a,@b>. See the Unicode
31987 * Standard for the definition of Primary Composite.
31989 * If @a and @b do not compose a new character, @ch is set to zero.
31992 * [UAX#15](http://unicode.org/reports/tr15/)
31995 * Returns: %TRUE if the characters could be composed
32001 * g_unichar_decompose:
32002 * @ch: a Unicode character
32003 * @a: return location for the first component of @ch
32004 * @b: return location for the second component of @ch
32006 * Performs a single decomposition step of the
32007 * Unicode canonical decomposition algorithm.
32009 * This function does not include compatibility
32010 * decompositions. It does, however, include algorithmic
32011 * Hangul Jamo decomposition, as well as 'singleton'
32012 * decompositions which replace a character by a single
32013 * other character. In the case of singletons *@b will
32016 * If @ch is not decomposable, *@a is set to @ch and *@b
32019 * Note that the way Unicode decomposition pairs are
32020 * defined, it is guaranteed that @b would not decompose
32021 * further, but @a may itself decompose. To get the full
32022 * canonical decomposition for @ch, one would need to
32023 * recursively call this function on @a. Or use
32024 * g_unichar_fully_decompose().
32027 * [UAX#15](http://unicode.org/reports/tr15/)
32030 * Returns: %TRUE if the character could be decomposed
32036 * g_unichar_digit_value:
32037 * @c: a Unicode character
32039 * Determines the numeric value of a character as a decimal
32042 * Returns: If @c is a decimal digit (according to
32043 * g_unichar_isdigit()), its numeric value. Otherwise, -1.
32048 * g_unichar_fully_decompose:
32049 * @ch: a Unicode character.
32050 * @compat: whether perform canonical or compatibility decomposition
32051 * @result: (allow-none): location to store decomposed result, or %NULL
32052 * @result_len: length of @result
32054 * Computes the canonical or compatibility decomposition of a
32055 * Unicode character. For compatibility decomposition,
32056 * pass %TRUE for @compat; for canonical decomposition
32057 * pass %FALSE for @compat.
32059 * The decomposed sequence is placed in @result. Only up to
32060 * @result_len characters are written into @result. The length
32061 * of the full decomposition (irrespective of @result_len) is
32062 * returned by the function. For canonical decomposition,
32063 * currently all decompositions are of length at most 4, but
32064 * this may change in the future (very unlikely though).
32065 * At any rate, Unicode does guarantee that a buffer of length
32066 * 18 is always enough for both compatibility and canonical
32067 * decompositions, so that is the size recommended. This is provided
32068 * as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH.
32071 * [UAX#15](http://unicode.org/reports/tr15/)
32074 * Returns: the length of the full decomposition.
32080 * g_unichar_get_mirror_char:
32081 * @ch: a Unicode character
32082 * @mirrored_ch: location to store the mirrored character
32084 * In Unicode, some characters are "mirrored". This means that their
32085 * images are mirrored horizontally in text that is laid out from right
32086 * to left. For instance, "(" would become its mirror image, ")", in
32087 * right-to-left text.
32089 * If @ch has the Unicode mirrored property and there is another unicode
32090 * character that typically has a glyph that is the mirror image of @ch's
32091 * glyph and @mirrored_ch is set, it puts that character in the address
32092 * pointed to by @mirrored_ch. Otherwise the original character is put.
32094 * Returns: %TRUE if @ch has a mirrored character, %FALSE otherwise
32100 * g_unichar_get_script:
32101 * @ch: a Unicode character
32103 * Looks up the #GUnicodeScript for a particular character (as defined
32104 * by Unicode Standard Annex \#24). No check is made for @ch being a
32105 * valid Unicode character; if you pass in invalid character, the
32106 * result is undefined.
32108 * This function is equivalent to pango_script_for_unichar() and the
32109 * two are interchangeable.
32111 * Returns: the #GUnicodeScript for the character.
32117 * g_unichar_isalnum:
32118 * @c: a Unicode character
32120 * Determines whether a character is alphanumeric.
32121 * Given some UTF-8 text, obtain a character value
32122 * with g_utf8_get_char().
32124 * Returns: %TRUE if @c is an alphanumeric character
32129 * g_unichar_isalpha:
32130 * @c: a Unicode character
32132 * Determines whether a character is alphabetic (i.e. a letter).
32133 * Given some UTF-8 text, obtain a character value with
32134 * g_utf8_get_char().
32136 * Returns: %TRUE if @c is an alphabetic character
32141 * g_unichar_iscntrl:
32142 * @c: a Unicode character
32144 * Determines whether a character is a control character.
32145 * Given some UTF-8 text, obtain a character value with
32146 * g_utf8_get_char().
32148 * Returns: %TRUE if @c is a control character
32153 * g_unichar_isdefined:
32154 * @c: a Unicode character
32156 * Determines if a given character is assigned in the Unicode
32159 * Returns: %TRUE if the character has an assigned value
32164 * g_unichar_isdigit:
32165 * @c: a Unicode character
32167 * Determines whether a character is numeric (i.e. a digit). This
32168 * covers ASCII 0-9 and also digits in other languages/scripts. Given
32169 * some UTF-8 text, obtain a character value with g_utf8_get_char().
32171 * Returns: %TRUE if @c is a digit
32176 * g_unichar_isgraph:
32177 * @c: a Unicode character
32179 * Determines whether a character is printable and not a space
32180 * (returns %FALSE for control characters, format characters, and
32181 * spaces). g_unichar_isprint() is similar, but returns %TRUE for
32182 * spaces. Given some UTF-8 text, obtain a character value with
32183 * g_utf8_get_char().
32185 * Returns: %TRUE if @c is printable unless it's a space
32190 * g_unichar_islower:
32191 * @c: a Unicode character
32193 * Determines whether a character is a lowercase letter.
32194 * Given some UTF-8 text, obtain a character value with
32195 * g_utf8_get_char().
32197 * Returns: %TRUE if @c is a lowercase letter
32202 * g_unichar_ismark:
32203 * @c: a Unicode character
32205 * Determines whether a character is a mark (non-spacing mark,
32206 * combining mark, or enclosing mark in Unicode speak).
32207 * Given some UTF-8 text, obtain a character value
32208 * with g_utf8_get_char().
32210 * Note: in most cases where isalpha characters are allowed,
32211 * ismark characters should be allowed to as they are essential
32212 * for writing most European languages as well as many non-Latin
32215 * Returns: %TRUE if @c is a mark character
32221 * g_unichar_isprint:
32222 * @c: a Unicode character
32224 * Determines whether a character is printable.
32225 * Unlike g_unichar_isgraph(), returns %TRUE for spaces.
32226 * Given some UTF-8 text, obtain a character value with
32227 * g_utf8_get_char().
32229 * Returns: %TRUE if @c is printable
32234 * g_unichar_ispunct:
32235 * @c: a Unicode character
32237 * Determines whether a character is punctuation or a symbol.
32238 * Given some UTF-8 text, obtain a character value with
32239 * g_utf8_get_char().
32241 * Returns: %TRUE if @c is a punctuation or symbol character
32246 * g_unichar_isspace:
32247 * @c: a Unicode character
32249 * Determines whether a character is a space, tab, or line separator
32250 * (newline, carriage return, etc.). Given some UTF-8 text, obtain a
32251 * character value with g_utf8_get_char().
32253 * (Note: don't use this to do word breaking; you have to use
32254 * Pango or equivalent to get word breaking right, the algorithm
32255 * is fairly complex.)
32257 * Returns: %TRUE if @c is a space character
32262 * g_unichar_istitle:
32263 * @c: a Unicode character
32265 * Determines if a character is titlecase. Some characters in
32266 * Unicode which are composites, such as the DZ digraph
32267 * have three case variants instead of just two. The titlecase
32268 * form is used at the beginning of a word where only the
32269 * first letter is capitalized. The titlecase form of the DZ
32270 * digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z.
32272 * Returns: %TRUE if the character is titlecase
32277 * g_unichar_isupper:
32278 * @c: a Unicode character
32280 * Determines if a character is uppercase.
32282 * Returns: %TRUE if @c is an uppercase character
32287 * g_unichar_iswide:
32288 * @c: a Unicode character
32290 * Determines if a character is typically rendered in a double-width
32293 * Returns: %TRUE if the character is wide
32298 * g_unichar_iswide_cjk:
32299 * @c: a Unicode character
32301 * Determines if a character is typically rendered in a double-width
32302 * cell under legacy East Asian locales. If a character is wide according to
32303 * g_unichar_iswide(), then it is also reported wide with this function, but
32304 * the converse is not necessarily true. See the
32305 * [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
32308 * If a character passes the g_unichar_iswide() test then it will also pass
32309 * this test, but not the other way around. Note that some characters may
32310 * pass both this test and g_unichar_iszerowidth().
32312 * Returns: %TRUE if the character is wide in legacy East Asian locales
32318 * g_unichar_isxdigit:
32319 * @c: a Unicode character.
32321 * Determines if a character is a hexidecimal digit.
32323 * Returns: %TRUE if the character is a hexadecimal digit
32328 * g_unichar_iszerowidth:
32329 * @c: a Unicode character
32331 * Determines if a given character typically takes zero width when rendered.
32332 * The return value is %TRUE for all non-spacing and enclosing marks
32333 * (e.g., combining accents), format characters, zero-width
32334 * space, but not U+00AD SOFT HYPHEN.
32336 * A typical use of this function is with one of g_unichar_iswide() or
32337 * g_unichar_iswide_cjk() to determine the number of cells a string occupies
32338 * when displayed on a grid display (terminals). However, note that not all
32339 * terminals support zero-width rendering of zero-width marks.
32341 * Returns: %TRUE if the character has zero width
32347 * g_unichar_to_utf8:
32348 * @c: a Unicode character code
32349 * @outbuf: (out caller-allocates) (optional): output buffer, must have at
32350 * least 6 bytes of space. If %NULL, the length will be computed and
32351 * returned and nothing will be written to @outbuf.
32353 * Converts a single character to UTF-8.
32355 * Returns: number of bytes written
32360 * g_unichar_tolower:
32361 * @c: a Unicode character.
32363 * Converts a character to lower case.
32365 * Returns: the result of converting @c to lower case.
32366 * If @c is not an upperlower or titlecase character,
32367 * or has no lowercase equivalent @c is returned unchanged.
32372 * g_unichar_totitle:
32373 * @c: a Unicode character
32375 * Converts a character to the titlecase.
32377 * Returns: the result of converting @c to titlecase.
32378 * If @c is not an uppercase or lowercase character,
32379 * @c is returned unchanged.
32384 * g_unichar_toupper:
32385 * @c: a Unicode character
32387 * Converts a character to uppercase.
32389 * Returns: the result of converting @c to uppercase.
32390 * If @c is not an lowercase or titlecase character,
32391 * or has no upper case equivalent @c is returned unchanged.
32397 * @c: a Unicode character
32399 * Classifies a Unicode character by type.
32401 * Returns: the type of the character.
32406 * g_unichar_validate:
32407 * @ch: a Unicode character
32409 * Checks whether @ch is a valid Unicode character. Some possible
32410 * integer values of @ch will not be valid. 0 is considered a valid
32411 * character, though it's normally a string terminator.
32413 * Returns: %TRUE if @ch is a valid Unicode character
32418 * g_unichar_xdigit_value:
32419 * @c: a Unicode character
32421 * Determines the numeric value of a character as a hexidecimal
32424 * Returns: If @c is a hex digit (according to
32425 * g_unichar_isxdigit()), its numeric value. Otherwise, -1.
32430 * g_unicode_canonical_decomposition:
32431 * @ch: a Unicode character.
32432 * @result_len: location to store the length of the return value.
32434 * Computes the canonical decomposition of a Unicode character.
32436 * Returns: a newly allocated string of Unicode characters.
32437 * @result_len is set to the resulting length of the string.
32438 * Deprecated: 2.30: Use the more flexible g_unichar_fully_decompose()
32444 * g_unicode_canonical_ordering:
32445 * @string: a UCS-4 encoded string.
32446 * @len: the maximum length of @string to use.
32448 * Computes the canonical ordering of a string in-place.
32449 * This rearranges decomposed characters in the string
32450 * according to their combining classes. See the Unicode
32451 * manual for more information.
32456 * g_unicode_script_from_iso15924:
32457 * @iso15924: a Unicode script
32459 * Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter
32460 * codes to scripts. For example, the code for Arabic is 'Arab'.
32461 * This function accepts four letter codes encoded as a @guint32 in a
32462 * big-endian fashion. That is, the code expected for Arabic is
32463 * 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
32466 * [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
32469 * Returns: the Unicode script for @iso15924, or
32470 * of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and
32471 * %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown.
32477 * g_unicode_script_to_iso15924:
32478 * @script: a Unicode script
32480 * Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter
32481 * codes to scripts. For example, the code for Arabic is 'Arab'. The
32482 * four letter codes are encoded as a @guint32 by this function in a
32483 * big-endian fashion. That is, the code returned for Arabic is
32484 * 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
32487 * [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
32490 * Returns: the ISO 15924 code for @script, encoded as an integer,
32491 * of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or
32492 * ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood.
32499 * @fd: a file descriptor
32500 * @condition: IO conditions to watch for on @fd
32501 * @function: a #GPollFDFunc
32502 * @user_data: data to pass to @function
32504 * Sets a function to be called when the IO condition, as specified by
32505 * @condition becomes true for @fd.
32507 * @function will be called when the specified IO condition becomes
32508 * %TRUE. The function is expected to clear whatever event caused the
32509 * IO condition to become true and return %TRUE in order to be notified
32510 * when it happens again. If @function returns %FALSE then the watch
32511 * will be cancelled.
32513 * The return value of this function can be passed to g_source_remove()
32514 * to cancel the watch at any time that it exists.
32516 * The source will never close the fd -- you must do it yourself.
32518 * Returns: the ID (greater than 0) of the event source
32524 * g_unix_fd_add_full:
32525 * @priority: the priority of the source
32526 * @fd: a file descriptor
32527 * @condition: IO conditions to watch for on @fd
32528 * @function: a #GUnixFDSourceFunc
32529 * @user_data: data to pass to @function
32530 * @notify: function to call when the idle is removed, or %NULL
32532 * Sets a function to be called when the IO condition, as specified by
32533 * @condition becomes true for @fd.
32535 * This is the same as g_unix_fd_add(), except that it allows you to
32536 * specify a non-default priority and a provide a #GDestroyNotify for
32539 * Returns: the ID (greater than 0) of the event source
32545 * g_unix_fd_source_new:
32546 * @fd: a file descriptor
32547 * @condition: IO conditions to watch for on @fd
32549 * Creates a #GSource to watch for a particular IO condition on a file
32552 * The source will never close the fd -- you must do it yourself.
32554 * Returns: the newly created #GSource
32560 * g_unix_open_pipe:
32561 * @fds: Array of two integers
32562 * @flags: Bitfield of file descriptor flags, as for fcntl()
32563 * @error: a #GError
32565 * Similar to the UNIX pipe() call, but on modern systems like Linux
32566 * uses the pipe2() system call, which atomically creates a pipe with
32567 * the configured flags. The only supported flag currently is
32568 * %FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that
32569 * must still be done separately with fcntl().
32571 * This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if
32572 * for fcntl(); these are different on Linux/glibc.
32574 * Returns: %TRUE on success, %FALSE if not (and errno will be set).
32580 * g_unix_set_fd_nonblocking:
32581 * @fd: A file descriptor
32582 * @nonblock: If %TRUE, set the descriptor to be non-blocking
32583 * @error: a #GError
32585 * Control the non-blocking state of the given file descriptor,
32586 * according to @nonblock. On most systems this uses %O_NONBLOCK, but
32587 * on some older ones may use %O_NDELAY.
32589 * Returns: %TRUE if successful
32595 * g_unix_signal_add:
32596 * @signum: Signal number
32597 * @handler: Callback
32598 * @user_data: Data for @handler
32600 * A convenience function for g_unix_signal_source_new(), which
32601 * attaches to the default #GMainContext. You can remove the watch
32602 * using g_source_remove().
32604 * Returns: An ID (greater than 0) for the event source
32610 * g_unix_signal_add_full: (rename-to g_unix_signal_add)
32611 * @priority: the priority of the signal source. Typically this will be in
32612 * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
32613 * @signum: Signal number
32614 * @handler: Callback
32615 * @user_data: Data for @handler
32616 * @notify: #GDestroyNotify for @handler
32618 * A convenience function for g_unix_signal_source_new(), which
32619 * attaches to the default #GMainContext. You can remove the watch
32620 * using g_source_remove().
32622 * Returns: An ID (greater than 0) for the event source
32628 * g_unix_signal_source_new:
32629 * @signum: A signal number
32631 * Create a #GSource that will be dispatched upon delivery of the UNIX
32632 * signal @signum. In GLib versions before 2.36, only `SIGHUP`, `SIGINT`,
32633 * `SIGTERM` can be monitored. In GLib 2.36, `SIGUSR1` and `SIGUSR2`
32636 * Note that unlike the UNIX default, all sources which have created a
32637 * watch will be dispatched, regardless of which underlying thread
32638 * invoked g_unix_signal_source_new().
32640 * For example, an effective use of this function is to handle `SIGTERM`
32641 * cleanly; flushing any outstanding files, and then calling
32642 * g_main_loop_quit (). It is not safe to do any of this a regular
32643 * UNIX signal handler; your handler may be invoked while malloc() or
32644 * another library function is running, causing reentrancy if you
32645 * attempt to use it from the handler. None of the GLib/GObject API
32646 * is safe against this kind of reentrancy.
32648 * The interaction of this source when combined with native UNIX
32649 * functions like sigprocmask() is not defined.
32651 * The source will not initially be associated with any #GMainContext
32652 * and must be added to one with g_source_attach() before it will be
32655 * Returns: A newly created #GSource
32662 * @filename: (type filename): a pathname in the GLib file name encoding
32663 * (UTF-8 on Windows)
32665 * A wrapper for the POSIX unlink() function. The unlink() function
32666 * deletes a name from the filesystem. If this was the last link to the
32667 * file and no processes have it opened, the diskspace occupied by the
32670 * See your C library manual for more details about unlink(). Note
32671 * that on Windows, it is in general not possible to delete files that
32672 * are open to some process, or mapped into memory.
32674 * Returns: 0 if the name was successfully deleted, -1 if an error
32682 * @variable: the environment variable to remove, must not contain '='
32684 * Removes an environment variable from the environment.
32686 * Note that on some systems, when variables are overwritten, the
32687 * memory used for the previous variables and its value isn't reclaimed.
32689 * You should be mindful of the fact that environment variable handling
32690 * in UNIX is not thread-safe, and your program may crash if one thread
32691 * calls g_unsetenv() while another thread is calling getenv(). (And note
32692 * that many functions, such as gettext(), call getenv() internally.) This
32693 * function is only safe to use at the very start of your program, before
32694 * creating any other threads (or creating objects that create worker
32695 * threads of their own).
32697 * If you need to set up the environment for a child process, you can
32698 * use g_get_environ() to get an environment array, modify that with
32699 * g_environ_setenv() and g_environ_unsetenv(), and then pass that
32700 * array directly to execvpe(), g_spawn_async(), or the like.
32707 * g_uri_escape_string:
32708 * @unescaped: the unescaped input string.
32709 * @reserved_chars_allowed: (allow-none): a string of reserved characters that
32710 * are allowed to be used, or %NULL.
32711 * @allow_utf8: %TRUE if the result can include UTF-8 characters.
32713 * Escapes a string for use in a URI.
32715 * Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical
32716 * characters plus dash, dot, underscore and tilde) are escaped.
32717 * But if you specify characters in @reserved_chars_allowed they are not
32718 * escaped. This is useful for the "reserved" characters in the URI
32719 * specification, since those are allowed unescaped in some portions of
32722 * Returns: an escaped version of @unescaped. The returned string should be
32723 * freed when no longer needed.
32729 * g_uri_list_extract_uris:
32730 * @uri_list: an URI list
32732 * Splits an URI list conforming to the text/uri-list
32733 * mime type defined in RFC 2483 into individual URIs,
32734 * discarding any comments. The URIs are not validated.
32736 * Returns: (transfer full): a newly allocated %NULL-terminated list
32737 * of strings holding the individual URIs. The array should be freed
32738 * with g_strfreev().
32744 * g_uri_parse_scheme:
32745 * @uri: a valid URI.
32747 * Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as:
32749 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
32751 * Common schemes include "file", "http", "svn+ssh", etc.
32753 * Returns: The "Scheme" component of the URI, or %NULL on error.
32754 * The returned string should be freed when no longer needed.
32760 * g_uri_unescape_segment:
32761 * @escaped_string: (allow-none): A string, may be %NULL
32762 * @escaped_string_end: (allow-none): Pointer to end of @escaped_string, may be %NULL
32763 * @illegal_characters: (allow-none): An optional string of illegal characters not to be allowed, may be %NULL
32765 * Unescapes a segment of an escaped string.
32767 * If any of the characters in @illegal_characters or the character zero appears
32768 * as an escaped character in @escaped_string then that is an error and %NULL
32769 * will be returned. This is useful it you want to avoid for instance having a
32770 * slash being expanded in an escaped path element, which might confuse pathname
32773 * Returns: an unescaped version of @escaped_string or %NULL on error.
32774 * The returned string should be freed when no longer needed. As a
32775 * special case if %NULL is given for @escaped_string, this function
32776 * will return %NULL.
32782 * g_uri_unescape_string:
32783 * @escaped_string: an escaped string to be unescaped.
32784 * @illegal_characters: (allow-none): a string of illegal characters not to be
32785 * allowed, or %NULL.
32787 * Unescapes a whole escaped string.
32789 * If any of the characters in @illegal_characters or the character zero appears
32790 * as an escaped character in @escaped_string then that is an error and %NULL
32791 * will be returned. This is useful it you want to avoid for instance having a
32792 * slash being expanded in an escaped path element, which might confuse pathname
32795 * Returns: an unescaped version of @escaped_string. The returned string
32796 * should be freed when no longer needed.
32803 * @microseconds: number of microseconds to pause
32805 * Pauses the current thread for the given number of microseconds.
32807 * There are 1 million microseconds per second (represented by the
32808 * #G_USEC_PER_SEC macro). g_usleep() may have limited precision,
32809 * depending on hardware and operating system; don't rely on the exact
32810 * length of the sleep.
32816 * @str: a UTF-16 encoded string
32817 * @len: the maximum length (number of #gunichar2) of @str to use.
32818 * If @len < 0, then the string is nul-terminated.
32819 * @items_read: (out caller-allocates) (optional): location to store number of
32820 * words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
32821 * be returned in case @str contains a trailing partial character. If
32822 * an error occurs then the index of the invalid input is stored here.
32823 * @items_written: (out caller-allocates) (optional): location to store number
32824 * of characters written, or %NULL. The value stored here does not include
32825 * the trailing 0 character.
32826 * @error: location to store the error occurring, or %NULL to ignore
32827 * errors. Any of the errors in #GConvertError other than
32828 * %G_CONVERT_ERROR_NO_CONVERSION may occur.
32830 * Convert a string from UTF-16 to UCS-4. The result will be
32833 * Returns: a pointer to a newly allocated UCS-4 string.
32834 * This value must be freed with g_free(). If an error occurs,
32835 * %NULL will be returned and @error set.
32841 * @str: a UTF-16 encoded string
32842 * @len: the maximum length (number of #gunichar2) of @str to use.
32843 * If @len < 0, then the string is nul-terminated.
32844 * @items_read: (out caller-allocates) (optional): location to store number of
32845 * words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
32846 * be returned in case @str contains a trailing partial character. If
32847 * an error occurs then the index of the invalid input is stored here.
32848 * @items_written: (out caller-allocates) (optional): location to store number
32849 * of bytes written, or %NULL. The value stored here does not include the
32851 * @error: location to store the error occurring, or %NULL to ignore
32852 * errors. Any of the errors in #GConvertError other than
32853 * %G_CONVERT_ERROR_NO_CONVERSION may occur.
32855 * Convert a string from UTF-16 to UTF-8. The result will be
32856 * terminated with a 0 byte.
32858 * Note that the input is expected to be already in native endianness,
32859 * an initial byte-order-mark character is not handled specially.
32860 * g_convert() can be used to convert a byte buffer of UTF-16 data of
32861 * ambiguous endianess.
32863 * Further note that this function does not validate the result
32864 * string; it may e.g. include embedded NUL characters. The only
32865 * validation done by this function is to ensure that the input can
32866 * be correctly interpreted as UTF-16, i.e. it doesn't contain
32867 * things unpaired surrogates.
32869 * Returns: a pointer to a newly allocated UTF-8 string.
32870 * This value must be freed with g_free(). If an error occurs,
32871 * %NULL will be returned and @error set.
32877 * @str: a UTF-8 encoded string
32878 * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
32880 * Converts a string into a form that is independent of case. The
32881 * result will not correspond to any particular case, but can be
32882 * compared for equality or ordered with the results of calling
32883 * g_utf8_casefold() on other strings.
32885 * Note that calling g_utf8_casefold() followed by g_utf8_collate() is
32886 * only an approximation to the correct linguistic case insensitive
32887 * ordering, though it is a fairly good one. Getting this exactly
32888 * right would require a more sophisticated collation function that
32889 * takes case sensitivity into account. GLib does not currently
32890 * provide such a function.
32892 * Returns: a newly allocated string, that is a
32893 * case independent form of @str.
32899 * @str1: a UTF-8 encoded string
32900 * @str2: a UTF-8 encoded string
32902 * Compares two strings for ordering using the linguistically
32903 * correct rules for the [current locale][setlocale].
32904 * When sorting a large number of strings, it will be significantly
32905 * faster to obtain collation keys with g_utf8_collate_key() and
32906 * compare the keys with strcmp() when sorting instead of sorting
32907 * the original strings.
32909 * Returns: < 0 if @str1 compares before @str2,
32910 * 0 if they compare equal, > 0 if @str1 compares after @str2.
32915 * g_utf8_collate_key:
32916 * @str: a UTF-8 encoded string.
32917 * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
32919 * Converts a string into a collation key that can be compared
32920 * with other collation keys produced by the same function using
32923 * The results of comparing the collation keys of two strings
32924 * with strcmp() will always be the same as comparing the two
32925 * original keys with g_utf8_collate().
32927 * Note that this function depends on the [current locale][setlocale].
32929 * Returns: a newly allocated string. This string should
32930 * be freed with g_free() when you are done with it.
32935 * g_utf8_collate_key_for_filename:
32936 * @str: a UTF-8 encoded string.
32937 * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
32939 * Converts a string into a collation key that can be compared
32940 * with other collation keys produced by the same function using strcmp().
32942 * In order to sort filenames correctly, this function treats the dot '.'
32943 * as a special case. Most dictionary orderings seem to consider it
32944 * insignificant, thus producing the ordering "event.c" "eventgenerator.c"
32945 * "event.h" instead of "event.c" "event.h" "eventgenerator.c". Also, we
32946 * would like to treat numbers intelligently so that "file1" "file10" "file5"
32947 * is sorted as "file1" "file5" "file10".
32949 * Note that this function depends on the [current locale][setlocale].
32951 * Returns: a newly allocated string. This string should
32952 * be freed with g_free() when you are done with it.
32958 * g_utf8_find_next_char:
32959 * @p: a pointer to a position within a UTF-8 encoded string
32960 * @end: (nullable): a pointer to the byte following the end of the string,
32961 * or %NULL to indicate that the string is nul-terminated
32963 * Finds the start of the next UTF-8 character in the string after @p.
32965 * @p does not have to be at the beginning of a UTF-8 character. No check
32966 * is made to see if the character found is actually valid other than
32967 * it starts with an appropriate byte.
32969 * Returns: a pointer to the found character or %NULL
32974 * g_utf8_find_prev_char:
32975 * @str: pointer to the beginning of a UTF-8 encoded string
32976 * @p: pointer to some position within @str
32978 * Given a position @p with a UTF-8 encoded string @str, find the start
32979 * of the previous UTF-8 character starting before @p. Returns %NULL if no
32980 * UTF-8 characters are present in @str before @p.
32982 * @p does not have to be at the beginning of a UTF-8 character. No check
32983 * is made to see if the character found is actually valid other than
32984 * it starts with an appropriate byte.
32986 * Returns: a pointer to the found character or %NULL.
32992 * @p: a pointer to Unicode character encoded as UTF-8
32994 * Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
32996 * If @p does not point to a valid UTF-8 encoded character, results
32997 * are undefined. If you are not sure that the bytes are complete
32998 * valid Unicode characters, you should use g_utf8_get_char_validated()
33001 * Returns: the resulting character
33006 * g_utf8_get_char_validated:
33007 * @p: a pointer to Unicode character encoded as UTF-8
33008 * @max_len: the maximum number of bytes to read, or -1, for no maximum or
33009 * if @p is nul-terminated
33011 * Convert a sequence of bytes encoded as UTF-8 to a Unicode character.
33012 * This function checks for incomplete characters, for invalid characters
33013 * such as characters that are out of the range of Unicode, and for
33014 * overlong encodings of valid characters.
33016 * Returns: the resulting character. If @p points to a partial
33017 * sequence at the end of a string that could begin a valid
33018 * character (or if @max_len is zero), returns (gunichar)-2;
33019 * otherwise, if @p does not point to a valid UTF-8 encoded
33020 * Unicode character, returns (gunichar)-1.
33025 * g_utf8_normalize:
33026 * @str: a UTF-8 encoded string.
33027 * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
33028 * @mode: the type of normalization to perform.
33030 * Converts a string into canonical form, standardizing
33031 * such issues as whether a character with an accent
33032 * is represented as a base character and combining
33033 * accent or as a single precomposed character. The
33034 * string has to be valid UTF-8, otherwise %NULL is
33035 * returned. You should generally call g_utf8_normalize()
33036 * before comparing two Unicode strings.
33038 * The normalization mode %G_NORMALIZE_DEFAULT only
33039 * standardizes differences that do not affect the
33040 * text content, such as the above-mentioned accent
33041 * representation. %G_NORMALIZE_ALL also standardizes
33042 * the "compatibility" characters in Unicode, such
33043 * as SUPERSCRIPT THREE to the standard forms
33044 * (in this case DIGIT THREE). Formatting information
33045 * may be lost but for most text operations such
33046 * characters should be considered the same.
33048 * %G_NORMALIZE_DEFAULT_COMPOSE and %G_NORMALIZE_ALL_COMPOSE
33049 * are like %G_NORMALIZE_DEFAULT and %G_NORMALIZE_ALL,
33050 * but returned a result with composed forms rather
33051 * than a maximally decomposed form. This is often
33052 * useful if you intend to convert the string to
33053 * a legacy encoding or pass it to a system with
33054 * less capable Unicode handling.
33056 * Returns: a newly allocated string, that is the
33057 * normalized form of @str, or %NULL if @str is not
33063 * g_utf8_offset_to_pointer:
33064 * @str: a UTF-8 encoded string
33065 * @offset: a character offset within @str
33067 * Converts from an integer character offset to a pointer to a position
33068 * within the string.
33070 * Since 2.10, this function allows to pass a negative @offset to
33071 * step backwards. It is usually worth stepping backwards from the end
33072 * instead of forwards if @offset is in the last fourth of the string,
33073 * since moving forward is about 3 times faster than moving backward.
33075 * Note that this function doesn't abort when reaching the end of @str.
33076 * Therefore you should be sure that @offset is within string boundaries
33077 * before calling that function. Call g_utf8_strlen() when unsure.
33078 * This limitation exists as this function is called frequently during
33079 * text rendering and therefore has to be as fast as possible.
33081 * Returns: the resulting pointer
33086 * g_utf8_pointer_to_offset:
33087 * @str: a UTF-8 encoded string
33088 * @pos: a pointer to a position within @str
33090 * Converts from a pointer to position within a string to a integer
33091 * character offset.
33093 * Since 2.10, this function allows @pos to be before @str, and returns
33094 * a negative offset in this case.
33096 * Returns: the resulting character offset
33101 * g_utf8_prev_char:
33102 * @p: a pointer to a position within a UTF-8 encoded string
33104 * Finds the previous UTF-8 character in the string before @p.
33106 * @p does not have to be at the beginning of a UTF-8 character. No check
33107 * is made to see if the character found is actually valid other than
33108 * it starts with an appropriate byte. If @p might be the first
33109 * character of the string, you must use g_utf8_find_prev_char() instead.
33111 * Returns: a pointer to the found character
33117 * @p: a nul-terminated UTF-8 encoded string
33118 * @len: the maximum length of @p
33119 * @c: a Unicode character
33121 * Finds the leftmost occurrence of the given Unicode character
33122 * in a UTF-8 encoded string, while limiting the search to @len bytes.
33123 * If @len is -1, allow unbounded search.
33125 * Returns: %NULL if the string does not contain the character,
33126 * otherwise, a pointer to the start of the leftmost occurrence
33127 * of the character in the string.
33133 * @str: a UTF-8 encoded string
33134 * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
33136 * Converts all Unicode characters in the string that have a case
33137 * to lowercase. The exact manner that this is done depends
33138 * on the current locale, and may result in the number of
33139 * characters in the string changing.
33141 * Returns: a newly allocated string, with all characters
33142 * converted to lowercase.
33148 * @p: pointer to the start of a UTF-8 encoded string
33149 * @max: the maximum number of bytes to examine. If @max
33150 * is less than 0, then the string is assumed to be
33151 * nul-terminated. If @max is 0, @p will not be examined and
33152 * may be %NULL. If @max is greater than 0, up to @max
33153 * bytes are examined
33155 * Computes the length of the string in characters, not including
33156 * the terminating nul character. If the @max'th byte falls in the
33157 * middle of a character, the last (partial) character is not counted.
33159 * Returns: the length of the string in characters
33165 * @dest: buffer to fill with characters from @src
33166 * @src: UTF-8 encoded string
33167 * @n: character count
33169 * Like the standard C strncpy() function, but copies a given number
33170 * of characters instead of a given number of bytes. The @src string
33171 * must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
33172 * text before trying to use UTF-8 utility functions with it.)
33180 * @p: a nul-terminated UTF-8 encoded string
33181 * @len: the maximum length of @p
33182 * @c: a Unicode character
33184 * Find the rightmost occurrence of the given Unicode character
33185 * in a UTF-8 encoded string, while limiting the search to @len bytes.
33186 * If @len is -1, allow unbounded search.
33188 * Returns: %NULL if the string does not contain the character,
33189 * otherwise, a pointer to the start of the rightmost occurrence
33190 * of the character in the string.
33195 * g_utf8_strreverse:
33196 * @str: a UTF-8 encoded string
33197 * @len: the maximum length of @str to use, in bytes. If @len < 0,
33198 * then the string is nul-terminated.
33200 * Reverses a UTF-8 string. @str must be valid UTF-8 encoded text.
33201 * (Use g_utf8_validate() on all text before trying to use UTF-8
33202 * utility functions with it.)
33204 * This function is intended for programmatic uses of reversed strings.
33205 * It pays no attention to decomposed characters, combining marks, byte
33206 * order marks, directional indicators (LRM, LRO, etc) and similar
33207 * characters which might need special handling when reversing a string
33208 * for display purposes.
33210 * Note that unlike g_strreverse(), this function returns
33211 * newly-allocated memory, which should be freed with g_free() when
33212 * no longer needed.
33214 * Returns: a newly-allocated string which is the reverse of @str
33221 * @str: a UTF-8 encoded string
33222 * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
33224 * Converts all Unicode characters in the string that have a case
33225 * to uppercase. The exact manner that this is done depends
33226 * on the current locale, and may result in the number of
33227 * characters in the string increasing. (For instance, the
33228 * German ess-zet will be changed to SS.)
33230 * Returns: a newly allocated string, with all characters
33231 * converted to uppercase.
33236 * g_utf8_substring:
33237 * @str: a UTF-8 encoded string
33238 * @start_pos: a character offset within @str
33239 * @end_pos: another character offset within @str
33241 * Copies a substring out of a UTF-8 encoded string.
33242 * The substring will contain @end_pos - @start_pos characters.
33244 * Returns: a newly allocated copy of the requested
33245 * substring. Free with g_free() when no longer needed.
33252 * @str: a UTF-8 encoded string
33253 * @len: the maximum length of @str to use, in bytes. If @len < 0,
33254 * then the string is nul-terminated.
33255 * @items_read: (out caller-allocates) (optional): location to store number of
33256 * bytes read, or %NULL.
33257 * If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
33258 * returned in case @str contains a trailing partial
33259 * character. If an error occurs then the index of the
33260 * invalid input is stored here.
33261 * @items_written: (out caller-allocates) (optional): location to store number
33262 * of characters written or %NULL. The value here stored does not include
33263 * the trailing 0 character.
33264 * @error: location to store the error occurring, or %NULL to ignore
33265 * errors. Any of the errors in #GConvertError other than
33266 * %G_CONVERT_ERROR_NO_CONVERSION may occur.
33268 * Convert a string from UTF-8 to a 32-bit fixed width
33269 * representation as UCS-4. A trailing 0 character will be added to the
33270 * string after the converted text.
33272 * Returns: a pointer to a newly allocated UCS-4 string.
33273 * This value must be freed with g_free(). If an error occurs,
33274 * %NULL will be returned and @error set.
33279 * g_utf8_to_ucs4_fast:
33280 * @str: a UTF-8 encoded string
33281 * @len: the maximum length of @str to use, in bytes. If @len < 0,
33282 * then the string is nul-terminated.
33283 * @items_written: (out caller-allocates) (optional): location to store the
33284 * number of characters in the result, or %NULL.
33286 * Convert a string from UTF-8 to a 32-bit fixed width
33287 * representation as UCS-4, assuming valid UTF-8 input.
33288 * This function is roughly twice as fast as g_utf8_to_ucs4()
33289 * but does no error checking on the input. A trailing 0 character
33290 * will be added to the string after the converted text.
33292 * Returns: a pointer to a newly allocated UCS-4 string.
33293 * This value must be freed with g_free().
33299 * @str: a UTF-8 encoded string
33300 * @len: the maximum length (number of bytes) of @str to use.
33301 * If @len < 0, then the string is nul-terminated.
33302 * @items_read: (out caller-allocates) (optional): location to store number of
33303 * bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
33304 * be returned in case @str contains a trailing partial character. If
33305 * an error occurs then the index of the invalid input is stored here.
33306 * @items_written: (out caller-allocates) (optional): location to store number
33307 * of #gunichar2 written, or %NULL. The value stored here does not include
33309 * @error: location to store the error occurring, or %NULL to ignore
33310 * errors. Any of the errors in #GConvertError other than
33311 * %G_CONVERT_ERROR_NO_CONVERSION may occur.
33313 * Convert a string from UTF-8 to UTF-16. A 0 character will be
33314 * added to the result after the converted text.
33316 * Returns: a pointer to a newly allocated UTF-16 string.
33317 * This value must be freed with g_free(). If an error occurs,
33318 * %NULL will be returned and @error set.
33324 * @str: (array length=max_len) (element-type guint8): a pointer to character data
33325 * @max_len: max bytes to validate, or -1 to go until NUL
33326 * @end: (allow-none) (out) (transfer none): return location for end of valid data
33328 * Validates UTF-8 encoded text. @str is the text to validate;
33329 * if @str is nul-terminated, then @max_len can be -1, otherwise
33330 * @max_len should be the number of bytes to validate.
33331 * If @end is non-%NULL, then the end of the valid range
33332 * will be stored there (i.e. the start of the first invalid
33333 * character if some bytes were invalid, or the end of the text
33334 * being validated otherwise).
33336 * Note that g_utf8_validate() returns %FALSE if @max_len is
33337 * positive and any of the @max_len bytes are nul.
33339 * Returns %TRUE if all of @str was valid. Many GLib and GTK+
33340 * routines require valid UTF-8 as input; so data read from a file
33341 * or the network should be checked with g_utf8_validate() before
33342 * doing anything else with it.
33344 * Returns: %TRUE if the text was valid UTF-8
33350 * @filename: (type filename): a pathname in the GLib file name encoding
33351 * (UTF-8 on Windows)
33352 * @utb: a pointer to a struct utimbuf.
33354 * A wrapper for the POSIX utime() function. The utime() function
33355 * sets the access and modification timestamps of a file.
33357 * See your C library manual for more details about how utime() works
33360 * Returns: 0 if the operation was successful, -1 if an error occurred
33366 * g_variant_builder_add: (skip)
33367 * @builder: a #GVariantBuilder
33368 * @format_string: a #GVariant varargs format string
33369 * @...: arguments, as per @format_string
33371 * Adds to a #GVariantBuilder.
33373 * This call is a convenience wrapper that is exactly equivalent to
33374 * calling g_variant_new() followed by g_variant_builder_add_value().
33376 * Note that the arguments must be of the correct width for their types
33377 * specified in @format_string. This can be achieved by casting them. See
33378 * the [GVariant varargs documentation][gvariant-varargs].
33380 * This function might be used as follows:
33382 * |[<!-- language="C" -->
33384 * make_pointless_dictionary (void)
33386 * GVariantBuilder builder;
33389 * g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
33390 * for (i = 0; i < 16; i++)
33394 * sprintf (buf, "%d", i);
33395 * g_variant_builder_add (&builder, "{is}", i, buf);
33398 * return g_variant_builder_end (&builder);
33407 * g_variant_builder_add_parsed:
33408 * @builder: a #GVariantBuilder
33409 * @format: a text format #GVariant
33410 * @...: arguments as per @format
33412 * Adds to a #GVariantBuilder.
33414 * This call is a convenience wrapper that is exactly equivalent to
33415 * calling g_variant_new_parsed() followed by
33416 * g_variant_builder_add_value().
33418 * Note that the arguments must be of the correct width for their types
33419 * specified in @format_string. This can be achieved by casting them. See
33420 * the [GVariant varargs documentation][gvariant-varargs].
33422 * This function might be used as follows:
33424 * |[<!-- language="C" -->
33426 * make_pointless_dictionary (void)
33428 * GVariantBuilder builder;
33431 * g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
33432 * g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600);
33433 * g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo");
33434 * g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}");
33435 * return g_variant_builder_end (&builder);
33444 * g_variant_builder_add_value:
33445 * @builder: a #GVariantBuilder
33446 * @value: a #GVariant
33448 * Adds @value to @builder.
33450 * It is an error to call this function in any way that would create an
33451 * inconsistent value to be constructed. Some examples of this are
33452 * putting different types of items into an array, putting the wrong
33453 * types or number of items in a tuple, putting more than one value into
33456 * If @value is a floating reference (see g_variant_ref_sink()),
33457 * the @builder instance takes ownership of @value.
33464 * g_variant_builder_clear: (skip)
33465 * @builder: a #GVariantBuilder
33467 * Releases all memory associated with a #GVariantBuilder without
33468 * freeing the #GVariantBuilder structure itself.
33470 * It typically only makes sense to do this on a stack-allocated
33471 * #GVariantBuilder if you want to abort building the value part-way
33472 * through. This function need not be called if you call
33473 * g_variant_builder_end() and it also doesn't need to be called on
33474 * builders allocated with g_variant_builder_new (see
33475 * g_variant_builder_unref() for that).
33477 * This function leaves the #GVariantBuilder structure set to all-zeros.
33478 * It is valid to call this function on either an initialised
33479 * #GVariantBuilder or one that is set to all-zeros but it is not valid
33480 * to call this function on uninitialised memory.
33487 * g_variant_builder_close:
33488 * @builder: a #GVariantBuilder
33490 * Closes the subcontainer inside the given @builder that was opened by
33491 * the most recent call to g_variant_builder_open().
33493 * It is an error to call this function in any way that would create an
33494 * inconsistent value to be constructed (ie: too few values added to the
33502 * g_variant_builder_end:
33503 * @builder: a #GVariantBuilder
33505 * Ends the builder process and returns the constructed value.
33507 * It is not permissible to use @builder in any way after this call
33508 * except for reference counting operations (in the case of a
33509 * heap-allocated #GVariantBuilder) or by reinitialising it with
33510 * g_variant_builder_init() (in the case of stack-allocated). This
33511 * means that for the stack-allocated builders there is no need to
33512 * call g_variant_builder_clear() after the call to
33513 * g_variant_builder_end().
33515 * It is an error to call this function in any way that would create an
33516 * inconsistent value to be constructed (ie: insufficient number of
33517 * items added to a container with a specific number of children
33518 * required). It is also an error to call this function if the builder
33519 * was created with an indefinite array or maybe type and no children
33520 * have been added; in this case it is impossible to infer the type of
33523 * Returns: (transfer none): a new, floating, #GVariant
33529 * g_variant_builder_init: (skip)
33530 * @builder: a #GVariantBuilder
33531 * @type: a container type
33533 * Initialises a #GVariantBuilder structure.
33535 * @type must be non-%NULL. It specifies the type of container to
33536 * construct. It can be an indefinite type such as
33537 * %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)".
33538 * Maybe, array, tuple, dictionary entry and variant-typed values may be
33541 * After the builder is initialised, values are added using
33542 * g_variant_builder_add_value() or g_variant_builder_add().
33544 * After all the child values are added, g_variant_builder_end() frees
33545 * the memory associated with the builder and returns the #GVariant that
33548 * This function completely ignores the previous contents of @builder.
33549 * On one hand this means that it is valid to pass in completely
33550 * uninitialised memory. On the other hand, this means that if you are
33551 * initialising over top of an existing #GVariantBuilder you need to
33552 * first call g_variant_builder_clear() in order to avoid leaking
33555 * You must not call g_variant_builder_ref() or
33556 * g_variant_builder_unref() on a #GVariantBuilder that was initialised
33557 * with this function. If you ever pass a reference to a
33558 * #GVariantBuilder outside of the control of your own code then you
33559 * should assume that the person receiving that reference may try to use
33560 * reference counting; you should use g_variant_builder_new() instead of
33568 * g_variant_builder_new:
33569 * @type: a container type
33571 * Allocates and initialises a new #GVariantBuilder.
33573 * You should call g_variant_builder_unref() on the return value when it
33574 * is no longer needed. The memory will not be automatically freed by
33577 * In most cases it is easier to place a #GVariantBuilder directly on
33578 * the stack of the calling function and initialise it with
33579 * g_variant_builder_init().
33581 * Returns: (transfer full): a #GVariantBuilder
33587 * g_variant_builder_open:
33588 * @builder: a #GVariantBuilder
33589 * @type: a #GVariantType
33591 * Opens a subcontainer inside the given @builder. When done adding
33592 * items to the subcontainer, g_variant_builder_close() must be called.
33594 * It is an error to call this function in any way that would cause an
33595 * inconsistent value to be constructed (ie: adding too many values or
33596 * a value of an incorrect type).
33603 * g_variant_builder_ref:
33604 * @builder: a #GVariantBuilder allocated by g_variant_builder_new()
33606 * Increases the reference count on @builder.
33608 * Don't call this on stack-allocated #GVariantBuilder instances or bad
33609 * things will happen.
33611 * Returns: (transfer full): a new reference to @builder
33617 * g_variant_builder_unref:
33618 * @builder: (transfer full): a #GVariantBuilder allocated by g_variant_builder_new()
33620 * Decreases the reference count on @builder.
33622 * In the event that there are no more references, releases all memory
33623 * associated with the #GVariantBuilder.
33625 * Don't call this on stack-allocated #GVariantBuilder instances or bad
33626 * things will happen.
33633 * g_variant_byteswap:
33634 * @value: a #GVariant
33636 * Performs a byteswapping operation on the contents of @value. The
33637 * result is that all multi-byte numeric data contained in @value is
33638 * byteswapped. That includes 16, 32, and 64bit signed and unsigned
33639 * integers as well as file handles and double precision floating point
33642 * This function is an identity mapping on any value that does not
33643 * contain multi-byte numeric data. That include strings, booleans,
33644 * bytes and containers containing only these things (recursively).
33646 * The returned value is always in normal form and is marked as trusted.
33648 * Returns: (transfer full): the byteswapped form of @value
33654 * g_variant_check_format_string:
33655 * @value: a #GVariant
33656 * @format_string: a valid #GVariant format string
33657 * @copy_only: %TRUE to ensure the format string makes deep copies
33659 * Checks if calling g_variant_get() with @format_string on @value would
33660 * be valid from a type-compatibility standpoint. @format_string is
33661 * assumed to be a valid format string (from a syntactic standpoint).
33663 * If @copy_only is %TRUE then this function additionally checks that it
33664 * would be safe to call g_variant_unref() on @value immediately after
33665 * the call to g_variant_get() without invalidating the result. This is
33666 * only possible if deep copies are made (ie: there are no pointers to
33667 * the data inside of the soon-to-be-freed #GVariant instance). If this
33668 * check fails then a g_critical() is printed and %FALSE is returned.
33670 * This function is meant to be used by functions that wish to provide
33671 * varargs accessors to #GVariant values of uncertain values (eg:
33672 * g_variant_lookup() or g_menu_model_get_item_attribute()).
33674 * Returns: %TRUE if @format_string is safe to use
33680 * g_variant_classify:
33681 * @value: a #GVariant
33683 * Classifies @value according to its top-level type.
33685 * Returns: the #GVariantClass of @value
33691 * g_variant_compare:
33692 * @one: (type GVariant): a basic-typed #GVariant instance
33693 * @two: (type GVariant): a #GVariant instance of the same type
33695 * Compares @one and @two.
33697 * The types of @one and @two are #gconstpointer only to allow use of
33698 * this function with #GTree, #GPtrArray, etc. They must each be a
33701 * Comparison is only defined for basic types (ie: booleans, numbers,
33702 * strings). For booleans, %FALSE is less than %TRUE. Numbers are
33703 * ordered in the usual way. Strings are in ASCII lexographical order.
33705 * It is a programmer error to attempt to compare container values or
33706 * two values that have types that are not exactly equal. For example,
33707 * you cannot compare a 32-bit signed integer with a 32-bit unsigned
33708 * integer. Also note that this function is not particularly
33709 * well-behaved when it comes to comparison of doubles; in particular,
33710 * the handling of incomparable values (ie: NaN) is undefined.
33712 * If you only require an equality comparison, g_variant_equal() is more
33715 * Returns: negative value if a < b;
33717 * positive value if a > b.
33723 * g_variant_dict_clear:
33724 * @dict: a #GVariantDict
33726 * Releases all memory associated with a #GVariantDict without freeing
33727 * the #GVariantDict structure itself.
33729 * It typically only makes sense to do this on a stack-allocated
33730 * #GVariantDict if you want to abort building the value part-way
33731 * through. This function need not be called if you call
33732 * g_variant_dict_end() and it also doesn't need to be called on dicts
33733 * allocated with g_variant_dict_new (see g_variant_dict_unref() for
33736 * It is valid to call this function on either an initialised
33737 * #GVariantDict or one that was previously cleared by an earlier call
33738 * to g_variant_dict_clear() but it is not valid to call this function
33739 * on uninitialised memory.
33746 * g_variant_dict_contains:
33747 * @dict: a #GVariantDict
33748 * @key: the key to lookup in the dictionary
33750 * Checks if @key exists in @dict.
33752 * Returns: %TRUE if @key is in @dict
33758 * g_variant_dict_end:
33759 * @dict: a #GVariantDict
33761 * Returns the current value of @dict as a #GVariant of type
33762 * %G_VARIANT_TYPE_VARDICT, clearing it in the process.
33764 * It is not permissible to use @dict in any way after this call except
33765 * for reference counting operations (in the case of a heap-allocated
33766 * #GVariantDict) or by reinitialising it with g_variant_dict_init() (in
33767 * the case of stack-allocated).
33769 * Returns: (transfer none): a new, floating, #GVariant
33775 * g_variant_dict_init: (skip)
33776 * @dict: a #GVariantDict
33777 * @from_asv: (allow-none): the initial value for @dict
33779 * Initialises a #GVariantDict structure.
33781 * If @from_asv is given, it is used to initialise the dictionary.
33783 * This function completely ignores the previous contents of @dict. On
33784 * one hand this means that it is valid to pass in completely
33785 * uninitialised memory. On the other hand, this means that if you are
33786 * initialising over top of an existing #GVariantDict you need to first
33787 * call g_variant_dict_clear() in order to avoid leaking memory.
33789 * You must not call g_variant_dict_ref() or g_variant_dict_unref() on a
33790 * #GVariantDict that was initialised with this function. If you ever
33791 * pass a reference to a #GVariantDict outside of the control of your
33792 * own code then you should assume that the person receiving that
33793 * reference may try to use reference counting; you should use
33794 * g_variant_dict_new() instead of this function.
33801 * g_variant_dict_insert:
33802 * @dict: a #GVariantDict
33803 * @key: the key to insert a value for
33804 * @format_string: a #GVariant varargs format string
33805 * @...: arguments, as per @format_string
33807 * Inserts a value into a #GVariantDict.
33809 * This call is a convenience wrapper that is exactly equivalent to
33810 * calling g_variant_new() followed by g_variant_dict_insert_value().
33817 * g_variant_dict_insert_value:
33818 * @dict: a #GVariantDict
33819 * @key: the key to insert a value for
33820 * @value: the value to insert
33822 * Inserts (or replaces) a key in a #GVariantDict.
33824 * @value is consumed if it is floating.
33831 * g_variant_dict_lookup:
33832 * @dict: a #GVariantDict
33833 * @key: the key to lookup in the dictionary
33834 * @format_string: a GVariant format string
33835 * @...: the arguments to unpack the value into
33837 * Looks up a value in a #GVariantDict.
33839 * This function is a wrapper around g_variant_dict_lookup_value() and
33840 * g_variant_get(). In the case that %NULL would have been returned,
33841 * this function returns %FALSE. Otherwise, it unpacks the returned
33842 * value and returns %TRUE.
33844 * @format_string determines the C types that are used for unpacking the
33845 * values and also determines if the values are copied or borrowed, see the
33846 * section on [GVariant format strings][gvariant-format-strings-pointers].
33848 * Returns: %TRUE if a value was unpacked
33854 * g_variant_dict_lookup_value:
33855 * @dict: a #GVariantDict
33856 * @key: the key to lookup in the dictionary
33857 * @expected_type: (allow-none): a #GVariantType, or %NULL
33859 * Looks up a value in a #GVariantDict.
33861 * If @key is not found in @dictionary, %NULL is returned.
33863 * The @expected_type string specifies what type of value is expected.
33864 * If the value associated with @key has a different type then %NULL is
33867 * If the key is found and the value has the correct type, it is
33868 * returned. If @expected_type was specified then any non-%NULL return
33869 * value will have this type.
33871 * Returns: (transfer full): the value of the dictionary key, or %NULL
33877 * g_variant_dict_new:
33878 * @from_asv: (allow-none): the #GVariant with which to initialise the
33881 * Allocates and initialises a new #GVariantDict.
33883 * You should call g_variant_dict_unref() on the return value when it
33884 * is no longer needed. The memory will not be automatically freed by
33887 * In some cases it may be easier to place a #GVariantDict directly on
33888 * the stack of the calling function and initialise it with
33889 * g_variant_dict_init(). This is particularly useful when you are
33890 * using #GVariantDict to construct a #GVariant.
33892 * Returns: (transfer full): a #GVariantDict
33898 * g_variant_dict_ref:
33899 * @dict: a heap-allocated #GVariantDict
33901 * Increases the reference count on @dict.
33903 * Don't call this on stack-allocated #GVariantDict instances or bad
33904 * things will happen.
33906 * Returns: (transfer full): a new reference to @dict
33912 * g_variant_dict_remove:
33913 * @dict: a #GVariantDict
33914 * @key: the key to remove
33916 * Removes a key and its associated value from a #GVariantDict.
33918 * Returns: %TRUE if the key was found and removed
33924 * g_variant_dict_unref:
33925 * @dict: (transfer full): a heap-allocated #GVariantDict
33927 * Decreases the reference count on @dict.
33929 * In the event that there are no more references, releases all memory
33930 * associated with the #GVariantDict.
33932 * Don't call this on stack-allocated #GVariantDict instances or bad
33933 * things will happen.
33940 * g_variant_dup_bytestring:
33941 * @value: an array-of-bytes #GVariant instance
33942 * @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store
33943 * the length (not including the nul terminator)
33945 * Similar to g_variant_get_bytestring() except that instead of
33946 * returning a constant string, the string is duplicated.
33948 * The return value must be freed using g_free().
33950 * Returns: (transfer full) (array zero-terminated=1 length=length) (element-type guint8):
33951 * a newly allocated string
33957 * g_variant_dup_bytestring_array:
33958 * @value: an array of array of bytes #GVariant ('aay')
33959 * @length: (out) (allow-none): the length of the result, or %NULL
33961 * Gets the contents of an array of array of bytes #GVariant. This call
33962 * makes a deep copy; the return result should be released with
33965 * If @length is non-%NULL then the number of elements in the result is
33966 * stored there. In any case, the resulting array will be
33967 * %NULL-terminated.
33969 * For an empty array, @length will be set to 0 and a pointer to a
33970 * %NULL pointer will be returned.
33972 * Returns: (array length=length) (transfer full): an array of strings
33978 * g_variant_dup_objv:
33979 * @value: an array of object paths #GVariant
33980 * @length: (out) (allow-none): the length of the result, or %NULL
33982 * Gets the contents of an array of object paths #GVariant. This call
33983 * makes a deep copy; the return result should be released with
33986 * If @length is non-%NULL then the number of elements in the result
33987 * is stored there. In any case, the resulting array will be
33988 * %NULL-terminated.
33990 * For an empty array, @length will be set to 0 and a pointer to a
33991 * %NULL pointer will be returned.
33993 * Returns: (array length=length zero-terminated=1) (transfer full): an array of strings
33999 * g_variant_dup_string:
34000 * @value: a string #GVariant instance
34001 * @length: (out): a pointer to a #gsize, to store the length
34003 * Similar to g_variant_get_string() except that instead of returning
34004 * a constant string, the string is duplicated.
34006 * The string will always be UTF-8 encoded.
34008 * The return value must be freed using g_free().
34010 * Returns: (transfer full): a newly allocated string, UTF-8 encoded
34016 * g_variant_dup_strv:
34017 * @value: an array of strings #GVariant
34018 * @length: (out) (allow-none): the length of the result, or %NULL
34020 * Gets the contents of an array of strings #GVariant. This call
34021 * makes a deep copy; the return result should be released with
34024 * If @length is non-%NULL then the number of elements in the result
34025 * is stored there. In any case, the resulting array will be
34026 * %NULL-terminated.
34028 * For an empty array, @length will be set to 0 and a pointer to a
34029 * %NULL pointer will be returned.
34031 * Returns: (array length=length zero-terminated=1) (transfer full): an array of strings
34038 * @one: (type GVariant): a #GVariant instance
34039 * @two: (type GVariant): a #GVariant instance
34041 * Checks if @one and @two have the same type and value.
34043 * The types of @one and @two are #gconstpointer only to allow use of
34044 * this function with #GHashTable. They must each be a #GVariant.
34046 * Returns: %TRUE if @one and @two are equal
34052 * g_variant_get: (skip)
34053 * @value: a #GVariant instance
34054 * @format_string: a #GVariant format string
34055 * @...: arguments, as per @format_string
34057 * Deconstructs a #GVariant instance.
34059 * Think of this function as an analogue to scanf().
34061 * The arguments that are expected by this function are entirely
34062 * determined by @format_string. @format_string also restricts the
34063 * permissible types of @value. It is an error to give a value with
34064 * an incompatible type. See the section on
34065 * [GVariant format strings][gvariant-format-strings].
34066 * Please note that the syntax of the format string is very likely to be
34067 * extended in the future.
34069 * @format_string determines the C types that are used for unpacking
34070 * the values and also determines if the values are copied or borrowed,
34071 * see the section on
34072 * [GVariant format strings][gvariant-format-strings-pointers].
34079 * g_variant_get_boolean:
34080 * @value: a boolean #GVariant instance
34082 * Returns the boolean value of @value.
34084 * It is an error to call this function with a @value of any type
34085 * other than %G_VARIANT_TYPE_BOOLEAN.
34087 * Returns: %TRUE or %FALSE
34093 * g_variant_get_byte:
34094 * @value: a byte #GVariant instance
34096 * Returns the byte value of @value.
34098 * It is an error to call this function with a @value of any type
34099 * other than %G_VARIANT_TYPE_BYTE.
34101 * Returns: a #guchar
34107 * g_variant_get_bytestring:
34108 * @value: an array-of-bytes #GVariant instance
34110 * Returns the string value of a #GVariant instance with an
34111 * array-of-bytes type. The string has no particular encoding.
34113 * If the array does not end with a nul terminator character, the empty
34114 * string is returned. For this reason, you can always trust that a
34115 * non-%NULL nul-terminated string will be returned by this function.
34117 * If the array contains a nul terminator character somewhere other than
34118 * the last byte then the returned string is the string, up to the first
34119 * such nul character.
34121 * g_variant_get_fixed_array() should be used instead if the array contains
34122 * arbitrary data that could not be nul-terminated or could contain nul bytes.
34124 * It is an error to call this function with a @value that is not an
34127 * The return value remains valid as long as @value exists.
34129 * Returns: (transfer none) (array zero-terminated=1) (element-type guint8):
34130 * the constant string
34136 * g_variant_get_bytestring_array:
34137 * @value: an array of array of bytes #GVariant ('aay')
34138 * @length: (out) (allow-none): the length of the result, or %NULL
34140 * Gets the contents of an array of array of bytes #GVariant. This call
34141 * makes a shallow copy; the return result should be released with
34142 * g_free(), but the individual strings must not be modified.
34144 * If @length is non-%NULL then the number of elements in the result is
34145 * stored there. In any case, the resulting array will be
34146 * %NULL-terminated.
34148 * For an empty array, @length will be set to 0 and a pointer to a
34149 * %NULL pointer will be returned.
34151 * Returns: (array length=length) (transfer container): an array of constant strings
34157 * g_variant_get_child: (skip)
34158 * @value: a container #GVariant
34159 * @index_: the index of the child to deconstruct
34160 * @format_string: a #GVariant format string
34161 * @...: arguments, as per @format_string
34163 * Reads a child item out of a container #GVariant instance and
34164 * deconstructs it according to @format_string. This call is
34165 * essentially a combination of g_variant_get_child_value() and
34168 * @format_string determines the C types that are used for unpacking
34169 * the values and also determines if the values are copied or borrowed,
34170 * see the section on
34171 * [GVariant format strings][gvariant-format-strings-pointers].
34178 * g_variant_get_child_value:
34179 * @value: a container #GVariant
34180 * @index_: the index of the child to fetch
34182 * Reads a child item out of a container #GVariant instance. This
34183 * includes variants, maybes, arrays, tuples and dictionary
34184 * entries. It is an error to call this function on any other type of
34187 * It is an error if @index_ is greater than the number of child items
34188 * in the container. See g_variant_n_children().
34190 * The returned value is never floating. You should free it with
34191 * g_variant_unref() when you're done with it.
34193 * This function is O(1).
34195 * Returns: (transfer full): the child at the specified index
34201 * g_variant_get_data:
34202 * @value: a #GVariant instance
34204 * Returns a pointer to the serialised form of a #GVariant instance.
34205 * The returned data may not be in fully-normalised form if read from an
34206 * untrusted source. The returned data must not be freed; it remains
34207 * valid for as long as @value exists.
34209 * If @value is a fixed-sized value that was deserialised from a
34210 * corrupted serialised container then %NULL may be returned. In this
34211 * case, the proper thing to do is typically to use the appropriate
34212 * number of nul bytes in place of @value. If @value is not fixed-sized
34213 * then %NULL is never returned.
34215 * In the case that @value is already in serialised form, this function
34216 * is O(1). If the value is not already in serialised form,
34217 * serialisation occurs implicitly and is approximately O(n) in the size
34220 * To deserialise the data returned by this function, in addition to the
34221 * serialised data, you must know the type of the #GVariant, and (if the
34222 * machine might be different) the endianness of the machine that stored
34223 * it. As a result, file formats or network messages that incorporate
34224 * serialised #GVariants must include this information either
34225 * implicitly (for instance "the file always contains a
34226 * %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or
34227 * explicitly (by storing the type and/or endianness in addition to the
34228 * serialised data).
34230 * Returns: (transfer none): the serialised form of @value, or %NULL
34236 * g_variant_get_data_as_bytes:
34237 * @value: a #GVariant
34239 * Returns a pointer to the serialised form of a #GVariant instance.
34240 * The semantics of this function are exactly the same as
34241 * g_variant_get_data(), except that the returned #GBytes holds
34242 * a reference to the variant data.
34244 * Returns: (transfer full): A new #GBytes representing the variant data
34250 * g_variant_get_double:
34251 * @value: a double #GVariant instance
34253 * Returns the double precision floating point value of @value.
34255 * It is an error to call this function with a @value of any type
34256 * other than %G_VARIANT_TYPE_DOUBLE.
34258 * Returns: a #gdouble
34264 * g_variant_get_fixed_array:
34265 * @value: a #GVariant array with fixed-sized elements
34266 * @n_elements: (out): a pointer to the location to store the number of items
34267 * @element_size: the size of each element
34269 * Provides access to the serialised data for an array of fixed-sized
34272 * @value must be an array with fixed-sized elements. Numeric types are
34273 * fixed-size, as are tuples containing only other fixed-sized types.
34275 * @element_size must be the size of a single element in the array,
34276 * as given by the section on
34277 * [serialized data memory][gvariant-serialised-data-memory].
34279 * In particular, arrays of these fixed-sized types can be interpreted
34280 * as an array of the given C type, with @element_size set to the size
34281 * the appropriate type:
34282 * - %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.)
34283 * - %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!)
34284 * - %G_VARIANT_TYPE_BYTE: #guchar
34285 * - %G_VARIANT_TYPE_HANDLE: #guint32
34286 * - %G_VARIANT_TYPE_DOUBLE: #gdouble
34288 * For example, if calling this function for an array of 32-bit integers,
34289 * you might say sizeof(gint32). This value isn't used except for the purpose
34290 * of a double-check that the form of the serialised data matches the caller's
34293 * @n_elements, which must be non-%NULL is set equal to the number of
34294 * items in the array.
34296 * Returns: (array length=n_elements) (transfer none): a pointer to
34303 * g_variant_get_handle:
34304 * @value: a handle #GVariant instance
34306 * Returns the 32-bit signed integer value of @value.
34308 * It is an error to call this function with a @value of any type other
34309 * than %G_VARIANT_TYPE_HANDLE.
34311 * By convention, handles are indexes into an array of file descriptors
34312 * that are sent alongside a D-Bus message. If you're not interacting
34313 * with D-Bus, you probably don't need them.
34315 * Returns: a #gint32
34321 * g_variant_get_int16:
34322 * @value: a int16 #GVariant instance
34324 * Returns the 16-bit signed integer value of @value.
34326 * It is an error to call this function with a @value of any type
34327 * other than %G_VARIANT_TYPE_INT16.
34329 * Returns: a #gint16
34335 * g_variant_get_int32:
34336 * @value: a int32 #GVariant instance
34338 * Returns the 32-bit signed integer value of @value.
34340 * It is an error to call this function with a @value of any type
34341 * other than %G_VARIANT_TYPE_INT32.
34343 * Returns: a #gint32
34349 * g_variant_get_int64:
34350 * @value: a int64 #GVariant instance
34352 * Returns the 64-bit signed integer value of @value.
34354 * It is an error to call this function with a @value of any type
34355 * other than %G_VARIANT_TYPE_INT64.
34357 * Returns: a #gint64
34363 * g_variant_get_maybe:
34364 * @value: a maybe-typed value
34366 * Given a maybe-typed #GVariant instance, extract its value. If the
34367 * value is Nothing, then this function returns %NULL.
34369 * Returns: (allow-none) (transfer full): the contents of @value, or %NULL
34375 * g_variant_get_normal_form:
34376 * @value: a #GVariant
34378 * Gets a #GVariant instance that has the same value as @value and is
34379 * trusted to be in normal form.
34381 * If @value is already trusted to be in normal form then a new
34382 * reference to @value is returned.
34384 * If @value is not already trusted, then it is scanned to check if it
34385 * is in normal form. If it is found to be in normal form then it is
34386 * marked as trusted and a new reference to it is returned.
34388 * If @value is found not to be in normal form then a new trusted
34389 * #GVariant is created with the same value as @value.
34391 * It makes sense to call this function if you've received #GVariant
34392 * data from untrusted sources and you want to ensure your serialised
34393 * output is definitely in normal form.
34395 * Returns: (transfer full): a trusted #GVariant
34401 * g_variant_get_objv:
34402 * @value: an array of object paths #GVariant
34403 * @length: (out) (allow-none): the length of the result, or %NULL
34405 * Gets the contents of an array of object paths #GVariant. This call
34406 * makes a shallow copy; the return result should be released with
34407 * g_free(), but the individual strings must not be modified.
34409 * If @length is non-%NULL then the number of elements in the result
34410 * is stored there. In any case, the resulting array will be
34411 * %NULL-terminated.
34413 * For an empty array, @length will be set to 0 and a pointer to a
34414 * %NULL pointer will be returned.
34416 * Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings
34422 * g_variant_get_size:
34423 * @value: a #GVariant instance
34425 * Determines the number of bytes that would be required to store @value
34426 * with g_variant_store().
34428 * If @value has a fixed-sized type then this function always returned
34431 * In the case that @value is already in serialised form or the size has
34432 * already been calculated (ie: this function has been called before)
34433 * then this function is O(1). Otherwise, the size is calculated, an
34434 * operation which is approximately O(n) in the number of values
34437 * Returns: the serialised size of @value
34443 * g_variant_get_string:
34444 * @value: a string #GVariant instance
34445 * @length: (allow-none) (default 0) (out): a pointer to a #gsize,
34446 * to store the length
34448 * Returns the string value of a #GVariant instance with a string
34449 * type. This includes the types %G_VARIANT_TYPE_STRING,
34450 * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE.
34452 * The string will always be UTF-8 encoded, and will never be %NULL.
34454 * If @length is non-%NULL then the length of the string (in bytes) is
34455 * returned there. For trusted values, this information is already
34456 * known. For untrusted values, a strlen() will be performed.
34458 * It is an error to call this function with a @value of any type
34459 * other than those three.
34461 * The return value remains valid as long as @value exists.
34463 * Returns: (transfer none): the constant string, UTF-8 encoded
34469 * g_variant_get_strv:
34470 * @value: an array of strings #GVariant
34471 * @length: (out) (allow-none): the length of the result, or %NULL
34473 * Gets the contents of an array of strings #GVariant. This call
34474 * makes a shallow copy; the return result should be released with
34475 * g_free(), but the individual strings must not be modified.
34477 * If @length is non-%NULL then the number of elements in the result
34478 * is stored there. In any case, the resulting array will be
34479 * %NULL-terminated.
34481 * For an empty array, @length will be set to 0 and a pointer to a
34482 * %NULL pointer will be returned.
34484 * Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings
34490 * g_variant_get_type:
34491 * @value: a #GVariant
34493 * Determines the type of @value.
34495 * The return value is valid for the lifetime of @value and must not
34498 * Returns: a #GVariantType
34504 * g_variant_get_type_string:
34505 * @value: a #GVariant
34507 * Returns the type string of @value. Unlike the result of calling
34508 * g_variant_type_peek_string(), this string is nul-terminated. This
34509 * string belongs to #GVariant and must not be freed.
34511 * Returns: the type string for the type of @value
34517 * g_variant_get_uint16:
34518 * @value: a uint16 #GVariant instance
34520 * Returns the 16-bit unsigned integer value of @value.
34522 * It is an error to call this function with a @value of any type
34523 * other than %G_VARIANT_TYPE_UINT16.
34525 * Returns: a #guint16
34531 * g_variant_get_uint32:
34532 * @value: a uint32 #GVariant instance
34534 * Returns the 32-bit unsigned integer value of @value.
34536 * It is an error to call this function with a @value of any type
34537 * other than %G_VARIANT_TYPE_UINT32.
34539 * Returns: a #guint32
34545 * g_variant_get_uint64:
34546 * @value: a uint64 #GVariant instance
34548 * Returns the 64-bit unsigned integer value of @value.
34550 * It is an error to call this function with a @value of any type
34551 * other than %G_VARIANT_TYPE_UINT64.
34553 * Returns: a #guint64
34559 * g_variant_get_va: (skip)
34560 * @value: a #GVariant
34561 * @format_string: a string that is prefixed with a format string
34562 * @endptr: (allow-none) (default NULL): location to store the end pointer,
34564 * @app: a pointer to a #va_list
34566 * This function is intended to be used by libraries based on #GVariant
34567 * that want to provide g_variant_get()-like functionality to their
34570 * The API is more general than g_variant_get() to allow a wider range
34571 * of possible uses.
34573 * @format_string must still point to a valid format string, but it only
34574 * need to be nul-terminated if @endptr is %NULL. If @endptr is
34575 * non-%NULL then it is updated to point to the first character past the
34576 * end of the format string.
34578 * @app is a pointer to a #va_list. The arguments, according to
34579 * @format_string, are collected from this #va_list and the list is left
34580 * pointing to the argument following the last.
34582 * These two generalisations allow mixing of multiple calls to
34583 * g_variant_new_va() and g_variant_get_va() within a single actual
34584 * varargs call by the user.
34586 * @format_string determines the C types that are used for unpacking
34587 * the values and also determines if the values are copied or borrowed,
34588 * see the section on
34589 * [GVariant format strings][gvariant-format-strings-pointers].
34596 * g_variant_get_variant:
34597 * @value: a variant #GVariant instance
34599 * Unboxes @value. The result is the #GVariant instance that was
34600 * contained in @value.
34602 * Returns: (transfer full): the item contained in the variant
34609 * @value: (type GVariant): a basic #GVariant value as a #gconstpointer
34611 * Generates a hash value for a #GVariant instance.
34613 * The output of this function is guaranteed to be the same for a given
34614 * value only per-process. It may change between different processor
34615 * architectures or even different versions of GLib. Do not use this
34616 * function as a basis for building protocols or file formats.
34618 * The type of @value is #gconstpointer only to allow use of this
34619 * function with #GHashTable. @value must be a #GVariant.
34621 * Returns: a hash value corresponding to @value
34627 * g_variant_is_container:
34628 * @value: a #GVariant instance
34630 * Checks if @value is a container.
34632 * Returns: %TRUE if @value is a container
34638 * g_variant_is_floating:
34639 * @value: a #GVariant
34641 * Checks whether @value has a floating reference count.
34643 * This function should only ever be used to assert that a given variant
34644 * is or is not floating, or for debug purposes. To acquire a reference
34645 * to a variant that might be floating, always use g_variant_ref_sink()
34646 * or g_variant_take_ref().
34648 * See g_variant_ref_sink() for more information about floating reference
34651 * Returns: whether @value is floating
34657 * g_variant_is_normal_form:
34658 * @value: a #GVariant instance
34660 * Checks if @value is in normal form.
34662 * The main reason to do this is to detect if a given chunk of
34663 * serialised data is in normal form: load the data into a #GVariant
34664 * using g_variant_new_from_data() and then use this function to
34667 * If @value is found to be in normal form then it will be marked as
34668 * being trusted. If the value was already marked as being trusted then
34669 * this function will immediately return %TRUE.
34671 * Returns: %TRUE if @value is in normal form
34677 * g_variant_is_object_path:
34678 * @string: a normal C nul-terminated string
34680 * Determines if a given string is a valid D-Bus object path. You
34681 * should ensure that a string is a valid D-Bus object path before
34682 * passing it to g_variant_new_object_path().
34684 * A valid object path starts with '/' followed by zero or more
34685 * sequences of characters separated by '/' characters. Each sequence
34686 * must contain only the characters "[A-Z][a-z][0-9]_". No sequence
34687 * (including the one following the final '/' character) may be empty.
34689 * Returns: %TRUE if @string is a D-Bus object path
34695 * g_variant_is_of_type:
34696 * @value: a #GVariant instance
34697 * @type: a #GVariantType
34699 * Checks if a value has a type matching the provided type.
34701 * Returns: %TRUE if the type of @value matches @type
34707 * g_variant_is_signature:
34708 * @string: a normal C nul-terminated string
34710 * Determines if a given string is a valid D-Bus type signature. You
34711 * should ensure that a string is a valid D-Bus type signature before
34712 * passing it to g_variant_new_signature().
34714 * D-Bus type signatures consist of zero or more definite #GVariantType
34715 * strings in sequence.
34717 * Returns: %TRUE if @string is a D-Bus type signature
34723 * g_variant_iter_copy:
34724 * @iter: a #GVariantIter
34726 * Creates a new heap-allocated #GVariantIter to iterate over the
34727 * container that was being iterated over by @iter. Iteration begins on
34728 * the new iterator from the current position of the old iterator but
34729 * the two copies are independent past that point.
34731 * Use g_variant_iter_free() to free the return value when you no longer
34734 * A reference is taken to the container that @iter is iterating over
34735 * and will be releated only when g_variant_iter_free() is called.
34737 * Returns: (transfer full): a new heap-allocated #GVariantIter
34743 * g_variant_iter_free:
34744 * @iter: (transfer full): a heap-allocated #GVariantIter
34746 * Frees a heap-allocated #GVariantIter. Only call this function on
34747 * iterators that were returned by g_variant_iter_new() or
34748 * g_variant_iter_copy().
34755 * g_variant_iter_init: (skip)
34756 * @iter: a pointer to a #GVariantIter
34757 * @value: a container #GVariant
34759 * Initialises (without allocating) a #GVariantIter. @iter may be
34760 * completely uninitialised prior to this call; its old value is
34763 * The iterator remains valid for as long as @value exists, and need not
34764 * be freed in any way.
34766 * Returns: the number of items in @value
34772 * g_variant_iter_loop: (skip)
34773 * @iter: a #GVariantIter
34774 * @format_string: a GVariant format string
34775 * @...: the arguments to unpack the value into
34777 * Gets the next item in the container and unpacks it into the variable
34778 * argument list according to @format_string, returning %TRUE.
34780 * If no more items remain then %FALSE is returned.
34782 * On the first call to this function, the pointers appearing on the
34783 * variable argument list are assumed to point at uninitialised memory.
34784 * On the second and later calls, it is assumed that the same pointers
34785 * will be given and that they will point to the memory as set by the
34786 * previous call to this function. This allows the previous values to
34787 * be freed, as appropriate.
34789 * This function is intended to be used with a while loop as
34790 * demonstrated in the following example. This function can only be
34791 * used when iterating over an array. It is only valid to call this
34792 * function with a string constant for the format string and the same
34793 * string constant must be used each time. Mixing calls to this
34794 * function and g_variant_iter_next() or g_variant_iter_next_value() on
34795 * the same iterator causes undefined behavior.
34797 * If you break out of a such a while loop using g_variant_iter_loop() then
34798 * you must free or unreference all the unpacked values as you would with
34799 * g_variant_get(). Failure to do so will cause a memory leak.
34801 * Here is an example for memory management with g_variant_iter_loop():
34802 * |[<!-- language="C" -->
34803 * // Iterates a dictionary of type 'a{sv}'
34805 * iterate_dictionary (GVariant *dictionary)
34807 * GVariantIter iter;
34811 * g_variant_iter_init (&iter, dictionary);
34812 * while (g_variant_iter_loop (&iter, "{sv}", &key, &value))
34814 * g_print ("Item '%s' has type '%s'\n", key,
34815 * g_variant_get_type_string (value));
34817 * // no need to free 'key' and 'value' here
34818 * // unless breaking out of this loop
34823 * For most cases you should use g_variant_iter_next().
34825 * This function is really only useful when unpacking into #GVariant or
34826 * #GVariantIter in order to allow you to skip the call to
34827 * g_variant_unref() or g_variant_iter_free().
34829 * For example, if you are only looping over simple integer and string
34830 * types, g_variant_iter_next() is definitely preferred. For string
34831 * types, use the '&' prefix to avoid allocating any memory at all (and
34832 * thereby avoiding the need to free anything as well).
34834 * @format_string determines the C types that are used for unpacking
34835 * the values and also determines if the values are copied or borrowed.
34837 * See the section on
34838 * [GVariant format strings][gvariant-format-strings-pointers].
34840 * Returns: %TRUE if a value was unpacked, or %FALSE if there was no
34847 * g_variant_iter_n_children:
34848 * @iter: a #GVariantIter
34850 * Queries the number of child items in the container that we are
34851 * iterating over. This is the total number of items -- not the number
34852 * of items remaining.
34854 * This function might be useful for preallocation of arrays.
34856 * Returns: the number of children in the container
34862 * g_variant_iter_new:
34863 * @value: a container #GVariant
34865 * Creates a heap-allocated #GVariantIter for iterating over the items
34868 * Use g_variant_iter_free() to free the return value when you no longer
34871 * A reference is taken to @value and will be released only when
34872 * g_variant_iter_free() is called.
34874 * Returns: (transfer full): a new heap-allocated #GVariantIter
34880 * g_variant_iter_next: (skip)
34881 * @iter: a #GVariantIter
34882 * @format_string: a GVariant format string
34883 * @...: the arguments to unpack the value into
34885 * Gets the next item in the container and unpacks it into the variable
34886 * argument list according to @format_string, returning %TRUE.
34888 * If no more items remain then %FALSE is returned.
34890 * All of the pointers given on the variable arguments list of this
34891 * function are assumed to point at uninitialised memory. It is the
34892 * responsibility of the caller to free all of the values returned by
34893 * the unpacking process.
34895 * Here is an example for memory management with g_variant_iter_next():
34896 * |[<!-- language="C" -->
34897 * // Iterates a dictionary of type 'a{sv}'
34899 * iterate_dictionary (GVariant *dictionary)
34901 * GVariantIter iter;
34905 * g_variant_iter_init (&iter, dictionary);
34906 * while (g_variant_iter_next (&iter, "{sv}", &key, &value))
34908 * g_print ("Item '%s' has type '%s'\n", key,
34909 * g_variant_get_type_string (value));
34911 * // must free data for ourselves
34912 * g_variant_unref (value);
34918 * For a solution that is likely to be more convenient to C programmers
34919 * when dealing with loops, see g_variant_iter_loop().
34921 * @format_string determines the C types that are used for unpacking
34922 * the values and also determines if the values are copied or borrowed.
34924 * See the section on
34925 * [GVariant format strings][gvariant-format-strings-pointers].
34927 * Returns: %TRUE if a value was unpacked, or %FALSE if there as no value
34933 * g_variant_iter_next_value:
34934 * @iter: a #GVariantIter
34936 * Gets the next item in the container. If no more items remain then
34937 * %NULL is returned.
34939 * Use g_variant_unref() to drop your reference on the return value when
34940 * you no longer need it.
34942 * Here is an example for iterating with g_variant_iter_next_value():
34943 * |[<!-- language="C" -->
34944 * // recursively iterate a container
34946 * iterate_container_recursive (GVariant *container)
34948 * GVariantIter iter;
34951 * g_variant_iter_init (&iter, container);
34952 * while ((child = g_variant_iter_next_value (&iter)))
34954 * g_print ("type '%s'\n", g_variant_get_type_string (child));
34956 * if (g_variant_is_container (child))
34957 * iterate_container_recursive (child);
34959 * g_variant_unref (child);
34964 * Returns: (allow-none) (transfer full): a #GVariant, or %NULL
34970 * g_variant_lookup: (skip)
34971 * @dictionary: a dictionary #GVariant
34972 * @key: the key to lookup in the dictionary
34973 * @format_string: a GVariant format string
34974 * @...: the arguments to unpack the value into
34976 * Looks up a value in a dictionary #GVariant.
34978 * This function is a wrapper around g_variant_lookup_value() and
34979 * g_variant_get(). In the case that %NULL would have been returned,
34980 * this function returns %FALSE. Otherwise, it unpacks the returned
34981 * value and returns %TRUE.
34983 * @format_string determines the C types that are used for unpacking
34984 * the values and also determines if the values are copied or borrowed,
34985 * see the section on
34986 * [GVariant format strings][gvariant-format-strings-pointers].
34988 * This function is currently implemented with a linear scan. If you
34989 * plan to do many lookups then #GVariantDict may be more efficient.
34991 * Returns: %TRUE if a value was unpacked
34997 * g_variant_lookup_value:
34998 * @dictionary: a dictionary #GVariant
34999 * @key: the key to lookup in the dictionary
35000 * @expected_type: (allow-none): a #GVariantType, or %NULL
35002 * Looks up a value in a dictionary #GVariant.
35004 * This function works with dictionaries of the type a{s*} (and equally
35005 * well with type a{o*}, but we only further discuss the string case
35006 * for sake of clarity).
35008 * In the event that @dictionary has the type a{sv}, the @expected_type
35009 * string specifies what type of value is expected to be inside of the
35010 * variant. If the value inside the variant has a different type then
35011 * %NULL is returned. In the event that @dictionary has a value type other
35012 * than v then @expected_type must directly match the key type and it is
35013 * used to unpack the value directly or an error occurs.
35015 * In either case, if @key is not found in @dictionary, %NULL is returned.
35017 * If the key is found and the value has the correct type, it is
35018 * returned. If @expected_type was specified then any non-%NULL return
35019 * value will have this type.
35021 * This function is currently implemented with a linear scan. If you
35022 * plan to do many lookups then #GVariantDict may be more efficient.
35024 * Returns: (transfer full): the value of the dictionary key, or %NULL
35030 * g_variant_n_children:
35031 * @value: a container #GVariant
35033 * Determines the number of children in a container #GVariant instance.
35034 * This includes variants, maybes, arrays, tuples and dictionary
35035 * entries. It is an error to call this function on any other type of
35038 * For variants, the return value is always 1. For values with maybe
35039 * types, it is always zero or one. For arrays, it is the length of the
35040 * array. For tuples it is the number of tuple items (which depends
35041 * only on the type). For dictionary entries, it is always 2
35043 * This function is O(1).
35045 * Returns: the number of children in the container
35051 * g_variant_new: (skip)
35052 * @format_string: a #GVariant format string
35053 * @...: arguments, as per @format_string
35055 * Creates a new #GVariant instance.
35057 * Think of this function as an analogue to g_strdup_printf().
35059 * The type of the created instance and the arguments that are expected
35060 * by this function are determined by @format_string. See the section on
35061 * [GVariant format strings][gvariant-format-strings]. Please note that
35062 * the syntax of the format string is very likely to be extended in the
35065 * The first character of the format string must not be '*' '?' '@' or
35066 * 'r'; in essence, a new #GVariant must always be constructed by this
35067 * function (and not merely passed through it unmodified).
35069 * Note that the arguments must be of the correct width for their types
35070 * specified in @format_string. This can be achieved by casting them. See
35071 * the [GVariant varargs documentation][gvariant-varargs].
35073 * |[<!-- language="C" -->
35074 * MyFlags some_flags = FLAG_ONE | FLAG_TWO;
35075 * const gchar *some_strings[] = { "a", "b", "c", NULL };
35076 * GVariant *new_variant;
35078 * new_variant = g_variant_new ("(t^as)",
35079 * /<!-- -->* This cast is required. *<!-- -->/
35080 * (guint64) some_flags,
35084 * Returns: a new floating #GVariant instance
35090 * g_variant_new_array:
35091 * @child_type: (allow-none): the element type of the new array
35092 * @children: (allow-none) (array length=n_children): an array of
35093 * #GVariant pointers, the children
35094 * @n_children: the length of @children
35096 * Creates a new #GVariant array from @children.
35098 * @child_type must be non-%NULL if @n_children is zero. Otherwise, the
35099 * child type is determined by inspecting the first element of the
35100 * @children array. If @child_type is non-%NULL then it must be a
35103 * The items of the array are taken from the @children array. No entry
35104 * in the @children array may be %NULL.
35106 * All items in the array must have the same type, which must be the
35107 * same as @child_type, if given.
35109 * If the @children are floating references (see g_variant_ref_sink()), the
35110 * new instance takes ownership of them as if via g_variant_ref_sink().
35112 * Returns: (transfer none): a floating reference to a new #GVariant array
35118 * g_variant_new_boolean:
35119 * @value: a #gboolean value
35121 * Creates a new boolean #GVariant instance -- either %TRUE or %FALSE.
35123 * Returns: (transfer none): a floating reference to a new boolean #GVariant instance
35129 * g_variant_new_byte:
35130 * @value: a #guint8 value
35132 * Creates a new byte #GVariant instance.
35134 * Returns: (transfer none): a floating reference to a new byte #GVariant instance
35140 * g_variant_new_bytestring:
35141 * @string: (array zero-terminated=1) (element-type guint8): a normal
35142 * nul-terminated string in no particular encoding
35144 * Creates an array-of-bytes #GVariant with the contents of @string.
35145 * This function is just like g_variant_new_string() except that the
35146 * string need not be valid UTF-8.
35148 * The nul terminator character at the end of the string is stored in
35151 * Returns: (transfer none): a floating reference to a new bytestring #GVariant instance
35157 * g_variant_new_bytestring_array:
35158 * @strv: (array length=length): an array of strings
35159 * @length: the length of @strv, or -1
35161 * Constructs an array of bytestring #GVariant from the given array of
35164 * If @length is -1 then @strv is %NULL-terminated.
35166 * Returns: (transfer none): a new floating #GVariant instance
35172 * g_variant_new_dict_entry: (constructor)
35173 * @key: a basic #GVariant, the key
35174 * @value: a #GVariant, the value
35176 * Creates a new dictionary entry #GVariant. @key and @value must be
35177 * non-%NULL. @key must be a value of a basic type (ie: not a container).
35179 * If the @key or @value are floating references (see g_variant_ref_sink()),
35180 * the new instance takes ownership of them as if via g_variant_ref_sink().
35182 * Returns: (transfer none): a floating reference to a new dictionary entry #GVariant
35188 * g_variant_new_double:
35189 * @value: a #gdouble floating point value
35191 * Creates a new double #GVariant instance.
35193 * Returns: (transfer none): a floating reference to a new double #GVariant instance
35199 * g_variant_new_fixed_array:
35200 * @element_type: the #GVariantType of each element
35201 * @elements: a pointer to the fixed array of contiguous elements
35202 * @n_elements: the number of elements
35203 * @element_size: the size of each element
35205 * Provides access to the serialised data for an array of fixed-sized
35208 * @value must be an array with fixed-sized elements. Numeric types are
35209 * fixed-size as are tuples containing only other fixed-sized types.
35211 * @element_size must be the size of a single element in the array.
35212 * For example, if calling this function for an array of 32-bit integers,
35213 * you might say sizeof(gint32). This value isn't used except for the purpose
35214 * of a double-check that the form of the serialised data matches the caller's
35217 * @n_elements, which must be non-%NULL is set equal to the number of
35218 * items in the array.
35220 * Returns: (transfer none): a floating reference to a new array #GVariant instance
35226 * g_variant_new_from_bytes:
35227 * @type: a #GVariantType
35228 * @bytes: a #GBytes
35229 * @trusted: if the contents of @bytes are trusted
35231 * Constructs a new serialised-mode #GVariant instance. This is the
35232 * inner interface for creation of new serialised values that gets
35233 * called from various functions in gvariant.c.
35235 * A reference is taken on @bytes.
35237 * Returns: (transfer none): a new #GVariant with a floating reference
35243 * g_variant_new_from_data:
35244 * @type: a definite #GVariantType
35245 * @data: (array length=size) (element-type guint8): the serialised data
35246 * @size: the size of @data
35247 * @trusted: %TRUE if @data is definitely in normal form
35248 * @notify: (scope async): function to call when @data is no longer needed
35249 * @user_data: data for @notify
35251 * Creates a new #GVariant instance from serialised data.
35253 * @type is the type of #GVariant instance that will be constructed.
35254 * The interpretation of @data depends on knowing the type.
35256 * @data is not modified by this function and must remain valid with an
35257 * unchanging value until such a time as @notify is called with
35258 * @user_data. If the contents of @data change before that time then
35259 * the result is undefined.
35261 * If @data is trusted to be serialised data in normal form then
35262 * @trusted should be %TRUE. This applies to serialised data created
35263 * within this process or read from a trusted location on the disk (such
35264 * as a file installed in /usr/lib alongside your application). You
35265 * should set trusted to %FALSE if @data is read from the network, a
35266 * file in the user's home directory, etc.
35268 * If @data was not stored in this machine's native endianness, any multi-byte
35269 * numeric values in the returned variant will also be in non-native
35270 * endianness. g_variant_byteswap() can be used to recover the original values.
35272 * @notify will be called with @user_data when @data is no longer
35273 * needed. The exact time of this call is unspecified and might even be
35274 * before this function returns.
35276 * Returns: (transfer none): a new floating #GVariant of type @type
35282 * g_variant_new_handle:
35283 * @value: a #gint32 value
35285 * Creates a new handle #GVariant instance.
35287 * By convention, handles are indexes into an array of file descriptors
35288 * that are sent alongside a D-Bus message. If you're not interacting
35289 * with D-Bus, you probably don't need them.
35291 * Returns: (transfer none): a floating reference to a new handle #GVariant instance
35297 * g_variant_new_int16:
35298 * @value: a #gint16 value
35300 * Creates a new int16 #GVariant instance.
35302 * Returns: (transfer none): a floating reference to a new int16 #GVariant instance
35308 * g_variant_new_int32:
35309 * @value: a #gint32 value
35311 * Creates a new int32 #GVariant instance.
35313 * Returns: (transfer none): a floating reference to a new int32 #GVariant instance
35319 * g_variant_new_int64:
35320 * @value: a #gint64 value
35322 * Creates a new int64 #GVariant instance.
35324 * Returns: (transfer none): a floating reference to a new int64 #GVariant instance
35330 * g_variant_new_maybe:
35331 * @child_type: (allow-none): the #GVariantType of the child, or %NULL
35332 * @child: (allow-none): the child value, or %NULL
35334 * Depending on if @child is %NULL, either wraps @child inside of a
35335 * maybe container or creates a Nothing instance for the given @type.
35337 * At least one of @child_type and @child must be non-%NULL.
35338 * If @child_type is non-%NULL then it must be a definite type.
35339 * If they are both non-%NULL then @child_type must be the type
35342 * If @child is a floating reference (see g_variant_ref_sink()), the new
35343 * instance takes ownership of @child.
35345 * Returns: (transfer none): a floating reference to a new #GVariant maybe instance
35351 * g_variant_new_object_path:
35352 * @object_path: a normal C nul-terminated string
35354 * Creates a D-Bus object path #GVariant with the contents of @string.
35355 * @string must be a valid D-Bus object path. Use
35356 * g_variant_is_object_path() if you're not sure.
35358 * Returns: (transfer none): a floating reference to a new object path #GVariant instance
35364 * g_variant_new_objv:
35365 * @strv: (array length=length) (element-type utf8): an array of strings
35366 * @length: the length of @strv, or -1
35368 * Constructs an array of object paths #GVariant from the given array of
35371 * Each string must be a valid #GVariant object path; see
35372 * g_variant_is_object_path().
35374 * If @length is -1 then @strv is %NULL-terminated.
35376 * Returns: (transfer none): a new floating #GVariant instance
35382 * g_variant_new_parsed:
35383 * @format: a text format #GVariant
35384 * @...: arguments as per @format
35386 * Parses @format and returns the result.
35388 * @format must be a text format #GVariant with one extension: at any
35389 * point that a value may appear in the text, a '%' character followed
35390 * by a GVariant format string (as per g_variant_new()) may appear. In
35391 * that case, the same arguments are collected from the argument list as
35392 * g_variant_new() would have collected.
35394 * Note that the arguments must be of the correct width for their types
35395 * specified in @format. This can be achieved by casting them. See
35396 * the [GVariant varargs documentation][gvariant-varargs].
35398 * Consider this simple example:
35399 * |[<!-- language="C" -->
35400 * g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three");
35403 * In the example, the variable argument parameters are collected and
35404 * filled in as if they were part of the original string to produce the
35406 * |[<!-- language="C" -->
35407 * [('one', 1), ('two', 2), ('three', 3)]
35410 * This function is intended only to be used with @format as a string
35411 * literal. Any parse error is fatal to the calling process. If you
35412 * want to parse data from untrusted sources, use g_variant_parse().
35414 * You may not use this function to return, unmodified, a single
35415 * #GVariant pointer from the argument list. ie: @format may not solely
35416 * be anything along the lines of "%*", "%?", "\%r", or anything starting
35419 * Returns: a new floating #GVariant instance
35424 * g_variant_new_parsed_va:
35425 * @format: a text format #GVariant
35426 * @app: a pointer to a #va_list
35428 * Parses @format and returns the result.
35430 * This is the version of g_variant_new_parsed() intended to be used
35433 * The return value will be floating if it was a newly created GVariant
35434 * instance. In the case that @format simply specified the collection
35435 * of a #GVariant pointer (eg: @format was "%*") then the collected
35436 * #GVariant pointer will be returned unmodified, without adding any
35437 * additional references.
35439 * Note that the arguments in @app must be of the correct width for their types
35440 * specified in @format when collected into the #va_list. See
35441 * the [GVariant varargs documentation][gvariant-varargs].
35443 * In order to behave correctly in all cases it is necessary for the
35444 * calling function to g_variant_ref_sink() the return result before
35445 * returning control to the user that originally provided the pointer.
35446 * At this point, the caller will have their own full reference to the
35447 * result. This can also be done by adding the result to a container,
35448 * or by passing it to another g_variant_new() call.
35450 * Returns: a new, usually floating, #GVariant
35455 * g_variant_new_printf: (skip)
35456 * @format_string: a printf-style format string
35457 * @...: arguments for @format_string
35459 * Creates a string-type GVariant using printf formatting.
35461 * This is similar to calling g_strdup_printf() and then
35462 * g_variant_new_string() but it saves a temporary variable and an
35463 * unnecessary copy.
35465 * Returns: (transfer none): a floating reference to a new string
35466 * #GVariant instance
35472 * g_variant_new_signature:
35473 * @signature: a normal C nul-terminated string
35475 * Creates a D-Bus type signature #GVariant with the contents of
35476 * @string. @string must be a valid D-Bus type signature. Use
35477 * g_variant_is_signature() if you're not sure.
35479 * Returns: (transfer none): a floating reference to a new signature #GVariant instance
35485 * g_variant_new_string:
35486 * @string: a normal UTF-8 nul-terminated string
35488 * Creates a string #GVariant with the contents of @string.
35490 * @string must be valid UTF-8, and must not be %NULL. To encode
35491 * potentially-%NULL strings, use g_variant_new() with `ms` as the
35492 * [format string][gvariant-format-strings-maybe-types].
35494 * Returns: (transfer none): a floating reference to a new string #GVariant instance
35500 * g_variant_new_strv:
35501 * @strv: (array length=length) (element-type utf8): an array of strings
35502 * @length: the length of @strv, or -1
35504 * Constructs an array of strings #GVariant from the given array of
35507 * If @length is -1 then @strv is %NULL-terminated.
35509 * Returns: (transfer none): a new floating #GVariant instance
35515 * g_variant_new_take_string: (skip)
35516 * @string: a normal UTF-8 nul-terminated string
35518 * Creates a string #GVariant with the contents of @string.
35520 * @string must be valid UTF-8, and must not be %NULL. To encode
35521 * potentially-%NULL strings, use this with g_variant_new_maybe().
35523 * This function consumes @string. g_free() will be called on @string
35524 * when it is no longer required.
35526 * You must not modify or access @string in any other way after passing
35527 * it to this function. It is even possible that @string is immediately
35530 * Returns: (transfer none): a floating reference to a new string
35531 * #GVariant instance
35537 * g_variant_new_tuple:
35538 * @children: (array length=n_children): the items to make the tuple out of
35539 * @n_children: the length of @children
35541 * Creates a new tuple #GVariant out of the items in @children. The
35542 * type is determined from the types of @children. No entry in the
35543 * @children array may be %NULL.
35545 * If @n_children is 0 then the unit tuple is constructed.
35547 * If the @children are floating references (see g_variant_ref_sink()), the
35548 * new instance takes ownership of them as if via g_variant_ref_sink().
35550 * Returns: (transfer none): a floating reference to a new #GVariant tuple
35556 * g_variant_new_uint16:
35557 * @value: a #guint16 value
35559 * Creates a new uint16 #GVariant instance.
35561 * Returns: (transfer none): a floating reference to a new uint16 #GVariant instance
35567 * g_variant_new_uint32:
35568 * @value: a #guint32 value
35570 * Creates a new uint32 #GVariant instance.
35572 * Returns: (transfer none): a floating reference to a new uint32 #GVariant instance
35578 * g_variant_new_uint64:
35579 * @value: a #guint64 value
35581 * Creates a new uint64 #GVariant instance.
35583 * Returns: (transfer none): a floating reference to a new uint64 #GVariant instance
35589 * g_variant_new_va: (skip)
35590 * @format_string: a string that is prefixed with a format string
35591 * @endptr: (allow-none) (default NULL): location to store the end pointer,
35593 * @app: a pointer to a #va_list
35595 * This function is intended to be used by libraries based on
35596 * #GVariant that want to provide g_variant_new()-like functionality
35599 * The API is more general than g_variant_new() to allow a wider range
35600 * of possible uses.
35602 * @format_string must still point to a valid format string, but it only
35603 * needs to be nul-terminated if @endptr is %NULL. If @endptr is
35604 * non-%NULL then it is updated to point to the first character past the
35605 * end of the format string.
35607 * @app is a pointer to a #va_list. The arguments, according to
35608 * @format_string, are collected from this #va_list and the list is left
35609 * pointing to the argument following the last.
35611 * Note that the arguments in @app must be of the correct width for their
35612 * types specified in @format_string when collected into the #va_list.
35613 * See the [GVariant varargs documentation][gvariant-varargs.
35615 * These two generalisations allow mixing of multiple calls to
35616 * g_variant_new_va() and g_variant_get_va() within a single actual
35617 * varargs call by the user.
35619 * The return value will be floating if it was a newly created GVariant
35620 * instance (for example, if the format string was "(ii)"). In the case
35621 * that the format_string was '*', '?', 'r', or a format starting with
35622 * '@' then the collected #GVariant pointer will be returned unmodified,
35623 * without adding any additional references.
35625 * In order to behave correctly in all cases it is necessary for the
35626 * calling function to g_variant_ref_sink() the return result before
35627 * returning control to the user that originally provided the pointer.
35628 * At this point, the caller will have their own full reference to the
35629 * result. This can also be done by adding the result to a container,
35630 * or by passing it to another g_variant_new() call.
35632 * Returns: a new, usually floating, #GVariant
35638 * g_variant_new_variant: (constructor)
35639 * @value: a #GVariant instance
35641 * Boxes @value. The result is a #GVariant instance representing a
35642 * variant containing the original value.
35644 * If @child is a floating reference (see g_variant_ref_sink()), the new
35645 * instance takes ownership of @child.
35647 * Returns: (transfer none): a floating reference to a new variant #GVariant instance
35654 * @type: (allow-none): a #GVariantType, or %NULL
35655 * @text: a string containing a GVariant in text form
35656 * @limit: (allow-none): a pointer to the end of @text, or %NULL
35657 * @endptr: (allow-none): a location to store the end pointer, or %NULL
35658 * @error: (allow-none): a pointer to a %NULL #GError pointer, or %NULL
35660 * Parses a #GVariant from a text representation.
35662 * A single #GVariant is parsed from the content of @text.
35664 * The format is described [here][gvariant-text].
35666 * The memory at @limit will never be accessed and the parser behaves as
35667 * if the character at @limit is the nul terminator. This has the
35668 * effect of bounding @text.
35670 * If @endptr is non-%NULL then @text is permitted to contain data
35671 * following the value that this function parses and @endptr will be
35672 * updated to point to the first character past the end of the text
35673 * parsed by this function. If @endptr is %NULL and there is extra data
35674 * then an error is returned.
35676 * If @type is non-%NULL then the value will be parsed to have that
35677 * type. This may result in additional parse errors (in the case that
35678 * the parsed value doesn't fit the type) but may also result in fewer
35679 * errors (in the case that the type would have been ambiguous, such as
35680 * with empty arrays).
35682 * In the event that the parsing is successful, the resulting #GVariant
35683 * is returned. It is never floating, and must be freed with
35684 * g_variant_unref().
35686 * In case of any error, %NULL will be returned. If @error is non-%NULL
35687 * then it will be set to reflect the error that occurred.
35689 * Officially, the language understood by the parser is "any string
35690 * produced by g_variant_print()".
35692 * Returns: a non-floating reference to a #GVariant, or %NULL
35697 * g_variant_parse_error_print_context:
35698 * @error: a #GError from the #GVariantParseError domain
35699 * @source_str: the string that was given to the parser
35701 * Pretty-prints a message showing the context of a #GVariant parse
35702 * error within the string for which parsing was attempted.
35704 * The resulting string is suitable for output to the console or other
35705 * monospace media where newlines are treated in the usual way.
35707 * The message will typically look something like one of the following:
35710 * unterminated string constant:
35718 * unable to find a common type:
35723 * The format of the message may change in a future version.
35725 * @error must have come from a failed attempt to g_variant_parse() and
35726 * @source_str must be exactly the same string that caused the error.
35727 * If @source_str was not nul-terminated when you passed it to
35728 * g_variant_parse() then you must add nul termination before using this
35731 * Returns: (transfer full): the printed message
35737 * g_variant_parser_get_error_quark:
35739 * Same as g_variant_error_quark().
35741 * Deprecated: Use g_variant_parse_error_quark() instead.
35747 * @value: a #GVariant
35748 * @type_annotate: %TRUE if type information should be included in
35751 * Pretty-prints @value in the format understood by g_variant_parse().
35753 * The format is described [here][gvariant-text].
35755 * If @type_annotate is %TRUE, then type information is included in
35758 * Returns: (transfer full): a newly-allocated string holding the result.
35764 * g_variant_print_string: (skip)
35765 * @value: a #GVariant
35766 * @string: (allow-none) (default NULL): a #GString, or %NULL
35767 * @type_annotate: %TRUE if type information should be included in
35770 * Behaves as g_variant_print(), but operates on a #GString.
35772 * If @string is non-%NULL then it is appended to and returned. Else,
35773 * a new empty #GString is allocated and it is returned.
35775 * Returns: a #GString containing the string
35782 * @value: a #GVariant
35784 * Increases the reference count of @value.
35786 * Returns: the same @value
35792 * g_variant_ref_sink:
35793 * @value: a #GVariant
35795 * #GVariant uses a floating reference count system. All functions with
35796 * names starting with `g_variant_new_` return floating
35799 * Calling g_variant_ref_sink() on a #GVariant with a floating reference
35800 * will convert the floating reference into a full reference. Calling
35801 * g_variant_ref_sink() on a non-floating #GVariant results in an
35802 * additional normal reference being added.
35804 * In other words, if the @value is floating, then this call "assumes
35805 * ownership" of the floating reference, converting it to a normal
35806 * reference. If the @value is not floating, then this call adds a
35807 * new normal reference increasing the reference count by one.
35809 * All calls that result in a #GVariant instance being inserted into a
35810 * container will call g_variant_ref_sink() on the instance. This means
35811 * that if the value was just created (and has only its floating
35812 * reference) then the container will assume sole ownership of the value
35813 * at that point and the caller will not need to unreference it. This
35814 * makes certain common styles of programming much easier while still
35815 * maintaining normal refcounting semantics in situations where values
35816 * are not floating.
35818 * Returns: the same @value
35825 * @value: the #GVariant to store
35826 * @data: (not nullable): the location to store the serialised data at
35828 * Stores the serialised form of @value at @data. @data should be
35829 * large enough. See g_variant_get_size().
35831 * The stored data is in machine native byte order but may not be in
35832 * fully-normalised form if read from an untrusted source. See
35833 * g_variant_get_normal_form() for a solution.
35835 * As with g_variant_get_data(), to be able to deserialise the
35836 * serialised variant successfully, its type and (if the destination
35837 * machine might be different) its endianness must also be available.
35839 * This function is approximately O(n) in the size of @data.
35846 * g_variant_take_ref:
35847 * @value: a #GVariant
35849 * If @value is floating, sink it. Otherwise, do nothing.
35851 * Typically you want to use g_variant_ref_sink() in order to
35852 * automatically do the correct thing with respect to floating or
35853 * non-floating references, but there is one specific scenario where
35854 * this function is helpful.
35856 * The situation where this function is helpful is when creating an API
35857 * that allows the user to provide a callback function that returns a
35858 * #GVariant. We certainly want to allow the user the flexibility to
35859 * return a non-floating reference from this callback (for the case
35860 * where the value that is being returned already exists).
35862 * At the same time, the style of the #GVariant API makes it likely that
35863 * for newly-created #GVariant instances, the user can be saved some
35864 * typing if they are allowed to return a #GVariant with a floating
35867 * Using this function on the return value of the user's callback allows
35868 * the user to do whichever is more convenient for them. The caller
35869 * will alway receives exactly one full reference to the value: either
35870 * the one that was returned in the first place, or a floating reference
35871 * that has been converted to a full reference.
35873 * This function has an odd interaction when combined with
35874 * g_variant_ref_sink() running at the same time in another thread on
35875 * the same #GVariant instance. If g_variant_ref_sink() runs first then
35876 * the result will be that the floating reference is converted to a hard
35877 * reference. If g_variant_take_ref() runs first then the result will
35878 * be that the floating reference is converted to a hard reference and
35879 * an additional reference on top of that one is added. It is best to
35880 * avoid this situation.
35882 * Returns: the same @value
35887 * g_variant_type_copy:
35888 * @type: a #GVariantType
35890 * Makes a copy of a #GVariantType. It is appropriate to call
35891 * g_variant_type_free() on the return value. @type may not be %NULL.
35893 * Returns: (transfer full): a new #GVariantType
35900 * g_variant_type_dup_string:
35901 * @type: a #GVariantType
35903 * Returns a newly-allocated copy of the type string corresponding to
35904 * @type. The returned string is nul-terminated. It is appropriate to
35905 * call g_free() on the return value.
35907 * Returns: (transfer full): the corresponding type string
35914 * g_variant_type_element:
35915 * @type: an array or maybe #GVariantType
35917 * Determines the element type of an array or maybe type.
35919 * This function may only be used with array or maybe types.
35921 * Returns: (transfer none): the element type of @type
35928 * g_variant_type_equal:
35929 * @type1: (type GVariantType): a #GVariantType
35930 * @type2: (type GVariantType): a #GVariantType
35932 * Compares @type1 and @type2 for equality.
35934 * Only returns %TRUE if the types are exactly equal. Even if one type
35935 * is an indefinite type and the other is a subtype of it, %FALSE will
35936 * be returned if they are not exactly equal. If you want to check for
35937 * subtypes, use g_variant_type_is_subtype_of().
35939 * The argument types of @type1 and @type2 are only #gconstpointer to
35940 * allow use with #GHashTable without function pointer casting. For
35941 * both arguments, a valid #GVariantType must be provided.
35943 * Returns: %TRUE if @type1 and @type2 are exactly equal
35950 * g_variant_type_first:
35951 * @type: a tuple or dictionary entry #GVariantType
35953 * Determines the first item type of a tuple or dictionary entry
35956 * This function may only be used with tuple or dictionary entry types,
35957 * but must not be used with the generic tuple type
35958 * %G_VARIANT_TYPE_TUPLE.
35960 * In the case of a dictionary entry type, this returns the type of
35963 * %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT.
35965 * This call, together with g_variant_type_next() provides an iterator
35966 * interface over tuple and dictionary entry types.
35968 * Returns: (transfer none): the first item type of @type, or %NULL
35975 * g_variant_type_free:
35976 * @type: (allow-none): a #GVariantType, or %NULL
35978 * Frees a #GVariantType that was allocated with
35979 * g_variant_type_copy(), g_variant_type_new() or one of the container
35980 * type constructor functions.
35982 * In the case that @type is %NULL, this function does nothing.
35989 * g_variant_type_get_string_length:
35990 * @type: a #GVariantType
35992 * Returns the length of the type string corresponding to the given
35993 * @type. This function must be used to determine the valid extent of
35994 * the memory region returned by g_variant_type_peek_string().
35996 * Returns: the length of the corresponding type string
36003 * g_variant_type_hash:
36004 * @type: (type GVariantType): a #GVariantType
36008 * The argument type of @type is only #gconstpointer to allow use with
36009 * #GHashTable without function pointer casting. A valid
36010 * #GVariantType must be provided.
36012 * Returns: the hash value
36019 * g_variant_type_is_array:
36020 * @type: a #GVariantType
36022 * Determines if the given @type is an array type. This is true if the
36023 * type string for @type starts with an 'a'.
36025 * This function returns %TRUE for any indefinite type for which every
36026 * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
36029 * Returns: %TRUE if @type is an array type
36036 * g_variant_type_is_basic:
36037 * @type: a #GVariantType
36039 * Determines if the given @type is a basic type.
36041 * Basic types are booleans, bytes, integers, doubles, strings, object
36042 * paths and signatures.
36044 * Only a basic type may be used as the key of a dictionary entry.
36046 * This function returns %FALSE for all indefinite types except
36047 * %G_VARIANT_TYPE_BASIC.
36049 * Returns: %TRUE if @type is a basic type
36056 * g_variant_type_is_container:
36057 * @type: a #GVariantType
36059 * Determines if the given @type is a container type.
36061 * Container types are any array, maybe, tuple, or dictionary
36062 * entry types plus the variant type.
36064 * This function returns %TRUE for any indefinite type for which every
36065 * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
36068 * Returns: %TRUE if @type is a container type
36075 * g_variant_type_is_definite:
36076 * @type: a #GVariantType
36078 * Determines if the given @type is definite (ie: not indefinite).
36080 * A type is definite if its type string does not contain any indefinite
36081 * type characters ('*', '?', or 'r').
36083 * A #GVariant instance may not have an indefinite type, so calling
36084 * this function on the result of g_variant_get_type() will always
36085 * result in %TRUE being returned. Calling this function on an
36086 * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
36087 * %FALSE being returned.
36089 * Returns: %TRUE if @type is definite
36096 * g_variant_type_is_dict_entry:
36097 * @type: a #GVariantType
36099 * Determines if the given @type is a dictionary entry type. This is
36100 * true if the type string for @type starts with a '{'.
36102 * This function returns %TRUE for any indefinite type for which every
36103 * definite subtype is a dictionary entry type --
36104 * %G_VARIANT_TYPE_DICT_ENTRY, for example.
36106 * Returns: %TRUE if @type is a dictionary entry type
36113 * g_variant_type_is_maybe:
36114 * @type: a #GVariantType
36116 * Determines if the given @type is a maybe type. This is true if the
36117 * type string for @type starts with an 'm'.
36119 * This function returns %TRUE for any indefinite type for which every
36120 * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
36123 * Returns: %TRUE if @type is a maybe type
36130 * g_variant_type_is_subtype_of:
36131 * @type: a #GVariantType
36132 * @supertype: a #GVariantType
36134 * Checks if @type is a subtype of @supertype.
36136 * This function returns %TRUE if @type is a subtype of @supertype. All
36137 * types are considered to be subtypes of themselves. Aside from that,
36138 * only indefinite types can have subtypes.
36140 * Returns: %TRUE if @type is a subtype of @supertype
36147 * g_variant_type_is_tuple:
36148 * @type: a #GVariantType
36150 * Determines if the given @type is a tuple type. This is true if the
36151 * type string for @type starts with a '(' or if @type is
36152 * %G_VARIANT_TYPE_TUPLE.
36154 * This function returns %TRUE for any indefinite type for which every
36155 * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
36158 * Returns: %TRUE if @type is a tuple type
36165 * g_variant_type_is_variant:
36166 * @type: a #GVariantType
36168 * Determines if the given @type is the variant type.
36170 * Returns: %TRUE if @type is the variant type
36177 * g_variant_type_key:
36178 * @type: a dictionary entry #GVariantType
36180 * Determines the key type of a dictionary entry type.
36182 * This function may only be used with a dictionary entry type. Other
36183 * than the additional restriction, this call is equivalent to
36184 * g_variant_type_first().
36186 * Returns: (transfer none): the key type of the dictionary entry
36193 * g_variant_type_n_items:
36194 * @type: a tuple or dictionary entry #GVariantType
36196 * Determines the number of items contained in a tuple or
36197 * dictionary entry type.
36199 * This function may only be used with tuple or dictionary entry types,
36200 * but must not be used with the generic tuple type
36201 * %G_VARIANT_TYPE_TUPLE.
36203 * In the case of a dictionary entry type, this function will always
36206 * Returns: the number of items in @type
36213 * g_variant_type_new:
36214 * @type_string: a valid GVariant type string
36216 * Creates a new #GVariantType corresponding to the type string given
36217 * by @type_string. It is appropriate to call g_variant_type_free() on
36218 * the return value.
36220 * It is a programmer error to call this function with an invalid type
36221 * string. Use g_variant_type_string_is_valid() if you are unsure.
36223 * Returns: (transfer full): a new #GVariantType
36229 * g_variant_type_new_array: (constructor)
36230 * @element: a #GVariantType
36232 * Constructs the type corresponding to an array of elements of the
36235 * It is appropriate to call g_variant_type_free() on the return value.
36237 * Returns: (transfer full): a new array #GVariantType
36244 * g_variant_type_new_dict_entry: (constructor)
36245 * @key: a basic #GVariantType
36246 * @value: a #GVariantType
36248 * Constructs the type corresponding to a dictionary entry with a key
36249 * of type @key and a value of type @value.
36251 * It is appropriate to call g_variant_type_free() on the return value.
36253 * Returns: (transfer full): a new dictionary entry #GVariantType
36260 * g_variant_type_new_maybe: (constructor)
36261 * @element: a #GVariantType
36263 * Constructs the type corresponding to a maybe instance containing
36264 * type @type or Nothing.
36266 * It is appropriate to call g_variant_type_free() on the return value.
36268 * Returns: (transfer full): a new maybe #GVariantType
36275 * g_variant_type_new_tuple:
36276 * @items: (array length=length): an array of #GVariantTypes, one for each item
36277 * @length: the length of @items, or -1
36279 * Constructs a new tuple type, from @items.
36281 * @length is the number of items in @items, or -1 to indicate that
36282 * @items is %NULL-terminated.
36284 * It is appropriate to call g_variant_type_free() on the return value.
36286 * Returns: (transfer full): a new tuple #GVariantType
36293 * g_variant_type_next:
36294 * @type: a #GVariantType from a previous call
36296 * Determines the next item type of a tuple or dictionary entry
36299 * @type must be the result of a previous call to
36300 * g_variant_type_first() or g_variant_type_next().
36302 * If called on the key type of a dictionary entry then this call
36303 * returns the value type. If called on the value type of a dictionary
36304 * entry then this call returns %NULL.
36306 * For tuples, %NULL is returned when @type is the last item in a tuple.
36308 * Returns: (transfer none): the next #GVariantType after @type, or %NULL
36315 * g_variant_type_peek_string: (skip)
36316 * @type: a #GVariantType
36318 * Returns the type string corresponding to the given @type. The
36319 * result is not nul-terminated; in order to determine its length you
36320 * must call g_variant_type_get_string_length().
36322 * To get a nul-terminated string, see g_variant_type_dup_string().
36324 * Returns: the corresponding type string (not nul-terminated)
36331 * g_variant_type_string_is_valid:
36332 * @type_string: a pointer to any string
36334 * Checks if @type_string is a valid GVariant type string. This call is
36335 * equivalent to calling g_variant_type_string_scan() and confirming
36336 * that the following character is a nul terminator.
36338 * Returns: %TRUE if @type_string is exactly one valid type string
36345 * g_variant_type_string_scan:
36346 * @string: a pointer to any string
36347 * @limit: (allow-none): the end of @string, or %NULL
36348 * @endptr: (out) (allow-none): location to store the end pointer, or %NULL
36350 * Scan for a single complete and valid GVariant type string in @string.
36351 * The memory pointed to by @limit (or bytes beyond it) is never
36354 * If a valid type string is found, @endptr is updated to point to the
36355 * first character past the end of the string that was found and %TRUE
36358 * If there is no valid type string starting at @string, or if the type
36359 * string does not end before @limit then %FALSE is returned.
36361 * For the simple case of checking if a string is a valid type string,
36362 * see g_variant_type_string_is_valid().
36364 * Returns: %TRUE if a valid type string was found
36370 * g_variant_type_value:
36371 * @type: a dictionary entry #GVariantType
36373 * Determines the value type of a dictionary entry type.
36375 * This function may only be used with a dictionary entry type.
36377 * Returns: (transfer none): the value type of the dictionary entry
36385 * @value: a #GVariant
36387 * Decreases the reference count of @value. When its reference count
36388 * drops to 0, the memory used by the variant is freed.
36396 * @string: the return location for the newly-allocated string.
36397 * @format: a standard printf() format string, but notice
36398 * [string precision pitfalls][string-precision]
36399 * @args: the list of arguments to insert in the output.
36401 * An implementation of the GNU vasprintf() function which supports
36402 * positional parameters, as specified in the Single Unix Specification.
36403 * This function is similar to g_vsprintf(), except that it allocates a
36404 * string to hold the output, instead of putting the output in a buffer
36405 * you allocate in advance.
36407 * Returns: the number of bytes printed.
36414 * @file: (not nullable): the stream to write to.
36415 * @format: a standard printf() format string, but notice
36416 * [string precision pitfalls][string-precision]
36417 * @args: the list of arguments to insert in the output.
36419 * An implementation of the standard fprintf() function which supports
36420 * positional parameters, as specified in the Single Unix Specification.
36422 * Returns: the number of bytes printed.
36429 * @format: a standard printf() format string, but notice
36430 * [string precision pitfalls][string-precision]
36431 * @args: the list of arguments to insert in the output.
36433 * An implementation of the standard vprintf() function which supports
36434 * positional parameters, as specified in the Single Unix Specification.
36436 * Returns: the number of bytes printed.
36443 * @string: the buffer to hold the output.
36444 * @n: the maximum number of bytes to produce (including the
36445 * terminating nul character).
36446 * @format: a standard printf() format string, but notice
36447 * string precision pitfalls][string-precision]
36448 * @args: the list of arguments to insert in the output.
36450 * A safer form of the standard vsprintf() function. The output is guaranteed
36451 * to not exceed @n characters (including the terminating nul character), so
36452 * it is easy to ensure that a buffer overflow cannot occur.
36454 * See also g_strdup_vprintf().
36456 * In versions of GLib prior to 1.2.3, this function may return -1 if the
36457 * output was truncated, and the truncated string may not be nul-terminated.
36458 * In versions prior to 1.3.12, this function returns the length of the output
36461 * The return value of g_vsnprintf() conforms to the vsnprintf() function
36462 * as standardized in ISO C99. Note that this is different from traditional
36463 * vsnprintf(), which returns the length of the output string.
36465 * The format string may contain positional parameters, as specified in
36466 * the Single Unix Specification.
36468 * Returns: the number of bytes which would be produced if the buffer
36469 * was large enough.
36475 * @string: the buffer to hold the output.
36476 * @format: a standard printf() format string, but notice
36477 * [string precision pitfalls][string-precision]
36478 * @args: the list of arguments to insert in the output.
36480 * An implementation of the standard vsprintf() function which supports
36481 * positional parameters, as specified in the Single Unix Specification.
36483 * Returns: the number of bytes printed.
36489 * g_wakeup_acknowledge:
36490 * @wakeup: a #GWakeup
36492 * Acknowledges receipt of a wakeup signal on @wakeup.
36494 * You must call this after @wakeup polls as ready. If not, it will
36495 * continue to poll as ready until you do so.
36497 * If you call this function and @wakeup is not signaled, nothing
36506 * @wakeup: a #GWakeup
36510 * You must not currently be polling on the #GPollFD returned by
36511 * g_wakeup_get_pollfd(), or the result is undefined.
36516 * g_wakeup_get_pollfd:
36517 * @wakeup: a #GWakeup
36518 * @poll_fd: a #GPollFD
36520 * Prepares a @poll_fd such that polling on it will succeed when
36521 * g_wakeup_signal() has been called on @wakeup.
36523 * @poll_fd is valid until @wakeup is freed.
36532 * Creates a new #GWakeup.
36534 * You should use g_wakeup_free() to free it when you are done.
36536 * Returns: a new #GWakeup
36543 * @wakeup: a #GWakeup
36547 * Any future (or present) polling on the #GPollFD returned by
36548 * g_wakeup_get_pollfd() will immediately succeed until such a time as
36549 * g_wakeup_acknowledge() is called.
36551 * This function is safe to call from a UNIX signal handler.
36558 * g_warn_message: (skip)
36559 * @domain: (nullable):
36563 * @warnexpr: (nullable):
36569 * @...: format string, followed by parameters to insert
36570 * into the format string (as with printf())
36572 * A convenience function/macro to log a warning message.
36574 * This is not intended for end user error reporting. Use of #GError is
36575 * preferred for that instead, as it allows calling functions to perform actions
36576 * conditional on the type of error.
36578 * You can make warnings fatal at runtime by setting the `G_DEBUG`
36579 * environment variable (see
36580 * [Running GLib Applications](glib-running.html)).
36582 * If g_log_default_handler() is used as the log handler function,
36583 * a newline character will automatically be appended to @..., and
36584 * need not be entered manually.
36589 * g_win32_check_windows_version:
36590 * @major: major version of Windows
36591 * @minor: minor version of Windows
36592 * @spver: Windows Service Pack Level, 0 if none
36593 * @os_type: Type of Windows OS
36595 * Returns whether the version of the Windows operating system the
36596 * code is running on is at least the specified major, minor and
36597 * service pack versions. See MSDN documentation for the Operating
36598 * System Version. Software that needs even more detailed version and
36599 * feature information should use the Win32 API VerifyVersionInfo()
36602 * Successive calls of this function can be used for enabling or
36603 * disabling features at run-time for a range of Windows versions,
36604 * as per the VerifyVersionInfo() API documentation.
36606 * Returns: %TRUE if the Windows Version is the same or greater than
36607 * the specified major, minor and service pack versions, and
36608 * whether the running Windows is a workstation or server edition
36609 * of Windows, if specifically specified.
36615 * g_win32_error_message:
36616 * @error: error code.
36618 * Translate a Win32 error code (as returned by GetLastError() or
36619 * WSAGetLastError()) into the corresponding message. The message is
36620 * either language neutral, or in the thread's language, or the user's
36621 * language, the system's language, or US English (see docs for
36622 * FormatMessage()). The returned string is in UTF-8. It should be
36623 * deallocated with g_free().
36625 * Returns: newly-allocated error message
36630 * g_win32_get_command_line:
36632 * Gets the command line arguments, on Windows, in the GLib filename
36633 * encoding (ie: UTF-8).
36635 * Normally, on Windows, the command line arguments are passed to main()
36636 * in the system codepage encoding. This prevents passing filenames as
36637 * arguments if the filenames contain characters that fall outside of
36638 * this codepage. If such filenames are passed, then substitutions
36639 * will occur (such as replacing some characters with '?').
36641 * GLib's policy of using UTF-8 as a filename encoding on Windows was
36642 * designed to localise the pain of dealing with filenames outside of
36643 * the system codepage to one area: dealing with commandline arguments
36646 * As such, most GLib programs should ignore the value of argv passed to
36647 * their main() function and call g_win32_get_command_line() instead.
36648 * This will get the "full Unicode" commandline arguments using
36649 * GetCommandLineW() and convert it to the GLib filename encoding (which
36650 * is UTF-8 on Windows).
36652 * The strings returned by this function are suitable for use with
36653 * functions such as g_open() and g_file_new_for_commandline_arg() but
36654 * are not suitable for use with g_option_context_parse(), which assumes
36655 * that its input will be in the system codepage. The return value is
36656 * suitable for use with g_option_context_parse_strv(), however, which
36657 * is a better match anyway because it won't leak memory.
36659 * Unlike argv, the returned value is a normal strv and can (and should)
36660 * be freed with g_strfreev() when no longer needed.
36662 * Returns: (transfer full): the commandline arguments in the GLib
36663 * filename encoding (ie: UTF-8)
36669 * g_win32_get_package_installation_directory:
36670 * @package: (allow-none): You should pass %NULL for this.
36671 * @dll_name: (allow-none): The name of a DLL that a package provides in UTF-8, or %NULL.
36673 * Try to determine the installation directory for a software package.
36675 * This function is deprecated. Use
36676 * g_win32_get_package_installation_directory_of_module() instead.
36678 * The use of @package is deprecated. You should always pass %NULL. A
36679 * warning is printed if non-NULL is passed as @package.
36681 * The original intended use of @package was for a short identifier of
36682 * the package, typically the same identifier as used for
36683 * `GETTEXT_PACKAGE` in software configured using GNU
36684 * autotools. The function first looks in the Windows Registry for the
36685 * value `#InstallationDirectory` in the key
36686 * `#HKLM\Software\@package`, and if that value
36687 * exists and is a string, returns that.
36689 * It is strongly recommended that packagers of GLib-using libraries
36690 * for Windows do not store installation paths in the Registry to be
36691 * used by this function as that interfers with having several
36692 * parallel installations of the library. Enabling multiple
36693 * installations of different versions of some GLib-using library, or
36694 * GLib itself, is desirable for various reasons.
36696 * For this reason it is recommeded to always pass %NULL as
36697 * @package to this function, to avoid the temptation to use the
36698 * Registry. In version 2.20 of GLib the @package parameter
36699 * will be ignored and this function won't look in the Registry at all.
36701 * If @package is %NULL, or the above value isn't found in the
36702 * Registry, but @dll_name is non-%NULL, it should name a DLL loaded
36703 * into the current process. Typically that would be the name of the
36704 * DLL calling this function, looking for its installation
36705 * directory. The function then asks Windows what directory that DLL
36706 * was loaded from. If that directory's last component is "bin" or
36707 * "lib", the parent directory is returned, otherwise the directory
36708 * itself. If that DLL isn't loaded, the function proceeds as if
36709 * @dll_name was %NULL.
36711 * If both @package and @dll_name are %NULL, the directory from where
36712 * the main executable of the process was loaded is used instead in
36713 * the same way as above.
36715 * Returns: a string containing the installation directory for
36716 * @package. The string is in the GLib file name encoding,
36717 * i.e. UTF-8. The return value should be freed with g_free() when not
36718 * needed any longer. If the function fails %NULL is returned.
36719 * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to
36720 * g_win32_get_package_installation_directory_of_module() instead.
36725 * g_win32_get_package_installation_directory_of_module:
36726 * @hmodule: (allow-none): The Win32 handle for a DLL loaded into the current process, or %NULL
36728 * This function tries to determine the installation directory of a
36729 * software package based on the location of a DLL of the software
36732 * @hmodule should be the handle of a loaded DLL or %NULL. The
36733 * function looks up the directory that DLL was loaded from. If
36734 * @hmodule is NULL, the directory the main executable of the current
36735 * process is looked up. If that directory's last component is "bin"
36736 * or "lib", its parent directory is returned, otherwise the directory
36739 * It thus makes sense to pass only the handle to a "public" DLL of a
36740 * software package to this function, as such DLLs typically are known
36741 * to be installed in a "bin" or occasionally "lib" subfolder of the
36742 * installation folder. DLLs that are of the dynamically loaded module
36743 * or plugin variety are often located in more private locations
36744 * deeper down in the tree, from which it is impossible for GLib to
36745 * deduce the root of the package installation.
36747 * The typical use case for this function is to have a DllMain() that
36748 * saves the handle for the DLL. Then when code in the DLL needs to
36749 * construct names of files in the installation tree it calls this
36750 * function passing the DLL handle.
36752 * Returns: a string containing the guessed installation directory for
36753 * the software package @hmodule is from. The string is in the GLib
36754 * file name encoding, i.e. UTF-8. The return value should be freed
36755 * with g_free() when not needed any longer. If the function fails
36756 * %NULL is returned.
36762 * g_win32_get_package_installation_subdirectory:
36763 * @package: (allow-none): You should pass %NULL for this.
36764 * @dll_name: (allow-none): The name of a DLL that a package provides, in UTF-8, or %NULL.
36765 * @subdir: A subdirectory of the package installation directory, also in UTF-8
36767 * This function is deprecated. Use
36768 * g_win32_get_package_installation_directory_of_module() and
36769 * g_build_filename() instead.
36771 * Returns a newly-allocated string containing the path of the
36772 * subdirectory @subdir in the return value from calling
36773 * g_win32_get_package_installation_directory() with the @package and
36774 * @dll_name parameters. See the documentation for
36775 * g_win32_get_package_installation_directory() for more details. In
36776 * particular, note that it is deprecated to pass anything except NULL
36779 * Returns: a string containing the complete path to @subdir inside
36780 * the installation directory of @package. The returned string is in
36781 * the GLib file name encoding, i.e. UTF-8. The return value should be
36782 * freed with g_free() when no longer needed. If something goes wrong,
36783 * %NULL is returned.
36784 * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to
36785 * g_win32_get_package_installation_directory_of_module() instead, and
36786 * then construct a subdirectory pathname with g_build_filename().
36791 * g_win32_get_windows_version:
36793 * This function is deprecated. Use
36794 * g_win32_check_windows_version() instead.
36796 * Returns version information for the Windows operating system the
36797 * code is running on. See MSDN documentation for the GetVersion()
36798 * function. To summarize, the most significant bit is one on Win9x,
36799 * and zero on NT-based systems. Since version 2.14, GLib works only
36800 * on NT-based systems, so checking whether your are running on Win9x
36801 * in your own software is moot. The least significant byte is 4 on
36802 * Windows NT 4, and 5 on Windows XP. Software that needs really
36803 * detailed version and feature information should use Win32 API like
36804 * GetVersionEx() and VerifyVersionInfo().
36806 * Returns: The version information.
36807 * Deprecated: 2.44: Be aware that for Windows 8.1 and Windows Server
36808 * 2012 R2 and later, this will return 62 unless the application is
36809 * manifested for Windows 8.1/Windows Server 2012 R2, for example.
36810 * MSDN stated that GetVersion(), which is used here, is subject to
36811 * further change or removal after Windows 8.1.
36816 * g_win32_getlocale:
36818 * The setlocale() function in the Microsoft C library uses locale
36819 * names of the form "English_United States.1252" etc. We want the
36820 * UNIXish standard form "en_US", "zh_TW" etc. This function gets the
36821 * current thread locale from Windows - without any encoding info -
36822 * and returns it as a string of the above form for use in forming
36823 * file names etc. The returned string should be deallocated with
36826 * Returns: newly-allocated locale name.
36831 * g_win32_locale_filename_from_utf8:
36832 * @utf8filename: a UTF-8 encoded filename.
36834 * Converts a filename from UTF-8 to the system codepage.
36836 * On NT-based Windows, on NTFS file systems, file names are in
36837 * Unicode. It is quite possible that Unicode file names contain
36838 * characters not representable in the system codepage. (For instance,
36839 * Greek or Cyrillic characters on Western European or US Windows
36840 * installations, or various less common CJK characters on CJK Windows
36843 * In such a case, and if the filename refers to an existing file, and
36844 * the file system stores alternate short (8.3) names for directory
36845 * entries, the short form of the filename is returned. Note that the
36846 * "short" name might in fact be longer than the Unicode name if the
36847 * Unicode name has very short pathname components containing
36848 * non-ASCII characters. If no system codepage name for the file is
36849 * possible, %NULL is returned.
36851 * The return value is dynamically allocated and should be freed with
36852 * g_free() when no longer needed.
36854 * Returns: The converted filename, or %NULL on conversion
36855 * failure and lack of short names.
36863 * A standard boolean type.
36864 * Variables of this type should only contain the value
36872 * Corresponds to the standard C char type.
36879 * An untyped pointer to constant data.
36880 * The data pointed to should not be changed.
36882 * This is typically used in function prototypes to indicate
36883 * that the data pointed to will not be altered by the function.
36890 * Corresponds to the standard C double type.
36891 * Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE.
36898 * Corresponds to the standard C float type.
36899 * Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT.
36906 * Corresponds to the standard C int type.
36907 * Values of this type can range from #G_MININT to #G_MAXINT.
36914 * A signed integer guaranteed to be 16 bits on all platforms.
36915 * Values of this type can range from #G_MININT16 (= -32,768) to
36916 * #G_MAXINT16 (= 32,767).
36918 * To print or scan values of this type, use
36919 * %G_GINT16_MODIFIER and/or %G_GINT16_FORMAT.
36926 * A signed integer guaranteed to be 32 bits on all platforms.
36927 * Values of this type can range from #G_MININT32 (= -2,147,483,648)
36928 * to #G_MAXINT32 (= 2,147,483,647).
36930 * To print or scan values of this type, use
36931 * %G_GINT32_MODIFIER and/or %G_GINT32_FORMAT.
36938 * A signed integer guaranteed to be 64 bits on all platforms.
36939 * Values of this type can range from #G_MININT64
36940 * (= -9,223,372,036,854,775,808) to #G_MAXINT64
36941 * (= 9,223,372,036,854,775,807).
36943 * To print or scan values of this type, use
36944 * %G_GINT64_MODIFIER and/or %G_GINT64_FORMAT.
36951 * A signed integer guaranteed to be 8 bits on all platforms.
36952 * Values of this type can range from #G_MININT8 (= -128) to
36953 * #G_MAXINT8 (= 127).
36960 * Corresponds to the C99 type intptr_t,
36961 * a signed integer type that can hold any pointer.
36963 * To print or scan values of this type, use
36964 * %G_GINTPTR_MODIFIER and/or %G_GINTPTR_FORMAT.
36972 * @arg: Do not use this argument
36974 * Do not call this function; it is used to share private
36975 * API between glib, gobject, and gio.
36982 * The binary age of the GLib library.
36983 * Defines how far back backwards compatibility reaches.
36985 * An integer variable exported from the library linked
36986 * against at application run time.
36991 * glib_check_version:
36992 * @required_major: the required major version
36993 * @required_minor: the required minor version
36994 * @required_micro: the required micro version
36996 * Checks that the GLib library in use is compatible with the
36997 * given version. Generally you would pass in the constants
36998 * #GLIB_MAJOR_VERSION, #GLIB_MINOR_VERSION, #GLIB_MICRO_VERSION
36999 * as the three arguments to this function; that produces
37000 * a check that the library in use is compatible with
37001 * the version of GLib the application or module was compiled
37004 * Compatibility is defined by two things: first the version
37005 * of the running library is newer than the version
37006 * @required_major.required_minor.@required_micro. Second
37007 * the running library must be binary compatible with the
37008 * version @required_major.required_minor.@required_micro
37009 * (same major version.)
37011 * Returns: %NULL if the GLib library is compatible with the
37012 * given version, or a string describing the version mismatch.
37013 * The returned string is owned by GLib and must not be modified
37021 * @str: The string to be translated
37023 * Returns the translated string from the glib translations.
37024 * This is an internal function and should only be used by
37025 * the internals of glib (such as libgio).
37027 * Returns: the transation of @str to the current locale
37032 * glib_interface_age:
37034 * The interface age of the GLib library.
37035 * Defines how far back the API has last been extended.
37037 * An integer variable exported from the library linked
37038 * against at application run time.
37043 * glib_major_version:
37045 * The major version of the GLib library.
37047 * An integer variable exported from the library linked
37048 * against at application run time.
37053 * glib_mem_profiler_table:
37055 * Used to be a #GMemVTable containing profiling variants of the memory
37056 * allocation functions, but this variable shouldn't be modified anymore.
37058 * Deprecated: 2.46: Use other memory profiling tools instead
37063 * glib_micro_version:
37065 * The micro version number of the GLib library.
37067 * An integer variable exported from the library linked
37068 * against at application run time.
37073 * glib_minor_version:
37075 * The minor version number of the GLib library.
37077 * An integer variable exported from the library linked
37078 * against at application run time.
37084 * @msgctxtid: a combined message context and message id, separated
37085 * by a \004 character
37086 * @msgidoffset: the offset of the message id in @msgctxid
37088 * This function is a variant of glib_gettext() which supports
37089 * a disambiguating message context. See g_dpgettext() for full
37092 * This is an internal function and should only be used by
37093 * the internals of glib (such as libgio).
37095 * Returns: the translation of @str to the current locale
37102 * Corresponds to the standard C long type.
37103 * Values of this type can range from #G_MINLONG to #G_MAXLONG.
37110 * A signed integer type that is used for file offsets,
37111 * corresponding to the C99 type off64_t.
37112 * Values of this type can range from #G_MINOFFSET to
37115 * To print or scan values of this type, use
37116 * %G_GOFFSET_MODIFIER and/or %G_GOFFSET_FORMAT.
37125 * An untyped pointer.
37126 * #gpointer looks better and is easier to use than void*.
37133 * Corresponds to the standard C short type.
37134 * Values of this type can range from #G_MINSHORT to #G_MAXSHORT.
37141 * An unsigned integer type of the result of the sizeof operator,
37142 * corresponding to the size_t type defined in C99.
37143 * This type is wide enough to hold the numeric value of a pointer,
37144 * so it is usually 32 bit wide on a 32-bit platform and 64 bit wide
37145 * on a 64-bit platform. Values of this type can range from 0 to
37148 * To print or scan values of this type, use
37149 * %G_GSIZE_MODIFIER and/or %G_GSIZE_FORMAT.
37156 * A signed variant of #gsize, corresponding to the
37157 * ssize_t defined on most platforms.
37158 * Values of this type can range from #G_MINSSIZE
37161 * To print or scan values of this type, use
37162 * %G_GSSIZE_MODIFIER and/or %G_GSSIZE_FORMAT.
37169 * Corresponds to the standard C unsigned char type.
37176 * Corresponds to the standard C unsigned int type.
37177 * Values of this type can range from 0 to #G_MAXUINT.
37184 * An unsigned integer guaranteed to be 16 bits on all platforms.
37185 * Values of this type can range from 0 to #G_MAXUINT16 (= 65,535).
37187 * To print or scan values of this type, use
37188 * %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT.
37195 * An unsigned integer guaranteed to be 32 bits on all platforms.
37196 * Values of this type can range from 0 to #G_MAXUINT32 (= 4,294,967,295).
37198 * To print or scan values of this type, use
37199 * %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
37206 * An unsigned integer guaranteed to be 64-bits on all platforms.
37207 * Values of this type can range from 0 to #G_MAXUINT64
37208 * (= 18,446,744,073,709,551,615).
37210 * To print or scan values of this type, use
37211 * %G_GINT64_MODIFIER and/or %G_GUINT64_FORMAT.
37218 * An unsigned integer guaranteed to be 8 bits on all platforms.
37219 * Values of this type can range from 0 to #G_MAXUINT8 (= 255).
37226 * Corresponds to the C99 type uintptr_t,
37227 * an unsigned integer type that can hold any pointer.
37229 * To print or scan values of this type, use
37230 * %G_GINTPTR_MODIFIER and/or %G_GUINTPTR_FORMAT.
37239 * Corresponds to the standard C unsigned long type.
37240 * Values of this type can range from 0 to #G_MAXULONG.
37247 * Corresponds to the standard C unsigned short type.
37248 * Values of this type can range from 0 to #G_MAXUSHORT.
37253 /************************************************************/
37254 /* THIS FILE IS GENERATED DO NOT EDIT */
37255 /************************************************************/